2698 Commits

Author SHA1 Message Date
G. Branden Robinson
3d398b07cd doc: improve typography of synopses
* find/find.1:
* locate/locate.1: Place thin space escape sequences between ellipsis
  dots for more pleasant output when typesetting.

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

Copyright-paperwork-exempt: Yes
2026-01-05 16:52:58 +01:00
G. Branden Robinson
7e8712f0ca 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
2026-01-05 16:52:58 +01:00
G. Branden Robinson
fe5b98b247 find.1: use AT&T troff-compatible syntax
Before and after, using DWB 3.3 troff (Plan 9 and Solaris 10 troffs are
similar):

  $ diff -U0 find.1.dwb-[12].txt|head -n 19
  --- find.1.dwb-1.txt    2025-10-13 10:09:17.024054824 -0500
  +++ find.1.dwb-2.txt    2025-10-13 10:09:24.764012282 -0500
  @@ -2039 +2039 @@
  -            [bu]
  +            o   Find files named core in or below the directory /tmp and
  @@ -2054 +2053,0 @@
  -                Find files named core in or below the directory /tmp and
  @@ -2064,2 +2063 @@
  -            [bu]
  -                Find files named core in or below the directory /tmp and
  +            o   Find files named core in or below the directory /tmp and
  @@ -2080,2 +2078 @@
  -            [bu]
  -                Given that another program proggy pre-filters and cre-
  +            o   Given that another program proggy pre-filters and cre-
  @@ -2097,2 +2094 @@
  -            [bu]
  -                Run file on every file in or below the current direc-
  +            o   Run file on every file in or below the current direc-

Further changes in the diff appear because the document now paginates
differently with these troffs.  That's because a one-en-wide mark 'o'
(the ASCII representation of a bullet) fits within the 4n space allotted
by the document's `IP` calls, whereas "[bu]" does not.

Fixes warnings from "nroff -C -ww -man" in the forthcoming groff 1.24:
troff:./find/find.1:2260: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2277: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2305: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2326: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2349: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2372: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2392: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2402: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2415: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2431: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2442: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2459: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2471: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2498: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2542: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2597: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2618: warning: an escaped '[' is not portable to AT&T troff
troff:./find/find.1:2630: warning: an escaped '[' is not portable to AT&T troff

* find/find.1: Replace '\[bu]' by '\(bu'.

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

Copyright-paperwork-exempt: Yes
2026-01-05 16:52:58 +01:00
G. Branden Robinson
ad7e34650a doc: delete blank lines from man page sources
* 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
2026-01-05 16:52:37 +01:00
G. Branden Robinson
d1edc59b19 find.1: fix typo in *roff syntax
Style warning from `groff -rCHECKSTYLE=3 -man`:
an.tmac:/.../share/man/man1/find.1:9: style: 1 leading space(s) on input line

* find/find.1 (SYNOPSIS): Make an intended empty request work that way.

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

Copyright-paperwork-exempt: Yes
2026-01-02 22:48:58 +01:00
G. Branden Robinson
627072f022 doc: populate man pages' headers and footers more
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
2026-01-02 22:48:58 +01:00
G. Branden Robinson
2749632838 find.1: drop unportable tbl(1) 'x' modifier
Plan 9 and Solaris tbl, like Seventh Edition Unix tbl, do not support
the 'x' column modifier.  This extension appeared in DWB tbl by version
3.3 and early in GNU troff development (both circa 1990).  I suspect,
but do not know, that other System V Unix tbl programs don't support it
either.

These old tbl programs are brutal when they encounter an unsupported
column modifier--they abort the preprocessor altogether ("tbl quits")
without attempting recovery.[1]  Because tbl works as a filter, like
eqn, pic, soelim, or more familiar Unix tools (cat, sed, nl), this means
that tbl truncated the entire remainder of the input at that point.  GNU
tbl is more robust, and discards input only until the next `.TE` token.

