Generating documentation with gtk-doc

Makefile

@@ -1,6 +1,6 @@
 PACKAGE	= c99
 VERSION	= 0.0.0
-SUBDIRS	= include src
+SUBDIRS	= doc include src
 RM	?= rm -f
 LN	?= ln -f
 TAR	?= tar -czvf
@@ -21,6 +21,18 @@ dist:
 	$(RM) -r -- $(PACKAGE)-$(VERSION)
 	$(LN) -s -- . $(PACKAGE)-$(VERSION)
 	@$(TAR) $(PACKAGE)-$(VERSION).tar.gz -- \
+		$(PACKAGE)-$(VERSION)/doc/Makefile \
+		$(PACKAGE)-$(VERSION)/doc/GRAMMAR \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc.sh \
+		$(PACKAGE)-$(VERSION)/doc/project.conf \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc/Makefile \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc/c99-docs.xml \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc/project.conf \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc/tmpl/Makefile \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc/tmpl/c99-unused.sgml \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc/tmpl/c99.sgml \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc/tmpl/target.sgml \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc/tmpl/project.conf \
 		$(PACKAGE)-$(VERSION)/include/c99.h \
 		$(PACKAGE)-$(VERSION)/include/Makefile \
 		$(PACKAGE)-$(VERSION)/include/project.conf \
@@ -103,6 +115,7 @@ dist:
 		$(PACKAGE)-$(VERSION)/src/target/project.conf \
 		$(PACKAGE)-$(VERSION)/Makefile \
 		$(PACKAGE)-$(VERSION)/config.h \
+		$(PACKAGE)-$(VERSION)/config.sh \
 		$(PACKAGE)-$(VERSION)/project.conf
 	$(RM) -- $(PACKAGE)-$(VERSION)
 

doc/Makefile

@@ -0,0 +1,45 @@
+SUBDIRS	= gtkdoc
+TARGETS	= gtkdoc/c99.types gtkdoc/tmpl.stamp gtkdoc/sgml.stamp gtkdoc/html.stamp
+PREFIX	= /usr/local
+DESTDIR	=
+RM	?= rm -f
+LN	?= ln -f
+MKDIR	?= mkdir -p
+INSTALL	?= install
+
+
+all: subdirs $(TARGETS)
+
+subdirs:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE)) || exit; done
+
+gtkdoc/c99.types:
+	./gtkdoc.sh -P "$(PREFIX)" -- "gtkdoc/c99.types"
+
+gtkdoc/tmpl.stamp: gtkdoc/c99.types
+	./gtkdoc.sh -P "$(PREFIX)" -- "gtkdoc/tmpl.stamp"
+
+gtkdoc/sgml.stamp: gtkdoc/tmpl.stamp
+	./gtkdoc.sh -P "$(PREFIX)" -- "gtkdoc/sgml.stamp"
+
+gtkdoc/html.stamp: gtkdoc/c99-docs.xml gtkdoc/sgml.stamp
+	./gtkdoc.sh -P "$(PREFIX)" -- "gtkdoc/html.stamp"
+
+clean:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) clean) || exit; done
+	$(RM) -- $(gtkdoc/c99.types_OBJS) $(gtkdoc/tmpl.stamp_OBJS) $(gtkdoc/sgml.stamp_OBJS) $(gtkdoc/html.stamp_OBJS)
+
+distclean:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) distclean) || exit; done
+	$(RM) -- $(gtkdoc/c99.types_OBJS) $(gtkdoc/tmpl.stamp_OBJS) $(gtkdoc/sgml.stamp_OBJS) $(gtkdoc/html.stamp_OBJS)
+	$(RM) -- $(TARGETS)
+
+install: $(TARGETS)
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) install) || exit; done
+	./gtkdoc.sh -P "$(DESTDIR)$(PREFIX)" -i -- "gtkdoc/html.stamp"
+
+uninstall:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) uninstall) || exit; done
+	./gtkdoc.sh -P "$(DESTDIR)$(PREFIX)" -u -- "gtkdoc/html.stamp"
+
+.PHONY: all subdirs clean distclean install uninstall

doc/gtkdoc.sh

