[boost] [boostbook] Building documentation with generate.consistent.ids

Subject: [boost] [boostbook] Building documentation with generate.consistent.ids
From: Daniel James (dnljms_at_[hidden])
Date: 2017-10-30 21:54:08

Hi,

This was originally sent to the boost-docs list, but it doesn't seem
to be working, so I'm sending it here. Sorry if you receive it twice.

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