[Firebird-docs] ATTN Darcy, and all: PDF rendering

[Paul V. <pa...@vi...>]

Hi Darcy,

Here are the issues I've found in the PDF you made with Ventura. I
have no idea how easy or difficult it will be to fix them, but most of
them *must* be fixed because they really "break" the doc.

Just an idea: would it be easier if you imported the HTML instead of
the XML? Because in the HTML, the rendering has already taken place. I
can easily set up a target so that what needs to become one PDF file
is also in one HTML file (unlike now, where it is chunked into
top-level sections).

OK, here goes:

- "Chapter One" shouldn't be there (single-chapter doc).

- Can URL/email links be made to work? It's not critical, but it
  would be nice.

- Speaking of which: URL links wreak havoc all over the place: they
  are formatted as a block (should be inline) and they "outdent"
  from their surrounding blockquotes, listitems etc. instead of
  respecting the current indentation/margins. They also tend to
  break away from the listitems they're supposed to belong to.

- <sect1>: Leave more vertical space before it (say 1.5 times as much
  as now). Within an <article> (as opposed to a <book>) it would be
  nice if <sect1>s started on a new page (but not very important).

- Blockquotes: bit more space before them (one line's worth).

- <quote> tags should not translate to italics. Italics emphasize,
  whereas quotes often relativize. Best translate them as surrounding
  double-quotes.

- Sometimes spaces get eaten after a tag, e.g.: "primerif" and
  "primersif" under "DocBook XML - An Introduction".

- Internal links should work.

- <programlisting>s should honour whitespace, especially newlines
  and start-of-line spaces/tabs. A fixed-width font is also highly
  desirable here.
  OTOH, no extra whitespace or newlines must be added. This goes
  wrong under "Typing text" where the text demonstrates that an
  "unreadable" layout has the same validity as a pretty one.

- If a programlisting occurs within an indented block, it should not
  "outdent" from the block. Same goes for <example>s.

- The element <sgmltag class="starttag"> should be translated to '<'
  + element content + '>', like in the HTML. If class = "endtag", it
  should be rendered as '</' + constant + '>'. For "emptytag", it's
  '<' + content + '/>'
  Now you see in the PDF: "italics is a start tag, italics is an end
  tag, ..." - you don't see the difference between the two.

- The element <sgmltag class="genentity"> should be translated to '&'
  + element content + ';', like in the HTML. In the PDF it now says:

      ...you type this:

        lt

      That's an ampersand, followed by the letters l and t (for less
      than), followed by a semicolon.

  The "lt" should be "&lt;" of course, otherwise the whole point of
  the text is lost.

- Content of <literal> elements should stand out typographically. The
  usual solution is to use a fixed-width font with the same size as
  the surrounding text. No italics or boldface. And keep it inline.

- <emphasis> should stand out, preferably as italics. But:
    <emphasis role="bold"> should always be rendered in boldface.

- Admonitions (<caution>, <important>, <note>, <tip>, and <warning>)
  should be recognizable as such. They should be formatted as a block,
  indented or with a frame around it, possibly in a smaller font, and
  with some kind of caption denoting what it is: a note, a warning,
  a tip, ...
  Of course this can also be a graphic (light bulb for a tip, excl.
  mark for a warning etc.)

- Paragraphs within a listitem shouldn't get bullets of their own -
  this makes them look like extra listitems. I see this happen in
  itemizedlists and variablelists.

- listitems in an <orderedlist> should not have bullets, but (by
  default) Arabic numerals. Unless otherwise specified by the
  "numeration" attribute.

- <literallayout> and <screen> MUST honour the source layout!
  <screen> must have fixed-width font.

- Tables: <tfoot> elements should wind up at the foot of the table,
  not near the top. <thead> and <tfoot> content should be printed
  bold or italic (preferably bold) to distinguish them from ordinary
  rows.
  "align" attributes should be honoured if possible.

- command, application, superscript and subscript tags should be
  honoured. Same for all those other tags discussed under "Various
  inline elements". It's OK if you render them all the same as
  <literal> (see above).

- <computeroutput> is an inline element and shouldn't be formatted
  as a block.

- Spaces before a smiley :-) are eaten in the PDF.

- A nested list should have its own indentation level and preferably
  also another type of bullet. This goes wrong under "Style".


Greetings,
Paul Vinkenoog