GNOME.org
 

Re: generating documentation in a printable format...

Stefan Kost schrieb:
> 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
>   
I filed bugs:
https://sourceforge.net/tracker/?func=detail&aid=2818211&group_id=72607&atid=535062
https://sourceforge.net/tracker/?func=detail&aid=2818215&group_id=72607&atid=535062
https://sourceforge.net/tracker/?func=detail&aid=2818216&group_id=72607&atid=535062

Stefan
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]