GNOME.org
 

bonobo-activation doc build fixes

Hi,

bonobo-activation docs build is a bit hosed, I think too many people
are using --disable-gtk-doc.

Appended is how I would fix it. I know Darin won't like the level of
cut-and-paste, so I'm going ahead and cc'ing gtk-doc-list because if
we have an m4 macro and/or Makefile-hunks-to-include somewhere, those
should come with gtk-doc.

However until gtk-doc has this feature I think putting in my patch is
right, since things don't work at the moment.

Also, the template files need to be committed, the ones in CVS are
behind the latest that gtk-doc will generate. I can do that if you
want.

Havoc

Index: configure.in
===================================================================
RCS file: /cvs/gnome/bonobo-activation/configure.in,v
retrieving revision 1.101
diff -u -p -u -r1.101 configure.in
--- configure.in	2002/01/25 19:28:44	1.101
+++ configure.in	2002/02/01 20:42:19
@@ -78,14 +78,64 @@ AC_SUBST(UTILS_CFLAGS)
 ORBIT_IDL="`$PKG_CONFIG --variable=orbit_idl ORBit-2.0`"
 AC_SUBST(ORBIT_IDL)
 
-dnl ======================
-dnl = gtk-doc stuff
-dnl ======================
-GNOME_GTKDOC_CHECK
-
-dnl ======================
-dnl = end gtk-doc stuff
-dnl ======================
+  
+dnl **************************
+dnl *** Checks for gtk-doc ***
+dnl **************************
+
+AC_ARG_WITH(html-dir, [  --with-html-dir=PATH path to installed docs ])
+
+if test "x$with_html_dir" = "x" ; then
+  HTML_DIR='${datadir}/gtk-doc/html'
+else
+  HTML_DIR=$with_html_dir
+fi
+
+AC_SUBST(HTML_DIR)
+
+AC_CHECK_PROG(GTKDOC, gtkdoc-mkdb, true, false)
+
+gtk_doc_min_version=0.6
+if $GTKDOC ; then 
+    gtk_doc_version=`gtkdoc-mkdb --version`
+    AC_MSG_CHECKING([gtk-doc version ($gtk_doc_version) >= $gtk_doc_min_version])
+    if perl <<EOF ; then
+      exit (("$gtk_doc_version" =~ /^[[0-9]]+\.[[0-9]]+$/) &&
+            ("$gtk_doc_version" >= "$gtk_doc_min_version") ? 0 : 1);
+EOF
+      AC_MSG_RESULT(yes)
+   else
+      AC_MSG_RESULT(no)
+      GTKDOC=false
+   fi
+fi
+
+AM_CONDITIONAL(HAVE_GTK_DOC, $GTKDOC)
+AC_SUBST(HAVE_GTK_DOC)
+
+AC_CHECK_PROG(DB2HTML, db2html, true, false)
+AM_CONDITIONAL(HAVE_DOCBOOK, $DB2HTML)
+
+dnl Let people disable the gtk-doc stuff.
+AC_ARG_ENABLE(gtk-doc, [  --enable-gtk-doc  Use gtk-doc to build documentation [default=auto]], enable_gtk_doc="$enableval", enable_gtk_doc=auto)
+
+if test x$enable_gtk_doc = xauto ; then
+  if test x$GTKDOC = xtrue ; then
+    enable_gtk_doc=yes
+  else
+    enable_gtk_doc=no 
+  fi
+fi
+
+dnl NOTE: We need to use a separate automake conditional for this
+dnl       to make this work with the tarballs.
+AM_CONDITIONAL(ENABLE_GTK_DOC, test x$enable_gtk_doc = xyes)
+
+  
+dnl **************************
+dnl *** End checks for gtk-doc ***
+dnl **************************
+
 
 AC_CHECK_LIB(popt, poptDupArgv,,
 AC_MSG_ERROR([You must have popt 1.5 or newer to compile bonobo-activation.]))
