findutils developers: I have some man page patches in preparation.[1]
Bjarni,
At 2025-03-08T15:50:36+0000, Bjarni Ingi Gislason wrote:
> Package: findutils
> Version: upstream (git)
> Severity: minor
> Tags: patch
>
> * What led up to the situation?
>
> Checking for defects with a new version
>
> test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man
> page"
[...]
>
> Remove quotes when there is a printable
> but no space character between them
> and the quotes are not for emphasis (markup),
> for example as an argument to a macro.
>
> find.1:638:.IP "\-noleaf"
> find.1:1154:.IP "\-writable"
> find.1:1196:.IP "\-delete\fR"
> find.1:1802:.IP "\-quit"
> find.1:2233:.SH "EXAMPLES"
> find.1:2638:.SH "HISTORY"
> find.1:2659:.SH "COMPATIBILITY"
> find.1:2724:.SH "NON-BUGS"
> find.1:2770:.SH "BUGS"
The foregoing practice is harmless and I don't think you should be
advising people to stop quoting macro arguments in this case because
your understanding of man(7) portability issues is evidently lacking.
If you would read the groff_man_style(7) man page, you would have known
better.
groff_man_style(7):
Portability
...
The wise man author quotes multi‐word section and subsection
headings; the SH and SS macros of man(7) implementations descended
from Seventh Edition Unix supported six arguments at most. This
restriction also applied to the B, I, SM, and font style
alternation macros.
> Section headings (.SH and .SS) do not need quoting their arguments.
>
> 1968:.SH "STANDARDS CONFORMANCE"
> 2120:.SH "ENVIRONMENT VARIABLES"
> 2233:.SH "EXAMPLES"
> 2638:.SH "HISTORY"
> 2659:.SH "COMPATIBILITY"
> 2724:.SH "NON-BUGS"
> 2770:.SH "BUGS"
> 2788:.SH "REPORTING BUGS"
> 2811:.SH "SEE ALSO"
...as we see here. This is bad advice (and bad English).
It's *VERY* advisable to quote the arguments to the `SH` and `SS` macro
calls if portability to AT&T troff/man is desired, as it is for GNU
findutils.
Please stop issuing the foregoing guidance. It can lead to text being
dropped from (sub)section headings.
> Create a "space" between some tags and the its following text by adding
> " \&" to the tag.
[...]
> +.IP "\-O\fIlevel\fP \&"
This is also suboptimal advice. The dummy character escape sequence
`\&` you're advising people to use is a no-op here. Observe:
---example---
$ printf '.TH foo 1 2025-11-12 "groff test suite"\n.IP "abcde "\nfoo\n.IP
"abcde \\&"\nbar\n' | nroff -rLL=72n -man
foo(1) General Commands Manual foo(1)
abcde foo
abcde bar
groff test suite 2025‐11‐12 foo(1)
---end example---
If a document demands a certain amount of indentation for an `IP` (or
`HP`, or `TP` paragraph), these macros all support an argument for its
specification.
groff_man(7) (from groff Git, but groff 1.23.0 is similar):
Paragraphing macros
These macros break the output line. An ordinary paragraph (P)
indents all output lines by the same amount. A hanging paragraph
(HP) is a cosmetic variant of P with a hanging indent. Definition
lists frequently occur in man pages; these can be set as tagged
paragraphs, which have one (TP) or more (TQ) leading tags followed
by a paragraph that has an additional indentation. The indented
paragraph (IP) macro is useful to continue the indented content of
a narrative started with TP, or to present an itemized or ordered
list. If paragraph macro has been called since SH or SS, all
except for TQ follow the break with vertical space (in an amount
configured by the deprecated PD macro); see subsection “Horizontal
and vertical spacing” below. Except for TQ, these macros reset the
type size and font style to defaults, and restore the configured
hyphenation mode.
...
.HP [indentation]
Set a paragraph with a hanging indentation. Text on output
lines after the first is indented by indentation, if
specified, and by the amount of the IN register otherwise.
...
.TP [indentation]
Set an indented paragraph with a leading unindented tag.
The macro plants a one‐line input trap that honors the \c
escape sequence; text on the next line becomes the tag, set
without indentation. Text on subsequent lines is indented
by indentation, if specified, and by the amount of the IN
register otherwise. If the tag, plus the “tag spacing”
stored in the TS register (see section “Options” below) is
wider than the indentation, the package breaks the line
after the tag.
...
.IP [mark [indentation]]
Set an indented paragraph with an optional mark. Arguments,
if present, are handled as with TP, except that the mark
argument to IP cannot include a macro call, and the tag
separation amount stored in the TS register is not enforced.
Regards,
Branden
[1] Here's what my local branch looks like right now.
$ git log --oneline --reverse master..HEAD
e27fa502 Fix troff error in find(1).
efa5f304 Replace UTF-8 character sequence in find(1).
34ff5532 Populate man pages' headers and footers more.
88e256e2 Fix typo in find(1).
058cdb24 Delete blank lines from man page sources.
3a9abc1e Use AT&T troff-compatible syntax in find(1).
c2269c0a Use man(7) macros to style command synopses.
f25ccd40 Improve typography of synopses.
b33d81b4 Improve formatting of command synopses (1/x).
410fa36d Improve formatting of command synopses (2/x).
a5541b2e locate/locate.1: Improve table formatting.
c662a9be find/find.1: Improve table formatting.
44308da4 find/find.1: Access " character somewhat portably.
b9bee647 find/find.1: Access ' character portably.
21dbaf38 find/find.1: Use em dash for linguistic pausa.
e6c63674 man pages: Access en dash character portably.
0a1186a6 find/find.1: Improve cosmetics of *roff logic.
89178a30 find/find.1: Access ~ character portably.
bfcd70ef find/find.1: Use new ~ string for pastable tilde.
177b7daa find/find.1: Access “ and ” portably.
18acbd55 xargs/xargs.1: Use portable typographer's quotes.
3928c856 locate/locatedb.5: Fix unescaped hyphens.
92aa1583 locate/locate.1: Access ^ character portably.
adea377b xargs/xargs.1: Overcome limited portability of \~.
3eeb4556 xargs/xargs.1: Access ' character portably.
1eca2ec7 (HEAD -> gbr-man-page-fixes) xargs/xargs.1: Add styling to text.
signature.asc
Description: PGP signature
