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

Paul W. Frields paul at frields.com
Mon Aug 16 20:10:02 UTC 2004


On Mon, 2004-08-16 at 14: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.

"Be able to tell" != "rely on"... If I open a directory full of chunked
HTML in a browser, and see files marked "node0592.html" or some such,
that's just not as helpful as "sn-srv-ttr-help.html". This happens
frequently when using manuals installed in /usr/share/doc. Yes, I can
always open "index.html" and navigate there, but why make me (the user)
take those steps? Didn't you mention something to me about the system
being user friendly and not the other way around? ;-) We don't yet know
how these docs will make it onto an installed FC system, so let's not
discount the possibility. 

> > 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? 

Moment of clarity needed. I went back and re-read this thread because I
couldn't remember what was being argued here. Let me see if I can
summarize this right.

Originally the topic was whether to use <sectN> vs. <section>. Everybody
agrees that's easy to change in existing documents. It looks to me, a
relatively non-stupid individual (relative to whom? *shrugs*), that e.g.
promoting <sect2> to <sect1> is:

- considerably more difficult if all the "id" attributes include
"s2-..." due to <xref>s and such.
- not much more difficult if the "id" attributes don't include "s2-..."

However, since "id" tags are used in the current XSLT's to set filenames
for HTML transforms, include graphics, and so forth, they do have some
use if we keep the current XSLT's.

I assume that if we change to using <section id="configuring-foobar">
instead of <sect1 id="s1-configuring-foobar">, the XSLT can be set to
recognize the section as a new HTML chunk file only if <section> is at
level 1, right? If that's the case, I have yet to see a convincing
argument why we shouldn't use <section id="configuring-foobar">. 

I still think having an id for every element currently listed in the
naming conventions is a good idea. I see a good bit of value in:
     grep "id=" doc-source.xml
Not quite as much as "grep 'section'", but quite a bit.

-- 
Paul W. Frields, RHCE





More information about the fedora-docs-list mailing list