Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Conversation

@g-branden-robinson
Copy link

No description provided.

Fixes:
$ mandoc -T lint src/xfile.1
mandoc: src/xfile.1:9:2: WARNING: skipping paragraph macro: PP after SH
mandoc: src/xfile.1:120:2: WARNING: skipping paragraph macro: PP after SS
mandoc: src/xfile.1:135:2: WARNING: skipping paragraph macro: PP after SS
mandoc: src/xfile.1:143:2: WARNING: skipping paragraph macro: PP after SS
mandoc: src/xfile.1:84:2: WARNING: skipping paragraph macro: PP after SH
mandoc: src/xfile.1:159:2: WARNING: skipping paragraph macro: PP after SS
mandoc: src/xfile.1:248:2: WARNING: skipping paragraph macro: PP after SS
mandoc: src/xfile.1:323:2: WARNING: skipping paragraph macro: PP after SS
mandoc: src/xfile.1:337:2: WARNING: skipping paragraph macro: PP after SS
mandoc: src/xfile.1:355:2: WARNING: skipping paragraph macro: PP after SH
mandoc: src/xfile.1:368:2: WARNING: skipping paragraph macro: PP after SH
mandoc: src/xfile.1:371:2: WARNING: skipping paragraph macro: PP after SH

The `SH` and `SS` macros always follow the section heading with
inter-paragraph vertical space and begin a new paragraph as with `PP`
(or its synonyms `LP` and `P`).

groff_man(7):
       .SH [heading‐text]
              Set heading‐text as a section heading.  If no argument is
              given, a one‐line input trap is planted; text on the next
              line becomes heading‐text.  The left margin is reset to
              zero to set the heading text in bold (or the font
              specified by the string HF), and, on typesetting devices,
              slightly larger than the base type size.  If the heading
              font \*[HF] is bold, use of an italic style in heading‐
              text is mapped to the bold‐italic style if available in
              the font family.  The inset level is reset to 1, setting
              the left margin to the value of the IN register.  Text
              after heading‐text is set as an ordinary paragraph (.P).
[...]
       .SS [subheading‐text]
              Set subheading‐text as a subsection heading indented
              between a section heading and an ordinary paragraph (.P).
              If no argument is given, a one‐line input trap is planted;
              text on the next line becomes subheading‐text.  The left
              margin is reset to the value of the SN register to set the
              heading text in bold (or the font specified by the string
              HF).  If the heading font \*[HF] is bold, use of an italic
              style in subheading‐text is mapped to the bold‐italic
              style if available in the font family.  The inset level is
              reset to 1, setting the left margin to the value of the IN
              register.  Text after subheading‐text is set as an
              ordinary paragraph (.P).
Fixes:
$ mandoc -T lint src/xfile.1
mandoc: src/xfile.1:19:1: WARNING: invalid escape sequence: \fb
$ nroff -z -man src/xfile.1
troff:src/xfile.1:19: warning: cannot select font 'b'
Fixes:
$ nroff -z -rCHECKSTYLE=1 -man src/xfile.1
an.tmac:src/xfile.1:1: style: .TH missing third argument; suggest document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:src/xfile.1:1: style: .TH missing fourth argument; suggest package/project name and version (e.g., "groff 1.23.0")
$ mandoc -T lint src/xfile.1
mandoc: src/xfile.1:1:2: WARNING: missing date, using "": TH

groff_man_style(7):
       .TH topic section [footer‐middle] [footer‐inside] [header‐middle]
              Determine the contents of the page header and footer.
              roff systems refer to these collectively as “titles”.  The
              subject of the man page is topic and the section of the
              manual to which it belongs is section.  This use of
              “section” has nothing to do with the section headings
              otherwise discussed in this page; it arises from the
              organizational scheme of printed and bound Unix manuals.
              See man(1) or intro(1) for the manual sectioning
              applicable to your system.  topic and section are
              positioned together at the left and right in the header
              (with section in parentheses immediately appended to
              topic).  footer‐middle is centered in the footer.  The
              arrangement of the rest of the footer depends on whether
              double‐sided layout is enabled with the option -rD1.  When
              disabled (the default), footer‐inside is positioned at the
              bottom left.  Otherwise, footer‐inside appears at the
              bottom left on recto (odd‐numbered) pages, and at the
              bottom right on verso (even‐numbered) pages.  The outside
              footer is the page number, except in the continuous‐
              rendering mode enabled by the option -rcR=1, in which case
              it is the topic and section, as in the header.  header‐
              middle is centered in the header.  If section is an
              integer between 1 and 9 (inclusive), there is no need to
              specify header‐middle; an.tmac will supply text for it.
              The macro package may also abbreviate topic and footer‐
              inside with ellipses (...) if they would overrun the space
              available in the header and footer, respectively.  For
              HTML output, headers and footers are suppressed.

              Additionally, this macro breaks the page, resetting the
              number to 1 (unless the -rC1 option is given).  This
              feature is intended only for formatting multiple man
              documents in sequence.

              A valid man document calls .TH once, early in the file,
              prior to any other macro calls.

              By convention, footer‐middle is the date of the most
              recent modification to the man page source document, and
              footer‐inside is the name and version or release of the
              project providing it.
