-
Couldn't load subscription status.
- Fork 2
Man page fixes #2
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
Open
g-branden-robinson
wants to merge
7
commits into
alx210:master
Choose a base branch
from
g-branden-robinson:man-page-fixes
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Man page fixes #2
g-branden-robinson
wants to merge
7
commits into
alx210:master
from
g-branden-robinson:man-page-fixes
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
7c9f3ea to
cd50c98
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.