Due to this rudeness it's impossible to portably use 'x' without
rewriting the page text, and I know of no good way to parameterize a
table format.  (tbl(1) doesn't have variables or anything like a macro
preprocessor.  *roff strings are no use because tbl is a _pre_processor
for troff.)

To portably use 'x' requires a man page to test the underlying
implementation and potentially rewrite the page prior to installing it.

See a recent patch of mine to ncurses (merged in its 20251115 release)
for an approach potentially adaptable to findutils.

https://lists.gnu.org/archive/html/bug-ncurses/2025-11/msg00035.html

[1] I've proposed a merge request to Plan 9 from User Space to make its
    tbl less intolerant.  Even if accepted, that won't help anyone who
    uses other "legacy" troffs.

    https://github.com/9fans/plan9port/pull/739

* find/find.1 (Functional Changes): Drop 'x' table modifier.

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

Copyright-paperwork-exempt: Yes
2026-01-02 22:48:58 +01:00
Bernhard Voelker
04738593b4 find: add more -mount tests (check-root)
Add some more tests exercising bind mounts on the same device which
should not be affected by -mount or -xdev, and tests with a loopback
file system and a bind mount from there.

* tests/find/mount-vs-xdev-bind.sh: Add test.
* tests/find/mount-vs-xdev-other-fs.sh: Likewise.
* tests/local.mk (all_root_tests): Reference them.
2026-01-02 22:36:44 +01:00
Bernhard Voelker
0d8de87299 find: add -mount tests
* tests/find/mount-vs-xdev.sh: Add test.
* tests/local.mk (sh_tests): Reference it.
2026-01-02 22:36:42 +01:00
Bernhard Voelker
6da3a73f73 NEWS: enhance description about the -mount change
* NEWS (Changes in find): Clarify better what is the difference between
the -mount and -xdev options including an example.  Also move the
topic to the top of the section due to its importance.
2026-01-02 22:35:49 +01:00
Lukáš Zaoral
cd8568758a find: make -mount POSIX 2024 compliant
* find/defs.h (struct options): Add mount member and rename
stay_on_filesystem to xdev.
* find/ftsfind.c (find): Set FTS_MOUNT flag when -mount is enabled.
* find/parser.c (parse_table): Use a separate parser for -mount.
(parse_mount): Declare and define function.
(parse_xdev): Use xdev option flag.
* find/util.c (set_option_defaults): Initialize new struct members.
* doc/find.texi (node Filesystems): Add new section describing the new
behaviour of -mount and specify the current behaviour of -xdev.
* find/find.1: Document the new -mount behaviour and specify current
behaviour of -xdev.
* NEWS (Changes in find): Mention the -mount behaviour change.
2026-01-02 11:48:31 +01:00
Bernhard Voelker
733bb9a054 maint: update copyright year number ranges
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.
2026-01-02 11:46:15 +01:00
Bernhard Voelker
e69e78fb1d maint: update gnulib to latest
Run 'make update-gnulib-to-latest'; there have been 135 commits on gnulib
since the last update.
This is mainly for the following change making sc_copyright_check pass
again, but there are also other useful fixes and improvements:
  > maint: run 'make update-copyright'

* gnulib: Update to latest.
* autogen.sh: Likewise.
* autopull.sh: Likewise.
* bootstrap: Likewise.
* bootstrap-funclib.sh: Likewise.
2026-01-02 11:45:58 +01:00
James Youngman
580be65e25 [find] Format findutils changes as reverse-time-ordered tables.
* find/find.1 (COMPATIBILITY): Add release-year information to the
feature addition table.  Format the functional changes as a table,
too.
2025-11-18 09:49:21 +00:00
James Youngman
99cfb6cf42 [maint] Stricter manpage checks.
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.
2025-11-17 10:08:13 +00:00
James Youngman
c9a2aaa354 [find] Fix a lint problem in the find manual page.
Without this fix, we get this error from `groff -C -t -z -ww
-rCHECKSTYLE=2 -man find/find.1`:

