Hi!
Here is the big picture:
---------------------------------------
I. Sources
-----------
One module (maybe in 'html') is dedicated to the documentation binding:
it contains the general documents about the ggi project, stylesheets,
and everything needed to build the online (and printed) document set.
Each module contains its own documentation.
There must be a "doc/docbook/" directory containing
the following files :
- libname.sgml
root : <chapter id="libname-doc">
Module role, design, ...
- libname-faq.sgml :
root : <qandaset id="libname-faq">
- libname-api.sgml :
root : <reference id="libname-api">
This file is used to generate the manpages.
- libname-tutorial.sgml (if any) :
root : <article id="libname-tutorial">
All the files must be SGML DocBook 4.1 compliant.
Event better, try to make it XML compliant: means avoid using
SGML specific markup (like <example/this/ or <example>this</> or
even <>this</>) and use lowercase.
II. The GGI book
----------------
The GGI book documents the GGI project as a whole.
Part of it comes from the module doc directory (marked as *)
I suggest the following layout:
Preface
Part I : Introduction
Chapter 1 : What is GGI? (project)
Chapter 2 : Design (general structure, exts/targets..., why it
rocks)
Part II : User documentation
Chapter 3 : Installing GGI (where? what? why?)
Chapter 4 : Configuration (env variables, files...)
Part III : Developer Documentation
Chapter 5(*): libgg (using, issues,...)
Chapter 6(*): libgii (input and event model)
Chapter 7(*): libggi (visual, colors, mode, framebuffers,
drawing...)
Chapter 8(*): libgalloc (role, ressources,...)
Part IV : Extending GGI
Chapter 9 : Extension writing
Chapter 10 : The target dl mechanism
Part V : Official extensions
Chapter 11...n(*): libblt, libovl...
Part VI : Appendices
Appendix A : General FAQ + module FAQs(*)
Appendix B : APIs(*)
Index
III. Online doc:
---------------
In html and as tarballs:
- the book,
- set of FAQs
- set of APIs
- set of tutorials
FAQs and APIs will also appear in the book, but that's ok.
-----------------------------------------
Comments or ideas on this?
Eric.
