[dev.icinga.com #3193] add TOCs on chunked pages

[icinga-migration]

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

Assignee: mfriedrich
Status: Resolved (closed on 2012-10-11 17:08:23 +00:00)
Target Version: 1.8
Last Update: 2012-10-11 17:08:27 +00:00 (in Redmine)

---

basically, we have the foremost generic TOC on the title page, which is awesome.

http://www.sagehill.net/docbookxsl/TOCcontrol.html
as well as controlling the depth with

2

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

2.) put all sub sections into their according xml tags

• sections
• xml anchors
• indexes

    Host definition

...

    
      Host Definition
    

    
      Object Definitions

      Host

1. is easy, but 2. will require deep down rewrites of the existing chunked pages, which can be messy. that would generally be the goal for 1.9 rather.

Attachments

• docs_1.8_section_toc.png mfriedrich - 2012-09-26 20:07:29 +00:00
• icinga_docs_1.8_javascript_toc_x.y.z_sections.png mfriedrich - 2012-10-09 01:48:13 +00:00

Changesets

2012-09-26 14:13:43 +00:00 by mfriedrich 21aa638

add TOCs on chunked pages, by sections refs #3193

this only adds the docbook directive, the sections and anchors
themselves must be provided by local page edits as described
in the issue.

refs #3193

2012-10-09 12:10:38 +00:00 by mfriedrich ffbbe18

toc: fix for jquery toggle when clicked on x.y section url

refs #3193

2012-10-09 16:10:43 +00:00 by mfriedrich 118ed4b

remove label of ido2db in db_components (only xml id is valid and required)

refs #3193

2012-10-10 01:20:35 +00:00 by mfriedrich 4155c11

section id example for TOC #name linking

refs #3193

2012-10-10 15:13:23 +00:00 by mfriedrich 1474070

add section ids to all english parts for non-generated ids by name in new TOCs refs #3193

2012-10-10 21:14:00 +00:00 by mfriedrich d06140f

german docs with named section ids, removed xml anchors where possible, broke some stuff (TODO)

https://dev.icinga.org/issues/3193#note-22

refs #3193

2012-10-11 11:59:25 +00:00 by mfriedrich a965f7c

fix all changed section ids incorrectly linkend'ed (refs #3193)

[icinga-migration]

Updated by mfriedrich on 2012-09-26 20:07:29 +00:00

• File added docs_1.8_section_toc.png

[icinga-migration]

Updated by Wolfgang on 2012-09-29 11:41:12 +00:00

• Status changed from New to Assigned
• Assigned to set to Wolfgang

[icinga-migration]

Updated by Wolfgang on 2012-09-30 14:33:19 +00:00

• Done % changed from 0 to 30

commit d805a61 in wnieder/toc

[icinga-migration]

Updated by Wolfgang on 2012-10-01 22:01:13 +00:00

• Done % changed from 30 to 40

commits 9f0e50b, f422c90, 50e6e65 in wnieder/toc

[icinga-migration]

Updated by Wolfgang on 2012-10-03 13:01:58 +00:00

• Done % changed from 40 to 60

commit 3e104e5
commit 44c507c

[icinga-migration]

Updated by mfriedrich on 2012-10-09 01:48:13 +00:00

• File added icinga_docs_1.8_javascript_toc_x.y.z_sections.png
• Target Version changed from 1.9 to 1.8

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.
https://wiki.icinga.org/display/Dev/Docbook+Style#DocbookStyle-TOCLabelsnotinHyperlinks

the section depths remains 2, otherwise docbook won't even create that, and we cannot work with the data.

well, docbook does not ship javascript functionality out of the box (only a different extensions named webhelp - wtf?). working around with css isn't possible either, as you can only trigger hover, but not direct click actions.

well, back within javascript and jquery - i've added a new jquery based toggle functionality, which makes sure to

• hide all X.Y.Z sections by default
• show a [+] on all X.Y sections which contain X.Y.Z sections
• on click, toggle the view and show the X.Y.Z menue
• toggling [+] with [-] was not possible yet, my javascript knowledge is pretty low on that

the changes required - include 2 javascript files into the docs: jquery and my own written javascript addin. the duplication of the existing classic ui is done to stay independent (and packagers can softlink that either way).

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.

[icinga-migration]

Updated by mfriedrich on 2012-10-09 13:03:47 +00:00

updated documentation - https://wiki.icinga.org/display/Dev/Docbook+Style

looking good so far.

[icinga-migration]