@@ -0,0 +1,160 @@
+#!/bin/sh
+#$Id$
+#Copyright (c) 2012 Pierre Pronchery <khorben@defora.org>
+#
+#Redistribution and use in source and binary forms, with or without
+#modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+#THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+#AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+#IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+#DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+#FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+#DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+#SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+#CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+#OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+#OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+
+#variables
+PREFIX="/usr/local"
+. "../config.sh"
+DEBUG="_debug"
+GTKDOC_FIXXREF="gtkdoc-fixxref"
+GTKDOC_MKDB="gtkdoc-mkdb"
+GTKDOC_MKHTML="gtkdoc-mkhtml"
+GTKDOC_MKTMPL="gtkdoc-mktmpl"
+GTKDOC_SCAN="gtkdoc-scan"
+INSTALL="install -m 0644"
+MKDIR="mkdir -p"
+MODULE="$PACKAGE"
+RM="rm -f"
+TOUCH="touch"
+
+
+#functions
+#debug
+_debug()
+{
+	echo $@
+	$@
+}
+
+
+#usage
+_usage()
+{
+	echo "Usage: gtkdoc.sh [-i|-u][-P prefix] target" 1>&2
+	return 1
+}
+
+
+#main
+install=0
+uninstall=0
+while getopts "iuP:" "name"; do
+	case "$name" in
+		i)
+			uninstall=0
+			install=1
+			;;
+		u)
+			install=0
+			uninstall=1
+			;;
+		P)
+			PREFIX="$2"
+			;;
+		?)
+			_usage
+			exit $?
+			;;
+	esac
+done
+shift $((OPTIND - 1))
+if [ $# -eq 0 ]; then
+	_usage
+	exit $?
+fi
+
+[ -z "$DATADIR" ] && DATADIR="$PREFIX/share"
+instdir="$DATADIR/gtk-doc/html"
+
+while [ $# -gt 0 ]; do
+	target="$1"
+	shift
+
+	#uninstall
+	if [ "$uninstall" -eq 1 ]; then
+		for i in gtkdoc/html/*.*; do
+			file="${i##*/}"
+			echo $DEBUG $RM "$instdir/$MODULE/$file" \
+								|| exit 2
+		done
+		continue
+	fi
+
+	#create
+	case "$target" in
+		gtkdoc/html.stamp)
+			$MKDIR "gtkdoc/html" &&
+			(cd "gtkdoc/html" &&
+				$DEBUG $GTKDOC_MKHTML "$MODULE" \
+					"../$MODULE-docs.xml") &&
+			(cd "gtkdoc" &&
+				$DEBUG $GTKDOC_FIXXREF \
+					--module="$MODULE" \
+					--module-dir="html" \
+					--html-dir="$instdir")
+			;;
+		gtkdoc/sgml.stamp)
+			(cd "gtkdoc" &&
+				$DEBUG $GTKDOC_MKDB \
+					--module="$MODULE" \
+					--output-dir="xml" \
+					--output-format="xml" \
+					--tmpl-dir="tmpl")
+			;;
+		gtkdoc/tmpl.stamp)
+			(cd "gtkdoc" &&
+				$DEBUG $GTKDOC_MKTMPL \
+					--module="$MODULE" \
+					--output-dir="tmpl")
+			;;
+		gtkdoc/*.types)
+			(cd ".." &&
+				$DEBUG $GTKDOC_SCAN \
+					--module="$MODULE" \
+					--source-dir="include" \
+					--output-dir="doc/gtkdoc")
+			;;
+		*)
+			echo "$0: $target: Unknown type" 1>&2
+			exit 2
+			;;
+	esac
+	#XXX ignore errors
+	if [ $? -ne 0 ]; then
+		echo "$0: $target: Could not create documentation" 1>&2
+		install=0
+	fi
+	$TOUCH "$target"
+
+	#install
+	if [ "$install" -eq 1 ]; then
+		$DEBUG $MKDIR "$instdir/$MODULE"		|| exit 2
+		for i in gtkdoc/html/*.*; do
+			file="${i##*/}"
+			$DEBUG $INSTALL "$i" "$instdir/$MODULE/$file" \
+								|| exit 2
+		done
+	fi
+done

doc/gtkdoc/Makefile

