[boostbook] Building documentation with generate.consistent.ids

Daniel James via Boost-docs <[email protected]> Mon, 30 Oct 2017 15:00:37 +0000
Newsgroups gmane.comp.lib.boost.documentation
Message-ID <CAHOE3ydRrMHo3mpwkMo_5n4OQ-_Ey8JBg61yxqRAkiAF768hwg@mail.gmail.com>
Hi,

A while ago Gregor Jasny suggested building with the
generate.consistent.ids option to reduce the changes between snapshots
(as many elements in the documentation had random id numbers). I've
tried turning it on for the develop documentation build, and tweaked
boostbook a little to take advantage of it as well.

With this setting generated ids can change when the documentation is
edited, but not on every build. If you have standalone documentation
and you want to use this feature, you need to use
'<xsl:param>generate.consistent.ids=1' in the boostbook rule in your
jamfile.

This mainly affects boostbook reference documentation, such as:

http://www.boost.org/doc/libs/1_65_1/doc/html/boost/accumulators/as_feature_ta_idp421358304.html

This page gets a new location in every build. With consistent ids it
has the consistent, although admittedly uglier, URL:

http://www.boost.org/doc/libs/develop/doc/html/boost/accumulators/as_featu_1_3_2_6_2_7_1_1_1.html

The advantage is that this will only change when the accumulators
documentation is changed (btw. the text part of that url is probably
truncated more than it needs to be, I might try to fix that).

Other documentation won't be affected so much, as sections usually
have explicit ids (quickbook always generates them). An example where
a section doesn't is:

http://www.boost.org/doc/libs/1_65_1/doc/html/idp22435328-bb.html

I suggest you should probably add an explicit id to something like
that (I've done so in that case).

Daniel