Updated by mfriedrich on 2012-10-09 16:08:06 +00:00

• Target Version changed from 1.8 to 1.9
• Done % changed from 60 to 80

some missing bits for future releases:

• icinga web config
  add sections for access.xml, database.xml, etc

• quickstart idoutils
  add sections for each step like prerequisites, packages, create account info, download, compile&install, customise configuration, enable idomod, create idoutils database, configure classic web interface, compile and install nagios plugins, start idoutils and icinga, configure icinga startup, other modifications, ...)

(same goes for the other quickstart guides as well)

• icinga web introduction
  add sections to 1.8 (and following included versions) in order to not scroll to the admin principal console, but link on top.

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).

[icinga-migration]

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".

[icinga-migration]

Updated by mfriedrich on 2012-10-09 18:34:01 +00:00

hmmm, i guess this is yet another docbook setting for the toc.

[icinga-migration]

Updated by Wolfgang on 2012-10-09 23:15:49 +00:00

commit f109e93 in next

[icinga-migration]

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:

we use

    Host definition

which is generated for the object.id template, when it comes to generic generation of unique item ids.

BUT - the

identifier 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).

  1.1.1. What is Icinga?

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.

[icinga-migration]

Updated by mfriedrich on 2012-10-10 01:03:56 +00:00

postgresql defines a section id, instead of a title anchor.

http://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/mvcc.sgml;h=d5c6076d4aa64ae3b899977447424197f1ef7bff;hb=HEAD#l20

(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).

[icinga-migration]

Updated by mfriedrich on 2012-10-10 01:11:34 +00:00

i've tried with a small diff against about.xml

diff --git a/en/about.xml b/en/about.xml
index 05826f6..32cb61b 100644
--- a/en/about.xml
+++ b/en/about.xml
@@ -8,7 +8,7 @@
          xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook">
   About &name-icinga;

-  
+  
     What is &name-icinga;?

     &name-icinga; is a monitoring system checking hosts and services you specify and notifying you when things go wrong and when they

the toc looks correct for the first entry.

    1.1. About IcingaTable of Contents1.1.1. What is Icinga?1.1.2. System requirements1.1.3. Licensing1.1.4. Acknowledgements1.1.5. Downloading The Latest Version1.1.6. Compatibility

then the id below

  1.1.1. What is Icinga?

as well as the main TOC

    Table of Contents1. About1.1. About Icinga1.1.1. What is Icinga?1.1.2. System 

conlusion - all section title xml:ids need to be duplicated as id into sections as well.

[icinga-migration]

Updated by mfriedrich on 2012-10-10 11:14:20 +00:00

ok.

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.

[icinga-migration]

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.

[icinga-migration]

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:

-    What is &name-icinga;?
+    What is &name-icinga;?

The above example generates a valid toc and index.

[icinga-migration]

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

• name the section ids in german the same as english? or get german, and name them accordingly?

[icinga-migration]

Updated by Wolfgang on 2012-10-10 17:47:02 +00:00

I'd name the section the same.

[icinga-migration]

Updated by mfriedrich on 2012-10-10 17:53:58 +00:00

• Assigned to changed from Wolfgang to mfriedrich

ok, i'll port them over. the anchor cleaning might happen in the same step, or not. guess copypaste is faster than copypastesearchdelete.

[icinga-migration]

Updated by mfriedrich on 2012-10-10 17:55:41 +00:00

btw - once we get lost of the generated ids for indexterm, the generated html diffs will be short and readable.

[icinga-migration]

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.

Writing ../../html/docs/en/config.html for section(config)
Error: no ID for constraint linkend: checkscheduling-service_inter_check_delay.
Error: no ID for constraint linkend: checkscheduling-max_concurrent_checks.

Writing ../../html/docs/en/configcgi.html for section(configcgi)
Error: no ID for constraint linkend: cgiauth-definitions.
Error: no ID for constraint linkend: cgiauth-definitions.
Error: no ID for constraint linkend: cgiauth-definitions.
Error: no ID for constraint linkend: cgiauth-definitions.

Writing ../../html/docs/en/ch04.html for chapter(ch04)
Error: no ID for constraint linkend: plugins-obtaining.

Writing ../../html/docs/en/icinga-web-scratch.html for section(icinga-web-scratch)
Error: no ID for constraint linkend: icinga-web-scratch-errors.
Writing ../../html/docs/en/upgrading_icingaweb.html for section(upgrading_icingaweb)
Error: no ID for constraint linkend: configweb-globalconfig.
Error: no ID for constraint linkend: configweb-module.
Error: no ID for constraint linkend: configweb-customconfig.

