Re: [Firebird-docs] Minor DocBook -> PDF Improvement

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

Hi Phil,

> In build XML, if you change...
>
> <style basedir="${src.dir}/docs"
>                      style="src/docs/docbook/html/docbook.xsl"
>                      destdir="${printablehtml.dir}"
>                      includes="firebirddocs.xml"/>
>
> ...to...
>
> <style basedir="${src.dir}/docs"
>                      style="src/docs/docbook/html/docbook.xsl"
>                      destdir="${printablehtml.dir}"
>                      includes="firebirddocs.xml">
>      <param name="title.margin.left" expression="0pc"/>
> </style>
>
> It will sort out the alignment of the all the Titles in the PDF
> output

Thanks, that looks better indeed. I've changed it. But in the pdf
target, not in the printablehtml target like you did ;-)


> We use DocBook for all our documentation, and the PDF output we get
> is more than acceptable, I could look in to see what we are doing
> different if that is of any interest?

Have you ever rendered the manual module stuff to PDF with our current
build setup? Well I suppose you have :-) I think the result really
sucks. I want to learn more about how this works, but that will take
time. So yes, if you have any ideas for improvements I would really
appreciate it. Here are some of the things I would like to see
changed:

- More spacing between sections, i.e. titles should be closer to their
  own section than to the previous one.

- Can links be made visible as such (underlined or so)?

- Generated URL links are broken. They point to "URL"s like this:
  http://url(news://news.atkin.com/sourceforge.firebird-doc)

- Widows/orphans: sometimes a section header winds up at the bottom
  of a page.

- Non-monospaced <literallayout> is justified. See example in:
    Docwriting Howto
      :: Writing your DocBook doc
        :: Elements we use frequently
          :: Program listings, screens, literal layout, and examples
            :: literallayout

- Variablelists are rendered as (frameless) tables. The effect is that
  the <listitem> content moves considerably to the right. If you have
  preformatted stuff in there (which does happen) it runs off the
  right edge of the page.

  If the <term> of a <varlistentry> exceeds a certain length, in the
  PDF it overlaps with the <listitem> text. See example in:
    Docwriting Howto
      :: Writing your DocBook doc
        :: Elements we use frequently
          :: Various inline elements

  All of this senseless bloodshed can be avoided if - just like in
  HTML - the <term> (<dt> in HTML) is placed on a line of its own, and
  the <listitem> (<dd> in HTML) on the lines *below* it, and indented
  by a couple of characters.

- Ouch! Random hyphenating in tables! Like this:
          InterB-
          ase

- An Appendix is rendered as if it were a subsection of the preceding
  section. It doesn't start on new page (ideally I would like to see
  it started on a recto page).

- Most headers are way too big, which is especially disturbing for
  "minor" sections.

- Can the PDF output be "chunked" just like the HTML? Now we can only
  produce the entire docset in one PDF. This is not reader-friendly,
  and it gets worse as more docs are added. It would be ideal if each
  <book> was in a separate PDF document. It would be even more ideal
  if a cross-document index would be generated (like with the Borland
  6.0 docset).

- It is possible to have a navigation frame generated?


If you have ideas to improve any of these points, that would be great.


Greetings,
Paul Vinkenoog