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

[Mark Johnson]

Paul W. Frields wrote:
>>I'd recommend a standard of:
>>
>><section id="like-the-title">
>>  <title>Like The Title: The Details</title>
>>
>>The ID has meaning to the content.  When moving chunks if <section>s
>>around, you can know what something is easily.  Want an idea what
>>sections you have in what order?  'grep "<section" *.xml' gives back
>>something meaningful that directly corresponds to your table of
>>contents.
>>
>>Any other thoughts on this?  I'll hold off for a bit on filling out the
>>bug report. :)
> 
> 
> Up until now we've been using Documentation Guide instructions that
> recommend attributes such as id="s1-top-section" or id="s2-subsection".

To me (& I would guess Karsten), assigning IDs based on the document 
structure seems not to take advantage of ID="meaning-of-content". If 
one wants to give IDs such as id="s1-top-section", one can get the 
same effect by having the stylesheet *not* use IDs as filenames for 
html output. The output filenames then serve the purpose of 
identifying the structural location of the output file within the 
document.

I have to admit that I found it bizarre when I first discovered that 
one would assign IDs as id="s2-subsection", etc. This method seems 
to throw out the possibility to add some content-related info to the 
tags themselves. Don't forget that we're trying to convey meaning 
here. The more semantic meaning we can give to the structural markup 
the better, IMO.

FWIW, I've always used meaning-derived IDs, such as 
id="xml-catalogs", as that's what the section is about. And to me, I 
  *want* the output filename to be "xml-catalogs.html" because it 
carries more meaning than does the sort of structure identifier 
recommended in the Documentation Guide.

Perhaps in some abstract way, having output filenames like 
"s2-subsection.html" adds a more 'professional' touch to the docs, 
but I'm not even sure what I mean by that:)

My $0.02,
Mark

> Will we likewise be abandoning those as well? They don't actually cut
> down on portability but definitely interfere with the logic of the
> document when one starts copying and pasting sections around.
> 
> Perhaps using id="sn-*" would work better, and allow us to keep most of
> the guidelines as they are. I supposed sed really is our friend! :-D
> 


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