Re: [Docutils-develop] Re: Xsl for rst docs.

[David G. <go...@py...>]

Ray Leyva wrote:
> Working by running html.py on tools/test.txt, and checking the
> results ( visually / manually )

How is the HTML being rendered?

> versus what I get when I transform tools/test.txt with
> docutils-xml.py, and apply xsl stylesheet to the resulting test.xml
> documnt.  In some cases there are disparaties, what is the best way
> to determing what it *should* be?

The internal document tree is described in spec/doctree.txt
(http://docutils.sf.net/spec/doctree.html); it specifies how
attributes should be interpreted and processing expectations.

The output should match the input as much as possible.  I haven't
written anything to specify what the output should be.  The HTML
output assumes a modern graphical browser (Mozilla, MSIE, etc.) that
understands and correctly processes cascading stylesheets (at least
level 1, preferably level 2 also).  Support for stylesheets is
improving, but there are differences between browsers.  I check the
rendering on Mozilla and MSIE specifically.

> For instance in the examples below I believe my interpretation to be
> more correct, but I may be wrong please let me know.
> 
> Specifically on the enumerated lists samples :

It took me a while to see what the difference was.  Please point out
the differences explicitly.  I believe you mean that in the HTML, the
enumerators of list items are always arabic numerals, where some ought
to be letters or roman numerals instead.

I've seen this before from people using older browsers, especially
text-based browsers (links/lynx?).  The rendering of enumerators is
completely governed by the stylesheet, so either the browser can't
find the stylesheet (try using "--embed-stylesheet"), or it can't
understand it (try a recent Mozilla or MSIE).

If HTML that doesn't rely on stylesheets is desired, a new Writer
component is needed.  As I've said before, the writers/html4css1.py
module I wrote is a proof of concept, reference implementation, but it
doesn't have to be the only game in town.

I've updated the FAQ with some of these issues:
<http://docutils.sf.net/FAQ.html>.

-- 
David Goodger  <go...@py...>  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/