Re: generating documentation in a printable format...

[Simos Xenitellis <simos lists googlemail com>]

On Wed, Jul 1, 2009 at 8:41 PM, Stefan Kost<ensonic hora-obscura de> wrote:
> hi,
>
> Simos Xenitellis schrieb:
>> On Wed, Jul 1, 2009 at 12:11 AM, Simos
>> Xenitellis<simos lists googlemail com> wrote:
>>> 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.
>>>
>> ...snip...
>>
>> I generated PDFs with dblatex, using both backends,
>> http://simos.info/pub/gtk-reference-documentation-test-latex.pdf
>> http://simos.info/pub/gtk-reference-documentation-test-xetex.pdf
>>
>> I modified the intermediate .tex files in a few places so that a PDF
>> can be produced.
>>
>> Simos
>
>
> this looks pretty good. WOuld be nice to see a diff of what you changed. I
> wonder it those are things that could be fixed in dblatex. I'll try to integrate
> that into gtkdoc-mkpdf (maybe during guadec).

Here is a diff of the prominent issues,

diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 72aed73..42e5c55 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -171,6 +171,7 @@ expand_content_files =                              \
        migrating-GtkLinkButton.sgml            \
        migrating-GtkBuilder.sgml               \
        migrating-GtkTooltip.sgml               \
+       migrating-GtkLabel-links.sgml           \
        tree_widget.sgml                        \
        text_widget.sgml                        \
        question_index.sgml
diff --git a/docs/reference/gtk/tmpl/gtksettings.sgml
b/docs/reference/gtk/tmpl/gtksettings.sgml
index 5219c1a..cdc4a17 100644
--- a/docs/reference/gtk/tmpl/gtksettings.sgml
+++ b/docs/reference/gtk/tmpl/gtksettings.sgml
@@ -23,7 +23,7 @@ realized at least once. The following example
demonstrates a way to do this:
 <informalexample><programlisting>
   gtk_init (&amp;argc, &amp;argv);

-  /&ast; make sure the type is realized &ast/
+  /&ast; make sure the type is realized &ast;/
   g_type_class_unref (g_type_class_ref (GTK_TYPE_IMAGE_MENU_ITEM));

   g_object_set (gtk_settings_get_default (), "gtk-menu-images", FALSE, NULL);

Another issue is that when you use dblatex, it expects to find the
images/ directory inside xml/.
This can be solved by a symbolic link or by generating a big XML file
above xml/, with
xmllint --noent --xinclude --format gtk-docs.xml > gtk-docs-all.xml

Here are the errors and the relevant generated .tex file segment.

1.
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}}]

 79742 \subsection*{See Also}
 79743 \label{GtkToolItem.see-also}\hyperlabel{GtkToolItem.see-also}%
 79744
 79745  \item[{\hyperlink{GtkToolbar}{GtkToolbar}}] The toolbar widget
 79746  \item[{\hyperlink{GtkToolButton}{GtkToolButton}}] A subclass
of \hyperlink{GtkToolItem}{GtkToolItem} that displays buttons on
 79747       the toolbar
 79748  \item[{\hyperlink{GtkSeparatorToolItem}{GtkSeparatorToolItem}}]
A subclass of \hyperlink{GtkToolItem}{GtkToolItem} that separates
groups of
 79749       items on a toolbar

2.
gtk-docs_tmp.tex:80983: Lonely \item--perhaps a missing list environment.
gtk-docs_tmp.tex:80983: leading text: ...aratorToolItem}{GtkSeparatorToolItem}}]

 80980 \subsection*{See Also}
 80981 \label{GtkToggleToolButton.see-also}\hyperlabel{GtkToggleToolButton.see-also}%
 80982
 80983   \item[{\hyperlink{GtkToolbar}{GtkToolbar},
\hyperlink{GtkToolButton}{GtkToolButton},
\hyperlink{GtkSeparatorToolItem}{GtkSeparatorToolItem}}] The toolbar
widget
 80984         The parent class of
\hyperlink{GtkToggleToolButton}{GtkToggleToolButton}. The properties
 80985         "label\_widget", "label", "icon\_widget", and "stock\_id" on
 80986  \hyperlink{GtkToolButton}{GtkToolButton} determine the label
and icon used on
 80987  \hyperlink{GtkToggleToolButton}{GtkToggleToolButton}s.

3.
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: [ ]

147676 \begin{tabular*}{\linewidth}{l}
147677 Zoom In \\
147678 Zoom Out \\
147679 \textemdash{} \\
147680 [ ] Full Screen \\
147681 \textemdash{} \\
147682 ( ) High Quality \\
147683 ( ) Normal Quality \\
147684 ( ) Low Quality \\

For (1), (2), something is wrong with the labels. I do not know that
match LaTeX to diagnose.
For (3), it appears that the conversion scripts need to add some
escaping for []. (as in {[} {]}).

I am attending GUADEC as well. We can discuss about this.

Simos