Re: generating documentation in a printable format...

[Simos Xenitellis <simos lists googlemail com>]

On Tue, Jun 30, 2009 at 9:39 PM, Stefan Kost<ensonic hora-obscura de> wrote:
> Murray Cumming schrieb:
>> On Mon, 2009-06-29 at 22:23 +0300, Stefan Kost wrote:
>>> Unfortunately the docbook to pdf chain is in terrible state these
>>> days.
>>
>> It's not that bad if you can use fop. And that's not as difficult as it
>> once was. I think most of the bugs I found last time are now fixed.
>> http://www.murrayc.com/blog/permalink/2009/01/20/flumotion-documentation/
>>
> I tried using various versions of fop, but get java backtraces for all of them.
> I filed bugs for those, but nothing happens there :/

An additional method to generate PDF is to use dblatex with the LaTeX
or XeTeX backends.
XeTeX is getting more popular as it works better with Unicode.
See http://simos.info/blog/archives/31 for examples.

I just tried generating the PDF documentation for gtk-docs using
dblatex and either the LaTeX/XeTeX backends.

I got a warning for

warning: failed to load external entity
"/home/user/checkout/gnome2/gtk+/docs/reference/gtk/xml/migrating-GtkLabel-links.sgml"
/home/user/checkout/gnome2/gtk+/docs/reference/gtk/gtk-docs.xml:65535:
element include: XInclude error : could not load
/home/user/checkout/gnome2/gtk+/docs/reference/gtk/xml/migrating-GtkLabel-links.sgml,
and no fallback was found

and "pdflatex" (Latex backend) failed at the error

pdflatex failed
gtk-docs_tmp.tex:79745: Lonely \item--perhaps a missing list environment.
gtk-docs_tmp.tex:79745: leading text: ...m[{\hyperlink{GtkToolbar}{GtkToolbar}}]
gtk-docs_tmp.tex:79746: Lonely \item--perhaps a missing list environment.
gtk-docs_tmp.tex:79746: leading text: ...perlink{GtkToolButton}{GtkToolButton}}]
gtk-docs_tmp.tex:79748: Lonely \item--perhaps a missing list environment.
gtk-docs_tmp.tex:79748: leading text: ...aratorToolItem}{GtkSeparatorToolItem}}]
gtk-docs_tmp.tex:80766: Lonely \item--perhaps a missing list environment.
gtk-docs_tmp.tex:80766: leading text: ...perlink{GtkToolButton}{GtkToolButton}}]
gtk-docs_tmp.tex:80983: Lonely \item--perhaps a missing list environment.
gtk-docs_tmp.tex:80983: leading text: ...aratorToolItem}{GtkSeparatorToolItem}}]
gtk-docs_tmp.tex:147680: Missing number, treated as zero.
gtk-docs_tmp.tex:147680: leading text: [ ]
gtk-docs_tmp.tex:147680: Illegal unit of measure (pt inserted).
gtk-docs_tmp.tex:147680: leading text: [ ]
gtk-docs_tmp.tex:147680: Missing number, treated as zero.
gtk-docs_tmp.tex:147680: leading text: [ ]
gtk-docs_tmp.tex:147680: Illegal unit of measure (pt inserted).
gtk-docs_tmp.tex:147680: leading text: [ ]

and xelatex (XeTeX backend) failed similarly at

xelatex failed
gtk-docs_tmp.tex:79745: Lonely \item--perhaps a missing list environment.
gtk-docs_tmp.tex:79745: leading text: ...m[{\hyperlink{GtkToolbar}{GtkToolbar}}]
gtk-docs_tmp.tex:79746: Lonely \item--perhaps a missing list environment.
gtk-docs_tmp.tex:79746: leading text: ...perlink{GtkToolButton}{GtkToolButton}}]
gtk-docs_tmp.tex:79748: Lonely \item--perhaps a missing list environment.
gtk-docs_tmp.tex:79748: leading text: ...aratorToolItem}{GtkSeparatorToolItem}}]
gtk-docs_tmp.tex:80766: Lonely \item--perhaps a missing list environment.
gtk-docs_tmp.tex:80766: leading text: ...perlink{GtkToolButton}{GtkToolButton}}]
gtk-docs_tmp.tex:80983: Lonely \item--perhaps a missing list environment.
gtk-docs_tmp.tex:80983: leading text: ...aratorToolItem}{GtkSeparatorToolItem}}]
gtk-docs_tmp.tex:147680: Missing number, treated as zero.
gtk-docs_tmp.tex:147680: leading text: [ ]
gtk-docs_tmp.tex:147680: Illegal unit of measure (pt inserted).
gtk-docs_tmp.tex:147680: leading text: [ ]
gtk-docs_tmp.tex:147680: Missing number, treated as zero.
gtk-docs_tmp.tex:147680: leading text: [ ]
gtk-docs_tmp.tex:147680: Illegal unit of measure (pt inserted).
gtk-docs_tmp.tex:147680: leading text: [ ]
gtk-docs_tmp.tex:149003: Undefined control sequence.
gtk-docs_tmp.tex:149003: leading text: }
gtk-docs_tmp.tex:149003: Undefined control sequence.
gtk-docs_tmp.tex:149003: leading text: }
gtk-docs_tmp.tex:149008: Undefined control sequence.
gtk-docs_tmp.tex:149008: leading text: }
gtk-docs_tmp.tex:149008: Undefined control sequence.
gtk-docs_tmp.tex:149008: leading text: }
gtk-docs_tmp.tex:149025: Undefined control sequence.
gtk-docs_tmp.tex:149025: leading text: }
gtk-docs_tmp.tex:149025: Undefined control sequence.
gtk-docs_tmp.tex:149025: leading text: }

I did not look into the details yet as to what needs fixing. It takes
over 8 minutes on my system to process the gtk+ reference
documentation (huge document, 12MB) and it's painful to debug.
There is a --debug option in dblatex that allows to keep the
intermediate files, thus can use to locate what's wrong.

The translatable documentation of GNOME 2.26 compiles to PDF with
dblatex (xetex backend) without much trouble,
http://www.gnome.gr/files/gnome226/GNOMEGRDELIVERABLE/

Simos