troff: find/find.1:2255: warning: macro '."' not defined
troff: find/find.1:2255: warning: number register '[' not defined

* find/find.1: revert a change which caused a lint warning from
  troff.
2025-11-17 10:08:13 +00:00
James Youngman
8821923b49 [find] Use ASCII apostrophe in find.1 (instead of U+2019).
* find/find.1: Use ASCII apostrophe U+0027 instead of U+2019.
2025-11-17 10:08:13 +00:00
Bernhard Voelker
7156420fab maint: switch from gnulib ctype to ctype-h module
Prompted by the following bootstrap notice:
  Notice from module ctype:
    This module is deprecated. Use the module 'ctype-h' instead.

* bootstrap.conf (gnulib_modules): ctype -> ctype-h
2025-11-15 19:44:18 +01:00
Bernhard Voelker
bccc4f8a28 maint: update gnulib to latest
Run 'make update-gnulib-to-latest'; there have been 450 commits on gnulib
since the last update.

This pulls in the new FTS_MOUNT flag needed for the upcoming changes
to -mount vs. -xdev mandated by POSIX Issue 8 (IEEE Std 1003.1-2024),
thanks to Lukáš Zaoral <lzaoral@redhat.com>:
> fts: Introduce the FTS_MOUNT flag.

* gnulib: Update to latest.
* bootstrap-funclib.sh: Likewise.
2025-11-15 19:44:13 +01:00
Bernhard Voelker
c78d103e81 parser.c: simplify parse_table
Avoid macro preprocessing when filling the parse_table for better
readability.

* find/parser.c (PASTE, PARSE_OPTION, PARSE_POSOPT, PARSE_TEST,
PARSE_TEST_NP, PARSE_ACTION, PARSE_PUNCTUATION): Remove macros.
(parse_table): Replace macro-based filling with regular structure entries.
Group entries by types: regular options, positional options, punctuation,
tests and actions; loosely sort within each group.
Remove duplicate "atime" entry introduced in commit 7102a229fa.
While at it, change -help and -version from ARG_TEST to ARG_OPTION.
2025-11-15 19:43:35 +01:00
Bernhard Voelker
aa292af4c1 maint: help translators to disambiguate -0 as --null, not option "o"
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.
2025-11-15 19:39:43 +01:00
Bernhard Voelker
9e505ec52f maint: add entry to .gitignore file
* po/.gitignore (/insert-header.sed): Add.
2025-11-15 19:39:43 +01:00
Bernhard Voelker
93ce19f0d5 maint: prefer C23-style nullptr
* 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.
2025-11-15 19:39:43 +01:00
Bernhard Voelker
499e792fc0 maint: do not produce DVI-format manual anymore
The GNU standards don't require DVI-format documentation anymore:
https://lists.gnu.org/archive/html/bug-standards/2025-07/msg00011.html

