Re: generating documentation in a printable format...

[Stefan Kost <ensonic hora-obscura de>]

Simos Xenitellis schrieb:
> 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
>   
(1) and (2) looks like

\item[{\hyperlink{GtkToolbar}{GtkToolbar}}]

should actualy be

[\item{\hyperlink{GtkToolbar}{GtkToolbar}}]


(3) is
./docs/reference/gtk/migrating-GtkAction.sgml:197:
<member><guimenuitem>[ ] Full Screen</guimenuitem></member>

and I'd say the converter needs to be fixed in regard to handling []. The two issues where you sent the diffs are fixed in git HEAD of gtk.
What is the exact sequence of commands that you where running? I thinks it would be good to file bugs for dblatex then.


Stefan