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

[David Goodger]

[David]
>> Should we be supporting older browsers?  Or can we write code to the
>> latest & greatest specs exclusively?

[fantasai]
> I think it's a good idea to support older browsers--as an option, at
> least.  Not everybody has the latest and greatest software, and some
> older systems /can't/ support the latest and greatest software.

I agree, to a point.  I think Docutils should target the current
"mainstream", the software that most people are currently using.
Neither the bleeding edge (extreme early adopters) nor the trailing
edge (extreme laggards) need be considered if it's a pain to do so.
In any case, if there are problems for users outside the mainstream,
fixes will have to come from those users.

> Ah, I forgot to mention another problem with numerical IDs--
> If I add or delete a chapter, all the IDs from there on
> change. Suppose I had a bookmark to that part of the document. It
> wouldn't point to the right element anymore. It's not critical in a
> table of contents, where there's only a few list items to scroll
> through. But in general, you do *not* want numerical identifiers,
> and it's a good practice to avoid them.

I would agree if we were using numerical IDs exclusively, but we're
not.  We use named IDs wherever possible; a section titled
"Introduction" will have ID "introduction", and that won't change even
if a "Preface" section is inserted earlier in the document.  This
breaks down if we have two identical names: with two "Introduction"
sections, the first keeps the ID "introduction", but the second one
gets a numbered "id1".  I don't see any way around that.

The place we *are* using numerical IDs exclusively, is in TOC
back-references.  I don't think anyone would ever want to link to a
table of contents entry; to the TOC itself, perhaps, but not to an
arbitrary *entry*.  I've added automatic IDs to generated TOCs, taken
from the supplied or default title ("Contents" in English).

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/