Figure.paragraph: Typeset one or multiple paragraphs

[seisman]

Figure.paragraph is a high-level wrapper of GMT's text module to typeset one or multiple paragraphs in a plot.

• GMT documentation: https://docs.generic-mapping-tools.org/6.5/text.html
• PyGMT documentation: TODO

GMT options

Checked: Implemented; Unchecked: To be implemented/discussed; Strikethrough: Won't implement.

• <table>: Add Figure.paragraph to typeset one or multiple paragraph of text strings #3709
• -J
• -R
• -A
• -B
• -C
• -D
• -F
  • +a: set angle Add Figure.paragraph to typeset one or multiple paragraph of text strings #3709
  • +c:
  • +f: set font Add Figure.paragraph to typeset one or multiple paragraph of text strings #3709
  • +j: set justify Add Figure.paragraph to typeset one or multiple paragraph of text strings #3709
  • +h|l|r|z: Text string from segment header. Make no sense in paragraph mode.
  • +t: Make no sense in paragraph mode.
• -G
• -L
• -M: paragraph mode.
• -N
• -Q
• -S
• ~~-U: Use Figure.timestamp.
• -V
• -W
• ~~-X: Use Figure.shift_origin.
• ~~-Y: Use Figure.shift_origin.
• -Z
• -a
• -c
• -e
• -f
• -h
• -it
• -p: This option is not implemented in paragraph mode.
• -qi
• -t
• -wy
• -:

Input format

text's -M option means "paragraph mode". In this mode, the input file must be multi-segment files. Segments are separated by a special record whose first character must be flag [Default is >]. Multiple paragraphs are separated with a blank line. Its format is like:

> x y [font angle justify] linespace parwidth parjust
text for paragraph1

text for paragraph2
> x y [font angle justify] linespace parwidth parjust
text for paragraph3

• x/y: position of the paragraph
• font/angle: font and angle of the text [Requires -F]
• justify: justification of the paragraph box [Requires -F]
• linespace: line spacing
• parwidth: paragraph width
• parjust: text justification in the paragraph, can be l(eft), c(enter), r(ight), or j(ustified)

Notes:

1. Multiple paragraphs should be separated by a blank line when passing to GMT. A sequence of string is the most Pythonic way to represent multiple paragraphs.
2. When typesetting multiple paragraphs, each paragraph can have its own font/angle/justify/linespace/parwidth/parjust. It means the corresponding parameters should accept a sequence as input. I think it will makes codes much complicated, so prefer not to support it. Users who need different styles for different paragraphs can call Figure.paragraph multiple times.