Fixes:
$ mandoc -T lint src/xfile.1
mandoc: src/xfile.1:13:45: STYLE: whitespace at end of input line
mandoc: src/xfile.1:29:28: STYLE: whitespace at end of input line
mandoc: src/xfile.1:363:62: STYLE: whitespace at end of input line
Fixes:
$ nroff -z -rCHECKSTYLE=3 -man src/xfile.1
an.tmac:src/xfile.1:30: style: blank line in input
an.tmac:src/xfile.1:349: style: blank line in input
an.tmac:src/xfile.1:352: style: blank line in input
an.tmac:src/xfile.1:355: style: blank line in input

Replace blank lines separating paragraphs with `PP` calls.

Drop blank line that ends up preceding a (sub)section heading.

groff_man_style(7) briefly offers this advice:
         Do not put blank (empty) lines in a man page source document.

The reason is that a blank line puts 1 vee of vertical space in the
document, whereas the inter-paragraph spacing amount is configurable,
and has defaulted to 0.4 vees on typesetters since the man(7) package
debuted in Seventh Edition Unix in 1979.

https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/lib/tmac/tmac.an

(See the `PD` macro definition--the line starting `.de PD`.)
Fixes:
$ mandoc -T lint src/xfile.1
mandoc: src/xfile.1:23:87: STYLE: input text line longer than 80 bytes: Specify sort order: ...
mandoc: src/xfile.1:33:81: STYLE: input text line longer than 80 bytes: with the iconSize re...
mandoc: src/xfile.1:297:81: STYLE: input text line longer than 80 bytes: Specifies the file n...

I took the liberty of siting the breaks in "gui.man" such that the
formatter would produce correct inter-sentence spacing.

groff_man_style(7):
   Fundamental concepts
       groff is a programming system for typesetting: we thus often use
       the verb “to set” in the sense “to typeset”.  The formatter
       troff(1) collects words from the input and fills output lines
       with as many as will fit.  Words are separated by spaces and
       newlines.  A transition to a new output line is called a break.
       When formatted, a word may be broken at hyphens, at \% or \:
       escape sequences (see subsection “Portability” below), or at
       predetermined locations if automatic hyphenation is enabled (see
       the -rHY option in section “Options” below).  An output line may
       be supplemented with inter‐sentence space, and then optionally
       adjusted with more space to a consistent line length (see the
       -dAD option).  roff(7) details these processes.

"Unix for Beginners", Brian Kernighan, 1974:
  Hints for Preparing Documents
    Most documents go through several versions (always more than you
    expected) before they are finally finished.  Accordingly, you should
    do whatever possible to make the job of changing them easy.  First,
    when you do the purely mechanical operations of typing, type so
    subsequent editing will be easy.

    Start each sentence on a new line.  Make lines short, and break
    lines at natural places, such as after commas and semicolons, rather
    than randomly.  Since most people change documents by rewriting
    phrases and adding, deleting and rearranging sentences, these
    precautions simplify any editing you have to do later.

https://wolfram.schneider.org/bsd/7thEdManVol2/beginners/beginners.pdf
groff(7):
       ... roff documents should not
       use the \\ or \. character sequences outside of copy mode; they
       serve only to obfuscate the input.
@alx210 alx210 force-pushed the master branch 2 times, most recently from 7c9f3ea to cd50c98 Compare June 14, 2025 10:13
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.

1 participant