Chris Ridd | 1 Nov 2010 15:09
Picon
Gravatar

Conceptual problem formatting <preface> material

Hi,

I am trying to reproduce the structure of existing manuals written in Framemaker, in 2 new manuals written
using Docbook and I'm having a little trouble working out how one is supposed to do radical formatting of
front matter.

Our manuals are <book>s.

I have a custom title page constructed via a titlepage template, which just has the front cover. So far so
(relatively) easy...

But then I have some pages with different page numbering (eg i .. vi) that include a slightly custom
formatted TOC, an untitled copyright section, and then some titled (but un-numbered) sections
describing Typographical Conventions etc. (One of the existing Frame manuals is accessible at
<http://www.isode.com/Documentation/SWADMINT.pdf> in case I'm not explaining this well.)

The copyright section feels like it should come from the book info, but the remaining stuff feels like
preface material.

What's the best approach for arranging these things? I'm starting to look at overriding the "book"
template from fo/division.xsl, but have a sneaking suspicion that I really should be doing this all in the
titlepage template.

Or is there another way?

I did look at Bob's otherwise excellent book, but didn't really get a good feeling for the best approach here.

Cheers,

Chris 
(Continue reading)

Bob Stayton | 1 Nov 2010 17:49

Re: Conceptual problem formatting <preface> material

Hi Chris,
I've done similar books like this using preface elements with role attributes, and 
then customizing the book template to output them in the order you want.  The 
titlepage template system is not really appropriate for that kind of extended 
information.

For each special preface, I add a template with match="preface[ <at> role = 'something']" 
to handle its formatting, and then add the following to the book template to apply it:

  <xsl:apply-templates select="preface[ <at> role = 'something']"/>

That way if a book instance does not have such a preface, this step is just skipped.

You'll also want to add an empty template in normal mode to prevent the preface 
element from being processed again in book order:

  <xsl:template match="preface[ <at> role = 'something']"/>

You'll need to decide which of these have their own fo:page-sequence, and call the 
template name 'page.sequence' with that as content.

And you'll need to customize the templates named 'page.number.format' and 
'initial.page.number' to get the right page numbering scheme.

The trickiest part in this design is getting the copyright and "Contacting" 
information on the same page.  The copyright info is normally processed in the 
titlepage page-sequence.  For that case, I would customize the template named 
'book.titlepage.verso' to apply templates to that preface element, and leave that one 
out of the book template.

(Continue reading)

Chris Ridd | 1 Nov 2010 18:41
Picon
Gravatar

Re: Conceptual problem formatting <preface> material


On 1 Nov 2010, at 16:49, Bob Stayton wrote:

> Hi Chris,
> I've done similar books like this using preface elements with role attributes, and then customizing the
book template to output them in the order you want.  The titlepage template system is not really
appropriate for that kind of extended information.

Right, thanks for helping me avoid that particular blind alley :-)

> For each special preface, I add a template with match="preface[ <at> role = 'something']" to handle its
formatting, and then add the following to the book template to apply it:
> 
> <xsl:apply-templates select="preface[ <at> role = 'something']"/>
> 
> That way if a book instance does not have such a preface, this step is just skipped.
> 
> You'll also want to add an empty template in normal mode to prevent the preface element from being
processed again in book order:
> 
> <xsl:template match="preface[ <at> role = 'something']"/>

I'm confused now. Firstly I've got one <preface> with several sections, not multiple <preface>s. (Though
we're amenable to creating multiple <preface>s if it makes things easier. It isn't /quite/ separating
content from presentation though :-)

But I'm mostly confused about your contradictory suggestions in the 1st and last lines! ie

add a template with match="preface[ <at> role='something']" to format it
add an empty template with match="preface[ <at> role='something']"
(Continue reading)

Bob Stayton | 1 Nov 2010 20:18

Re: Conceptual problem formatting <preface> material


Bob Stayton
Sagehill Enterprises
bobs <at> sagehill.net

----- Original Message ----- 
From: "Chris Ridd" <chrisridd <at> mac.com>
To: "Bob Stayton" <bobs <at> sagehill.net>
Cc: <docbook-apps <at> lists.oasis-open.org>
Sent: Monday, November 01, 2010 10:41 AM
Subject: Re: [docbook-apps] Conceptual problem formatting <preface> material

>
> On 1 Nov 2010, at 16:49, Bob Stayton wrote:
>
>> Hi Chris,
>> I've done similar books like this using preface elements with role attributes, and 
>> then customizing the book template to output them in the order you want.  The 
>> titlepage template system is not really appropriate for that kind of extended 
>> information.
>
> Right, thanks for helping me avoid that particular blind alley :-)
>
>> For each special preface, I add a template with match="preface[ <at> role = 
>> 'something']" to handle its formatting, and then add the following to the book 
>> template to apply it:
>>
>> <xsl:apply-templates select="preface[ <at> role = 'something']"/>
>>
>> That way if a book instance does not have such a preface, this step is just 
(Continue reading)

Bob Stayton | 1 Nov 2010 20:21

Re: Conceptual problem formatting <preface> material

Oops, hit Send by accident on the previous mail.

I did omit a crucial piece of information.  In the first template I meant to process 
it in a mode other than normal mode:

<xsl:apply-templates select="preface[ <at> role = 'something']" mode="frontmatter"/>

and that uses the template with:

<xsl:template match="preface[ <at> role = 'something']" mode="frontmatter">
   actually processing goes here
</xsl:template>

and the empty template is for normal mode (without a mode attribute).  Hope that makes 
more sense.

Bob Stayton
Sagehill Enterprises
bobs <at> sagehill.net

----- Original Message ----- 
From: "Chris Ridd" <chrisridd <at> mac.com>
To: "Bob Stayton" <bobs <at> sagehill.net>
Cc: <docbook-apps <at> lists.oasis-open.org>
Sent: Monday, November 01, 2010 10:41 AM
Subject: Re: [docbook-apps] Conceptual problem formatting <preface> material

>
> On 1 Nov 2010, at 16:49, Bob Stayton wrote:
>
(Continue reading)

Chris Ridd | 1 Nov 2010 21:07
Picon
Gravatar

Re: Conceptual problem formatting <preface> material


On 1 Nov 2010, at 19:21, Bob Stayton wrote:

> Oops, hit Send by accident on the previous mail.
> 
> I did omit a crucial piece of information.  In the first template I meant to process it in a mode other than
normal mode:
> 
> <xsl:apply-templates select="preface[ <at> role = 'something']" mode="frontmatter"/>
> 
> and that uses the template with:
> 
> <xsl:template match="preface[ <at> role = 'something']" mode="frontmatter">
>  actually processing goes here
> </xsl:template>
> 
> and the empty template is for normal mode (without a mode attribute).  Hope that makes more sense.

It does make much more sense :-)

Thanks Bob and Guiseppe! I may have more questions as I get further up the creek without a paddle...

Cheers,

Chris

Gmane