Re: gnome-doc perl script

[Rodrigo Moya <rmoya tsai es>]

Rodrigo Moya wrote:

> Hi all!
>
> I've seen in the $datadir/doc directory, the gnome-doc script. My
> question is, why is it there (not in $PATH)? Should I use this script to
>
> generate docs for lib functions, or is it better to use gtk-doc?
>

I've included two files generated by gnome-doc in a Docbook document, and
everything appears ok, but after the inclusion of the first of these two
files, the generated HTML finishes, not showing up the rest of the document:

In gnome-db.sgml I've got:

<sect1>
      <title>Function Reference</title>
      <para>
      The following sections describe the functions available to the
      user of the GDA client library. Some elements in this library,
      especially enums are imported from the IDL source directory. As
      soon as i find out how to include those definitions with the
      gtk-doc system, the documentation wil be lot more complete and
      many cross-references will start to work.
      </para>
    &gda-gda-clnt

    </sect1>
  </chapter>

Then the document continues with some <chapter>, and in one of them there is:

<sect1>
      <title>Function Reference</title>
      <para>
      The following sections describe the functions available to the
      user of the GDA widget library.
      </para>
      &gda-gda-clnt-ui
    </sect1>
  </chapter>

But everything after the &gda-gda-clnt line is not included neither in the TOC
nor in the generated HTML. In fact, in the TOC is only included after
"Function Reference", the section for the first function in the &gda-gda-clnt
entity; the rest is not included. I've seen that gnome-doc generates a
<refentry> for each function, and the docbook guide says these elements can be
contained in <sect1> elements, which is my case, so what's the problem? or is
it that I shouldn't use this script and use gtk-doc instead.

Thanks