pygmt.paragraph: Improve docs

[yvonnefroehlich]

Related to #4592 (comment)

Preview:

Guidelines

• General Guidelines for Pull Request
• Guidelines for Contributing Documentation
• Guidelines for Contributing Code

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash command is:

• /format: automatically format and lint the code

[seisman]

Hmmm. what do you mean by "end with a white space"?

[yvonnefroehlich]

When working on the gallery example in #4595, I realized that whitespaces at the ends of the single strings of a list (except the last element) are needed so that the single strings are considered as separate paragraphs and separated by a blank line.

import pygmt

text1 = ["xxx", "yyy", "zzz"]
text2 = ["xxx ", "yyy ", "zzz"]  # note the white spaces at the ends of the first and second string

fig = pygmt.Figure()

fig.basemap(region=[-1, 1, -1, 1], projection="X5c/5c", frame=True)
fig.paragraph(text=text1, x=0, y=0, parwidth="3c", linespacing="10p")#, pen=True)

fig.shift_origin(xshift="+w+1c")

fig.basemap(region=[-1, 1, -1, 1], projection="X5c/5c", frame=True)
fig.paragraph(text=text2, x=0, y=0, parwidth="3c", linespacing="10p")#, pen=True)

fig.show()

[seisman]

I think there is a misunderstanding. The left example has three paragraphs.

import pygmt

text1 = [
    "Paragraph 1: long text string. long text string. long text string. long text string.",
    "Paragraph 2: another long text string. another long text string. another long text string. another long text string.",
    "Paragraph 3: yet another long text string. yet another long text string. yet another long text string. yet another long text string."
]

text2 = [
    "Paragraph 1: long text string. long text string. long text string. long text string. ",
    "Paragraph 2: another long text string. another long text string. another long text string. another long text string. ",
    "Paragraph 3: yet another long text string. yet another long text string. yet another long text string. yet another long text string."
]


fig = pygmt.Figure()

fig.basemap(region=[-1, 1, -1, 1], projection="X10c/5c", frame=True)
fig.paragraph(text=text1, x=0, y=0, parwidth="7c", linespacing="10p")#, pen=True)

fig.shift_origin(xshift="+w+1c")

fig.basemap(region=[-1, 1, -1, 1], projection="X10c/5c", frame=True)
fig.paragraph(text=text2, x=0, y=0, parwidth="7c", linespacing="10p")#, pen=True)

fig.show()

In GMT, multiple paragraphs are not typeset with a blank line between paragraphs. In other words, the behavior in the righ example is unexpected and is likely a bug in Figure.paragraph.

Actually, I find I cannot reproduce the right example using GMT CLI.

gmt text -R-1/1/-1/1 -JX10c/5c -Baf -M -pdf map << EOF
> 0 0 10p 7c l
Paragraph 1: long text string. long text string. long text string. long text string. 

Paragraph 2: another long text string. another long text string. another long text string. another long text string. 

Paragraph 3: yet another long text string. yet another long text string. yet another long text string. yet another long text string.
EOF

In this example, it has trailing whitespaces at the end of each paragraph, but it produces the left example, not the right one.

[seisman]

I'll open a detailed issue report in #3710 when I have time.

[yvonnefroehlich]

In GMT, multiple paragraphs are not typeset with a blank line between paragraphs. In other words, the behavior in the righ example is unexpected and is likely a bug in Figure.paragraph.

Ah, OK. Thanks for this detailed explanation 🙂.

I think there is a misunderstanding. The left example has three paragraphs.

You are correct I got confused by the docs:

Multiple paragraphs can be provided as a sequence of strings, where each string represents a separate paragraph, or as a single string with a blank line (\n\n) separating the paragraphs.

I thougth the blank line will be also present in the typset text. Maybe we can add this to the docs, otherwise this PR is not needed anymore and can be closed.

I'll open a detailed issue report in #3710 when I have time.

Sounds good. Thanks! No worries, this paragraph method is still only included in the dev version, and I think it's not likely that many people found this behavior so far.