[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