Re: [docbook-apps] Re: [docbook] TOC with parents

[Aristedes Maniatis <ari@ish.com.au>]

On 19/11/2015 10:48am, Bob Stayton wrote:
> Hi Ari,
> You want to look at autotoc.xsl. The toc.xsl module has templates for a TOC that is created by hand using <tocentry> elements, something that almost no one does.  Use autotoc.xsl for an automatically-generated TOC.

Excellent. Can I suggest that some descriptive text at the top of each xsl file would help people like me a lot. I've spent most of my time focussing on the toc.xsl file and trying to understand how it works. What's missing when trying to understand it is a high level overview of how all the XSL fits together.


> oOur first step is to turn on a table of contents for each chunk output. That is controlled by the stylesheet param named 'generate.toc', and few params that control which levels of section get a toc, all described here;
> 
> http://www.sagehill.net/docbookxsl/TOCcontrol.html
> 
> That will trigger each element mentioned in 'generate.toc' to call its
> special template from autotoc.xsl to generate a TOC, which would be:
> 
> 'division.toc' for set and book
> 'component.toc' for chapter, appendix, preface
> 'section.toc' for sections


Ah, the real trick here is that chapter isn't chapter.toc. And with that change, everything starts working! I got confused with and those mode things.

<xsl:template match="preface|chapter|appendix|article|topic" mode="toc">

I'm not trying to generate any TOC at the section level.


> By default, these will generate a "context-appropriate" TOC for each element, which means it includes only the children of the current element.  So you need to redefine 'component.toc' and 'section.toc' to instead call 'division.toc'.
> 
> <xsl:template name="section.toc">
>   <xsl:param name="toc-context" select="."/>
>   <xsl:param name="toc.title.p" select="true()"/>
> 
>   <xsl:for-each select="ancestor::d:book">
>     <xsl:call-template name="division.toc">
>       <xsl:with-param name="toc-context" select="."/>
>       <xsl:with-param name="toc.title.p" select="$toc.title.p"/>
>     </xsl:call-template>
>   </xsl:for-each>
> 
> </xsl:template>
> 
> The xsl:for-each is necessary to change the context from the current
> element to the book element.  The "d:book" is needed to match the namespace in DocBook 5, so use just "book" if you are using DocBook 4.


Interesting because I really thought I was using docbook 5 already. I'm using the XSLT from sourceforge (well, actually from maven central) with version 1.78.1 but nothing in that release (NEWS.html, README, REVISION, VERSION) gives me any clue as to whether it is tracking docbook 4 or 5. But since I had to remove the "d" namespace I'm guessing I must be on Docbook 4, even though I've been using the docbook 5 namespace and header

<book xmlns="http://docbook.org/ns/docbook"; version="5.0"...


The next interesting thing is that with the above template, the generation worked fine but was incredibly slow. A 3 minute build process now took over an hour. Playing with toc.section.depth and toc.max.depth didn't make it go any faster (unless I made toc.max.depth=1 of course and most of the TOC were skipped).

I couldn't really see why since the only logs even at debug level were:

13:29:39.512 [ERROR] [system.err] Writing /Users/ari/svn/onCourseDocs/apidocs/build/html/ish/oncourse/server/cayenne/Script.html for chapter(ish/oncourse/server/cayenne/Script)

The file was still written just fine.

However this brought it back to a good speed:

    <xsl:template match="preface|chapter|appendix|article" mode="toc">
        <xsl:param name="toc-context" select="."/>
                <xsl:call-template name="subtoc">
                    <xsl:with-param name="toc-context" select="$toc-context"/>
                    <xsl:with-param name="nodes" select="/NOT-AN-ELEMENT"/>
                </xsl:call-template>
    </xsl:template>


My second problem is that your hack breaks all the links. The path is duplicated in the href, which makes sense I guess. My files are all in folders of up to 4 levels, and the TOC is now generated with hrefs like this:

href="ish/common/types/AccountTransactionType.html"

rather than

href="../../../ish/common/types/AccountTransactionType.html"



I'm looking at the links in autotox.xsl but they all point to

      <xsl:call-template name="href.target">
        <xsl:with-param name="context" select="$toc-context"/>
        <xsl:with-param name="toc-context" select="$toc-context"/>
      </xsl:call-template>

