Re: Documentation format

[Mark Galassi <rosalia cygnus com>]

    Gianluca> developers) so speaking with a debian developer I have a
    Gianluca> idea: why we don't make the standard for the
    Gianluca> documentation of all the gnome project the sgml format ?

Gianluca, you are a bit behind on your email (I cannot blame you!): we
have already decided to use SGML, and in particular DocBook, which
allows the embedding of man page information.

[when you say "the sgml format", you are using very ambiguous
language.  SGML is a framework, not a particular markup language.
DocBook is the particular markup language we are using.  I suspect you 
were thinking of LinuxDoc, which is a rather poor SGML format and on
its way out: the LinuxDoc project is migrating to DocBook.]

    Gianluca> Another point is the method to extract the doc formthe
    Gianluca> code. Using the xcoral editor I can create a coherent
    Gianluca> docs for the code that look like this:

Horacio has already worked on that: take a look at
gnome-libs/devel-docs/gdoc/README for his proposal and tool.  I think
it's in early stages, but I think it's what you are talking about.

There has been a big discussion in gnu.misc.discuss about Knuth's
literate programming, and the consensus I have seen is that it's more
of a tool for browsing and documenting source than for publishing
documentation.

----  here is that README file:  ----

This is the first release of gdoc, the GNOME Documenter. 

It's intended to be used to autodocument the GNOME libgnome/libgnomeui API.

DOCUMENTING YOUR APIs
=====================

	Just add comments in the headers. For an example see gnome-about.h.

USING gdoc
==========

	You shouldn't need it unless you're enough brave to want to change
the code. I'm going to run it frequently to have it actualized. 

	If you want risks, get the c2man 2.41's sources (i've downloaded them
from ftp.debian.org) and patch it with c2man-to-gdoc-patch, compile and install
it. Now when you run make in devel-docs, it should detect it and generate the
new doc's.

CHANGING IT/HOW DOES IT WORKS
=============================

	Well, if you want to maintain the code, it's yours...

	After spending some time trying to understand how c2man works and
failing, i give up and started gdb.

	The result is really ugly. I wrote a new output_manual_pages that
dumps the c2man's structs to perl-code. This code is catched by gdoc.pl
and it generates the docbook output. 



GETTING GDOC (from the c2man FAQ)
=================================

Q. Where can I get an up-to-date already patched copy of c2man?

A. You can usually get the latest version via ftp:
        ftp /pub/Unix/Util/c2man-2.0.*.tar.gz from dnpap.et.tudelft.nl


Note: you still have to apply the Gnome patches to this version.