Thanks Larry!
Right now we use sect1, sect2, sect3, and sect4. When we produce our
output in HTML Help each sect starts a new page.
For example our table of contents can look like the following:
sect1
sect2
sect2
sect3
sect3
sect4
sect3
sect2
sect2
sect3
.........
Currently, within each sect1, sect2, sect3, and sect4 we have bridgeheads.
I like the idea of replacing the bridgeheads with a tag like section or
simplesect and using renderas to
make them appear like bridgeheads.
Can I add <section> to the element definitions for sect1, sect2, sect3,
and sect4? Is this a good idea?
My other thought was to change the element defintions for sect1 so that
within a sect1 you could have simplesects followed by sect2s.
For example:
sect1
simplesect
sect2
sect2
....
Thanks again,
Kate
"Rowland, Larry" <[email protected]>
02/04/2009 11:39 AM
To
Thomas Schraitle <[email protected]>, "[email protected]"
<[email protected]>
cc
"[email protected]" <[email protected]>
Subject
RE: [docbook] Bridgehead alternatives
Hello Kate,
Actually, simply replacing the bridgeheads with an appropriate sect<N>
(sect2, sect3, etc.) for the level at which they appear would also solve
the problem in the original markup. The refentry model is most
appropriate for reference type information (similar to the "Brick" in UNIX
systems and to "DocBook: The Definitive Guide"). While reference type
information benefits from constraining parts of the structure of a
document (which the refentry does) other types of information frequently
do not need the constrained structural model that the refentry element
provides. You do not have to do the entire document using refentry just
because you have some reference material to cover. We frequently provide
a reference element at the back of programming documents with the refentry
elements grouped in it, and also, less frequently, mix refentry elements
into other portions of a document built with regular chapter/section
structures.
If the appearance of the rendered lower-level sect<N> elements needs to be
consistent, the renderas attribute allows you to specify what rendering is
to be used (it can be mapped to any of the other sect<n> elements).
Unless you have a specific need for the explicit section level model, you
might consider using the section element instead. While I prefer explicit
sections for refentry elements (because we still produce NROFF from them
and I like to make sure we don't code something nested so deeply that the
MAN command cannot differentiate the heading levels) I generally prefer
nested section elements to the explicit sect<N> model for most content. It
makes repurposing content a bit easier.
Regards,
Larry Rowland
-----Original Message-----
From: Thomas Schraitle [mailto:[email protected]]
Sent: Wednesday, February 04, 2009 8:35 AM
To: [email protected]
Cc: [email protected]
Subject: Re: [docbook] Bridgehead alternatives
Hi Kate,
> Thanks Tom!
:-)
> I will look into the <refentry> for the reference sections. But we
> also use bridgeheads as titles in our conceptual/usage sections.
> I don't think that refentry will work in these sections.
It will work. Use refsect1 and replace bridgeheades with refsect2.
> For example:
>
> <sect1>Using the adminstration tool </sect1>
> <para>....
> <bridgehead>Admin tool's key features</bridgehead>
> <variablelist>...
> <bridgehead>Admin tool plugins</bridghead>
> <para>...
> <bridgehead>Example</bridgehead>
So your structure will probably look like this (abbreviated):
refsect1
title: Using the administration tool
para: ...
refsect1
title: Admin tool's key features
variablelist: ...
para
refsect1
title: Example
...
Tom
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