and that in turn can be found in html.xsl

<xsl:template name="href.target">
  <xsl:param name="context" select="."/>
  <xsl:param name="object" select="."/>
  <xsl:text>#</xsl:text>
  <xsl:call-template name="object.id">
    <xsl:with-param name="object" select="$object"/>
  </xsl:call-template>
</xsl:template>

but it appears to only link to anchors on the same page (starts with #) and not to the full path. So I'm a little stuck again. Do we need to reset the toc-context to point back to the top?


Thanks
Ari


> Do the same for redefining 'component.toc'.
> 
> Templates with mode="toc" are used in the construction of a TOC to
> generate a TOC entry for the given element.  You probably won't need to
> customize those for your purpose.
> 
> Let me know if this doesn't work for you.
> 
> Bob Stayton
> Sagehill Enterprises
> bobs@sagehill.net
> 
> On 11/18/2015 2:57 PM, Aristedes Maniatis wrote:
>> Thanks for your help, but the webhelp output was just way too
>> different. So I've struggled to try and modify the TOC output from
>> docbook. But nothing I try seems to be able to customise it. Even
>> when I try:
>>
>> <xsl:import href="@rootDir@/build/xslt/docbook/html/chunk.xsl"/>
>>
>> <xsl:template name="section.toc" mode="toc">
>> <xsl:text>******************</xsl:text> </xsl:template>
>>
>> <xsl:template match="section/toc" mode="toc">
>> <xsl:text>******************</xsl:text> </xsl:template>
>>
>> with or without the mode (I don't really understand how the mode is
>> used in XSLT).
>>
>> I'm a bit confused by the presence of both toc.xsl and autotoc.xsl.
>> But nothing I try seems to allow me to modify them.
>>
>> I have no problem modifying other things like <xsl:template
>> name="user.head.content">
>>
>>
>> I feel like I'm missing something really obvious.
>>
>> Ari
>>
>>
>>
>> On 22/10/2015 12:46pm, Peter Desjardins wrote:
>>> [moving to docbook-apps]
>>>
>>> What you are describing sounds like the webhelp output. Did you
>>> consider using that?
>>>
>>> Webhelp produces HTML pages with the full TOC on each page. I have
>>> customized the HTML and CSS significantly to match different web
>>> sites and branding.
>>>
>>> Peter
>>>
>>> On Wed, Oct 21, 2015 at 9:39 PM, Aristedes Maniatis
>>> <ari@ish.com.au> wrote:
>>>> I have chunked html output from docbook 5, and want to output the
>>>> entire TOC on every page, including all parents of the chapter
>>>> currently being rendered.
>>>>
>>>> I found one approach here:
>>>> http://markmail.org/message/xpmrfboyu3tr5ehn
>>>>
>>>> But it is 11 years old, and not quite right, so I modified it a
>>>> little...
>>>>
>>>> <!-- show all sections in TOC, including parents of the current
>>>> section --> <xsl:template match="chapter" mode="toc"> <xsl:param
>>>> name="toc-context" select="."/>
>>>>
>>>> <xsl:for-each select="ancestor::book"> <xsl:apply-templates
>>>> select="book" mode="toc"> <xsl:with-param name="toc-context"
>>>> select="."/> </xsl:apply-templates> </xsl:for-each>
>>>> </xsl:template>
>>>>
>>>> but it doesn't work. I'm a bit out of my depth with this level of
>>>> XSLT hackery. Any help would be welcome...
>>>>
>>>>
>>>>
>>>> Ari
>>>>
>>>>
>>>>
>>>> -- --------------------------> Aristedes Maniatis ish
>>>> http://www.ish.com.au Level 1, 30 Wilson Street Newtown 2042
>>>> Australia phone +61 2 9550 5001   fax +61 2 9550 4001 GPG
>>>> fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A
>>>>
>>

-- 
-------------------------->
Aristedes Maniatis
ish
http://www.ish.com.au
Level 1, 30 Wilson Street Newtown 2042 Australia
phone +61 2 9550 5001   fax +61 2 9550 4001
GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A

Attachment: signature.asc
Description: OpenPGP digital signature