Index: ChangeLog
===================================================================
RCS file: /cvs/gnome/bonobo-activation/ChangeLog,v
retrieving revision 1.261
diff -u -p -u -r1.261 ChangeLog
--- ChangeLog	2002/01/25 19:28:44	1.261
+++ ChangeLog	2002/02/01 20:42:19
@@ -1,3 +1,14 @@
+2002-02-01  Havoc Pennington  <hp redhat com>
+
+	* configure.in: improve gtk-doc check to handle more cases and set
+	up HTML_DIR.
+
+	* api-docs/Makefile.am: move to the boilerplate from 
+	pango, gtk, etc.
+
+	* api-docs/bonobo-activation.sgml: set id of book to index so we
+	get index.html
+
 2002-01-25  Alexander Shopov  <al_shopov web bg>
 
 	* configure.in (ALL_LINGUAS): Added "bg" (Bulgarian).
Index: api-docs/Makefile.am
===================================================================
RCS file: /cvs/gnome/bonobo-activation/api-docs/Makefile.am,v
retrieving revision 1.11
diff -u -p -u -r1.11 Makefile.am
--- api-docs/Makefile.am	2001/08/07 08:49:57	1.11
+++ api-docs/Makefile.am	2002/02/01 20:42:19
@@ -1,3 +1,5 @@
+## Process this file with automake to create Makefile.in.
+
 NULL=
 
 # The name of the module.
@@ -6,31 +8,35 @@ DOC_MODULE=bonobo-activation
 # The top-level SGML file.
 DOC_MAIN_SGML_FILE=bonobo-activation.sgml
 
-# The directory containing the source code (if it contains documentation).
-DOC_SOURCE_DIR=$(top_srcdir)/bonobo-activation
+# The directory containing the source code. Relative to $(srcdir)
+DOC_SOURCE_DIR=../bonobo-activation
 
-HTML_DIR=$(datadir)/bonobo-activation/html
+# Extra options to supply to gtkdoc-scan
+SCAN_OPTIONS=
 
-TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
+# Extra options to supply to gtkdoc-mkdb
+MKDB_OPTIONS=--sgml-mode
 
-tmpl_sources =				\
-	tmpl/utilities.sgml		\
-	tmpl/initialization.sgml	\
-	tmpl/query.sgml			\
-	tmpl/registration.sgml		\
-	tmpl/debugging.sgml		\
-	$(NULL)
+# Extra options to supply to gtkdoc-fixref
+FIXXREF_OPTIONS=
 
