crtxcr/cgitsb
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

doc: use consistent id's when generating html files

Browse Source 
The html documentation is generated using a2x which calls docbook tools
to do the work.  The generate.consistent.ids parameter ensures that when
the docbook stylesheet assigns an id value to an output element it is
consistent as long as the document structure has not changed.

Having consistent html files reduces frivolous changes between builds.
Distributions can more easily deploy multiple architecture builds and
compare changes between package versions.  End-users avoid needless
changes in files deployed or backed up.

The generate.consistent.ids parameter was added in docbook-xsl-1.77.0.
Older versions gracefully ignore the parameter, so we can pass the
parameter unconditionally.  Most distributions contain docbook-xsl newer
than 1.77.0.  This includes Fedora, Debian, Ubuntu, and RHEL/CentOS 7.
RHEL/CentOS 6 and Debian Wheezy (old stable) ship with an older version,
unsurprisingly.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
This commit is contained in:
Todd Zullinger 2018-02-20 20:36:03 -05:00 committed by Jason A. Donenfeld
parent 03f6e34bb9
commit 33414d7869
1 changed files with 1 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Makefile
View File

@ -134,7 +134,7 @@ doc-pdf: $(DOC_PDF)
a2x -f manpage $< a2x -f manpage $<
$(DOC_HTML): %.html : %.txt $(DOC_HTML): %.html : %.txt
a2x -f xhtml --stylesheet=cgit-doc.css $< a2x -f xhtml --stylesheet=cgit-doc.css --xsltproc-opts="--param generate.consistent.ids 1" $<
$(DOC_PDF): %.pdf : %.txt $(DOC_PDF): %.pdf : %.txt
a2x -f pdf cgitrc.5.txt a2x -f pdf cgitrc.5.txt