I pushed the attached version which defines a more general @optItem macro.
Then I pushed a further (large/boring so not attached), to use that macro
to add an anchor/index to each command option description,
while also reducing the texinfo source file by over 1000 lines.
https://github.com/coreutils/coreutils/commit/796b8d1a6
cheers,
Padraig
From cc3499326fc088b93bb67dddfcba9e71516883b1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Thu, 27 Nov 2025 20:45:44 +0000
Subject: [PATCH 1/2] doc: html: support defined anchors for command options
* doc/coreutils.texi (optAnchor): A new macro to output a
referencable anchor, called from ...
(optItem): ... here; a new macro to output all index entries
for each option item.
(optZero,optZeroTerminated): Show an example of the adjustment
done to each option description.
* doc/local.mk (html-local): Post-process the texinfo generated HTML
(`make html`) to remove our "-option" tag, and replace all
escaped _002d with a standard hyphen, which is fine in URLs.
---
doc/coreutils.texi | 32 ++++++++++++++++++++++----------
doc/local.mk | 10 ++++++++++
2 files changed, 32 insertions(+), 10 deletions(-)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 71fb01649..84102725a 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -568,6 +568,22 @@ manuals for textutils, fileutils, and sh-utils to produce the present
omnibus manual. Richard Stallman contributed his usual invaluable
insights to the overall process.
+@macro optAnchor{command,option}
+@anchor{\command\-option\option\}
+@end macro
+
+@macro optItem{command,option,param}
+@optAnchor{\command\,\option\}
+@item \option\\param\
+@opindex \option\
+@end macro
+
+@macro optItemx{command,option,param}
+@optAnchor{\command\,\option\}
+@itemx \option\\param\
+@opindex \option\
+@end macro
+
@node Common options
@chapter Common options
@@ -628,19 +644,15 @@ output even when that output would contain data with embedded newlines.
@outputNUL
@end macro
-@macro optZero
-@item -z
-@itemx --zero
-@opindex -z
-@opindex --zero
+@macro optZero{cmd}
+@optItem{\cmd\,-z}
+@optItemx{\cmd\,--zero}
@outputNUL
@end macro
-@macro optZeroTerminated
-@item -z
-@itemx --zero-terminated
-@opindex -z
-@opindex --zero-terminated
+@macro optZeroTerminated{cmd}
+@optItem{\cmd\,-z}
+@optItemx{\cmd\,--zero-terminated}
@cindex process zero-terminated items
Delimit items with a zero byte rather than a newline (ASCII LF).
I.e., treat input as items separated by ASCII NUL
diff --git a/doc/local.mk b/doc/local.mk
index 3a46e0820..da5d21240 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -131,3 +131,13 @@ sc-lower-case-var:
$(PERL) -lne $(find_upper_case_var) $(texi_files)
check-local: check-texinfo
+
+# Post-process generated HTML to clean up anchor IDs
+_sed_anchor_cleanup = \
+ -e '/id=.*_002doption/ { s/id="\([^"]*\)_002doption/id="\1/g; s/_002d/-/g; }'
+html-local:
+ $(AM_V_GEN)htmlfile=$(info_TEXINFOS:.texi=.html); \
+ sed $(_sed_anchor_cleanup) $$htmlfile > $$htmlfile-t \
+ && mv $$htmlfile-t $$htmlfile
+
+.PHONY: html-local
--
2.51.1
