Gtk-Doc Manual

[Dan Mueth <d-mueth uchicago edu>]

Hi everybody,

Several of us have been privately discussing writing up a document on
Gtk-Doc.  I'd like to move this discussion onto gtk-doc-list gnome org
where it will remain until it bugs people here enough they tell us to make
this discussion private again;)

The main objective is to make Gtk-Doc as well-documented and easy-to-use
as possible to lower the barrier to entry to new API documenters.  To this
end, we plan to create a single DocBook/SGML document which will cover all
of the information necessary for a person who is new to Gtk-Doc and
DocBook to be able to use gtk-doc to document an API.  We will likely
place this on developer.gnome.org and ship it with gtk-doc.  It will be
licensed under the FDL (of course).

I have prepared an outline (see below) for this document, titled "Gtk-Doc
Manual" to be consistant with the naming the GDP currently gives to user
documents which accompany GNOME applications.  (If people would prefer a
different name, we can discuss changing it.)  I have assigned certain
sections to Damon and myself which I think we may be well-suited for
writing.

Please feel free to discuss this outline, improve it, replace it,
volunteer to write sections, or whatever else seems appropriate. (This
outline could benefit from some eyes which know gtk-doc much better than I
do.)  As soon as discussion dies and I get a bit of spare time, I will put
the outline into DocBook and put it in CVS at
gtk-doc/help/manual/C/gtk-doc-manual.sgml and people can start working on
it.

Dan

----
                 -----------------------------
                 |  Gtk-Doc Manual (Outline) |
                 -----------------------------
Note: I see this as a <book>.  So the toplevel items shown below
are <chapter>'s, the second level items are <sect1>'s, etc.
Text in parenthesis describes content of a section, and names between
square brackets indicates assignment of a section to a particular person.

+ Introduction
  + What is Gtk-Doc? [Damon]
      (A system for embedding docs in libraries, extracting 
      them, automagically determining certain information 
      and relationships...)
  + How Does Gtk-Doc Work? [Damon]
      (Overview of the steps involved - start with Damon's 
      description below this outline.)
  + When to Use Gtk-Doc [Damon]
      (What things Gtk-Doc should, and shouldn't, be used for.)
  + About Gtk-Doc [Damon]
      (History, authors, web pages, license, future plans,
      comparison with other similar systems.)
  + About this manual
      (who it is meant for, where you can get it, license)

+ Before You Begin
  + Getting Gtk-Doc
      (Packages that you must install, where to get the packages,
      any configuration if applicable)
  + Installing and using DocBook [Dan]
      (DTD, jade, psgml)
  + Gtk-Doc Examples
    (Mention the examples and where they can be found.)

+ Setting Up Your Package to Use Gtk-Doc [Damon]
    (this is the hardest part...autoconf...) 
  + Setting Up Your Directories
  + Setting up Autoconf
  + Setting up Automake
  + Creating a Types File 
  + Creating a Sections File 
  + Creating The Main SGML Document
  + Building HTML

+ Documenting Your Libraries
  + About DocBook [Dan]
    + What is DocBook?
    + Why use DocBook?
    + Finding More Information
      (general, TDG, GDP, link to jade above)
  + DocBook Basics [Dan]
    + The DTD Declaration
    + Special Symbols and Character Entities
    + Some Basic DocBook Tags
    + Using External Entities
  + Gtk-Doc's DocBook Abbreviations
  + Writing a Function, Macro, or Structure Description   

+ Gtk-Doc Utilities
  + gtkdoc-scan
  + gtkdoc-scanobj
  + gtkdoc-mktmpl
  + gtkdoc-mkdb
  + gtkdoc-mkhtml
  + gtkdoc-mkman

+ Getting and Polishing the End Product
  + Building HTML
  + Keeping Your API Docs Up-To-Date
  + Packaging and Shipping Your API Docs
  + Cross-Referencing
  + Hand-Tweaking The Final Product

+ Tips

+ FAQ

+ Appendix I: The GPL 
+ Appendix II: The FDL 

----------------------------
Damon's Intro Text:

gtk-doc is used to document C code. It is typically used to document the public
API of libraries, such as the GTK+ and Gnome libraries. But it can also be
used to document application code.

Documentation on functions can be placed inside the source files in
specially-formatted comment blocks, or it can be added to the template files
which gtk-doc uses (though note that gtk-doc will only document functions that
are declared in header files; it won't produce output for static functions).
Currently gtk-doc does not support placing documentation of other types of
declarations, such as enums, macros, and structs, inside the source code.

gtk-doc consists of a number of perl scripts, each performing a different step
in the process.


There are 5 main steps in the process:


1) Gathering information about the code.

   gtkdoc-scan scans the header files of the code looking for declarations of
   functions, macros, enums, structs, and unions. It creates a list of the
   declarations, placing them into sections according to which header file they
   are in. The author can rearrange the sections, and the order of the
declarations
   within them, to produce the final desired order.

   gtkdoc-scanobj can also be used to dynamically query a library about
   any GtkObject subclasses it exports. It saves information about each
object's
   position in the class hierarchy and about any GTK Args and Signals it
provides.


2) Generating the "template" files.

   gtkdoc-mktmpl creates a number of files in the tmpl/ subdirectory, using the
   information gathered in the first step. (Note that this can be run
repeatedly.
   It will try to ensure that no documentation is ever lost.)


3) Writing the documentation.

   The author fills in the template files with the documentation for each
function,
   macro, union etc.


4) Generating the SGML and HTML.

   gtkdoc-mkdb turns the template files into SGML files in the sgml/
subdirectory.
   (If the source code contains documentation on functions, using the special
   comment blocks, it gets merged in here.)

   gtkdoc-mkhtml turns the SGML files into HTML files in the html/
subdirectory.


5) Fixing up cross-references between documents.

   After installing the HTML files, gtkdoc-fixxref can be run to fix up any
   cross-references between separate documents. For example, the GTK+
documentation
   contains many cross-references to types documented in the GLib manual.
----------------------
Resources:
	http://developer.gnome.org/arch/doc/authors.html
	Damon's description (above)
	John's notes (Dan has: gtk-doc-notes-trow.txt)
	Mathieu's notes (Dan has: gtk-doc-notes-mathieu.txt)
	doc/setting-up.txt
	doc/style-guide.txt
	doc/authors.txt
	doc/sections.txt
	(others?)