Re: [Firebird-docs] New PDF Build from Ventura

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

Hi Darcy,

> You can find a copy of the latest PDF document build at:
>
> http://firebird.methyl.ca/writing.pdf
>
> The are significant number of improvements in this document. A
> couple of issues still remain outstanding (tips / important block
> text).

OK, I had a thorough look at it today. Some of the points listed
below are simply copied from my "old" list; some have changed or
disappeared, and one or two new issues showed up.

But before I start the list let me first say that yes, a lot has been
improved and I noticed that too. Especially the URL links - which at
first didn't work but made lots of trouble - are working great now,
and are nicely inlined in the text. Thanks! I'm not going to list all
the improvements here, but I just wanted to say this because otherwise
it looks like I'm only criticizing (as the list is still pretty long).


List of suboptimalities (nice bit of Newspeak, eh?):
====================================================

+ <sect1>: Could use more vertical space before it (say twice as much
  as now). And the headers should be bigger.

+ <orderedlist>: numeration loweralpha should be rendered as a, b, c...
  instead of A, B, C...

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

+ Internal links should work.

+ Still trouble with nested lists, e.g. under "Style" where the nested
  list OUTdents instead of indents, and doesn't have bullets.

+ <orderedlist> under "Docwriter's block" is enumerated D, E, F...
  instead of 1, 2, 3... Also, <para>s *within* a listitem get a
  capital letter and are thus promoted to a listitem (the famous
  paras-in-listitems problem).

+ New: Under "Your copyright" the entire paragraph now gets a bullet,
  and is also moved closer to the section header. The URL link in this
  paragraph doesn't work (unlike most, which are fine now).

+ <programlisting> should have fixed-width font.

+ <screen>: has fixed-width font now, good! But it shouldn't add a
  three-character (or thereabouts) wide left margin.

+ <variablelist>: preferably, they should be indented as a whole, just
  like <itemizedlist> and <orderedlist>, *and* the <listitem>s should
  be indented wrt the <term>s - just like in the HTML version. If this
  is a problem the <term>s could be on the same indentation level as
  the surrounding text, but the <listitem>s should really indent.

+ <sgmltag>: start- and enddtags are rendered correctly now, but
  empty-element tags still aren't (need '<' prefix and '/>' suffix).

+ admonitions: In the <important> rendering, the blue filling is not
  aligned with the frame. Or is that intentional?
  <note>s (and possibly others) are still not recognizable as such.

+ spaces next to tags still get eaten sometimes, e.g.:

    cvs update -d[ only if you want to update first]

  Upon closer scrutiny, it turns out that not only the space between
  "-d" and "[" disappeared, but even that the "[" was pulled into the
  "command" rendering (selecting text in the PDF makes this clear).
  There was also a space between "t" and "]".

  Also, under "Elements we use frequently":

    filename- command - application- envar
    subscript- superscript
    varname- constant- database

  etc...
  In the source, the hyphens never touch the words. The words
  are tagged, so this is again a case of the spaces-adjacent-to-tags-
  get-eaten syndrome.

  Finally, under "function - parameter - returnvalue":

    promptis

  But I'm sure there's more... :-)

+ <literallayout> should not indent wrt its context, but there should
  be some vertical space (say: one empty line) above and below it.

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

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

+ Spaces before a smiley are still eaten in the PDF - even in
  UNprofessional docs! Woe, woe! :-)


Greetings,
Paul Vinkenoog