RE: [docbook] Best Practice in using sect1 - sect5

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

I frequently do manpages using DocBook for creating them.  I find
that knowing how many sections I am nested in is very valuable and
that is what refsect1, refsect2, etc is very valuable for, since
the NROFF that all of them are rendered through in a term window
does not provide coding for headings below a fixed level.  We also
have rules about depth of nesting of sections in nodes in help 
systems; again, having explicit sect1, sect2 provides very clear
indication of how deeply nested the sections are.

While I frequently use nested section elements in documents for 
which depth of nesting is not an issue, having the flexibility to 
know precisely how deeply my sections are nested is important in 
some cases.  Not everyone doing technical documentation is doing 
the same thing.  Simplify the schema as much as you want for your 
own use, but don't handicap the people who need a richer expression 
in the markup.

Regards,
Larry Rowland

-----Original Message-----
From: Dave Pawson [mailto:davep@dpawson.co.uk] 
Sent: Monday, May 16, 2011 6:56 AM
To: Eric Johnson
Cc: Fabián Mandelbaum; Bruce Wen; docbook@lists.oasis-open.org
Subject: Re: [docbook] Best Practice in using sect1 - sect5

On Mon, 16 May 2011 07:45:09 -0400
Eric Johnson <ericjohnson@apache.org> wrote:

> +1
> 
> 2011/5/16 Fabián Mandelbaum <fmandelbaum@gmail.com>:
> > (Oups, sorry Dave, you'll get this twice, I've clicked on the wrong
> > 'reply' button)
> >
> > Our preferences balance on the <section>-everywhere side. Use
> > <section> everywhere, and you won't have to think about it.
> >
> > I vote to ditch <sect1> to <sect5> elements from the next
> > incarnation of docbook. <section> is enough.
> >
> > While we are here, I also vote to ditch some structures that only
> > add to the confusion,


You are free to customize the schema for your own use?

Ditch what you like, add what you like....
But don't call it docbook.




-- 

regards 

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

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