From: Pádraig Brady <P@draigBrady.com>
Date: Thu, 27 Nov 2025 20:45:44 +0000 (+0000)
Subject: doc: html: support defined anchors for command options
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cc3499326fc088b93bb67dddfcba9e71516883b1;p=thirdparty%2Fcoreutils.git

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.
---

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 71fb016497..84102725a5 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 3a46e08204..da5d21240d 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