GNOME.org
 

Re: generating documentation in a printable format...

Stefan Kost schrieb:
> 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
>   

I figured the commands. Its works great. I just committed it. Will now
read more to fine-tune the look a bit.

Stefan
>
> _______________________________________________
> gtk-devel-list mailing list
> gtk-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-devel-list
>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]