[Doc-SIG] Cleaning up HTML output (part 1 - 'name' and numerical ids)

Sat, 06 Jul 2002 11:25:05 -0400

David Goodger wrote:
> fantasai wrote:
> > And numerical id's aren't very use-friendly.
> 
> Docutils actually uses names wherever possible.  I don't know that it
> could be improved much, but if you do, please let me know.

Well, let's take an example from your test.txt output:

 | <div class="section" id="structural-elements" name="structural-elements">
 | <h1><a href="#id21">Structural Elements</a></h1>

'name' is not a valid attribute for <div>, <li>, or most of the other elements
in HTML. It's used in forms, and it's used in the anchor tag. The above code
should be written one of three ways:

<div class="section" id="structural-elements">
<h1>Structural Elements</h1>

<div class="section">
<h1><a id="structural-elements" name="structural-elements">Structural Elements</a></h1>

<div class="section">
<h1><a name="structural-elements">Structural Elements</a></h1>

The first only works in browsers that support the 'id' attribute for targets,
but it is a cleaner syntax. The second is redundant. The third is not ideal, but
it works in every HTML browser I have ever come across.

You use the numerical ids to have headings refer back to their respective section
entries in the table of contents. I don't see that this is a particularly necessary
behavior to have--you can just link back to the table of contents as a whole, if
you really want to. Ideally, you'd put in a <link> to the table of contents in the
<head>:
         <link rel="toc" href="#table-of-contents" title="Table of Contents">

and leave it at that.

Unfortunatly, most browsers don't support <link>.

If linking back to the corresponding toc entry is important to you, then
identify the entries with the section's id preceded by 'toc-'.
For example:

  <li id="toc-structural-elements"><a href="#structural-elements">Structural
      Elements</a></li>

or

  <li><a href="#structural-elements" name="toc-structural-elements">Structural
      Elements</a></li>

IMO, having the headers as links is distracting. But that's just my opinion.

~fantasai