docbook-apps

Hi All,

I'm trying to add annotation to my docbook manual when rendered to pdf using xsltproc and fop.

I'm using a template in my custom xsl:

<xsl:template match="d:section">
<xsl:apply-templates/>
</xsl:template>

This is my first attempt. My expectation is that this should make not difference to the rendered pdf. However, after executing, I discover the sections titles are missing through-out the pdf document.

If you could explain why this is - and how I can modify my template so section titles are displayed in the pdf, I would be grateful.

cheers,
Richard

HI Richard,
You can get your titles back by adding a call to the template named
'section.titlepage':

<xsl:template match="d:section">
<xsl:call-template name="section.titlepage"/>
<xsl:apply-templates/>
</xsl:template>

In general, the title element is not processed in normal mode, but in
mode="titlepage.mode". The reason is because the d:info element can contain
a lot of information, not all of which is meant to be output. The DocBook
XSL stylesheets provide a mechanism for customizing the selection of d:info
elements to output and what formatting properties to apply to them. Your
title elements may not be in d:info, but d:info supports putting the title
there, so the system has to manage both locations. That titlepage mechanism
is described in this documentation:

http://www.sagehill.net/docbookxsl/HTMLTitlePage.html

I make it a practice of examining (or copying) the original template
matching on an element before customizing it. That way I can see what
special handling the stylesheet already performs, and fit my customizations
into that existing process. In this case, the template with
match="d:section" is in fo/sections.xsl, which in turn calls a template
named 'section.content', which in turn calls 'section.titlepage', which
handles mode="titlepage.mode".

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

--------------------------------------------------
From: "Richard Henwood" <rjhenwood@yahoo.co.uk>
Sent: Saturday, December 29, 2012 11:44 AM
To: <docbook-apps@lists.oasis-open.org>
Subject: [docbook-apps] annotating docbook sections

> Hi All,
>
> I'm trying to add annotation to my docbook manual when rendered to pdf
> using xsltproc and fop.
>
> I'm using a template in my custom xsl:
>
> <xsl:template match="d:section">
> <xsl:apply-templates/>
> </xsl:template>
>
> This is my first attempt. My expectation is that this should make not
> difference to the rendered pdf. However, after executing, I discover the
> sections titles are missing through-out the pdf document.
>
> If you could explain why this is - and how I can modify my template so
> section titles are displayed in the pdf, I would be grateful.
>
> cheers,
> Richard
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>
>

On 30/12/12 08:17, Bob Stayton wrote:

> That titlepage mechanism is described in this documentation:
>
> http://www.sagehill.net/docbookxsl/HTMLTitlePage.html
>
> I make it a practice of examining (or copying) the original template
> matching on an element before customizing it. That way I can see what
> special handling the stylesheet already performs, and fit my
> customizations into that existing process.

Very sage(hill?) advice.

Docbook has caught me out more than once with the subtleties of
processing such as those mentioned in this thread. It may be a bit
hard copying in a hundred lines or more of code, but it does ensure
a smoother customization.


Best wishes to the docbook team for 2013, and very many thanks for your
work in 2012.


regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Thanks for this prompt advice and guidance Bob.

What I'm noticing is with the recipe for section below, the line number in the section toc entry is omitted. I've played around with various configurations to try and fix this: if you have any further advice, I would be grateful!

cheers,
Richard

