[Docutils-develop] Re: LaTeX/PDF critique

[<gr...@us...>]

On Wed, 6 Nov 2002, David Goodger wrote:

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

julien did the table stuff and i think we both learned a lot about
latexs table and other commands by this.

> 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).

is in the todo (latex2e-README.txt (someday i wipe my sand/dustbox))


>   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).

i want to stay away of tables as long as possible. in latex you
have tabular, tabularx, supertabular, longtable, ltxtable and
table. some are duplicates or extensions. but there is more than
one table environment. e.g. some tables may not be broken so
i use tabular, but then it might be moved around.

i would go for decriptions for docinfo fields too, this is like:

<b>field:</b> the description breaking here
  and continuing intended.

<b>another:</b> some other ...

the reason why i donot use it is the space between the entries.
but these are much easier than tables.

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

donot talk about intendation (see test.txt line_block) latex
is sovereign over space vertical and horicontal.

> * (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).

i did not have a look at it, packed tools.pdf just because
i wanted a real document, not only the test. but the breaking
environment is already in todo.

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

i know: latex has an abstract environment and thanks (a footnote to
the document title), but as described earlier, i am not sure about
the direction. we use pagenumbering from latex and section numbering
from docutils (docutils has sectionnumbering because html does not have
it, but docutils uses <ol> numbering from html).

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

i tried to get the picture, linking except the bookmarks, are by
julien. so more to learn for me.

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

i too ?

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

because it is hard.
latex does it great (for me). up to know i seldom used multicolumns
not speaking of multirows.

what we might learn from latex is longtables have
  header for first page : e.g. column headings
  footer                : "continued on next page" (could be generated by
                          docutils).
  header on following pages : "continued from previous page" and the
                          column headings
  footer on last page   : plain line.

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

latex figures are moveable (as are tables, what should it do if it
does not fit on this page) therefore a reference to a figure says
"see fig.132" and there is a "list of figures".

<SNIP>
> Please feel free to take this list and incorporat it in your To-Do

feel free to do it yourself :-) my sandbox has no fence.

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

for me it is ready, except for one or two things
BUG all enumerations start at one.
BUG enumerations can not nest ad lib.

then i would have real documents: i go for the docutils documentation.
tools/test.txt is then used to make short snippets of problemtatic
constructs.

review and criticize

-- 
 BINGO:
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+