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

Karsten Wade kwade at redhat.com
Mon Aug 16 21:40:36 UTC 2004


On Mon, 2004-08-16 at 11:54, Dave Pawson wrote:
> On Mon, 2004-08-16 at 19:39, Karsten Wade wrote:
> 
> > I don't attach much importance to them in a short <article> with a few
> > <section>s, but it does help with a 200 page book to be able to tell
> > from the HTML filename roughly where you are in which file. 
> 
> If its sizable then you shouldn't need to rely on filenames?
> The structure of presented content should enable that, through
> toc's, headers and footers etc. 
>   See any standard docbook presented as a series of html files
> for examples.

I've never seen HTML output that made sense to me from DocBook, unless
the ID tags were used.

The link you posted,
http://www.sagehill.net/docbookxsl/Chunking.html#ChunkFilenames, didn't
have any solution that I saw that gave HTML files with meaning, with the
exception of bk01ch02s01.html.  However, that gives you something which
corresponds to the ToC rather than giving you contextual information
(what is the meaning in this file) or location information (what the
current practice of "s1-foo-bar" gives you.)

> 
> > 
> > In the SGML toolchain we use internally, all of the ID tags are used. 
> > <sect1> become the main filename, but every <section> has an <a name>
> > that is the same as the ID (all in caps), e.g.
> > s1-srv-ttr-help.sgml#S3-SRV-TTR-STANDING-STILL .
> Even if unused? 
> 
> > Without a compelling reasons to have both <sect1...5> and <section> as
> > FDP style, can we agree to use the more modular <section>?
> Infinitely recursive, not more modular.
>   If you need to nest to more than 4 then the document outline needs a
> review IMHO.
> Give me a reason to change, or persuade Tammy to change the guidelines.

Agreed about nesting, I don't even like to see four levels nested, that
cries out to me for a <variablelist> or somesuch.

As for modular ..

  modular
       adj : constructed with standardized units or dimensions allowing
             flexibility and variety in use; "modular furniture";
             "modular homes"

What I'm saying is that moving <section>s with context-only ID tags is a
no-brainer, you just move them.  Moving <sect1...5>s with context-only
IDs is just grunt work.  As soon as you start to get up to IDs with
location information (sn), you are changing <xref>s all over the
document, fixing the strings in the id="", changing the <secta> ->
<sectb>, and so forth.

And, yes, <section> is also infinitely recursive, but that has nothing
to do with why I recommend we use it.

- Karsten

-- 
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41





More information about the fedora-docs-list mailing list