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
|
