<section> vs <sect1>, ... [was: Re: usb-keys]

[Mark Johnson]

Karsten Wade wrote:
>>>
>>> [...] Especially if the practice
>>>is deprecated?
>>
>>I'd be very surprised to see it deprecated. Where was the origin of
>>this?
> 
> 
> 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 
require them.

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 
[1], 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
           class="attribute">prefer</sgmltag>
            attribute</title>

<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 
document structure.

My $0.02,
Mark

[1] 
http://www.oasis-open.org/committees/download.php/4952/wd-entity-xml-catalogs-1.0_2e.xml

> 
> 
>>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
> nesting. 
> 
> 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