Writing ../../html/docs/en/distributed.html for section(distributed)
Error: no ID for constraint linkend: redundancy-prerequisites.
Error: no ID for constraint linkend: redundancy-scenario_1.
Error: no ID for constraint linkend: redundancy-scenario_1.
Error: no ID for constraint linkend: redundancy-scenario_1.

Writing ../../html/docs/en/passivestatetranslation.html for section(passivestatetranslation)
Error: no ID for constraint linkend: checkscheduling-host_checks.

Writing ../../html/docs/en/db_components.html for section(db_components)
Error: no ID for constraint linkend: configido-idomod_options.
Error: no ID for constraint linkend: configido-ido2db_options.

Writing ../../html/docs/en/db_example-configs.html for section(db_example-configs)
Error: no ID for constraint linkend: dbm_ct.
Error: no ID for constraint linkend: dbm_dt.
Error: no ID for constraint linkend: dbm_ht.
Error: no ID for constraint linkend: dbm_cf.


Writing ../../html/docs/de/config.html for section(config)
Error: no ID for constraint linkend: checkscheduling-service_inter_check_delay.
Error: no ID for constraint linkend: checkscheduling-service_interleaving.
Error: no ID for constraint linkend: checkscheduling-max_concurrent_checks.
Error: no ID for constraint linkend: checkscheduling-service_inter_check_delay.
Error: no ID for constraint linkend: dependencies.

Writing ../../html/docs/de/configobject.html for section(configobject)
Error: no ID for constraint linkend: dependencies.
Error: no ID for constraint linkend: dependencies.

Writing ../../html/docs/de/configcgi.html for section(configcgi)
Error: no ID for constraint linkend: cgiauth-definitions.
Error: no ID for constraint linkend: cgiauth-definitions.
Error: no ID for constraint linkend: cgiauth-definitions.
Error: no ID for constraint linkend: cgiauth-definitions.

Writing ../../html/docs/de/macrolist.html for section(macrolist)
Error: no ID for constraint linkend: dependencies.
Writing ../../html/docs/de/hostchecks.html for section(hostchecks)
Error: no ID for constraint linkend: dependencies.

Writing ../../html/docs/de/statetypes.html for section(statetypes)
Error: no ID for constraint linkend: dependencies.

Writing ../../html/docs/de/icinga-web-scratch.html for section(icinga-web-scratch)
Element include in namespace 'http://www.w3.org/2001/XInclude' encountered in chapter, but no template matches.
Error: no ID for constraint linkend: icinga-web-scratch-errors.

Writing ../../html/docs/de/icinga-web-introduction.html for section(icinga-web-introduction)
Element include in namespace 'http://www.w3.org/2001/XInclude' encountered in chapter, but no template matches.

Writing ../../html/docs/de/extcommands2.html for section(extcommands2)
Error: no ID for constraint linkend: eventhandlers-example.

Writing ../../html/docs/de/distributed.html for section(distributed)
Error: no ID for constraint linkend: redundancy-prerequisites.

Writing ../../html/docs/de/clusters.html for section(clusters)
Element include in namespace 'http://www.w3.org/2001/XInclude' encountered in chapter, but no template matches.

Writing ../../html/docs/de/adaptive.html for section(adaptive)
Error: no ID for constraint linkend: dependencies.

Writing ../../html/docs/de/passivestatetranslation.html for section(passivestatetranslation)
Error: no ID for constraint linkend: checkscheduling-host_checks.

Writing ../../html/docs/de/components.html for section(components)
Error: no ID for constraint linkend: configido-idomod_options.
Error: no ID for constraint linkend: configido-ido2db_options.

Writing ../../html/docs/de/example-configs.html for section(example-configs)
Error: no ID for constraint linkend: dbm_ct.
Error: no ID for constraint linkend: dbm_dt.
Error: no ID for constraint linkend: dbm_ht.
Error: no ID for constraint linkend: dbm_cu.
Error: no ID for constraint linkend: dbm_cf.

[icinga-migration]

Updated by mfriedrich on 2012-10-11 17:08:23 +00:00

• Status changed from Assigned to Resolved
• Target Version changed from 1.9 to 1.8

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.

[icinga-migration]

Updated by mfriedrich on 2012-10-11 17:08:27 +00:00

• Done % changed from 80 to 100