OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

Hi Ari,
Interesting because I really thought I was using docbook 5 already.

Well, you are using DocBook 5 documents, but the stylesheets you are using are tuned for DocBook 4. The two sets of stylesheets are:

docbook-xsl-1.78.1     non-namespace element match
docbook-xsl-ns-1.78.1  namespace element match

You have the non-namespace match stylesheet, so when it is processing a DocBook 5 document, it first strips off the namespace and processes the resulting non-namespaced elements. The -ns- version would be a bit more efficient because it does not have to perform that step.

The ns version is generated from the non-ns version with a program, and that program does not change the descriptive text in any way. Clearly it should indicate somewhere that it works best with DocBook5, and I'll add something about that to the conversion program.

Bob Stayton
Sagehill Enterprises

On 11/18/2015 6:47 PM, Aristedes Maniatis wrote:
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;


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"

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>


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

13:29:39.512 [ERROR] [system.err] Writing
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:


rather than


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

I feel like I'm missing something really obvious.


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.


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:

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>

but it doesn't work. I'm a bit out of my depth with this
level of XSLT hackery. Any help would be welcome...


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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]