Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
[dev.icinga.com #3193] add TOCs on chunked pages #352
This issue has been migrated from Redmine: https://dev.icinga.com/issues/3193
Created by mfriedrich on 2012-09-26 14:15:39 +00:00
basically, we have the foremost generic TOC on the title page, which is awesome.
but now, all the chunked html pages can be called on their very own, and we all know that those pages can be very long - e.g. quickstart idoutils or icinga web introduction (scroll your way to the administration section).
there's 2 TODOs in order to achieve html page specific TOCs
1.) overwrite the default section.toc.level (which is 0 by default, but globally enabled - see http://www.sagehill.net/docbookxsl/TOCcontrol.html#SectionTocs )
2.) put all sub sections into their according xml tags
2012-09-26 14:13:43 +00:00 by mfriedrich 21aa638
2012-10-09 12:10:38 +00:00 by mfriedrich ffbbe18
2012-10-09 16:10:43 +00:00 by mfriedrich 118ed4b
2012-10-10 01:20:35 +00:00 by mfriedrich 4155c11
2012-10-10 15:13:23 +00:00 by mfriedrich 1474070
2012-10-10 21:14:00 +00:00 by mfriedrich d06140f
2012-10-11 11:59:25 +00:00 by mfriedrich a965f7c
Updated by mfriedrich on 2012-10-09 01:48:13 +00:00
since we now had a quite huge TOC, mainly unreadable, i started to search for possible animated tocs, using some jquery, hiding the X.Y.Z sections in the first place.
first of all, i've removed the labels within the urls.
the section depths remains 2, otherwise docbook won't even create that, and we cannot work with the data.
this screenshot shows what i mean, but the action is required by yourself installing it. though, it requires the make architecture of core git 'next' as well.
Updated by mfriedrich on 2012-10-09 16:08:06 +00:00
some missing bits for future releases:
(same goes for the other quickstart guides as well)
furthermore - all sections should get their xml id. so that docbook will not output a number (which can change on every release, or docs creation, when the index changes), but a dedicated id string, which can then be used as page anchor to scroll down automagically.
i know that this is a pita, and will take a while, but given that, it will be the optimum you can get out of docbook (and it should have happened in the first place when converting the olg html to docbook either way).
Updated by Wolfgang on 2012-10-09 18:04:12 +00:00
"furthermore - all sections should get their xml id. so that docbook will not output a number (which can change on every release, or docs creation, when the index changes), but a dedicated id string, which can then be used as page anchor to scroll down automagically."
Well, maybe something is missing. Looking at "index.html" there is a number, looking at "ix01.html" -> "Acknowledgements" there is a string "about.html#acknowledgements".
Updated by mfriedrich on 2012-10-10 01:01:21 +00:00
ok, it seems that the title anchors just do not work for TOC generation. since we are nearly the same like postgresql now from the generation part, the following guess:
which is generated for the object.id template, when it comes to generic generation of unique item ids.
BUT - theidentifier is the the one which requires the id, and furthermore THIS is the one where the TOC looks for the reference then.
since we do not set any section ids, docbook xsltproc generates ones for us (the idp... anchors).
parsing that one, TOC finds the first a id, and ignores the second. this would explain why everything is linked against numbers in the chunked output pages, but nothing directly against anchors via the toc.
Updated by mfriedrich on 2012-10-10 01:03:56 +00:00
postgresql defines a section id, instead of a title anchor.
(i'm not saying that title anchors are bad - you can always click anchors in the wild, and reference that. only the toc urls do not take that into account).
Updated by mfriedrich on 2012-10-10 01:11:34 +00:00
i've tried with a small diff against about.xml
the toc looks correct for the first entry.
then the id below
as well as the main TOC
conlusion - all section title xml:ids need to be duplicated as id into sections as well.
Updated by mfriedrich on 2012-10-10 11:14:20 +00:00
the anchor xml:ids can and must be used for the INDEX, but for the SECTIONs with TOC, new ids must be inserted into the existing sections. since the section2-5 will remain inner anchors of chunked pages on level down, it's not necesssary to prefix these ids with the section1 name.
i'll work on these changes locally.
Updated by mfriedrich on 2012-10-10 14:15:13 +00:00
tbh section ids must be unique, that's true, so all of the section1 ids (like plugins, hostchecks, etc) cannot be reused for that, as xsltproc would warnin about non unique linkend ids.
though, that's easily resolvable by giving telling short names to those. for the english version this is nearly done now.
Updated by Wolfgang on 2012-10-10 17:26:00 +00:00
It looks as if anchors can be omitted in the title tags below a section if there is a section id:
The above example generates a valid toc and index.
Updated by mfriedrich on 2012-10-10 17:37:25 +00:00
true. it seems that there is sort of dpublication by these anchor titles - during my nightly research in the docbook documentation (which is an entire mess btw), i did not find many examples on the anchor xml:id .. only icinga git commits.
seems a unique section id will be the safest place for now, but if the anchors are duplicated or not ... well.
i will start porting the changes to the english section ids to the german version.
your opinion on that
Updated by mfriedrich on 2012-10-10 21:12:21 +00:00
sucessfully broke some references over the document - but i am tired, will continue fixing that tomorrow.
Updated by mfriedrich on 2012-10-11 17:08:23 +00:00
making this shiny, and resolved. will add a new section for "external commands list" to extcommands.xml in order to have that listed in the main TOC as well - what i desperately need the most.