[Doc-SIG] compact HTML output from Docutils

[David Goodger]

I've tweaked Docutils' HTML writer to produce more visually compact
HTML (less vertical whitespace).  HTML's mixed content models allow
list items to contain "<li><p>body elements</p></li>" or "<li>just
text</li>" or even "<li>text<p>and body elements</p>combined</li>",
each with different effects.  I'd prefer to stick with strict body
elements in list items, but they affect vertical spacing in browsers
(although they really shouldn't).

Does anybody know of a good discussion of vertical space issues for
HTML and/or CSS?

After trying various algorithms, I've settled on a hybrid:

- Check for and omit <p> tags in "simple" lists: list items contain
  either a single paragraph, a nested simple list, or a paragraph
  followed by a nested simple list.  This means that this list can be
  compact:

      - Item 1.
      - Item 2.

  But this list cannot be compact:

      - Item 1.

        This second paragraph forces space between list items.

      - Item 2.

- In non-list contexts, omit <p> tags on a paragraph if that paragraph
  is the only child of its parent (footnotes & citations are allowed a
  label first).

- Regardless of the above, in definitions, table cells, field bodies,
  option descriptions, and list items, mark the first child with
  'class="first"' if it is a paragraph.  The stylesheet sets the top
  margin to 0 for these paragraphs.

I'd appreciate feedback, especially from people using different
browsers (I've checked IE and Mozilla on both MacOS & Win2K, and
Netscape 4 & 6 on MacOS).  Please browse the following files:

- http://docutils.sf.net/tools/test.html
- http://docutils.sf.net/spec/pep-0287.html
- http://docutils.sf.net/spec/pep-0000.html

Is the above approach correct?  Does the generated HTML come out
right?  Should the compact output be optional (i.e. should there be an
option to turn it off)?  Any suggestions?

Get your snapshots here: http://docutils.sf.net/docutils-snapshot.tgz

-- 
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/