[PATCH 06/42] doc: use man(7) macros to style command synopses

"G. Branden Robinson" <[email protected]> Tue, 18 Nov 2025 21:44:51 -0600
Newsgroups	gmane.comp.gnu.findutils.bugs
Message-ID	<20251119034451.d46nmbdj4yfds76u@illithid>
* 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.)
---
 find/find.1       | 11 +++++--
 locate/locate.1   | 84 ++++++++++++++++++++++++++++++++++++-----------
 locate/updatedb.1 |  3 +-
 xargs/xargs.1     |  7 ++--
 4 files changed, 79 insertions(+), 26 deletions(-)

diff --git a/find/find.1 b/find/find.1
index ae35a2b5..bfaac466 100644
--- a/find/find.1
+++ b/find/find.1
@@ -4,8 +4,15 @@ .SH NAME
 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
diff --git a/locate/locate.1 b/locate/locate.1
index b65d9036..c926dc43 100644
--- a/locate/locate.1
+++ b/locate/locate.1
@@ -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
diff --git a/locate/updatedb.1 b/locate/updatedb.1
index 07eac5ee..04314f6a 100644
--- a/locate/updatedb.1
+++ b/locate/updatedb.1
@@ -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
diff --git a/xargs/xargs.1 b/xargs/xargs.1
index 91f6f073..d2ce74de 100644
--- a/xargs/xargs.1
+++ b/xargs/xargs.1
@@ -3,10 +3,9 @@ .SH NAME
 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
-- 
2.30.2
signature.asc (application/pgp-signature, 833 B)