[Twisted-Python] Twisted 1.0.4 - `html' .vs. `xhtml'

[Andrew Bennetts]

On Mon, Apr 21, 2003 at 07:47:43PM -0400, Fran?ois Pinard wrote:
> Hello.
> 
> In the `doc/' hierarchy of the Twisted 1.0.4 distribution, some `.html'
> files have links to `.xhtml' files, where apparently `.html' files by the
> same base exist.  Should `.html' rather point to `.html' files whenever
> possible?  Here are possible points to visit:

Yes, the '.html' should link to '.html'.  They '.html' files are the source
format for our documentation generation system that will process these to
'.xhtml' files, with various nice things done to them (including changing
the links to point to the .xhtml).

This is actually a known problem (someone else reported this a couple of
days ago).  I'll take care of it in CVS later today.

[...]
> * `doc/howto/lore.html', `doc/api/private/twisted.lore.default.html' and
>   `doc/api/public/twisted.lore.default.html' also seem to indicate that
>   `lore' will generate `.xhtml'; I am not familiar with `lore', and cannot
>   say if it should or can generate `.html' instead.  If it can, it most
>   probably should for generated documents to pointed to by `.html' files.

Lore's default behaviour is '.html' -> '.xhtml'.  If you are reading the
docs, just ignore the .html files and read the .xhtml, which are nicer
anyway.

> P.S. - I'm using `links' by preference (fast startup and reasonable image
> support), which `links' does not seem to support `.xhtml' files.  Given that
> `.html' is pretty widespread and reasonably understood by all Web browsers,
> while `.xhtml' is more recent or specialised, would not it be a good idea to
> aim `.html' as a uniform standard base for interactive documentation, (given
> it ought to go through Web browsers), and offer `.xhtml' merely as an extra?

I suspect links is probably having problems with the lack of <!DOCTYPE ...>
declarations in the .xhtml files, which is a bug in microdom.  Hopefully
this will be fixed soon.

-Andrew.