www.pudn.com > common-1.2.8.zip > README

* --------------------------------------------------------------------------- 
* 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 (mm-tools@cs.ucl.ac.uk). 
 
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...