@@ -0,0 +1,21 @@
+SUBDIRS	= tmpl
+
+
+all: subdirs
+
+subdirs:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE)) || exit; done
+
+clean:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) clean) || exit; done
+
+distclean:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) distclean) || exit; done
+
+install:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) install) || exit; done
+
+uninstall:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) uninstall) || exit; done
+
+.PHONY: all subdirs clean distclean install uninstall

doc/gtkdoc/c99-docs.xml

@@ -0,0 +1,36 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY server "www.defora.org/doc/html">
+  <!ENTITY title "DeforaOS c99">
+  <!ENTITY version "0.0.0">
+]>
+<book id="index">
+  <bookinfo>
+    <title>c99 Reference Manual</title>
+    <releaseinfo>
+      for c99 &version;.
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="http://&server;/c99/index.html">http://&server;/c99/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>&title;</title>
+    <xi:include href="xml/c99.xml"/>
+    <xi:include href="xml/target.xml"/>
+
+  </chapter>
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>

doc/gtkdoc/project.conf

@@ -0,0 +1,2 @@
+subdirs=tmpl
+dist=Makefile,c99-docs.xml

doc/gtkdoc/tmpl/Makefile

@@ -0,0 +1,13 @@
+
+
+all:
+
+clean:
+
+distclean: clean
+
+install:
+
+uninstall:
+
+.PHONY: all clean distclean install uninstall

doc/gtkdoc/tmpl/c99.sgml

@@ -0,0 +1,106 @@
+<!-- ##### SECTION Title ##### -->
+C99
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### STRUCT C99 ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO C99PREFS_E ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO C99PREFS_c ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO C99PREFS_g ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO C99PREFS_s ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### FUNCTION c99_define_add ##### -->
+<para>
+
+</para>
+
+@c99: 
+@name: 
+@value: 
+@Returns: 
+
+
+<!-- ##### FUNCTION c99_delete ##### -->
+<para>
+
+</para>
+
+@c99: 
+@Returns: 
+
+
+<!-- ##### FUNCTION c99_new ##### -->
+<para>
+
+</para>
+
+@prefs: 
+@pathname: 
+@Returns: 
+
+
+<!-- ##### FUNCTION c99_parse ##### -->
+<para>
+
+</para>
+
+@c99: 
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION define_add ##### -->
+<para>
+
+</para>
+
+@c99: 
+@name: 
+@value: 
+@Returns: 
+
+

doc/gtkdoc/tmpl/project.conf

@@ -0,0 +1 @@
+dist=Makefile,c99-unused.sgml,c99.sgml,target.sgml

doc/gtkdoc/tmpl/target.sgml

@@ -0,0 +1,95 @@
+<!-- ##### SECTION Title ##### -->
+Target
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### USER_FUNCTION exit ##### -->
+<para>
+
+</para>
+
+@void: 
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION function_begin ##### -->
+<para>
+
+</para>
+
+@name: 
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION function_call ##### -->
+<para>
+
+</para>
+
+@name: 
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION function_end ##### -->
+<para>
+
+</para>
+
+@void: 
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION init ##### -->
+<para>
+
+</para>
+
+@outfile: 
+@optlevel: 
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION label_set ##### -->
+<para>
+
+</para>
+
+@name: 
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION section ##### -->
+<para>
+
+</para>
+
+@name: 
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION token ##### -->
+<para>
+
+</para>
+
+@token: 
+@Returns: 
+
+

doc/project.conf

@@ -0,0 +1,23 @@
+subdirs=gtkdoc
+targets=gtkdoc/c99.types,gtkdoc/tmpl.stamp,gtkdoc/sgml.stamp,gtkdoc/html.stamp
+dist=Makefile,GRAMMAR,gtkdoc.sh
+
+[gtkdoc/c99.types]
+type=script
+script=./gtkdoc.sh
+
+[gtkdoc/tmpl.stamp]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc/c99.types
+
+[gtkdoc/sgml.stamp]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc/tmpl.stamp
+
+[gtkdoc/html.stamp]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc/c99-docs.xml,gtkdoc/sgml.stamp
+install=

project.conf

@@ -1,6 +1,6 @@
 package=c99
 version=0.0.0
-config=h
+config=h,sh
 
-subdirs=include,src
+subdirs=doc,include,src
-dist=Makefile,config.h
+dist=Makefile,config.h,config.sh