Re: [docbook-apps] adding element to autotoc stylesheet

["Bob Stayton" <bobs@sagehill.net>]

Here is a basic outline of how a book TOC works, and I hope it helps you see
how you might customize the process to add a new element.

1.  The template with match="book" calls a template named 'division.toc' to
start the process.

2.  The division.toc template in autotoc.xsl selects into a variable named
'nodes' which elements are to appear at the top level of the book toc. These
include chapter, appendix, glossary, index, etc.  Then it generates the TOC
titlepage (basically just the "Table of Contents" title at the top of the
page).

3.  Then it applies templates to the selected elements using mode="toc".  So
you need to find how each element is processed in mode="toc" to see what
happens next.

4.  Also in autotoc.xsl, there is a template with
match="preface|chapter|appendix|article" with mode="toc". It processes the
current element by calling the template named 'toc.line', which generates a
single line in the TOC.

5.  Then it selects which of its child elements are to be subheadings under
the current element and stores them in a 'nodes' variable. If there are such
nodes to be processed, it sets an indent and applies templates to those
nodes, also in mode="toc".

This process continues to the next level and then the next, to the limit of
the sections that are designated to be included in the TOC.  As you can see,
it is a recursive process that generates the TOC, descending down through
the hierarchy of elements to create a similar hierarchy in the TOC.

To include other elements not already accounted for in the TOC, you need to
add them to the 'nodes' selection at the appropriate point.  This would most
likely be in the templates that match on section elements in mode="toc". So
you would copy that template to your customization layer and change which
nodes are selected.

Then you need to supply a new template that matches that element name and in
mode="toc". It should be similar to the others in that mode.  Since your
para element doesn't seem to have children that should appear in the toc,
calling the toc.line template may be enough.

To actually generate the text for the element in the toc, you should look at
the toc.line template.  It works by applying templates to  the current
element in mode="titleabbrev.markup".  Such templates already exist for any
titled elements in Docbook, but your paragraph elements wouldn't have
titles.  So you need to add a template in that mode that matches your
selected para elements.

You are correct that the TOC machinery calls a lot of templates, but it does
that because it is designed to be modular and recursive, instead of a single
monolithic procedure.  The key is to find the appropriate entry points and
modular templates to modify, and that lets you minimize the amount of code
in your customization layer.

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net


----- Original Message ----- 
From: "Jason Black" <jblack@limacorp.com>
To: <docbook-apps@lists.oasis-open.org>
Sent: Thursday, August 18, 2005 8:13 AM
Subject: [docbook-apps] adding element to autotoc stylesheet


> Hi all,
>
> I have a situation where I need to add the first paragraph of of a list
> item orderedlist to the automatically generated table of contents.
> Right now, I am trying to implement this in the fo version of the
stylesheet. I am having
> trouble just understanding how the xsl for the table of contents works.
> It seems to keep calling templates and setting variables all over the
> place, there seem to be multiple files involved on this, and it's become
> really confusing to me.
>
> Using a customization layered stylesheet, is there a simple way to do
> this?  Any ideas or help would be appreciated greatly.
>
> Thank you
>
> Jason Black
> jblack@limacorp.com
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>
>