OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook] Best Practice in using sect1 - sect5

On Wed, May 18, 2011 at 21:38, Rowland, Larry <larry.rowland@hp.com> wrote:
> 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.

How deeply your sections are nested is something that your tools ought
to be telling you, not something that the schema should have to lay


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]