+# Used for dependencies
+HFILE_GLOB=$(top_srcdir)/bonobo-activation/*.h
+CFILE_GLOB=$(top_srcdir)/bonobo-activation/*.c
 
-if ENABLE_GTK_DOC
-bonobo_activation_docdir = $(HTML_DIR)
-bonobo_activation_doc_DATA =		\
-	bonobo-activation.html		\
-	$(NULL)
-endif
+# Headers to ignore
+IGNORE_HFILES=
+
+# Extra files to add when scanning
+EXTRA_HFILES=
 
+# Images to copy into HTML directory
+HTML_IMAGES =				\
+	bonobo-activation.png		\
+	$(NULL)
 
-my_sgml_files = 			\
+# Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE)
+content_files =				\
 	tutorial.sgml			\
 	migrating.sgml			\
 	server-xml-reference.sgml	\
@@ -41,52 +47,123 @@ my_sgml_files = 			\
 	fdl.sgml			\
 	$(NULL)
 
+## extra dist stuff
+extra_files =
+
+# CFLAGS and LDFLAGS for compiling scan program. Only needed
+# if $(DOC_MODULE).types is non-empty.
+GTKDOC_CFLAGS =
+GTKDOC_LIBS =
+
+# Commands for compiling and linking 
+GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC)
+GTKDOC_LD=$(LIBTOOL) --mode=link $(CC)
+
+dist-hook-local:
+	mkdir $(distdir)/TEXT;          \
+	for f in $(srcdir)/TEXT/* ; do  \
+	  test -f $$f && cp -p $$f $(distdir)/TEXT; \
+	done
+
+
+####################################
+# Everything below here is generic #
+####################################
+
+# 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 = 				\
-	$(my_sgml_files)		\
-	bonobo-activation.png		\
-	bonobo-activation-decl.txt	\
-	bonobo-activation-sections.txt	\
-	$(NULL)
+	$(content_files)		\
+	$(extra_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).signals
 
 if ENABLE_GTK_DOC
-bonobo-activation.html:
-	if test ! -d $(top_builddir)/api-docs/tmpl; then			\
-		mkdir $(top_builddir)/api-docs/tmpl; 				\
-		cp $(srcdir)/tmpl/*.sgml $(top_builddir)/api-docs/tmpl/; 	\
-		cp $(srcdir)/*.sgml $(srcdir)/*.txt  $(top_builddir)/api-docs/; \
-	fi
-	cd $(top_builddir)/api-docs/ \
-	&& gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR)
-	if test ! -d $(top_builddir)/api-docs/html; then	\
-		mkdir $(top_builddir)/api-docs/html;		\
+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 --module=$(DOC_MODULE) --output-dir=$(srcdir) ; \
+	else \
+	    cd $(srcdir) ; \
+	    for i in $(SCANOBJ_FILES) ; do \
+               test -f $$i || touch $$i ; \
+	    done \
 	fi
-	-cd $(top_builddir)/api-docs/html && \
-	gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
-	-cd $(top_builddir)/api-docs/ && \
-	cp $(srcdir)/bonobo-activation.png $(top_builddir)/api-docs/html
+	cd $(srcdir) && \
+	  gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES)
+	touch scan-build.stamp
 
-else
+$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): scan-build.stamp
+	@true
 
-bonobo-activation.html:
+#### templates ####
 
-endif
+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 ####
 
-templates:
-	cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
+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 *.signals *-unused.txt
+	rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS)
 
 maintainer-clean-local: clean
-	cd $(top_builddir)/api-docs/ && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
+	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/*.html`; \
-	if test "$$installfiles" = '$(srcdir)/html/*.html'; \
+	(installfiles=`echo $(srcdir)/html/*`; \
+	if test "$$installfiles" = '$(srcdir)/html/*'; \
 	then echo '-- Nothing to install' ; \
 	else \
 	  for i in $$installfiles; do \
@@ -95,16 +172,25 @@ install-data-local:
 	  done; \
 	  echo '-- Installing $(srcdir)/html/index.sgml' ; \
 	  $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR); \
-	  echo '-- Fixing Crossreferences' ; \
-	  gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR)|| true; \
 	fi)
 
-dist-hook: sgml html
-	mkdir $(distdir)/html
+#
+# 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
-	-cp $(srcdir)/html/* $(distdir)/html
+	mkdir $(distdir)/sgml
+	mkdir $(distdir)/html
 	-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
-
-.PHONY : html sgml templates scan
-
+	-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
+	-cp $(srcdir)/html/* $(distdir)/html
 
+.PHONY : dist-hook-local
Index: api-docs/bonobo-activation.sgml
===================================================================
RCS file: /cvs/gnome/bonobo-activation/api-docs/bonobo-activation.sgml,v
retrieving revision 1.7
diff -u -p -u -r1.7 bonobo-activation.sgml
--- api-docs/bonobo-activation.sgml	2001/12/11 00:28:39	1.7
+++ api-docs/bonobo-activation.sgml	2002/02/01 20:42:19
@@ -14,7 +14,7 @@
 <!entity FDL SYSTEM "fdl.sgml">
 ]>
 
-<book>
+<book id="index">
   <bookinfo>
     <title>Bonobo Activation API Reference Manual</title>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]