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

François Pinard pinard at iro.umontreal.ca
Mon Apr 21 19:47:43 EDT 2003


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:

* `doc/index.html' has references to `howto/index.xhtml', 'man/index.xhtml',
  `specifications/index.xhtml' and `vision/index.xhtml'.

* `doc/howto/woven.html' refers to `listings/HelloWorld/HelloWorld.html'
  correctly, yet the text says `Listing 2: HelloWorld.xhtml...' which does
  not exist; it also refers to `listings/TwistedQuotes/WovenQuotes.xhtml'
  and says so in the text, yet sadly, there is no corresponding `.html' file.

* `doc/howto/domtemplate.html' refers to `TwistedQuotes/WebQuotes.xhtml',
  while the text which announces `Listing 2: WebQuotes.html...', and sadly,
  the reference is correct while the text is not.

* `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.

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?

-- 
François Pinard   http://www.iro.umontreal.ca/~pinard




More information about the Twisted-Python mailing list