[dev-serveez] Re: Serveez Documentation Review

[stefan]

On Thu, 18 Oct 2001, J C Fitzgerald wrote:

> > One more hint: Most of the serveez API documentation gets automatically
> > created from the source code comments. If you have a specific question
> > about this process you are welcome to ask.
> > 
> Ah, I hadn't realised this.  I guess some of the changes will be further
> afield than just the documentation directory.  Where is the code which
> builds the documentation from the comments?

Ok. There are two main documentation files. These are `serveez.texi' and
`serveez-api.texi.in' in the doc/ directory.

The `serveez.texi' file is plain texi format. But it includes a file named
`guile-api.texi' which stems from `guile-api.texi.in'.

The `*.texi.in' files (serveez-api.texi.in and guile-api.texi.in) go
through an AWK script named `serveez-api.awk' which produces an SED script
from a set of input *.c and/or *.h files (source code). The resulting SED
files contain simple replacement statements. When piping the `*.texi.in'
files through these kind of SED files you get `*.texi' files.

e.g. if you write something like SVZ_MALLOC_DEFUN in a `*.texi.in' file
and have a function named svz_malloc() in a `*.c' file you will get the
function definition including the corresponding comment in the `*.texi'
file:

$ echo "SVZ_MALLOC_DEFUN" > alloc.texi.in
$ awk -f serveez-api.awk ../src/libserveez/alloc.c > alloc.sed
$ sed -f alloc.sed < alloc.texi.in > alloc.texi

Anyway, this is mainly used in the API documentation, not in the user
manual (except some guile functionality).

Were I able to clarify it a bit ?

Cheers,
        address@hidden