[Docutils-develop] LaTeX/PDF critique

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

Engelbert wrote:
>>> p.s. still no interest complaining about rst to latex to pdf
>>> conversions ?

Thanks for posting new PDFs.  For the benefit of others, here are the
URLs:

    http://docutils.sf.net/sandbox/grubert/tools.pdf
    http://docutils.sf.net/sandbox/grubert/test.pdf

These documents look *very* good!  You've made a lot of progress.

Some observations for tools.pdf:

* Since TeX uses curly quotes (which it expresses ``thusly''), perhaps
  the LaTeX writer could convert regular double-quotes to TeX-style
  quotes?  Or can TeX/LaTeX do that automatically?  Currently all
  double-quotes look like (just blur your eyes a bit ;)::

      99    99
        this

  whereas they should look like this::

      66    99
        this

  If it's not feasible to get proper curly quotes, then the Writer
  should use straight quotes.  Better to be ugly (straight quotes)
  than wrong (bad curlies).

  If the LaTeX Writer does this conversion, it should be careful *not*
  to do it for literal blocks and inline literals.  No curly quotes in
  Python code ;)

* Field lists should be rendered as two-column tables, like the
  docinfo fields.  See
  http://docutils.sf.net/spec/doctree.html#field-list ("Details"
  subsection, "Processing" item).

* In tools.pdf, the source text ``<directory>`` is being rendered as
  ``!directory?``, but with the inverse-! (&iexcl;) and inverse-?
  (&iquest;) characters.

* Shouldn't literal blocks be indented, or have some kind of
  decoration (solid left margin, etc.)?  I think relying on the
  typeface is too subtle; indentation helps distinguish literal blocks
  from the surrounding text.  Inline literals look fine the way they
  are.

* (I'm sure you already are aware of this.)  The table in tools.pdf,
  which is longer than one page, is not breaking across page
  boundaries.  Also, the paragraphs inside table cells are being
  merged together (ISTR this coming up before).

* Table column widths can be taken from the "colwidth" attributes of
  "colspec" elements in the doctree.  Attribute values are relative
  numbers, originating from the number of character columns in the
  source text.  For tools.txt, the table's colwidth values are "20"
  and "50", so the first column should be 2/7 and the second column
  5/7 wide.

And test.pdf:

* Bibliographic field lists (docinfo) should have ":" appended to each
  field name.

* I see you got the address line-breaking right.  Great!

* The "dedication" and "abstract" bibliographic fields get transformed
  to "topic" elements, specifically <topic class="dedication"> and
  <topic class="abstract"> in the internal doctree.  Topic should be
  rendered like sections (i.e., title above the body), only indented
  or otherwise set off from the rest of the document.  See
  http://docutils.sf.net/spec/doctree.html#topic .

* It would be useful if "problematic" elements acted as internal
  references to their system messages.  Back-links are also useful,
  for system messages as well as for footnotes and citations.

* From doctree.txt, definition list terms and classifiers "should be
  separated visually, typically by spaces plus a colon or dash."  I'd
  recommend a colon, so the input looks like the output:

      term : classifier
          definition...

* I'd recommend that option list tables *not* have visible borders and
  row/column separators.

* From test.pdf, section 2.10, I guess that it's hard to render
  complex tables properly in LaTeX? ;)

* The "image" directive in section 2.14.2 is producing an *inline*
  image, whereas it should be a block element (flush left, separated
  by a blank line from the text above & below).

* Why does the "figure" (section 2.14.2) appear at the very end of the
  document?  I could understand it floating to the top or bottom of
  the page it appears on, but it moves too far.

* Why are footnotes (a) mostly at the end of the document, and (b)
  spaced so far apart?

* In line blocks, all whitespace is significant.  Look at the stanza
  beginning "But can a bee be said to be" in section 2.14.5; each line
  should be indented more than the last.

  The same thing applies to inline literals, although to a lesser
  extent.  In other words, it would be nice to have significant
  whitespace there, but not crucial.  Using a recent browser, look at
  the whitespace in the inline literals in the second paragraph of
  http://docutils.sf.net/tools/test.html#inline-markup .

* The admonitions ought to be more distinctive.  They should jump out
  at the reader.  There are degrees of alerts.  The HTML Writer shows
  a little bit of what I mean, but it should be more distinctive too.

Please feel free to take this list and incorporat it in your To-Do
list.

I bet you're learning a lot about LaTeX!

Do you consider the Writer ready to migrate into the docutils package?
It doesn't have to be perfect, just `reasonably complete`_ as I've
defined before.  I didn't notice anything missing from test.pdf, so it
looks like it is reasonably complete.  I'd like to review the code
first though; please let me know if you think its ready.

.. _reasonably complete:
   http://docutils.sf.net/spec/notes.html#reasonably-complete

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