On Wed, Jun 13, 2001 at 05:16:03PM +0200, Eric Faurot wrote:
> Hi folks.
> Second attempt to get this message to the list.
>
> I've been working a bit on the documentation,
> I've added files in libgii/doc/docbook, namely
> libgii-api.sgml : (together with libgii-api-[input|control].sgml)
> hook for the api
> libgii.sgml : empty now, but will contain ggi documentation.
> I didn't touch the other files there to avoid breaking things in the
> current doc build process.
>
> People concerned with documentation writing, please try to follow
> the same policy. Comments and ideas are welcome as usual, especially
> from those familiar with docbook.
Hello, a few comments and suggestions.
1. Use ID attributes in the tagging of ALL sections in the
documentation. This makes the stylesheets generate a sane name and when
you add pages doesn't break existing bookmarks.
2. Consider using a DocBook 'set' rather than a 'book' to encompass all
the documentation, with each module having its own 'book'. Put the
introductory material, common concepts, etc. in another book, and
xref/link extensively there to the other modules. It is more organized
that way, provides easy reference, and easier to manage.
3. The xrefs in libggi-faq.sgml are broken.
4. The stylesheet could be modified to generate all the refnames in the
refentry in the table of contents.
I'll have time from next week on, so if there is anything I can do...
--
Steve Cheng
鄭君博
