my "gtkdocize" work
- From: James Henstridge <james daa com au>
- To: gtk-doc-list gnome org
- Subject: my "gtkdocize" work
- Date: Mon, 10 Feb 2003 08:56:56 +0800
I have attached a patch containing my work on simplifying the gtk-doc
build infrastructure for packages building API docs.
I tried out converting libglade to use this setup, which turned out to
be fairly easy. I had to add a call to "gtkdocize" to the autogen.sh
script, replace the gtk-doc checks in the configure.in file with a
simple call to GTK_DOC_CHECK, and changed the gtk-doc makefile to the
following:
AUTOMAKE_OPTIONS = 1.6
## Process this file with automake to produce Makefile.in
# The name of the module.
DOC_MODULE = libglade
# The top-level SGML file.
DOC_MAIN_SGML_FILE = libglade-docs.xml
# The directory containing the source code (if it contains
documentation).
DOC_SOURCE_DIR = ../glade
SCANGOBJ_OPTIONS =
SCAN_OPTIONS = --deprecated-guards="LIBGLADE_DISABLE_DEPRECATED"
HFILE_GLOB = $(top_srcdir)/glade/*.h
CFILE_GLOB = $(top_srcdir)/glade/*.c
IGNORE_HFILES = glade-private.h
INCLUDES = -I$(top_srcdir) $(LIBGLADE_CFLAGS)
GTKDOC_LIBS = ../glade/libglade-2.0.la $(LIBGLADE_LIBS)
MKDB_OPTIONS = --output-format=xml
FIXXREF_OPTIONS =
HTML_IMAGES =
content_files =
include $(srcdir)/gtk-doc.make
The makefile fragment probably needs a bit more work. It is based on
the GTK+ Makefile, with a few changes to reduce the number of variables
you need to set.
I also have a few other modifications in the patch too:
* Move data files to $(prefix)/share/gtk-doc/data, so that they
don't get mixed up with the documentation installed by other packages
* Add some checks to the configure.in to make sure that the docbook
DTD and stylesheets are in the XML catalog (so that xstlproc
doesn't try to download them over the internet when building html
docs).
It is probably almost ready to check in, but will need a bit more
testing. I can split out these last two modifications and check them in
separately if that would be better.
James.
--
Email: james daa com au
WWW: http://www.daa.com.au/~james/
? dsssl-layout.patch
? example.mk
? gtkdocize
? gtkdocize.patch
? tmp
Index: ChangeLog
===================================================================
RCS file: /cvs/gnome/gtk-doc/ChangeLog,v
retrieving revision 1.160
diff -u -p -r1.160 ChangeLog
--- ChangeLog 20 Jan 2003 02:03:44 -0000 1.160
+++ ChangeLog 10 Feb 2003 00:34:58 -0000
@@ -1,3 +1,32 @@
+2003-02-09 James Henstridge <james daa com au>
+
+ * gtkdocize.in: script used to copy gtk-doc.make into another
+ module.
+
+ * gtk-doc.make: automake makefile fragment to handle gtk-doc
+ support in other modules.
+
+ * configure.in: check to make sure DocBook XML DTD and XSLT
+ stylesheets are present in the XML catalog.
+
+ * acinclude.m4 (JH_CHECK_XML_CATALOG): new macro to check for
+ entries in the XML catalog.
+
+2003-02-04 James Henstridge <james daa com au>
+
+ * gtk-doc.m4: a macro to check for gtk-doc.
+
+ * Makefile.am (gtkdocdata_DATA): don't bother installing xml.dcl.
+ It isn't used anymore (since switching xml mode to xsltproc).
+
+ * gtkdoc-mkhtml.in (gtkdocdir): and here.
+
+ * Makefile.am (gtkdocdatadir): change dir.
+
+ * configure.in: put data files in $(datadir)/gtk-doc/data, so that
+ they don't all get mixed up with the html docs installed by other
+ packages.
+
2003-01-20 Damon Chaplin <damon gnome org>
* Released 1.0.
Index: Makefile.am
===================================================================
RCS file: /cvs/gnome/gtk-doc/Makefile.am,v
retrieving revision 1.21
diff -u -p -r1.21 Makefile.am
--- Makefile.am 20 Jan 2003 01:50:45 -0000 1.21
+++ Makefile.am 10 Feb 2003 00:34:58 -0000
@@ -8,16 +8,17 @@ bin_SCRIPTS = \
gtkdoc-mkdb \
gtkdoc-mkhtml \
gtkdoc-mkman \
- gtkdoc-fixxref
+ gtkdoc-fixxref \
+ gtkdocize
-gtkdocdatadir = $(datadir)/gtk-doc
+gtkdocdatadir = $(datadir)/gtk-doc/data
gtkdocdata_DATA = \
gtkdoc-common.pl \
gtk-doc.dsl \
gtk-doc.dcl \
gtk-doc.xsl \
devhelp.xsl \
- xml.dcl \
+ gtk-doc.make \
home.png \
left.png \
right.png \
@@ -26,19 +27,22 @@ gtkdocdata_DATA = \
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = gtk-doc.pc
+aclocaldir = $(datadir)/aclocal
+aclocal_DATA = gtk-doc.m4
+
EXTRA_DIST= \
MAINTAINERS \
gtk-doc.pc.in \
gtk-doc.spec.in \
+ gtk-doc.spec \
gtk-doc.dcl \
gtk-doc.xsl \
devhelp.xsl \
- xml.dcl \
home.png \
left.png \
right.png \
- up.png
-
+ up.png \
+ gtk-doc.m4
dist-hook:
mkdir $(distdir)/doc
@@ -53,5 +57,4 @@ dist-hook:
mkdir $(distdir)/tools
cp -pr $(srcdir)/tools/* $(distdir)/tools
rm -rf $(distdir)/tools/CVS
- cp gtk-doc.spec $(distdir)
Index: configure.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/configure.in,v
retrieving revision 1.26
diff -u -p -r1.26 configure.in
--- configure.in 20 Jan 2003 01:53:28 -0000 1.26
+++ configure.in 10 Feb 2003 00:34:58 -0000
@@ -51,17 +51,21 @@ if test -z "$XSLTPROC"; then
AC_MSG_ERROR([xsltproc not found])
fi
+dnl check for DocBook DTD and stylesheets in the local catalog.
+JH_CHECK_XML_CATALOG([http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd])
+JH_CHECK_XML_CATALOG([http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl])
+
dnl
dnl Set PACKAGE_DATA_DIR so we can find the script containing common routines.
dnl
if test "x${datadir}" = 'x${prefix}/share'; then
if test "x${prefix}" = "xNONE"; then
- PACKAGE_DATA_DIR="${ac_default_prefix}/share/${PACKAGE}"
+ PACKAGE_DATA_DIR="${ac_default_prefix}/share/${PACKAGE}/data"
else
- PACKAGE_DATA_DIR="${prefix}/share/${PACKAGE}"
+ PACKAGE_DATA_DIR="${prefix}/share/${PACKAGE}/data"
fi
else
- PACKAGE_DATA_DIR="${datadir}/${PACKAGE}"
+ PACKAGE_DATA_DIR="${datadir}/${PACKAGE}/data"
fi
AC_SUBST(PACKAGE_DATA_DIR)
@@ -88,5 +92,6 @@ gtkdoc-mktmpl
gtkdoc-scan
gtkdoc-scanobj
gtkdoc-scangobj
+gtkdocize
],
-[chmod +x gtkdoc-mkman gtkdoc-mkhtml gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mktmpl gtkdoc-scan gtkdoc-scanobj])
+[chmod +x gtkdoc-mkman gtkdoc-mkhtml gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mktmpl gtkdoc-scan gtkdoc-scanobj gtkdocize])
Index: gtkdoc-mkhtml.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkhtml.in,v
retrieving revision 1.15
diff -u -p -r1.15 gtkdoc-mkhtml.in
--- gtkdoc-mkhtml.in 20 Jan 2003 01:54:47 -0000 1.15
+++ gtkdoc-mkhtml.in 10 Feb 2003 00:34:59 -0000
@@ -18,7 +18,7 @@ module=$1
document=$2
prefix= prefix@
-gtkdocdir= datadir@/gtk-doc
+gtkdocdir= datadir@/gtk-doc/data
declaration=$gtkdocdir/gtk-doc.dcl
--- /dev/null 2002-08-31 07:31:37.000000000 +0800
+++ acinclude.m4 2003-02-09 23:57:57.000000000 +0800
@@ -0,0 +1,36 @@
+
+AC_DEFUN([_JH_CHECK_XML_CATALOG_PREP],
+[
+ # check for the presence of the XML catalog
+ AC_ARG_WITH([xml-catalog],
+ AC_HELP_STRING([--with-xml-catalog=CATALOG],
+ [path to xml catalog to use]),,
+ [with_xml_catalog=/etc/xml/catalog])
+ XML_CATALOG_FILE="$with_xml_catalog"
+ AC_MSG_CHECKING([for XML catalog ($XML_CATALOG_FILE)])
+ if test -f "$XML_CATALOG_FILE"; then
+ AC_MSG_RESULT([found])
+ else
+ AC_MSG_ERROR([XML catalog not found])
+ fi
+
+ # check for the xmlcatalog program
+ AC_PATH_PROG(XMLCATALOG, xmlcatalog, no)
+ if test "x$XMLCATALOG" = xno; then
+ AC_MSG_ERROR([could not find xmlcatalog program])
+ fi
+])
+
+# Checks if a particular URI appears in the XML catalog
+# Usage:
+# JH_CHECK_XML_CATALOG(URI)
+AC_DEFUN([JH_CHECK_XML_CATALOG],
+[
+ AC_REQUIRE([_JH_CHECK_XML_CATALOG_PREP])dnl
+ AC_MSG_CHECKING([for $1 in XML catalog])
+ if $XMLCATALOG --noout "$XML_CATALOG_FILE" "$1" >/dev/null 2>&1; then
+ AC_MSG_RESULT([found])
+ else
+ AC_MSG_ERROR([not found])
+ fi
+])
--- /dev/null 2002-08-31 07:31:37.000000000 +0800
+++ gtk-doc.m4 2003-02-09 23:38:16.000000000 +0800
@@ -0,0 +1,53 @@
+dnl -*- mode: autoconf -*-
+
+# serial 1
+
+dnl Usage:
+dnl GTK_DOC_CHECK([minimum-gtk-doc-version])
+AC_DEFUN([GTK_DOC_CHECK],
+[
+ AC_BEFORE([AC_PROG_LIBTOOL],[$0])dnl setup libtool first
+ AC_BEFORE([AM_PROG_LIBTOOL],[$0])dnl setup libtool first
+ dnl for overriding the documentation installation directory
+ AC_ARG_WITH(html-dir,
+ AC_HELP_STRING([--with-html-dir=PATH], [path to installed docs]),,
+ [with_html_dir='${datadir}/gtk-doc/html'])
+ HTML_DIR="$with_html_dir"
+ AC_SUBST(HTML_DIR)
+
+ dnl enable/disable documentation building
+ AC_ARG_ENABLE(gtk-doc,
+ AC_HELP_STRING([--enable-gtk-doc],
+ [use gtk-doc to build documentation [default=no]]),,
+ enable_gtk_doc=no)
+
+ have_gtk_doc=no
+ if test -z "$PKG_CONFIG"; then
+ AC_PATH_PROG(PKG_CONFIG, pkg-config, no)
+ fi
+ if test "$PKG_CONFIG" != "no" && $PKG_CONFIG --exists gtk-doc; then
+ have_gtk_doc=yes
+ fi
+
+ dnl do we want to do a version check?
+ifelse([$1],[],,
+ [gtk_doc_min_version=$1
+ if test "$have_gtk_doc" = yes; then
+ AC_MSG_CHECKING([gtk-doc version >= $gtk_doc_min_version])
+ if $PKG_CONFIG --atleast-version $gtk_doc_min_version gtk-doc; then
+ AC_MSG_RESULT(yes)
+ else
+ AC_MSG_RESULT(no)
+ have_gtk_doc=no
+ fi
+ fi
+])
+ if test x$enable_gtk_doc = xyes; then
+ if test "$have_gtk_doc" != yes; then
+ enable_gtk_doc=no
+ fi
+ fi
+
+ AM_CONDITIONAL(ENABLE_GTK_DOC, test x$enable_gtk_doc = xyes)
+ AM_CONDITIONAL(GTK_DOC_USE_LIBTOOL, test -n "$LIBTOOL")
+])
--- /dev/null 2002-08-31 07:31:37.000000000 +0800
+++ gtk-doc.make 2003-02-05 21:28:04.000000000 +0800
@@ -0,0 +1,139 @@
+# -*- mode: makefile -*-
+
+####################################
+# Everything below here is generic #
+####################################
+
+if GTK_DOC_USE_LIBTOOL
+GTKDOC_CC = $(LIBTOOL) --mode=compile $(CC) $(INCLUDES) $(AM_CFLAGS) $(CFLAGS)
+GTKDOC_LD = $(LIBTOOL) --mode=link $(CC) $(AM_CFLAGS) $(CFLAGS) $(LDFLAGS)
+else
+GTKDOC_CC = $(CC) $(INCLUDES) $(AM_CFLAGS) $(CFLAGS)
+GTKDOC_LD = $(CC) $(AM_CFLAGS) $(CFLAGS) $(LDFLAGS)
+endif
+
+# We set GPATH here; this gives us semantics for GNU make
+# which are more like other make's VPATH, when it comes to
+# whether a source that is a target of one rule is then
+# searched for in VPATH/GPATH.
+#
+GPATH = $(srcdir)
+
+TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
+
+EXTRA_DIST = \
+ $(content_files) \
+ $(HTML_IMAGES) \
+ $(DOC_MAIN_SGML_FILE) \
+ $(DOC_MODULE).types \
+ $(DOC_MODULE)-sections.txt \
+ $(DOC_MODULE)-overrides.txt
+
+DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \
+ $(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp
+
+SCANOBJ_FILES = \
+ $(DOC_MODULE).args \
+ $(DOC_MODULE).hierarchy \
+ $(DOC_MODULE).interfaces \
+ $(DOC_MODULE).prerequisites \
+ $(DOC_MODULE).signals
+
+if ENABLE_GTK_DOC
+all-local: html-build.stamp
+
+#### scan ####
+
+scan-build.stamp: $(HFILE_GLOB)
+ @echo '*** Scanning header files ***'
+ if grep -l '^..*$$' $(srcdir)/$(DOC_MODULE).types > /dev/null ; then \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) --output-dir=$(srcdir) ; \
+ else \
+ cd $(srcdir) ; \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
+ fi
+ cd $(srcdir) && \
+ gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES)
+ touch scan-build.stamp
+
+$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): scan-build.stamp
+ @true
+
+#### templates ####
+
+tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
+ @echo '*** Rebuilding template files ***'
+ cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
+ touch tmpl-build.stamp
+
+tmpl.stamp: tmpl-build.stamp
+ @true
+
+#### sgml ####
+
+sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml
+ @echo '*** Building SGML ***'
+ cd $(srcdir) && \
+ gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS)
+ touch sgml-build.stamp
+
+sgml.stamp: sgml-build.stamp
+ @true
+
+#### html ####
+
+html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
+ @echo '*** Building HTML ***'
+ rm -rf $(srcdir)/html
+ mkdir $(srcdir)/html
+ cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+ test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html )
+ @echo '-- Fixing Crossreferences'
+ cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
+ touch html-build.stamp
+endif
+
+##############
+
+clean-local:
+ rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS)
+
+maintainer-clean-local: clean
+ cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
+
+install-data-local:
+ $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR)
+ (installfiles=`echo $(srcdir)/html/*`; \
+ if test "$$installfiles" = '$(srcdir)/html/*'; \
+ then echo '-- Nothing to install' ; \
+ else \
+ for i in $$installfiles; do \
+ echo '-- Installing '$$i ; \
+ $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \
+ done; \
+ echo '-- Installing $(srcdir)/html/index.sgml' ; \
+ $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR) || :; \
+ fi)
+
+#
+# Require gtk-doc when making dist
+#
+if ENABLE_GTK_DOC
+dist-check-gtkdoc:
+else
+dist-check-gtkdoc:
+ @echo "*** gtk-doc must be installed and enabled in order to make dist"
+ @false
+endif
+
+dist-hook: dist-check-gtkdoc dist-hook-local
+ mkdir $(distdir)/tmpl
+ mkdir $(distdir)/xml
+ mkdir $(distdir)/html
+ -cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
+ -cp $(srcdir)/xml/*.xml $(distdir)/xml
+ -cp $(srcdir)/html/* $(distdir)/html
+
+.PHONY : dist-hook-local
--- /dev/null 2002-08-31 07:31:37.000000000 +0800
+++ gtkdocize.in 2003-02-09 21:56:07.000000000 +0800
@@ -0,0 +1,63 @@
+#!/bin/sh
+
+progname=`echo "$0" | sed 's%^.*/%%'`
+
+PROGRAM=gtkdocize
+PACKAGE= PACKAGE@
+VERSION= VERSION@
+
+prefix= prefix@
+datadir= datadir@
+
+# options
+docdir=.
+copy=no
+
+while test $# -gt 0; do
+ case "$1" in
+ --help)
+ echo "usage: $progname [ --copy ] [ --docdir DIR ]" 1>&2
+ exit 1 ;;
+ --copy)
+ copy=yes
+ shift ;;
+ --docdir)
+ shift
+ docdir="$1"
+ shift ;;
+ -*)
+ echo "$progname: unrecognised option '$1'" 1>&2
+ echo "usage: $progname [ --copy ] [ --docdir DIR ]" 1>&2
+ exit 1 ;;
+ *)
+ echo "$progname: too many arguments" 1>&2
+ echo "usage: $progname [ --copy ] [ --docdir DIR ]" 1>&2
+ exit 1 ;;
+ esac
+done
+
+if test -f configure.ac; then
+ configure=configure.ac
+elif test -f configure.in; then
+ configure=configure.in
+else
+ echo "$progname: neither configure.ac nor configure.in exist" 1>&2
+ exit 1
+fi
+
+if grep '^GTK_DOC_CHECK' $configure >/dev/null 2>&1; then
+ :
+else
+ echo "$progname: GTK_DOC_CHECK not called in $configure" 1>&2
+ exit 1
+fi
+
+rm -f $docdir/gtk-doc.make
+if test "$copy" = yes; then
+ cp -f $datadir/gtk-doc/data/gtk-doc.make $docdir/ ||
+ exit 1
+else
+ ln -sf $datadir/gtk-doc/data/gtk-doc.make $docdir/ ||
+ cp -f $datadir/gtk-doc/data/gtk-doc.make $docdir/ ||
+ exit 1
+fi
[Date Prev][
Date Next] [Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
