doc: use man(7) macros to style command synopses

* find/find.1:
* locate/locate.1:
* locate/updatedb.1:
* xargs/xargs.1: Favor man(7) font alternation macros over *roff font
  escape sequences.  When typesetting with groff(1), the macros
  automatically apply italic corrections.

* locate/locate.1: Protect long option name literals from hyphenation.
  GNU troff, Heirloom Doctools troff, and mandoc all support use of the
  `\%` hyphenation control escape sequence at the _beginning_ of a word
  suppress its hyphenation.  Other troffs do not.  Indirect this
  application of the escape sequence through a string, interpolating
  nothing on formatters that don't advertise GNU compatibility via the
  `.g` register.  (This means that literals can hyphenate undesirably on
  DWB, Solaris, and Plan 9 troffs.)

Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html

Copyright-paperwork-exempt: Yes
This commit is contained in:
G. Branden Robinson 2025-11-18 21:44:51 -06:00 committed by Bernhard Voelker
parent fe5b98b247
commit 7e8712f0ca
4 changed files with 79 additions and 26 deletions

View File

@ -4,8 +4,15 @@
find \- search for files in a directory hierarchy
.SH SYNOPSIS
.B find
[\-H] [\-L] [\-P] [\-D debugopts] [\-O\fIlevel\fP] [starting-point...\&] \
[expression]
.RB [ \-H ]
.RB [ \-L ]
.RB [ \-P ]
.RB [ \-D
.IR debugopts ]
.RB [ \-O\c
.IR level ]
.RI [ starting-point ...]\&
.RI [ expression ]
.
.SH DESCRIPTION
This manual page

View File

@ -1,28 +1,74 @@
.TH LOCATE 1 2020-12-27 findutils \" -*- nroff -*-
.\" As a GNU troff extension, \% at the beginning of a word suppresses
.\" its hyphenation.
.ie \n(.g \{\
. ds % \%
.\}
.el \{\
. ds % \" empty
.\}
.SH NAME
locate \- list files in databases that match a pattern
.
.SH SYNOPSIS
.B locate
[\-d path | \-\-database=path]
[\-e | \-E | \-\-[non\-]existing]
[\-i | \-\-ignore-case]
[\-0 | \-\-null]
[\-c | \-\-count]
[\-w | \-\-wholename]
[\-b | \-\-basename]
[\-l N | \-\-limit=N]
[\-S | \-\-statistics]
[\-r | \-\-regex ]
[\-\-regextype R]
[\-\-max-database-age D]
[\-P | \-H | \-\-nofollow]
[\-L | \-\-follow]
[\-\-version]
[\-A | \-\-all]
[\-p | \-\-print]
[\-\-help]
pattern...
.RB [ \-d
.I path
|
.BI \*%\-\-database= path\c
]
.RB [ \-e
|
.B \-E
|
.BR \*%\-\- [ non\- ] existing ]
.RB [ \-i
|
.BR \*%\-\-ignore\-case ]
.RB [ \-0
|
.BR \-\-null ]
.RB [ \-c
|
.BR \*%\-\-count ]
.RB [ \-w
|
.BR \*%\-\-wholename ]
.RB [ \-b
|
.BR \*%\-\-basename ]
.RB [ \-l
.I N
|
.BI \*%\-\-limit= N\c
]
.RB [ \-S
|
.BR \*%\-\-statistics ]
.RB [ \-r
|
.BR \*%\-\-regex ]
.RB \*%[ \-\-regextype
.IR R ]
.RB \*%[ \-\-max\-database\-age
.IR D ]
.RB [ \-P
|
.B \-H
|
.BR \*%\-\-nofollow ]
.RB [ \-L
|
.BR \*%\-\-follow ]
.RB \*%[ \-\-version ]
.RB [ \-A
|
.BR \-\-all ]
.RB [ \-p
|
.BR \*%\-\-print ]
.RB \*%[ \-\-help ]
.IR pattern ...
.
.SH DESCRIPTION
This manual page

View File

@ -2,7 +2,8 @@
.SH NAME
updatedb \- update a file name database
.SH SYNOPSIS
.B updatedb [\fIoptions\fP]
.B updatedb
.RI [ options ]
.
.SH DESCRIPTION
This manual page

View File

@ -3,10 +3,9 @@
xargs \- build and execute command lines from standard input
.SH SYNOPSIS
.B xargs
.nh
[\fIoptions\fR]
[\fIcommand\fR [\fIinitial-arguments\fR]]
.hy
.RI [ options ]
.RI [ command ]
.RI [ initial-arguments ]
.
.SH DESCRIPTION
This manual page