| 1 | |
|---|
| 2 | GTK+ DocBook Documentation Generator |
|---|
| 3 | ==================================== |
|---|
| 4 | |
|---|
| 5 | GTK-Doc is used to document C code. It is typically used to document the public |
|---|
| 6 | API of libraries, such as the GTK+ and Gnome libraries. But it can also be |
|---|
| 7 | used to document application code. |
|---|
| 8 | |
|---|
| 9 | Documentation for functions, macros, widget signals, and widget properties |
|---|
| 10 | can be written in 2 ways: |
|---|
| 11 | |
|---|
| 12 | a) Embedded inside the source code in specially-formatted comments. |
|---|
| 13 | |
|---|
| 14 | or |
|---|
| 15 | |
|---|
| 16 | b) Added to the 'template' files which gtk-doc outputs after scanning all |
|---|
| 17 | the header files and parsing the declarations. |
|---|
| 18 | |
|---|
| 19 | |
|---|
| 20 | Documentation for other constructs such as enums, structs and callbacks must |
|---|
| 21 | be added to the template files as in (b) above. |
|---|
| 22 | |
|---|
| 23 | |
|---|
| 24 | |
|---|
| 25 | Requirements |
|---|
| 26 | ============ |
|---|
| 27 | |
|---|
| 28 | Perl v5 - the main scripts are in Perl. |
|---|
| 29 | http://www.perl.com/ |
|---|
| 30 | |
|---|
| 31 | DocBook SGML DTD v3.0 or DocBook XML DTD v4.1.2 - the DocBook DTDs. |
|---|
| 32 | http://www.oasis-open.org/docbook/ |
|---|
| 33 | |
|---|
| 34 | Jade v1.1 or OpenJade 1.3.1 for SGML. |
|---|
| 35 | http://www.jclark.com/jade |
|---|
| 36 | http://sourceforge.net/projects/openjade |
|---|
| 37 | |
|---|
| 38 | libxslt & libxml2 2.3.6 for XML. |
|---|
| 39 | http://xmlsoft.org/ |
|---|
| 40 | |
|---|
| 41 | DocBook DSSSL Stylesheets (I've got 1.40, but v1.19+ may be OK) |
|---|
| 42 | This is the DSSSL code to convert DocBook SGML to HTML (and a few other |
|---|
| 43 | formats). It's used together with jade. |
|---|
| 44 | I've customized the DSSSL code slightly, in gtk-doc.dsl, to colour |
|---|
| 45 | the program code listings/declarations, and to support global |
|---|
| 46 | cross-reference indices in the generated HTML. |
|---|
| 47 | http://docbook.sourceforge.net/projects/dsssl/ |
|---|
| 48 | |
|---|
| 49 | DocBook XSL Stylesheets |
|---|
| 50 | http://docbook.sourceforge.net/projects/xsl/ |
|---|
| 51 | |
|---|
| 52 | Most distributions now have packages for all of these, so I would strongly |
|---|
| 53 | advise that you grab those. |
|---|
| 54 | |
|---|
| 55 | You will also need to make sure that the DocBook XML DTD and XSL |
|---|
| 56 | stylesheets are installed in the system's XML catalog. The packages |
|---|
| 57 | for Red Hat Linux have done this for a while, and the Debian packages |
|---|
| 58 | will do so too soon. For Debian systems, you might want to try the |
|---|
| 59 | following script to set up the catalog: |
|---|
| 60 | http://www.daa.com.au/~james/files/build-xml-catalog-for-debian.sh |
|---|
| 61 | |
|---|
| 62 | For other systems, you can try the following steps provided by Mark |
|---|
| 63 | McLoughlin: |
|---|
| 64 | 1) download http://www.oasis-open.org/docbook/xml/4.1.2/docbkx412.zip |
|---|
| 65 | 2) install it in /usr/share/sgml/docbook/xml-dtd-4.1.2 |
|---|
| 66 | 3) Download docbook-xsl from docbook.sf.net and install it in |
|---|
| 67 | /usr/share/sgml |
|---|
| 68 | 4) download and run http://xmlsoft.org/buildDocBookCatalog |
|---|
| 69 | |
|---|
| 70 | |
|---|
| 71 | See the documentation in the docs directory for more information, especially |
|---|
| 72 | the setting-up.txt file which describes how to set up your application or |
|---|
| 73 | library to use gtk-doc. |
|---|
| 74 | |
|---|
| 75 | |
|---|
| 76 | Damon Chaplin (damon@gnome.org), 13 Nov 2002. |
|---|
| 77 | |
|---|
