readme

UCL Common Code Library Routines common to a number of multimedia tools. The library originates

* ---------------------------------------------------------------------------
* Introduction

This project uses gtkdoc to build DocBook documentation out of source
code and sgml files.  By using DocBook the option exists to build
documentation in a number of formats (html, man, ps), though we
currently target html only.  

gtkdoc is part of the GNOME project, details on downloading and
installing can be found at:

	http://developer.gnome.org/projects/gdp/

FreeBSD and Linux have standard packages to install DocBook and
gtkdoc.

* ---------------------------------------------------------------------------
* Building the documentation

On Unix, just type "make".  We don't have plans to build docs on
anything other than FreeBSD/Linux - it's just a time thing.

* ---------------------------------------------------------------------------
* Reading the documentation

The repository contains the HTML files so documentation is available
upon download and does not require users to build it.  The toplevel
document is:

	html/book1.html

* ---------------------------------------------------------------------------
* Rough Guidelines

Here is some "lore" on using gtkdoc and how things are with this
documentation.  This is our first attempt at using gtkdoc, and our
insight comes from reading the gtkdoc source code and various bits on
docbook (so we're probably missing some of the intentions).  If you
spot anything that would improve the documentation, please let us
know ([e-mail]).

Okay, so here's the deal.  There are a few "core" files:

1. uclmmbase-sections.txt

	The initial version of this file was generated by running
gtkdoc-scan on files in the source directory and copying the file
$MODULE-decl.txt to uclmmbase-sections.txt.  The file contains all
declarations found.  It will need updating when declarations change.
Don't worry about it too much as the error message following a change
instructs on what to do.

	If you want '#include "foo.h"' message to appear with
documentation associated with section foo, add it here (look for
"INCLUDE" for an example).

2. uclmmbase-driver.sgml 

	This is the top-level sgml document.  It is manually created
and edited.  Most of what we need is already there.

3) everything in tmpl/*

	These are templates that go around the libraries.  At the time
of writing only tmpl/rtp.sgml has anything in.  Take a look, the
general idea of what will appear should be apparent from this.

The code documentation method is somewhat akin to Sun's JavaDoc:
special comments are embedded in source files, and these are converted
into documentation.  The form of gtkdoc comments is:

/**
 * maybe_print_string:
 * @message: the string to be printed.
 *
 * This function prints the message on the terminal with a probability 0.5.
 * 
 * Returns: TRUE if message is printed, FALSE otherwise.
 */

int may_print_string(char *message)
{
	if (drand48() >= 0.5) {
		printf("%s\n", message);
		return TRUE;
	}
	return FALSE;
}

Okay, hopefully this is enough to get started...