* 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.
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.
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 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.
* 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.
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>
* cfg.mk (sc_prohibit_unhyphenated_eof): Add syntax-check rule.
* doc/find.texi: Change "end of file" to "end-of-file" in several places.
* xargs/xargs.1: Likewise.
* xargs/xargs.c (eof_str): Change comment to adhere to the new rule.
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.
Run 'make update-copyright'.
* lib/regexprops.c (copying): Update the year number manually.
The format of the copyright year number range in Texinfo files is
"YEAR1--YEAR2" now, i.e., with 2x '-'.
* tests/sample-test: Adjust to use the single most recent year.
* All other files: Update copyright years via the above make run.
The default command changed from '/bin/echo' to 'echo' in version 4.5.11,
but the commit 804ff7b90e only adjusted the Texinfo manual.
* xargs/xargs.1 (.SH DESCRIPTION): Change the default command here
in the man page as well.
* xargs/xargs.c (warn_mutually_exclusive): Add function to output the
new warning diagnostic.
(main): Call the above new function in order to show a warning message
if conflicting options (-L -l -I -i -n) are specified.
* xargs/xargs.1: Explicitly document the fact that -L -l -I -i -n
options are mutually exclusive and how xargs behaves when more than one
of these options are specified.
* doc/find.texi (node Conflicting xargs options): Likewise, add this
section with examples.
* xargs/testsuite/config/unix.exp (xargs_start): Replace the full path
of the xargs executable in the stderr output file by its basename.
* xargs/testsuite/xargs.gnu/P3-n1-IARG.xe: Add file containing the
expected output with the new warning diagnostic.
* xargs/testsuite/xargs.posix/L2-n2.xe: Likewise.
* xargs/testsuite/xargs.posix/rc-123.xe: Likewise.
* xargs/testsuite/xargs.sysv/l1n4.xe: Likewise.
* xargs/testsuite/xargs/testsuite/xargs.gnu/P3-n1-IARG.exp: Ensure the
error diagnostic is in C locale to avoid false positives in other locales.
* xargs/testsuite/xargs.posix/L2-n2.exp: Likewise.
* xargs/testsuite/xargs.posix/rc-123.exp: Likewise.
* xargs/testsuite/xargs.sysv/l1n4.exp: Likewise.
* tests/xargs/conflicting_opts.sh: Add test coverage for combinations
of the mutually exclusive options -I -L and -n.
* xargs/testsuite/Makefile.am (EXTRA_DIST_EXP): Reference the new tests.
(EXTRA_DIST_XO): Reference the new *.xo files.
(EXTRA_DIST_XE): Reference the new *.xe files.
* NEWS (Improvements): Mention the change.
Co-authored-by: Bernhard Voelker <mail@bernhard-voelker.de>
Discussed at https://savannah.gnu.org/bugs/?52137
Duplicate of https://savannah.gnu.org/bugs/?58156
Run 'make update-copyright'.
* lib/regexprops.c (copying): Update the year number manually.
The format of the copyright year number range in Texinfo files is
"YEAR1--YEAR2" now, i.e., with 2x '-'.
* tests/sample-test: Likewise, here to avoid starting a year number range.
* All other files: Update copyright years via the above make run.
The "BUGS" section also documented how to report bugs. This is better
done in a separate "REPORTING BUGS" section. Add this section where
missing. In it, redirect the user to the "How to get help" section
("#get-help") of the GNU findutils online page; also mention where
to report translation issues.
Bring the sections "SEE ALSO" and "COPYRIGHT" into the correct order,
which is: "REPORTING BUGS", "COPYRIGHT" and finally "SEE ALSO".
See 'man-pages(7)'.
The "SEE ALSO" section now refers to both the corresponding node in
the online HTML version of the Texinfo manual and lists the 'info' command.
Sort the entries referring to other man pages: first by their manual
section numbers, then alphabetically.
While at it, add an empty line (directive '.') before all '.SH' section
headers.
* find/find.1: Do the above.
* locate/locate.1: Likewise.
* locate/locatedb.5: Likewise.
* locate/updatedb.1: Likewise.
* xargs/xargs.1: Likewise.
Run 'make update-copyright'.
* lib/regexprops.c (copying): Update the year number manually.
* tests/sample-test: Likewise, here to avoid starting a year number range.
* All other files: Update copyright years via the above make run.
Run 'make update-copyright'.
* lib/regexprops.c (copying): Update the year number manually.
* All other files: Update copyright years via the above make run.
Run 'make update-copyright'.
* lib/regexprops.c (copying): Update the year number manually.
* All other files: Update copyright years via the above make run.
* doc/find.texi (Multiple Files): Mention the new --open-tty option
to be used as an alternative.
(Safe File Name Handling): Likewise.
* xargs/xargs.1 (EXAMPLES): Remove the tty redirection example.
This option is available in the xargs implementation of FreeBSD, NetBSD,
OpenBSD and in the Apple variant. Add it for compatibility.
* xargs/xargs.c (open_tty): Add static flag for the new option.
(longopts): Add member.
(main): Handle the 'o' case in the getopt_long() loop.
(prep_child_for_exec): Redirect stdin of the child to /dev/tty when
the -o option is given. Furthermore, move the just-opened file
descriptor to STDIN_FILENO.
(usage): Document the new option.
* bootstrap.conf (gnulib_modules): Add dup2.
* xargs/xargs.1 (SYNOPSIS): Replace the too-long list of options by
"[options]" - they are listed later anyway.
(OPTIONS): Document the new option.
(STANDARDS CONFORMANCE): Mention that the -o option is an extension.
* doc/find.texi (xargs options): Document the new option.
(Invoking the shell from xargs): Amend the explanation of the
redirection example with a note about the -o option.
(Viewing And Editing): Likewise.
(Error Messages From xargs): Add the message when dup2() fails.
(NEWS): Mention the new option.
Fixes http://savannah.gnu.org/bugs/?51151
* doc/find.texi (node Controlling Parallelism): s/ouptut/output/
* xargs/xargs.1: Likewise.
* find/util.c (cleanup): While at it, fix the same typo here
in a comment, too.
Copyright-paperwork-exempt: Yes
* xargs/xargs.c (__STDC_LIMIT_MACROS): Define __STDC_LIMIT_MACROS
in order to ensure that <stdint.h> defines the SIG_ATOMIC_MAX
macro, which we need.
(MAX_PROC_MAX): Define this as the maximum allowed value of
proc_max.
(main): Show the value of MAX_PROC_MAX for --show-limits.
(increment_proc_max): Don't increment proc_max beyond
MAX_PROC_MAX.
(parse_num): Fix small error in the error message; if the limit on
the value of a command-line argument is N, explain that the user
should specify a value <= N, not < N.
* xargs/xargs.1: Document the upper limit on --max-procs.
* doc/find.texi (Controlling Parallelism): Document the upper
limit on the amount of parallelism.
(xargs options): Document the limit on the value you can specify
for --max-procs.
* xargs/xargs.1: Update the description of -e option to emphasize
that the argument must follow the option letter immediately (in
other words, that it may not appear in the next program argument).
Likewise for the the -i and -l (lower-case L) options.
* xargs/xargs.c (usage): Minor consistency improvements to help
text.
* find/find.1 (SEE ALSO): Explain how to invoke info to read the
Texinfo manual.
* locate/locate.1 (SEE ALSO): Likewise.
* locate/updatedb.1 (SEE ALSO): Likewise.
* xargs/xargs.1 (SEE ALSO): Likewise.
* xargs/xargs.1: Expand on the warning about sharing stdout for
"xargs -P".
* doc/find.texi (Controlling Parallelism): Add a suitable warning
about sharing resources here, too.
* NEWS: Mention that all relevant documentation was updated with
this warning.
* xargs/xargs.1 (-P option): Add a note that it is the duty of the
called processes to access shared resources like stdout properly to
avoid undetermined results like mangled output.
Reported by Congshi Huang in http://sv.gnu.org/bugs/?38356.
* xargs/xargs.1: Update documentation for -d option to more
clearly distinguish the treatment of backslashes in the input and
the treatment of backslashes in the argument to -d.
* NEWS: Mention this bugfix.
* xargs/xargs.c (set_slot_var): New function; sets an environment
variable to the index of the entry in pids[] that represents the
relevant child process. This can be used in rudimentary load
distribution systems.
(slot_var_name): the name of the variable to use (selected by
--process-slot-var).
(enum LongOptionIdentifier): Unique identifiers for long options
with no short option equivalent (--process-slot-var is the first).
(longopts): Add --process-slot-var.
(add_proc): return the index within pids[] that we selected.
(main): Pass &option_index to getopt_long (option_index is a new
variable) in order to identify which long option was passed.
Handle --process-slot-var.
(prep_child_for_exec): Call set_slot_var.
(usage): Mention --process-slot-var.
* doc/find.texi (xargs options): Document --process-slot-var.
* xargs/xargs.1: Likewise.
* NEWS: Mention this change.
Signed-off-by: James Youngman <jay@gnu.org>
* xargs/xargs.1: Re-order the options to place them in
alphabetical order.
* xargs/xargs.c (usage): Describe the options in alphabeitcal
order.
* NEWS: Mention this change.
