On 19/01/2026 18:59, Pádraig Brady wrote:
On 19/01/2026 18:52, Egmont Koblinger wrote:
(Just wondering: How feasible would it be to add a "make check" step
that verify that all the anchors from every --help output are indeed
defined in the documentation?)
Oh right. I'll have a look at doing that.
That was well worth doing,
as it found various new and old gaps in the manual.
I'll apply the attached patch set later,
the last of which adds the test you mentioned.
thanks,
Padraig.
From f0e16541b3b3580e6eccc27aa6d1009a31b16018 Mon Sep 17 00:00:00 2001
From: Egmont Koblinger <[email protected]>
Date: Mon, 19 Jan 2026 22:13:07 +0000
Subject: [PATCH 1/8] doc: tty: fix indexing in texinfo
* doc/coreutils.texi: Fix recently introduced typo.
---
doc/coreutils.texi | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 5d40ee21a..fb628a3fb 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -15374,9 +15374,9 @@ The program accepts the following option. Also see @ref{Common options}.
@table @samp
-@optItem{printenv,-s,}
-@optItemx{printenv,--silent,}
-@optItemx{printenv,--quiet,}
+@optItem{tty,-s,}
+@optItemx{tty,--silent,}
+@optItemx{tty,--quiet,}
Print nothing; only return an exit status.
@end table
--
2.52.0
From 72774aa2f59ce35e641620b62b37a6b58a326213 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Tue, 20 Jan 2026 17:37:42 +0000
Subject: [PATCH 2/8] doc: more indexing fixes in manual
* doc/coreutils.texi: Add missing anchors.
* src/pr.c (Usage): Adjust to use -COLS, to avoid a clash
with the additional anchor added to the manual.
Also markup the --columns option as done for other options.
* tests/split/line-bytes.sh: Also fix --lines-bytes typo here.
---
doc/coreutils.texi | 24 ++++++++++++++++--------
src/pr.c | 8 +++++---
tests/split/line-bytes.sh | 4 ++--
3 files changed, 23 insertions(+), 13 deletions(-)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index fb628a3fb..b31c49d05 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -2293,6 +2293,8 @@ The program accepts the following options. Also see @ref{Common options}.
@optAnchor{base32,-w}
@optAnchor{base32,--wrap}
+@optAnchor{basenc,-w}
+@optAnchor{basenc,--wrap}
@optItem{base64,-w,@w{ }@var{cols}}
@optItemx{base64,--wrap,=@var{cols}}
@cindex wrap data
@@ -2305,6 +2307,8 @@ disable line wrapping altogether.
@optAnchor{base32,-d}
@optAnchor{base32,--decode}
+@optAnchor{basenc,-d}
+@optAnchor{basenc,--decode}
@optItem{base64,-d,}
@optItemx{base64,--decode,}
@cindex Decode base64 data
@@ -2315,6 +2319,8 @@ output will be the original data.
@optAnchor{base32,-i}
@optAnchor{base32,--ignore-garbage}
+@optAnchor{basenc,-i}
+@optAnchor{basenc,--ignore-garbage}
@optItem{base64,-i,}
@optItemx{base64,--ignore-garbage,}
@cindex Ignore garbage in base64 stream
@@ -2628,6 +2634,7 @@ is identical. By default, counting starts with the first page of input
file (not first page printed). Line numbering may be altered by @option{-N}
option.
+@optAnchor{pr,-COLS}
@optItem{pr,-@var{column},}
@optItemx{pr,--columns,=@var{column}}
@cindex down columns
@@ -3296,7 +3303,7 @@ Put @var{size} bytes of @var{input} into each output file.
@multiplierSuffixes{size}
@optItem{split,-C,@w{ }@var{size}}
-@optItemx{split,--lines-bytes,=@var{size}}
+@optItemx{split,--line-bytes,=@var{size}}
Put into each output file as many complete lines of @var{input} as
possible without exceeding @var{size} bytes. Individual lines or records
longer than @var{size} bytes are broken into multiple files.
@@ -5402,6 +5409,9 @@ Columns are separated by a single TAB character.
@c FIXME: when there's an option to supply an alternative separator
@c string, append "by default" to the above sentence.
+@optAnchor{comm,-1}
+@optAnchor{comm,-2}
+@optAnchor{comm,-3}
@opindex -1
@opindex -2
@opindex -3
@@ -6308,7 +6318,7 @@ a b c
@end example
@optItem{paste,-d,@w{ }@var{delim-list}}
-@optItemx{paste,--delimiter,=@var{delim-list}}
+@optItemx{paste,--delimiters,=@var{delim-list}}
Consecutively use the characters in @var{delim-list} instead of
TAB to separate merged lines. When @var{delim-list} is
exhausted, start again at its beginning.
@@ -7319,7 +7329,7 @@ The program accepts the following options. Also see @ref{Common options}.
@table @samp
-@optItem{expand,@w{ }@var{tab1}[@comma{}@var{tab2}]@dots{},}
+@optItem{expand,-t,@w{ }@var{tab1}[@comma{}@var{tab2}]@dots{}}
@optItemx{expand,--tabs,=@var{tab1}[@comma{}@var{tab2}]@dots{}}
@cindex tab stops, setting
If only one tab stop is given, set the tabs @var{tab1} spaces apart
@@ -7385,7 +7395,7 @@ The program accepts the following options. Also see @ref{Common options}.
@table @samp
-@optItem{unexpand,@w{ }@var{tab1}[@comma{}@var{tab2}]@dots{},}
+@optItem{unexpand,-t,@w{ }@var{tab1}[@comma{}@var{tab2}]@dots{}}
@optItemx{unexpand,--tabs,=@var{tab1}[@comma{}@var{tab2}]@dots{}}
If only one tab stop is given, set the tabs @var{tab1} columns apart
instead of the default 8. Otherwise, set the tabs at columns
@@ -11293,10 +11303,8 @@ Do not act on symbolic links themselves but rather on what they point to.
This is the default when not operating recursively.
@warnOptDerefWithRec
-@item -h
-@itemx --no-dereference
-@opindex -h
-@opindex --no-dereference
+@optItem{\cmd\,-h,}
+@optItemx{\cmd\,--no-dereference,}
@cindex symbolic links, changing owner
@findex lchown
Act on symbolic links themselves instead of what they point to.
diff --git a/src/pr.c b/src/pr.c
index d76a2c39f..569441167 100644
--- a/src/pr.c
+++ b/src/pr.c
@@ -2777,11 +2777,13 @@ Paginate or columnate FILE(s) for printing.\n\
fputs (_("\
+FIRST_PAGE[:LAST_PAGE], --pages=FIRST_PAGE[:LAST_PAGE]\n\
begin [stop] printing with page FIRST_[LAST_]PAGE\n\
- -COLUMN, --columns=COLUMN\n\
- output COLUMN columns and print columns down, unless -a is used.\n\
- Balance number of lines in the columns on each page\n\
"), stdout);
oputs (_("\
+ -COLS, --columns=COLS\n\
+ output COLS columns and print columns down, unless -a is used.\n\
+ Balance number of lines in the columns on each page\n\
+"));
+ oputs (_("\
-a, --across\n\
print columns across rather than down, used together with -COLUMN\n\
"));
diff --git a/tests/split/line-bytes.sh b/tests/split/line-bytes.sh
index b03343c94..2fbf1226d 100755
--- a/tests/split/line-bytes.sh
+++ b/tests/split/line-bytes.sh
@@ -1,5 +1,5 @@
#!/bin/sh
-# test -C, --lines-bytes
+# test -C, --line-bytes
# Copyright (C) 2013-2026 Free Software Foundation, Inc.
@@ -84,7 +84,7 @@ for b in $(seq 10); do
compare no_eol_splits_exp no_eol_splits || fail=1
done
-# Test hold buffer management with --lines-bytes.
+# Test hold buffer management with --line-bytes.
# The following triggers (with ASAN) a heap overflow issue
# between coreutils 9.2 and 9.4 inclusive.
printf '%131070s\n' '' >expaa || framework_failure_
--
2.52.0
From 841da474d2d772939798c230edf30013645b0e2c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Tue, 20 Jan 2026 17:40:34 +0000
Subject: [PATCH 3/8] doc: id: document -a in manual
* doc/coreutils.texi (id invocation): Mention this option is ignored.
---
doc/coreutils.texi | 3 +++
1 file changed, 3 insertions(+)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index b31c49d05..6a9fc5438 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -15455,6 +15455,9 @@ The options cause @command{id} to print only part of the above information.
Also see @ref{Common options}.
@table @samp
+@optItem{id,-a,}
+Ignored; for compatibility with other versions of @command{id}.
+
@optItem{id,-g,}
@optItemx{id,--group,}
Print only the group ID.
--
2.52.0
From 1ec611d839abaad6bd36c3ad1d2137fa58b80f89 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Tue, 20 Jan 2026 17:43:32 +0000
Subject: [PATCH 4/8] doc: who: document --users in manual
* doc/coreutils.texi (who invocation): Mention that --users
is equivalent to -u.
* src/who.c (usage): Mention -u shows idle time.
---
doc/coreutils.texi | 3 ++-
src/who.c | 2 +-
2 files changed, 3 insertions(+), 2 deletions(-)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 6a9fc5438..cea9efb84 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -15707,7 +15707,7 @@ Overrides all other options.
Print the current (and maybe previous) run-level of the init process.
@optItem{who,-s,}
-@optItem{who,--short,}
+@optItemx{who,--short,}
Ignored; for compatibility with other versions of @command{who}.
@optItem{who,-t,}
@@ -15715,6 +15715,7 @@ Ignored; for compatibility with other versions of @command{who}.
Print last system clock change.
@optItem{who,-u,}
+@optItemx{who,--users,}
@cindex idle time
After the login time, print the number of hours and minutes that the
user has been idle. @samp{.} means the user was active in the last minute.
diff --git a/src/who.c b/src/who.c
index dbf67297f..65c9e6788 100644
--- a/src/who.c
+++ b/src/who.c
@@ -679,7 +679,7 @@ Print information about users who are currently logged in.\n\
-T, -w, --mesg add user's message status as +, - or ?\n\
"));
oputs (_("\
- -u, --users list users logged in\n\
+ -u, --users list users logged in, including idle time\n\
"));
oputs (_("\
--message same as -T\n\
--
2.52.0
From 518b3cd70f1b1eb0a47fd1e9844e5af7f81e2696 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Tue, 20 Jan 2026 18:58:40 +0000
Subject: [PATCH 5/8] doc: ls: document --block-size in the manual
* doc/coreutils.texi (ls invocation): Document --block-size
---
doc/coreutils.texi | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index cea9efb84..261cb69df 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -7731,6 +7731,12 @@ Inhibit display of group information in long format.
(This is the default in some non-GNU versions of @command{ls}, so we
provide this option for compatibility.)
+@optItem{ls,--block-size,=@var{size}}
+@cindex file sizes
+With @option{-l}, scale sizes by @var{size} before printing them
+(@pxref{Block size}). For example,
+@option{--block-size=G} prints sizes in units of 1,073,741,824 bytes.
+
@optHumanReadable{ls}
@optItem{ls,-i,}
--
2.52.0
From e050220907ad8b85c8d99a69240a5462b8ff9b87 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Tue, 20 Jan 2026 19:11:40 +0000
Subject: [PATCH 6/8] doc: cp: document --keep-directory-symlink in correct
location
* src/cp.c (usage): Move to alphabetically in list.
* doc/coreutils.texi (mv invocation): Move description from here ...
(cp invocation): ... to here.
---
doc/coreutils.texi | 12 ++++++------
src/cp.c | 8 ++++----
2 files changed, 10 insertions(+), 10 deletions(-)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 261cb69df..34f1b775f 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -8835,6 +8835,12 @@ Copy symbolic links as symbolic links rather than copying the files that
they point to. This option affects only symbolic links in the source;
symbolic links in the destination are always followed if possible.
+@optItem{cp,--keep-directory-symlink,}
+Follow existing symlinks to directories when copying.
+Use this option only when the destination directory's contents are trusted,
+as an attacker can place symlinks in the destination
+to cause @command{cp} write to arbitrary target directories.
+
@optItem{cp,-p,}
@optItemx{cp,--preserve,[=@var{attribute_list}]}
@cindex file information, preserving, extended attributes, xattr
@@ -10019,12 +10025,6 @@ option is also specified.
@optItemx{mv,--verbose,}
Print the name of each file before moving it.
-@optItem{mv,--keep-directory-symlink,}
-Follow existing symlinks to directories when copying.
-Use this option only when the destination directory's contents are trusted,
-as an attacker can place symlinks in the destination
-to cause @command{cp} write to arbitrary target directories.
-
@optStripTrailingSlashes{mv}
@optBackupSuffix{mv}
diff --git a/src/cp.c b/src/cp.c
index 278f7cd34..fa464f2c4 100644
--- a/src/cp.c
+++ b/src/cp.c
@@ -225,6 +225,10 @@ Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.\n\
oputs (_("\
-P, --no-dereference\n\
never follow symbolic links in SOURCE\n\
+"));
+ oputs (_("\
+ --keep-directory-symlink\n\
+ follow existing symlinks to directories\n\
"));
oputs (_("\
-p\n\
@@ -291,10 +295,6 @@ Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.\n\
oputs (_("\
-v, --verbose\n\
explain what is being done\n\
-"));
- oputs (_("\
- --keep-directory-symlink\n\
- follow existing symlinks to directories\n\
"));
oputs (_("\
-x, --one-file-system\n\
--
2.52.0
From 212841fa3160638172422e18d78808202c912f38 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Tue, 20 Jan 2026 19:23:42 +0000
Subject: [PATCH 7/8] doc: cp: group related -HLP descriptions
* src/cp (usage): The -HLP options are close
in functionality and close alphabetically, so describe together.
* doc/coreutils.texi (cp invocation): Likewise.
---
doc/coreutils.texi | 38 +++++++++++++++++++-------------------
src/cp.c | 16 ++++++++--------
2 files changed, 27 insertions(+), 27 deletions(-)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 34f1b775f..4a098e24e 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -8794,12 +8794,6 @@ This option is independent of the @option{--interactive} or
This option is ignored when the @option{--no-clobber} or @option{-n} option
is also used.
-@optItem{cp,-H,}
-If a command line argument specifies a symbolic link, then copy the
-file it points to rather than the symbolic link itself. However,
-copy (preserving its nature) any symbolic link that is encountered
-via recursive traversal.
-
@optItem{cp,-i,}
@optItemx{cp,--interactive,}
When copying a file other than a directory, prompt whether to
@@ -8807,9 +8801,11 @@ overwrite an existing destination file, and fail if the response
is not affirmative. The @option{-i} option overrides
a previous @option{-n} option.
-@optItem{cp,-l,}
-@optItemx{cp,--link,}
-Make hard links instead of copies of non-directories.
+@optItem{cp,-H,}
+If a command line argument specifies a symbolic link, then copy the
+file it points to rather than the symbolic link itself. However,
+copy (preserving its nature) any symbolic link that is encountered
+via recursive traversal.
@optItem{cp,-L,}
@optItemx{cp,--dereference,}
@@ -8818,16 +8814,6 @@ With this option, @command{cp} cannot create a symbolic link.
For example, a symlink (to regular file) in the source tree will be copied to
a regular file in the destination tree.
-@optItem{cp,-n,}
-@optItemx{cp,--no-clobber,}
-Do not overwrite an existing file; silently skip instead.
-This option overrides a previous @option{-i} option.
-This option is mutually exclusive with @option{-b} or @option{--backup} option.
-This option is deprecated due to having a different exit status from
-other platforms. See also the @option{--update} option which will
-give more control over how to deal with existing files in the destination,
-and over the exit status in particular.
-
@optItem{cp,-P,}
@optItemx{cp,--no-dereference,}
@cindex symbolic links, copying
@@ -8841,6 +8827,20 @@ Use this option only when the destination directory's contents are trusted,
as an attacker can place symlinks in the destination
to cause @command{cp} write to arbitrary target directories.
+@optItem{cp,-l,}
+@optItemx{cp,--link,}
+Make hard links instead of copies of non-directories.
+
+@optItem{cp,-n,}
+@optItemx{cp,--no-clobber,}
+Do not overwrite an existing file; silently skip instead.
+This option overrides a previous @option{-i} option.
+This option is mutually exclusive with @option{-b} or @option{--backup} option.
+This option is deprecated due to having a different exit status from
+other platforms. See also the @option{--update} option which will
+give more control over how to deal with existing files in the destination,
+and over the exit status in particular.
+
@optItem{cp,-p,}
@optItemx{cp,--preserve,[=@var{attribute_list}]}
@cindex file information, preserving, extended attributes, xattr
diff --git a/src/cp.c b/src/cp.c
index fa464f2c4..e17484b5d 100644
--- a/src/cp.c
+++ b/src/cp.c
@@ -209,18 +209,10 @@ Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.\n\
oputs (_("\
-H\n\
follow command-line symbolic links in SOURCE\n\
-"));
- oputs (_("\
- -l, --link\n\
- hard link files instead of copying\n\
"));
oputs (_("\
-L, --dereference\n\
always follow symbolic links in SOURCE\n\
-"));
- oputs (_("\
- -n, --no-clobber\n\
- (deprecated) silently skip existing files. See also --update\n\
"));
oputs (_("\
-P, --no-dereference\n\
@@ -229,6 +221,14 @@ Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.\n\
oputs (_("\
--keep-directory-symlink\n\
follow existing symlinks to directories\n\
+"));
+ oputs (_("\
+ -l, --link\n\
+ hard link files instead of copying\n\
+"));
+ oputs (_("\
+ -n, --no-clobber\n\
+ (deprecated) silently skip existing files. See also --update\n\
"));
oputs (_("\
-p\n\
--
2.52.0
From ee85bb367d78230b5c781113181ed94d3affb597 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Tue, 20 Jan 2026 19:27:49 +0000
Subject: [PATCH 8/8] tests: ensure there is an anchor for each --help option
* tests/misc/usage_vs_refs.sh: A new test to correlation options
listed in --help, and anchors referenced in the texinfo (html) manual.
* tests/local.mk: Add the new test.
---
tests/local.mk | 1 +
tests/misc/usage_vs_refs.sh | 71 +++++++++++++++++++++++++++++++++++++
2 files changed, 72 insertions(+)
create mode 100755 tests/misc/usage_vs_refs.sh
diff --git a/tests/local.mk b/tests/local.mk
index 4bae33c6e..607901c6a 100644
--- a/tests/local.mk
+++ b/tests/local.mk
@@ -495,6 +495,7 @@ all_tests = \
tests/tty/tty.sh \
tests/misc/usage_vs_getopt.sh \
tests/misc/getopt_vs_usage.sh \
+ tests/misc/usage_vs_refs.sh \
tests/unexpand/unexpand.pl \
tests/unexpand/bounded-memory.sh \
tests/uniq/uniq.pl \
diff --git a/tests/misc/usage_vs_refs.sh b/tests/misc/usage_vs_refs.sh
new file mode 100755
index 000000000..48965b931
--- /dev/null
+++ b/tests/misc/usage_vs_refs.sh
@@ -0,0 +1,71 @@
+#!/bin/sh
+# Verify that all supported options have references in docs
+
+# Copyright (C) 2026 Free Software Foundation, Inc.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+. "${srcdir=.}/tests/init.sh"; path_prepend_ ./src
+
+# Currently only check short opts with corresponding long opt
+shortopts() { getopts $1 | cut -s -d"'" -f2; }
+longopts() { getopts $1 | cut -s -d'"' -f2; }
+
+getopts() {
+ skip='--help|--version' # These refs treated specially
+
+ HELP_NO_MARKUP=1 env "$1" --help |
+ grep -E '^( -| --)' | # find options
+ grep -Ev -- " - |-M.*from first" | # exclude invalid matches
+ sed -e 's/^ *//' -e's/ .*//' | # strip leading space and descriptions
+ tr ' ' '\n' | # split to one per line
+ sed -n 's/^\(--\?[^,=[]*\).*/\1/p' | # Remove parameters
+ grep -Ev -- "$skip" # These refs treated specially
+}
+
+for prg in $built_programs; do
+
+ dprg=$prg
+ test $prg = ginstall && dprg=install
+ test $prg = '[' && dprg=test
+ test $prg = 'dir' && dprg=ls
+ test $prg = 'vdir' && dprg=ls
+ test $prg = 'md5sum' && dprg=cksum
+ test $prg = 'b2sum' && dprg=cksum
+ test $prg = 'sha1sum' && dprg=cksum
+ test $prg = 'sha224sum' && dprg=cksum
+ test $prg = 'sha256sum' && dprg=cksum
+ test $prg = 'sha384sum' && dprg=cksum
+ test $prg = 'sha512sum' && dprg=cksum
+
+ test "$DEBUG" && echo processing $sprg
+ got_option=false
+ for opt in $(getopts $prg); do
+ got_option=true
+ if ! grep -E "opt(Itemx?|Anchor){$dprg,$opt[,}]" \
+ $abs_top_srcdir/doc/coreutils.texi >/dev/null; then
+ if ! grep "optItemx\\?{\\\\cmd\\\\,$opt," \
+ $abs_top_srcdir/doc/coreutils.texi >/dev/null; then
+ printf -- '%s %s reference missing in texi\n' $dprg $opt >&2
+ fail=1
+ elif test "$DEBUG"; then
+ echo "only matched $dprg $opt in a general macro"
+ fi
+ fi
+ done
+ test "$DEBUG" && test $got_option = false && echo No options for $prg ?
+
+done
+
+Exit $fail
--
2.52.0