* build-aux/update-online-manual.sh: Remove DVI format.
* doc/.gitignore: Remove ignore entries for DVI files.
2025-11-15 19:39:43 +01:00
Bernhard Voelker
deb3f7066d maint: use consistent references to standard files in messages
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.
2025-11-15 19:39:43 +01:00
Bernhard Voelker
c41a617953 doc: clarify that POSIX Issue 8 is "IEEE Std 1003.1-2024"
* doc/find.texi: Do the above in various places.
* find/find.1:  Likewise.
* xargs/xargs.1: Likewise.
2025-11-15 19:39:43 +01:00
Bernhard Voelker
56a376a26d doc: state that POSIX from Issue 8 specifies 'find -iname'
* doc/find.texi (-iname): Document POSIX compliance.
* find/find.1 (COMPATIBILITY): Mark POSIX compliance of -iname.
2025-11-15 19:39:43 +01:00
Collin Funk
c18bba5c59 maint: ensure that new "make syntax-check"-run sc_codespell passes
* cfg.mk (codespell_ignore_words_list): Ignore false-positives.
(exclude_file_name_regexp--sc_codespell): Skip some file names.
* NEWS: Fix typos.
* README-hacking: Likewise.
* doc/find-maint.texi: Likewise.
* doc/find.texi: Likewise.
* bootstrap.conf: Fix typos in comments.
* find/ftsfind.c: Likewise.
* find/parser.c: Likewise.
* find/print.c: Likewise.
* find/testsuite/find.gnu/exec-one-rtn-fail.exp: Likewise.
* find/testsuite/find.posix/bracket-depth.exp: Likewise.
* find/testsuite/find.posix/exec-nogaps.exp: Likewise.
* find/testsuite/find.posix/files-not-expressions1.exp: Likewise.
* find/testsuite/find.posix/files-not-expressions2.exp: Likewise.
* find/testsuite/find.posix/files-not-expressions3.exp: Likewise.
* find/util.c: Likewise.
* init.cfg: Likewise.
* lib/regextype.h: Likewise.
* lib/splitstring.h: Likewise.
* locate/locate.c: Likewise.
* locate/updatedb.sh: Likewise.
* tests/find/exec-plus-last-file.sh: Likewise.
* tests/find/files0-from.sh: Likewise.
* tests/xargs/test-sigusr.c: Likewise.
* tests/xargs/verbose-quote.sh: Likewise.
* xargs/xargs.c: Likewise.
2025-11-15 19:39:02 +01:00
James Youngman
0cac25f6e7 doc: minor shell coding improvements in examples.
- Use -type f so that the timestamp of `subdir` is not relevant.
- Use LC_ALL=C with sort, tail, cut (as file names are not text).
- Use "$(...)" instead of just $(...).

Also mention that Issue 8 of the POSIX standard has been published
now.
2025-10-15 05:55:05 +01:00
James Youngman
cabfc3b184 find: point out that -newer is false when timestamps are equal. 2025-10-15 05:55:05 +01:00
Bernhard Voelker
74d25ac58d find: document -newerXY in --help output
* find/util.c (usage): Add above find(1) option, and briefly explain
that XY stands for the combination [aBcm][aBcmt].
2025-10-13 22:15:09 +02:00
Bernhard Voelker
1c39dc6055 find: fix minor typo in --help output
* find/util.c (usage): Terminate sentence about -D with a dot.
(show_valid_debug_options): While at it, add indentation for -D values.
2025-10-13 22:12:01 +02:00
danny mcClanahan
fbbda507c6 doc: fix typo in symbolics links node
* doc/find.texi (node Symbolic Links): s/directoires/directories/
* find/testsuite/find.gnu/execdir-hier.exp: Likewise here in a comment.

Copyright-paperwork-exempt: Yes
2025-08-24 14:19:50 +02:00
Bernhard Voelker
facc27e180 doc: regenerate regexprops.texi
* doc/regexprops.texi: Regenerate due to recent changes in gnulib regex.h
to align with current Emacs behavior (gnulib commit efd5c380ff), and also
due to the change of the node sort order in regextype.c in the previous
commit.

Reported by Collin Funk in
  https://lists.gnu.org/r/bug-gnulib/2025-07/msg00037.html
2025-07-09 20:53:21 +02:00
Bernhard Voelker
c9c2c51175 regexprops: sort regex_map alphabetically
Commit '1b53838ddf' has changed the order of the nodes, yet not
quite well.  Let's use alphabetical sort order.

* lib/regextype.c (regex_map): Move 'awk' and 'egrep' entries up.
2025-07-09 20:49:51 +02:00
Bernhard Voelker
c7f5ff1ed8 maint: update gnulib to latest
Run 'make update-gnulib-to-latest'; there have been 645 commits on gnulib
since the last update.

* gnulib: Update to latest.
* bootstrap: Likewise.
* bootstrap-funclib.sh: Likewise.
2025-07-09 08:55:51 +02:00
Bernhard Voelker
acd4564eda doc: reference -newer for -anewer,-cnewer in find.1
* find/find.1 (-anewer): Reference the similarity to -newer.
(-cnewer): Likewise.

Discussed at:
  https://sv.gnu.org/bugs/?67220
2025-07-01 19:38:20 +02:00
raf
1ef8d7c2cf doc: supplement list of actions that suppress default -print
* find/find.1 (EXPRESSION): Add missing -print0 and -fprint0 to
the list of actions that suppress the default -print action.
Sort items.
* doc/find.texi (find Expressions): Likewise.
* NEWS: Mention the fix.
2025-04-18 13:01:22 +02:00
Bernhard Voelker
bad1de52aa NEWS: mention the previous doc fixes
* NEWS (Documentation Changes): Describe the fix done by the two
previous commits.
2025-04-18 13:01:08 +02:00
Bernhard Voelker
97b8920482 doc: fix the "Finding the Shallowest Instance" example in find.1
* find/find.1 (EXAMPLES): Fix the Pruning SCM example by changing the
attribution of the list from "Sample output" to "Sample directories".
The wrong attribution was made in commit v4.7.0-76-g9302afb9.
Then, add the output for clarity.

Fixes https://sv.gnu.org/bugs/?62259
2025-04-18 13:00:07 +02:00
raf
45530ee875 doc: fix the "Finding the Shallowest Instance" example in Texinfo manual
* doc/find.texi (Finding the Shallowest Instance): Add surrounding \(
and \) around the 3x -exec actions to correctly group them with higher
priority than the implicit '-a' for the following '-print'.  Otherwise,
only the SCM roots matching the last test, "CVS", would be printed.
Improve indentation of the multi-line command.
Add sample output for clarity.
While at it, fix a minor typo.

This bug was present since adding that example in 2008.
The very same issue was already fixed for the man page in commit
v4.6.0-55-g47d8fd38.

Fixes https://sv.gnu.org/bugs/?62259
2025-04-18 12:56:23 +02:00
Bernhard Voelker
ee500667d4 tests: add case for passing -files0-from multiple times
Passing -files0-from several times silently overrides the previously given
file names, and only takes the last one.  This behavior is quite common
and has precedence e.g. in 'du --files0-from ...'.
Add a test to document the current behavior.

* tests/find/files0-from.sh: Add a test passing -files0-from 3 times.

Discussed at:
  https://sv.gnu.org/bugs/?66965
2025-04-06 16:49:12 +02:00
Bernhard Voelker
8e1331d8a7 NEWS: document the previous fixes in find.1
* NEWS (Documentation Changes): Mention the change of the previous commit.
2025-03-25 22:40:37 +01:00
Bjarni Ingi Gislason
2be6812e01 find.1: some remarks and editing fixes in the man page
Reported at:
  https://lists.gnu.org/r/bug-findutils/2025-03/msg00002.html

Output from "mandoc -T lint  find.1": (shortened list)

      1 input text line longer than 80 bytes: Some of the conversi...
      1 missing date, using "": TH
      1 unterminated quoted argument

-.-.

Output from "test-nroff -mandoc -t -ww -z find.1": (shortened list)

      1 	Use macro '.B' for one argument or split argument.
      1 	Use macro '.I' for one argument or split argument.
      1 .BR is for at least 2 arguments, got 1
      1 .IR is for at least 2 arguments, got 1

-.-.

Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.

73:until an expression argument comes (which also starts with a `-').
74:Now, if a path argument would start with a `-', then
875:An exception to this is when using only a slash as \fIpattern\fR (`-name /'),
878:A warning is issued if you try to pass a pattern containing a - but not
879:consisting solely of one - slash, unless the environment variable
1095:The + and - prefixes signify greater than and less than, as usual;
1832:find / -name needle -print -quit
2252:.SS Safer `find -print0 | xargs -0` approach
2324:.SS Traversing the filesystem just once - for 2 different actions
2473:Pruning - omitting files and subdirectories
2590:.B $ find / -name needle -print -quit
2607:.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\en'
2654:.B find -print0
2656:.B xargs -0
2743:find: possible unquoted pattern after predicate `-name'?

-.-.

Add a "\&" (or a comma (Oxford comma)) after "e.g." and "i.e.",
or use English words
(man-pages(7)).
Abbreviation points should be marked as such and protected against being
interpreted as an end of sentence, if they are not, and that independent
of the current place on the line.

546:and e.g. from a pipe.
565:The processing of the starting points is otherwise as usual, e.g.

-.-.

Wrong distance (not two spaces) between sentences in the input file.

  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.

Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.

  The amount of space between sentences in the output can then be
controlled with the ".ss" request.

Mark a final abbreviation point as such by suffixing it with "\&".

Some sentences (etc.) do not begin on a new line.

Split (sometimes) lines after a punctuation mark; before a conjunction.

  Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.

Use

sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\.  */\1.\n/g' $1

to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"

[List of affected lines removed.]

-.-.

Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.

Line 1546, length 86

Some of the conversion specification characters might not be available on all systems,

Line 2487, length 82

.B $ find . \-name .snapshot \-prune \-o \e( \e! \-name \(aq*~\(aq \-print0 \e) \e

Line 2607, length 96

.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\en'

Line 2645, length 87

.I A Research UNIX Reader: Annotated Excerpts from the Programmer’s Manual, 1971-1986

-.-.

Use \(en (en-dash) for a dash at the beginning (end) of a line,
or between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.

find.1:2324:.SS Traversing the filesystem just once - for 2 different actions
find.1:2473:Pruning - omitting files and subdirectories

-.-.

Remove reverse slash (\) in front of a period (.) that is to be printed
as such, and can not come a control character in the first column of a line.
Use "\&" to protect the period to avoid that.
This is a sign, that the man page was transformed from another source
file with a program, whose name is NOT mentioned in a comment.

2715:\.B \-perm +MODE
2717:\.B \-perm

-.-.

Split a punctuation mark from a single argument for a two-font macro

1048:.IR ./fubar3,

-.-.

Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".

[List of affected lines removed.]

-.-.

One space only after an end of sentence.

find.1:339:no error message will be issued. This is the reason why such operation
find.1:546:and e.g. from a pipe.
find.1:960:find . \-path \(dq./sr*sc\(dq
find.1:1797:find . \-path ./src/emacs \-prune \-o \-print
find.1:1896:.B find . \-name afile \-o \-name bfile \-print
find.1:2309:.B $ find . \-type f \-exec file \(aq{}\(aq \e;
find.1:2384:.B $ find . \-perm 664
find.1:2399:.B $ find . \-perm \-664
find.1:2413:.B $ find . \-perm /222
find.1:2423:.B $ find . \-perm /220
find.1:2424:.B $ find . \-perm /u+w,g+w
find.1:2425:.B $ find . \-perm /u=w,g=w
find.1:2440:.B $ find . \-perm \-220
find.1:2441:.B $ find . \-perm \-g+w,u+w
find.1:2452:.B $ find . \-perm \-444 \-perm /222 \e! \-perm /111
find.1:2453:.B $ find . \-perm \-a+r \-perm /a+w \e! \-perm /a+x
find.1:2467:.RB ( "! \-perm /111"
find.1:2469:.B ! \-perm /a+x
find.1:2487:.B $ find . \-name .snapshot \-prune \-o \e( \e! \-name \(aq*~\(aq \-print0 \e) \e
find.1:2607:.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\en'
find.1:2727:.B find . \-name afile \-o \-name bfile \-print
find.1:2731:.BR "find . \-name afile \-o \e( \-name bfile \-a \-print \e)" .
find.1:2741:.B $ find . \-name *.c \-print
find.1:2754:.B find . \-name frcode.c locate.c word_io.c \-print
find.1:2766:.B $ find . \-name \(aq*.c\(aq \-print
find.1:2767:.B $ find . \-name \e*.c \-print

-.-.

Put a subordinate sentence (after a comma) on a new line.

[List of affected lines removed.]

-.-.

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"

-.-.

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"

-.-.

Space after an end of sentence.

temp.table:25:\-exec ... +	4.2.12	POSIX

-.-.

Output from "test-groff  -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":

an.tmac:<stdin>:2: style: .TH missing third argument; consider document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:<stdin>:2: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.0")
an.tmac:<stdin>:690: misuse, warning: .BR is for at least 2 arguments, got 1
	Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:1048: misuse, warning: .IR is for at least 2 arguments, got 1
	Use macro '.I' for one argument or split argument.

-.-.

Additionally:

  Change "1\ KB" to "1\ KiB"

  Change indent "4m" to "4n".  "4m" is too wide in troff-mode.

  Inhibit hyphenation of "strftime" once (based on an A4 page size).

  Create a "space" between some tags and the its following text by adding
" \&" to the tag.

  Decrease indent after a bullet in lists.

Generally:

Split (sometimes) lines after a punctuation mark; before a conjunction.

* find/find.1: Change as described above.
2025-03-25 21:57:29 +01:00
Bernhard Voelker
f3a3833320 maint: remove declared-only find_pred_name
Only user was inside a an #ifdef DEBUG / #endif block.
Introduced with -context in commit v4.5.5-42-g1a05af6a.

* find/parser.c (parse_context): Remove #ifdef/#endif block.
* find/defs.h (find_pred_name): Remove declaration.
2025-03-25 20:12:40 +01:00
Bernhard Voelker
dc3365628e find: issue a warning for wrongly accepted operators like '-!'
In the current implementation, GNU find accepts the operators '!', ',',
'(' and ')' with a leading dash, e.g. '-!'.
Let's issue a warning to see if anyone relies on that odd behavior.
With a later release, let's fix the parser, and not accept these anymore.

* find/parser.c (find_parser): Issue a warning in the case one of the
above operators has been passed with a leading '-'.
* tests/find/operators-wrong-with-dash.sh: Add test.
* tests/local.mk (sh_tests): Reference it.
* NEWS (Changes in find): Mention the change in behavior.

Discussed at:
https://lists.gnu.org/r/bug-findutils/2025-03/msg00005.html
2025-03-23 23:47:15 +01:00
Collin Funk
faa1301368 tests: adjust shell syntax that breaks AIX /bin/sh
* find/testsuite/find.gnu/execdir-multiple.exp: Move the 'do' of a for
loop to the same line so AIX doesn't fail.
2025-01-26 18:18:57 +01:00
Bernhard Voelker
e5d6eb919b find: avoid crash when diagnosing a file system loop
When gnulib's FTS returns FTS_DC indicating a directory cycle, then the
struct member 'fts_cycle' is not guaranteed to contain valid data.
Avoid dereferencing it when diagnosing the file system loop.

* find/ftsfind.c (issue_loop_warning): Change the error message to avoid
mentioning the other entry involved in the loop anymore.
(partial_quotearg_n): Remove now-unused function.
* NEWS (Bug Fixes): Mention the fix.

Reported by Dietmar Hahn in
<https://lists.gnu.org/r/bug-findutils/2025-01/msg00013.html>
2025-01-26 18:17:10 +01:00
Bernhard Voelker
d44172075a pred.c: consolidate numerical comparisons
Several predicate tests perform a numerical comparison based on the
comparison_type (COMP_GT, COMP_LT, COMP_EQ).
Factor that out into a utility function.

* find/pred.c (compare_num): Add static function.
(pred_gid, pred_inum, pred_links, pred_size, pred_uid): Use it.
2025-01-06 21:43:57 +01:00
Bernhard Voelker
0c20228608 xargs: clarify command as optional in --help output
* 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'.
2025-01-05 22:32:46 +01:00