<section> vs <sect1>, ... [was: Re: usb-keys]
mjohnson at redhat.com
Mon Aug 16 20:52:51 UTC 2004
Karsten Wade wrote:
>>> [...] Especially if the practice
>>I'd be very surprised to see it deprecated. Where was the origin of
> Word of mouth, Mark Johnson mentioned it several times on this list.
> Since he is an active member of the DocBook steering committee, I figure
> he has some clue there.
I recall a "DocBook Best Practices" tutorial at OSCON (2001??),
presented by members of the DocBook Technical Committee, where the
use of <section> over <sect1> was recommended. I also recall some
posts to the docbook (or docbook-apps) list on this same question,
and the general consensus was that <section> is the preferred element.
I also recall asking during a DocBook TC telcon whether <sect1>, ...
<sect5> where going to disappear in DocBook V5, and Norm responded
with something to the effect that he honestly didn't know, and that
the decision may eventually lie in the hands of the user community.
(To the best of my recollection.) Having said that, let me remind
you that the policy for changes in major revision numbers in DocBook
is to allow for backwards incompatibilities, but does certainly not
So there is no clear answer.
OTOH, just out of curiousity, I downloaded the DocBook source XML
for the latest working draft of the OASIS XML Catalogs Specification
, which Norm Walsh edits/authors and noted that (1) he uses
<section>s, and (2) that his ID attributes are more semantically
derived, than structurally derived (though notice the "s."
prefixes). Some examples:
<section id="s.ext.ent"><title>External Identifier Entries</title>
<section id="attrib.prefer"><title>The <sgmltag
<section id="s.using.catalogs"><title>Using Catalogs</title>
<section id="s.uri.ent"><title>URI Entries</title>
<section id="s.rewrite"><title>Rewrite Entries</title>
I think his example is a nice compromise.
If someone's source XML has nested <section>s that are truly
difficult to unravel, then that author needs to reconsider his/her
>>I'd be happy to live with either way, but like the option of both.
>>Certainly the standard docbook processing favours sect1... as I see it.
> It's possible we could make it optional, but I still don't understand
> what the value is in fixed nesting values for <section> tags. I always
> understood it to have been a self-limitation to keep newbies from overly
> Can you give some examples of where it is useful?
>>It does perhaps beg the question why does fedora-docs start at article,
>>when it can go all the way up to set.
> If I understand your statement correctly, I think this has been answered
> a number of times. We are doing <article> sized docs because it's a
> bite that we can chew. Look at how well we've done so far, which is not
> really that well. If we had massive <book>s to create as part of
> <set>s, we'd be finishing the set for FC2 just about the time that
> FC5test2 was being released.
> Have patience, it is through these tiny steps that we will walk our
> first mile.
> - Karsten
Mark Johnson <mjohnson at redhat.com>
Red Hat Documentation Group <http://www.redhat.com>
Tel: 919.754.4151 Fax: 919.754.3708
GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242
More information about the docs