Skip to content
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.

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

Fix missing line in man task-color #3665

Merged
merged 1 commit into from
Nov 5, 2024

Conversation

d2718nis
Copy link
Contributor

@d2718nis d2718nis commented Nov 4, 2024

Escape leading single quote to prevent groff misinterpretation as a control character.

Issue

In man 5 task-color, the sentence cuts off unexpectedly:
There is also 'color.project.none', 'color.tag.none' and
This occurs just before the THEMES section.

screenshot-2024-11-05-01-35-39

Explanation

According to man 7 groff documentation, a leading single quote ' is interpreted as a control character and should be escaped as \[aq] to render correctly.

       '   The neutral apostrophe is the no-break control character,
           recognized where the control character is.  It suppresses the
           (first) break implied by the .bp, .cf, .fi, .fl, .in, .nf,
           .rj, .sp, .ti, and .trf requests.  The requested operation
           takes effect at the next break.  It makes .br nilpotent.  The
           no-break control character can be changed with the .c2
           request.  When formatted, “'” may be typeset as a
           typographical quotation mark; use the \[aq] special character
           escape sequence to format a neutral apostrophe glyph.

The man 7 groff_char page provides further details on character usage, and there has been long-standing discussion about this issue.

As suggested in the Getting Started section of man 1 groff documentation, here’s a quick way of testing the escaped sequences output:

echo "\[aq]test" | groff -Tascii | sed '/^$/d'

For UTF-8:

echo "\[aq]test" | groff -Tutf8 | sed '/^$/d'

Other options

Other approaches considered:

  • Move the word "and" from the previous line to avoid starting with a single quote. However, a linter might reformat this in the future, returning it to the original state
  • Use the \' escape sequence which renders as rather than '
  • Use \(aq instead of \[aq] — while shorter, \[aq] clearly separates the escape sequence from the text, and documentation specifically recommends it

Escape leading single quote to prevent groff misinterpretation as a
control character.
Copy link
Collaborator

@djmitche djmitche left a comment

Choose a reason for hiding this comment

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

Looks good, and I don't see this mistake elsewhere in the manpages.

Thanks for understanding groff!

@djmitche djmitche merged commit 0ff7844 into GothenburgBitFactory:develop Nov 5, 2024
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants