Re: Problem about secondly run "gtkdoc-mkdb"

[Stefan Kost <ensonic hora-obscura de>]

cee1 schrieb:
> I've edited the foo-docs.sgml, following the glib style:
> """
> <!ENTITY bar1 SYSTEM "xml/bar1.xml">
> <!ENTITY bar2 SYSTEM "xml/bar2.xml">
> ...
> """
> , and then reference  not include them. The problem can be avoid.
Don't do this. glib is not doing this anymore. This makes your docbuild
slow. Use xml instead of sgml and then use xi:inlcude. Using entities
for includes will expand the entities in each document.

Stefan

>
> 2009/8/3 Stefan Kost <ensonic hora-obscura de
> <mailto:ensonic hora-obscura de>>
>
>     cee1 schrieb:
>     > 2009/8/3 Stefan Kost <ensonic hora-obscura de
>     <mailto:ensonic hora-obscura de>>
>     >
>     >> cee1 schrieb:
>     >>> 2009/8/2 Stefan Kost <ensonic hora-obscura de
>     <mailto:ensonic hora-obscura de>>
>     >>>
>     >>>> hi,
>     >>>>
>     >>>> cee1 schrieb:
>     >>>>> Hi all,
>     >>>>> I'm using gtk-doc(1.11) to manager documents of my small
>     project. I
>     >>>>> encounter some problems like: "../xml/foo.xml:161: parser
>     error :
>     >> Entity
>     >>>>> 'ast' not defined", when secondly running gtk-doc.
>     >>>>>
>     >>>>> The steps are:
>     >>>>> 1) gtkdoc-scan --module=foo --source-dir=../../foo
>     >> --ignore-headers="a.h
>     >>>>> b.h"
>     >>>>> 2) gtkdoc-mkdb --module=foo --source-dir=../../foo
>     --output-format=xml
>     >>>>> --expand-content-files="" --main-sgml-file=foo-docs.sgml
>     --sgml-mode
>     >>>>> --output-format=xml --ignore-files="a.c b.h"
>     >>>>> ...
>     >>>> Are you using the normal gtkdoc.make included in your makefile?
>     >>>>
>     >>> Yes.
>     >>>
>     >>>>> I find in the second time, gtkdoc-mkdb generates XML files
>     missing the
>     >>>>> following:
>     >>>>> <?xml version="1.0"?>
>     >>>>> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
>     >>>>>              
>      "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd
>     >> ">
>     >>>> The doctype is copied if the foo-docs.sgml or foo-docs.xml
>     main document
>     >>>> has it.
>     >>>> Is the project publicly available somewhere?
>     >>>>
>     >>> If the foo-docs.sgml already exists, rerunning gtkdoc-mkdb
>     will generate
>     >>> doctype-missing XML files, hence cause the
>     "../xml/foo.xml:161: parser
>     >> error
>     >>> : Entity 'ast' not defined".
>     >>>
>     >> How come it does not exist earlier? gtkdoc creates a template
>     on the very
>     >> first
>     >> run, but you need to edit that to suit you and add it to your
>     version
>     >> control
>     >> system.
>     >
>     >
>     > After first run gtk-doc,  the foo-docs.sgml is there. Re-run
>     gtkdoc-mkdb
>     > will generate doctype-missing XML files, unless delete the
>     foo-docs.sgml.
>     >
>     > The same problem exists in glib, when I do:
>     >
>     > 1) In the top-level directory of glib, run ./autogen.sh
>     --enable-gtk-doc
>     >
>     > 2) cd docs/reference/glib        # could see the glib-docs.sgml
>     is shipped
>     > with glib
>     >
>     > 3) make                               # check files in XML
>     directory, they
>     > are missing the "doctype"
>     >
>     > 4) rm -f glib-docs.sgml && make clean && make
>     >
>     > 5) now check files in XML directory, they are OK.
>
>     I had no time to try myself. If the generated foo-docs.sgml has no
>     DOCTYPE in
>     the header, just add it yourself. Or try adding
>     "--output-format=xml" to
>     MKDB_OPTIONS in your Makefile.am for the docs.
>
>     I had a quick look at the sources though and it needs a fix. If
>     there is no
>     foo-docs.{sgml,xml} we add a xml DOCTYPE to add generated files,
>     but generate
>     the main document as sgml. Please file a bug to bugzilla.gnome.org
>     <http://bugzilla.gnome.org>.
>
>     Stefan
>
>     >
>     >
>     >> Could you also try with gtk-doc from git.gnome.org
>     <http://git.gnome.org> - I'd like to release
>     >> 1.12 in
>     >> september, would be good to see if its already fixed?
>     Unfortunately I'll be
>     >> on
>     >> vacation starting from tomorrow, so I won't be able to reply in
>     august
>     >> anymore.
>     >> Hopefully someone else on the list can help.
>     >>
>     >> Stefan
>     >>
>     > OK, thanks any way.
>     >
>     >>> The project is not public yet, since the documents not ready.
>     >>>
>     >>>> Stefan
>     >>>>
>     >>>>> Any suggestions?
>     >>>>> Thanks.
>     >>>>>
>     >
>
>