--- On Sun, 30/12/12, Bob Stayton <bobs@sagehill.net> wrote:
> HI Richard,
> You can get your titles back by adding a call to the
> template named 'section.titlepage':
>
> <xsl:template match="d:section">
> <xsl:call-template name="section.titlepage"/>
> <xsl:apply-templates/>
> </xsl:template>
>
> In general, the title element is not processed in normal
> mode, but in mode="titlepage.mode".  The reason is
> because the d:info element can contain a lot of information,
> not all of which is meant to be output. The DocBook XSL
> stylesheets provide a mechanism for customizing the
> selection of d:info elements to output and what formatting
> properties to apply to them.   Your title
> elements may not be in d:info, but d:info supports putting
> the title there, so the system has to manage both
> locations.  That titlepage mechanism is described in
> this documentation:
>
> http://www.sagehill.net/docbookxsl/HTMLTitlePage.html
>
> I make it a practice of examining (or copying) the original
> template matching on an element before customizing it. 
> That way I can see what special handling the stylesheet
> already performs, and fit my customizations into that
> existing process.  In this case, the template with
> match="d:section" is in fo/sections.xsl, which in turn calls
> a template named 'section.content', which in turn calls
> 'section.titlepage', which handles mode="titlepage.mode".
>
> Bob Stayton
> Sagehill Enterprises
> bobs@sagehill.net
>
> --------------------------------------------------
> From: "Richard Henwood" <rjhenwood@yahoo.co.uk>
> Sent: Saturday, December 29, 2012 11:44 AM
> To: <docbook-apps@lists.oasis-open.org>
> Subject: [docbook-apps] annotating docbook sections
>
> > Hi All,
> >
> > I'm trying to add annotation to my docbook manual when
> rendered to pdf using xsltproc and fop.
> >
> > I'm using a template in my custom xsl:
> >
> > <xsl:template match="d:section">
> >  <xsl:apply-templates/>
> > </xsl:template>
> >
> > This is my first attempt. My expectation is that this
> should make not difference to the rendered pdf. However,
> after executing, I discover the sections titles are missing
> through-out the pdf document.
> >
> > If you could explain why this is - and how I can modify
> my template so section titles are displayed in the pdf, I
> would be grateful.
> >
> > cheers,
> > Richard
> >
> >
> ---------------------------------------------------------------------
> > To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> > For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
> >
> >
> >
>

--- On Wed, 2/1/13, Richard Henwood <rjhenwood@yahoo.co.uk> wrote:
> Thanks for this prompt advice and
> guidance Bob.
>
> What I'm noticing is with the recipe for section below, the
> line number in the section toc entry is omitted. I've played
> around with various configurations to try and fix this: if
> you have any further advice, I would be grateful!
>

Answering my own question:
It seems I need to include the $id into a new block - or at least, this worked for me:

<xsl:template match="d:section">
<xsl:variable name="id">
<xsl:call-template name="object.id"/>
</xsl:variable>
<xsl:message>found section</xsl:message>
<xsl:call-template name='section.titlepage'/>
<fo:block id="{$id}">
<fo:external-graphic src="section.png"/>
</fo:block>
<xsl:apply-templates/>
</xsl:template>

cheers,
Richard

<snip previous correspondence>

Right, what I provided was just a bare bones solution to your immediate
problem of missing titles. You are using a highly stripped down template
for sections, which is why I recommended looking at what the stock template
does. There might be other features missing for you as well.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

--------------------------------------------------
From: "Richard Henwood" <rjhenwood@yahoo.co.uk>
Sent: Wednesday, January 02, 2013 1:31 PM
To: <docbook-apps@lists.oasis-open.org>
Cc: "Bob Stayton" <bobs@sagehill.net>
Subject: Re: [docbook-apps] annotating docbook sections

>
>
> --- On Wed, 2/1/13, Richard Henwood <rjhenwood@yahoo.co.uk> wrote:
>> Thanks for this prompt advice and
>> guidance Bob.
>>
>> What I'm noticing is with the recipe for section below, the
>> line number in the section toc entry is omitted. I've played
>> around with various configurations to try and fix this: if
>> you have any further advice, I would be grateful!
>>
>
> Answering my own question:
> It seems I need to include the $id into a new block - or at least, this
> worked for me:
>
> <xsl:template match="d:section">
> <xsl:variable name="id">
> <xsl:call-template name="object.id"/>
> </xsl:variable>
> <xsl:message>found section</xsl:message>
> <xsl:call-template name='section.titlepage'/>
> <fo:block id="{$id}">
> <fo:external-graphic src="section.png"/>
> </fo:block>
> <xsl:apply-templates/>
> </xsl:template>
>
> cheers,
> Richard
>
> <snip previous correspondence>
>