RE: [docbook] Bridgehead alternatives

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

Once you start using a sect1 or a section, you are committed to using whichever form you chose for siblings and children.  However, in a parallel parent element, you can choose differently.  That is, you can have a chapter with sections in the same document that you have a chapter with sect1 elements.  Once you choose within a wrapper element, you have chosen for descendents of that wrapper.  The idea is that you either choose the nested section elements or the explicit section level elements and have to be consistent once you choose, but only within that parent element, not its siblings.

 

If you want to be able to use sect<n> that break into pages on section boundaries, but also for internal structure, it is possible to use a processing instruction or an attribute (we use role="no.new.page" to override the default breaking on sections but have decided to move it to a processing instruction on the next version of the system, to allow for different behaviors in the printed and HTML versions of a document).

 

The problem you are dealing with of wanting sections to break into pages but still use them for internal structure is what led us to implement our help system grammar based on a file for each page with an additional file that describes the structure of the help system.  Then we don't have to worry about structure within a help node interacting with the structure of the help system.

 

The renderas attribute, by default, only accepts other sect<n> values -- you would need to modify the DTD to change that.  You might also consider using a role attribute to control render and chunking simultaneously, something like role="bridgehead" that suppresses chunking and also sets the render up the way you want it.

 

Regards,

Larry

---

From: Kate.Wringe@sybase.com [mailto:Kate.Wringe@sybase.com]
Sent: Wednesday, February 04, 2009 10:09 AM
To: Rowland, Larry
Cc: docbook@lists.oasis-open.org; Thomas Schraitle
Subject: RE: [docbook] Bridgehead alternatives

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" <larry.rowland@hp.com>

02/04/2009 11:39 AM

To	Thomas Schraitle <tom_schr@web.de>, "Kate.Wringe@sybase.com" <Kate.Wringe@sybase.com>
cc	"docbook@lists.oasis-open.org" <docbook@lists.oasis-open.org>
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: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


---------------------------------------------------------------------
To 
unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional 
commands, e-mail: 
docbook-help@lists.oasis-open.org