RE: [docbook] Bridgehead alternatives

["Rowland, Larry" <larry.rowland@hp.com>]

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:tom_schr@web.de] 
Sent: Wednesday, February 04, 2009 8:35 AM
To: Kate.Wringe@sybase.com
Cc: docbook@lists.oasis-open.org
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: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org