Skip to content

pygmt.paragraph: Improve docs #4602

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
yvonnefroehlich wants to merge 3 commits into
base: main
Choose a base branch
from
+2 −1
Draft

pygmt.paragraph: Improve docs #4602

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9e6f607
Add note regarding white space at end of strings for paragraph recogn…
yvonnefroehlich Apr 26, 2026
b84867a
Revert note regarding blank line
yvonnefroehlich Apr 27, 2026
9587ec9
Add note regarding paragraph separation
yvonnefroehlich Apr 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions pygmt/src/paragraph.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,8 @@ def paragraph( # noqa: PLR0913
spacing. The text can be aligned left, center, right, or justified.

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.
needs to end with a white space and represents a separate paragraph, or as a single
Copy link
Copy Markdown
Member

@seisman seisman Apr 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member Author

@yvonnefroehlich yvonnefroehlich Apr 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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()
image

Copy link
Copy Markdown
Member

@seisman seisman Apr 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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()
Image

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.

Copy link
Copy Markdown
Member

@seisman seisman Apr 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member Author

@yvonnefroehlich yvonnefroehlich Apr 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

string with a blank line (``\n\n``) separating the paragraphs.

Full GMT docs at :gmt-docs:`text.html`.

Expand Down
Loading