NULL is best for C as discussed - for coreutils - at:
https://bugs.gnu.org/66221#53
* bootstrap.conf: Remove dependency on nullptr.
* s/nullptr/NULL/.
This effectively reverts 93ce19f0d5a1.
* xargs/xargs.1:
- Migrate from comma-separated to "stacked tag" formatting for command
options. This is easier to read and understand when option syntax is
complex, and eliminates the problem of the comma being misinterpreted.
Setting the comma in bold, not roman, might have increased this risk.
Stacking tags--without direct recourse to formatter requests--however
requires the use of a groff man(7) extension macro, `TQ` (from groff
1.20, 2009). Because this page needs to be portable to non-groff
formatters, define a page-local version after testing for its
nonexistence using other GNU troff extensions (the `do` request and
the `d` conditional expression operator). (Actually, the method here
is to test for `TQ`'s existence and then ignore the macro definition
if the test succeeds; the token `..` terminates whichever eventuates.)
- Use the `TQ` macro to stack paragraph tags presenting synonymous
options to xargs(1).
- Use the page-local `~~` string to put unbreakable spaces (where
supported) between short options and their arguments. (On the other
hand, if a paragraph tag breaks across lines, the document likely
requires revision.)
Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html
Copyright-paperwork-exempt: Yes
* xargs/xargs.1: Consistently use empty request before paragraphing macros
to aid document maintainers. This was already done, inconsistently.
Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html
Copyright-paperwork-exempt: Yes
groff_man(7):
History
M. Douglas McIlroy ⟨m.douglas.mcilroy@dartmouth.edu⟩ designed,
implemented, and documented the AT&T man macros for Unix Version 7
(1979) and employed them to edit Volume 1 of its Programmer’s
Manual, a compilation of all man pages supplied by the system. The
package supported the macros listed in this page not described as
extensions, except P and the deprecated AT and UC. It documented
no registers and defined only R and S strings.
UC appeared in 3BSD (1980). Unix System III (1980) introduced P
and exposed the registers IN and LL, which had been internal to
Seventh Edition Unix man. PWB/Unix 2.0 (1980) added the Tm string.
4BSD (1980) added lq and rq strings. SunOS 2.0 (1985) recognized
C, D, P, and X registers. 4.3BSD (1986) added AT and P. Ninth
Edition Unix (1986) introduced EX and EE. SunOS 4.0 (1988) added
SB. Unix System V (1988) incorporated BSD’s lq and rq strings.
Except for EX/EE, James Clark implemented the foregoing features in
early versions of groff. Later, groff 1.20 (2009) resurrected
EX/EE and originated SY/YS, TQ, MT/ME, and UR/UE. Plan 9 from User
Space’s troff introduced MR in 2020.
* xargs/xargs.1: Favor `P` macro, which the page predominantly uses, over
`PP` (`LP` is not observed). `P` has been universally portable since 1986.
Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html
Copyright-paperwork-exempt: Yes
* xargs/xargs.1:
Favor man(7) font macros over *roff font selection escape sequences.
Macros are (a) visually less cluttered, (b) interfere less with spell
checking, and (c), in groff man(7), automatically apply italic
corrections, which otherwise requires explicit use of GNU troff
extension escape sequences (`\/` and `\,`).
Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html
Copyright-paperwork-exempt: Yes
...not roman.
groff_man_style(7):
Font style macros
...
.I [text]
Set text in an italic or oblique face. Given no argument, I
plants a one‐line input trap; text on the next line, which
can be further formatted with a macro, is set in an italic
or oblique face.
Use italics for file and path names, for environment
variables, for C data types, for enumeration or preprocessor
constants in C, for variant (user‐replaceable) portions of
syntax synopses, for the first occurrence (only) of a
technical concept being introduced, for names of journals
and of literary works longer than an article, and anywhere a
parameter requiring replacement by the user is encountered.
An exception involves variant text in a context already
typeset in italics, such as file or path names with
replaceable components; in such cases, follow the convention
of mathematical typography: set the file or path name in
italics as usual but use roman for the variant part (see IR
and RI below), and italics again in running roman text when
referring to the variant material.
* xargs/xargs.1: Do the above.
Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html
Copyright-paperwork-exempt: Yes
* xargs/xargs.1: Also set the braces in `-I{}` in bold, not roman,
since they are literal.
The `lq` and `rq` strings are widely portable.
groff_man_style(7):
Strings
\*(lq
\*(rq interpolate special character escape sequences for left and
right double‐quotation marks, \(lq and \(rq, respectively.
...
A contemporary man page needs none of the above. \*S is
superfluous; type size changes are invisible on terminals, and
macros that change it restore its original value afterward. Better
alternatives exist for the rest; simply use the \[rg], \[lq],
\[rq], and \[tm] special character escape sequences directly.
Unless you are aiming for a pathological level of portability——
perhaps composing a man page for consumption on simulators of 1980s
Unix systems (or Solaris 10 troff, though even it supports
“\(rg”)——avoid using the above strings.
...
Notes
Some tips on composing and troubleshooting your man pages follow.
...
• When and how should I use quotation marks?
As noted above in subsection “Font style macros”, apply quotation
marks to “brief specimens of literal text, such as article
titles, inline examples, mentions of individual characters or
short strings, and (sub)section headings in man pages”. Multi‐
word literals, such as Unix commands with arguments, when set
inline (as opposed to displayed between EX and EE), should be
quoted to ensure that the boundaries of the literal are clear
even when the material is stripped of font styling by, for
example, copy‐and‐paste operations. groff, Heirloom Doctools
troff, neatroff, and mandoc support all of the special characters
\[oq], \[cq], \[lq], \[rq], \[aq], and \[dq] described in
subsection “Portability” above. DWB, Plan 9, and Solaris 10
troffs do not. Interpolating the strings \*(lq and \*(rq
portably yields directional double quotation marks, if available,
in all these formatters (though neatroff does not supply a man
macro package), but they cannot reliably be used in macro
arguments.
Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html
Copyright-paperwork-exempt: Yes
...for consistency with existing practice in findutils man pages.
* xargs/xargs.1: Set "find" (the command) and "-print0" in bold, not roman.
Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html
Copyright-paperwork-exempt: Yes
Warnings from `groff -C -ww -man` in the forthcoming groff 1.24:
troff:xargs/xargs.1:295: warning: an escaped '~' is not portable to AT&T troff
troff:xargs/xargs.1:296: warning: an escaped '~' is not portable to AT&T troff
troff:xargs/xargs.1:296: warning: an escaped '~' is not portable to AT&T troff
troff:xargs/xargs.1:298: warning: an escaped '~' is not portable to AT&T troff
groff_man_style(1):
Portability
...
\~ Adjustable non‐breaking space. Use this escape sequence
to prevent a break inside a short phrase or between a
numerical quantity and its corresponding unit(s).
Before starting the motor,
set the output speed to\~1.
There are 1,024\~bytes in 1\~KiB.
CSTR\~#8 documents the B\~language.
\~ is a GNU extension also supported by Heirloom Doctools
troff 050915 (September 2005), mandoc 1.9.14
(2009‐11‐16), neatroff (commit 1c6ab0f6e, 2016‐09‐13),
and Plan 9 from User Space troff (commit 93f8143600,
2022‐08‐12), but not by DWB or Solaris 10 troffs.
* xargs/xargs.1:
Define a string to indirect use of `\~` escape sequence. On formatters
that don't support groff extensions, use the AT&T troff `\ `
(backslash-space) escape sequence, which isn't quite as good because it
is a space that is not only unbreakable, but unadjustable--which,
however, doesn't matter when formatting man pages with adjustment
disabled, as some implementations do (and which groff makes
configurable).
Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html
Copyright-paperwork-exempt: Yes
The `\(en` special character escape sequence is not universally
portable. Indirect it through a string definition.
* find/find.1:
* locate/locate.1:
* locate/locatedb.5:
* locate/updatedb.1:
* xargs/xargs.1: Do the above.
Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html
Copyright-paperwork-exempt: Yes
* 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
* find/find.1:
* xargs/xargs.1: Replace blank lines with empty requests or paragraphing
macro calls as seems to be intended.
* find/find.1: Delete blank lines preceding paragraphing or sectioning
macros that serve only to put excess vertical space in the output.
* locate/locatedb.5: Replace blank lines with a dummy character
producing a blank output line as _might_ be intended.
groff_man_style(7):
? The empty request (.), which does nothing, vertically spaces the
input file for readability by the document maintainer. Do not
put blank (empty) lines in a man page source document. Some
man(1) programs ?squeeze? multiple blank output lines into one.
Fixes style warnings from `groff -rCHECKSTYLE=3 -man`:
an.tmac:/.../share/man/man1/find.1:87: style: blank line in input
...
an.tmac:/.../share/man/man1/xargs.1:231: style: blank line in input
...
an.tmac:/.../share/man/man5/locatedb.5:118: style: blank line in input
...
Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html
Copyright-paperwork-exempt: Yes
Style warnings from `groff -rCHECKSTYLE=3 -man`.
an.tmac:/.../share/man/man1/locate.1:1: style: .TH missing third argument; \
consider document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:/.../share/man/man1/locate.1:1: style: .TH missing fourth argument; \
consider package/project name and version (e.g., "groff 1.23.0")
...and similar.
groff_man_style(7):
.TH identifier section [footer‐middle [footer‐inside [header‐
middle]]]
...
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.
* find/find.1:
* locate/locate.1:
* locate/locatedb.5:
* locate/updatedb.1:
* xargs/xargs.1: Add appropriate third and fourth arguments to `TH` macro calls.
To determine the revision date to include in the page, I used the Git
"AuthorDate" of the last commit consituting anything but a "bump" to the
copyright notice.
Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-11/msg00094.html
Copyright-paperwork-exempt: Yes
Run 'make update-copyright'.
* lib/regexprops.c (copying): Update the year number manually.
* tests/sample-test: Adjust to use the single most recent year.
* All other files: Update copyright years via the above make run.
From a suggestion by G. Branden Robinson to use `groff -t -z -ww
-rCHECKSTYLE=2 -man`, by pointing to and example in
https://lists.gnu.org/archive/html/bug-findutils/2025-11/msg00004.html.
* configure.ac: discover the location of the groff binary.
* build-aux/man-lint.sh: also run groff with -rCHECKSTYLE=2. Use
groff at the path discovered during configuration.
* find/Makefile.am: Lint-check manpages during "make check",
not "make dist". Set the environment variable GROFF to the
location of the groff binary.
* locate/Makefile.am: Likewise.
* xargs/Makefile.am: Likewise.
As reported in <https://savannah.gnu.org/bugs/?67432>, it is easy to
confuse -0 with -O. Give a hint to translators.
* xargs/xargs.c (main): Add TRANSLATORS hints.
* bootstrap.conf (gnulib_modules): Add nullptr.
In code, prefer nullptr to NULL where either will do.
* cfg.mk (sc_prohibit_NULL): Direct to use nullptr instead.
(begword, endword): Add regex helper macros.
Use standard input instead of stdin, standard output instead of stdout,
and standard error instead of stderr in messages and documentation.
Inspired by coreutils commit:
https://cgit.git.sv.gnu.org/cgit/coreutils.git/commit/?id=c9a30d6781
* cfg.mk (sc_standard_outputs): Add syntax-check rule.
* doc/find.texi: Do the above.
* find/find.1: Likewise.
* locate/locate.1: Likewise.
* locate/locate.c: Likewise.
* xargs/xargs.1: Likewise.
* xargs/xargs.c: Likewise.
* xargs/xargs.c (usage): Fix synopsis by wrapping COMMAND in '[...]',
because it is in fact optional. Also add a sentence that the default
COMMAND is 'echo'.
The gnulib/NEWS file states:
SAFE_READ_ERROR and SAFE_WRITE_ERROR are now
obsolescent; callers can just check for < 0.
* xargs/xargs.c (xargs_do_exec): Adjust error handling of safe_read
accordingly.
Run 'make update-copyright'.
* lib/regexprops.c (copying): Update the year number manually.
* tests/sample-test: Adjust to use the single most recent year.
* All other files: Update copyright years via the above make run.
Like in the recent commit, also change the following variables to follow
the renaming done in gnulib:
- LIB_SETLOCALE_NULL -> SETLOCALE_NULL_LIB,
- LIB_MBRTOWC -> MBRTOWC_LIB,
- LIB_EACCESS -> EUIDACCESS_LIBGEN.
* find/Makefile.am (LDADD): Change as described above.
* lib/Makefile.am: Likewise.
* locate/Makefile.am: Likewise.
* xargs/Makefile.am: Likewise.
* locate/Makefile.am (LDADD): Remove $(LIB_CLOSE) as it is no longer
required per Gnulib NEWS 2009-03-20.
* xargs/Makefile.am (LADD): Likewise.
* find/Makefile.am (LDADD): Likewise. Change $(LIB_EACCESS) to
$(EUIDACCESS_LIBGEN) per Gnulib NEWS 2023-01-07.
The forthcoming Issue 8 of the POSIX standard includes find -print0
and xargs -0.
* doc/find.texi: find -print0 is no longer GNU-specific. Similarly
for xargs -0.
* xargs/xargs.1: Likewise.
* NEWS: mention these changes.
While we do use the gnulib safe_read function, we read input from
stdin using stdio, not direct Unix syscalls, so safe_read is not
involved.
* xargs/xargs.c: If a stdin read fails with EINTR, do it again. Use
SA_RESTART when setting up signal handlers. This fixes Savannah
bug #64442.
If the user uses -P we're not using only POSIX options, so in that
case it is OK to handle SIGUSR1/2. Otherwise (without -P) don't
handle these signals, meaning that they could cause xargs to
terminate.
* xargs/xargs.c: set signal handlers for SIGUSR1 and SIGUSR2 only if
the -P option was used. Warn if SIGUSR1 or SIGUSR2 is not defined.
* tests/xargs/test-sigusr: a new test for this.
* tests/local.mk: build and run the new test.
* NEWS: mention these changes.
* xargs/xargs.c: fix Savannah bug #64451 (xargs -P exits before all
children have exited if one exits with status 255).
* xargs/xargs.1 (BUGS): mention this bug and the corrected behaviour.
* doc/find.texi: Likewise.
* NEWS: mention this bugfix.
Run 'make update-copyright'.
* lib/regexprops.c (copying): Update the year number manually.
* tests/sample-test: Adjust to use the single most recent year.
* All other files: Update copyright years via the above make run.
The long option --replace it not deprecated, only the short form.
* xargs/xargs.1: Clarify the above better by explicitly mentioning
the short -i form.
Now that Gnulib's 'error' module does proper static checking
for not returning, we need no longer use the 'die' macro.
This makes code easier to read for people that are used to 'error'.
* cfg.mk (sc_die_EXIT_FAILURE): Remove.
* src/die.h: Remove. All includes removed. All calls to 'die'
changed back to calls to 'error'.
* lib/Makefile.am (libfind_a_SOURCES): Remove 'die.h'.
* src/system.h: Include error.h. Stop including error.h elsewhere.
* find/ftsfind.c (process_all_startpoints): Avoid extra '\n' in error
diagnostics wrt/ -files0-from. Also avoid redundant "%s" formats.
* find/parser.c (parse_perm, parse_regex):
* lib/buildcmd.c (bc_push_arg):
Wrap calls to 'error' in block when under an if-condition and either
the if-condition or the 'error' invocation is spanning over more
than one line.
* find/tree.c (get_pred_cost): Make error message translatable - found
by sc_unmarked_diagnostics.
Not in the patch.
Output from "mandoc -T lint xargs.1":
mandoc: xargs.1:1:2: WARNING: missing date, using "": TH
#######
Change '-' (\-) to '\(en' (en-dash) for a numeric range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
xargs.1:393:if any invocation of the command exited with status 1-125
xargs.1:518:Copyright \(co 1990-2023 Free Software Foundation, Inc.
#####
Change (or include a "FIXME" paragraph about) misused SI (metric)
numeric prefixes (or names) to the binary ones, like Ki (kibi), Mi
(mebi), Gi (gibi), or Ti (tebi), if indicated.
If the metric prefixes are correct, add the definitions or an
explanation to avoid misunderstanding.
254:more than 128KiB, 128Kib is used as the default value; otherwise, the
255:default value is the maximum. 1KiB is 1024 bytes.
#####
Reduce space between words.
51:prevents such problems. When using this option you will need to
94:command. Multibyte characters are not supported.
466:internally. This means that there is an upper limit on the length
492:a line which is longer than it can handle. This is not an ideal
#####
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-
268:.BR --no-run-if-empty )
#####
Change - to \- if it shall be printed as a minus sign.
xargs.1:393:if any invocation of the command exited with status 1-125
xargs.1:518:Copyright \(co 1990-2023 Free Software Foundation, Inc.
#####
Change a HYPHEN-MINUS (code 0x55, 2D) to a minus (\-), if in front of a
name for an option.
234:.BR -t .
248:.BI -s " max-chars\fR, \fI" \-\-max\-chars "=\fImax-chars\fR"
#####
Wrong distance between sentences.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
51:prevents such problems. When using this option you will need to
94:command. Multibyte characters are not supported.
316:are mutually exclusive. If some of them are specified at the same
466:internally. This means that there is an upper limit on the length
492:a line which is longer than it can handle. This is not an ideal
#####
Do not use more than two space characters between sentences or (better)
only a new line character.
51:prevents such problems. When using this option you will need to
94:command. Multibyte characters are not supported.
466:internally. This means that there is an upper limit on the length
492:a line which is longer than it can handle. This is not an ideal
#####
Not in the patch.
Output from "test-nroff -man -b -ww -z":
[ "test-groff" is a developmental version of "groff" ]
Input file is ./xargs.1
Output from test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z :
an.tmac:/tmp/chk_manuals.temp.ZC2PK6:1: style: .TH missing third argument;\
suggest document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:/tmp/chk_manuals.temp.ZC2PK6:1: style: .TH missing fourth argument;\
suggest package/project name and version (e.g., "groff 1.23.0")
####
* xargs/xargs.1: Change as described above.
* xargs/xargs.1 (--show-limits): Remove redundant backslash character,
introduced when adding the description of that option in commit
956992ff71b3 in 2005.
* doc/find.texi (node xargs options): Add description of the "--"
option delimiter.
* xargs/xargs.1 (OPTIONS): Likewise.
* NEWS (Documentation Changes): Document the change.
Suggested by Dan Jacobson <jidanni@jidanni.org> in
<https://lists.gnu.org/r/bug-findutils/2023-04/msg00009.html>
