Figure.paragraph: Typeset one or multiple paragraphs

[seisman]

This issue serves as the central place for discussing and tracking the implementation of the Figure.paragraph method in PyGMT. The issue will be closed when the initial implementation is complete. Progress is tracked at PyGMT: Wrapping GMT modules.

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

Documentation

• GMT: https://docs.generic-mapping-tools.org/dev/text.html
• GMT.jl: https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/text/
• PyGMT: https://www.pygmt.org/dev/api/generated/pygmt.Figure.paragraph.html

GMT Option Flags and Modifieres

☑️: Implemented; ⬜: 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|t: Can't be used in paragraph mode.
• -G: fill Add Figure.paragraph to typeset one or multiple paragraph of text strings #3709
• -L
• -M: paragraph mode Add Figure.paragraph to typeset one or multiple paragraph of text strings #3709
• -N
• -Q
• -S
• ~~-U: Use Figure.timestamp.
• -V: verbose Add Figure.paragraph to typeset one or multiple paragraph of text strings #3709
• -W: pen Add Figure.paragraph to typeset one or multiple paragraph of text strings #3709
• ~~-X: Use Figure.shift_origin.
• ~~-Y: Use Figure.shift_origin.
• -Z: Not implemented for paragraph mode
• -a
• -c: panel Add Figure.paragraph to typeset one or multiple paragraph of text strings #3709
• -e
• -f
• -h
• -it
• -p: This option is not implemented in paragraph mode.
• -qi
• -t: transparency Add Figure.paragraph to typeset one or multiple paragraph of text strings #3709
• -wy
• -:

Notes on Input Formats

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.
3. Passing a plaintext file is not supported. I prefer not to support it anyway.

Linked Pull Requests

• Initial feature implementation Add Figure.paragraph to typeset one or multiple paragraph of text strings #3709 @seisman
• Add a tutorial or gallery example

Related Issues and Discussions