Use asciidoc and xmlto to automatic generation of man and html docs

Michael Paquier · Michael Paquier · commit 663978530537 · 2014-01-12T03:03:30.000+09:00
This has the merit to put all the documentation of the project into a
single banner, and to centralize all the project in a single place at
code level.

Compiling documentation can be made by setting the variables ASCIIDOC
and XMLTO. As PostgreSQL extension system is not that smart for doc
generation, some custom Makefile path is used to install man pages into
a folder that could directly by used in MANPATH.
diff --git a/Makefile b/Makefile
@@ -18,11 +18,19 @@ SRCS = \
 	pgut/pgut.c \
 	pgut/pgut-port.c
 OBJS = $(SRCS:.c=.o)
-# pg_crc.c and are copied from PostgreSQL source tree.
 
-DOCS = pg_rman.txt
+DOCS = doc/pg_rman.txt
+
+# asciidoc and xmlto are present, so install the html documentation and man
+# pages as well. html is part of the vanilla documentation. Man pages need a
+# special handling at installation.
+ifneq ($(ASCIIDOC),)
+ifneq ($(XMLTO),)
+man_DOCS = doc/pg_rman.1
+DOCS += doc/pg_rman.html doc/README.html
+endif # XMLTO
+endif # ASCIIDOC
 
-# XXX for debug, add -g and disable optimization
 PG_CPPFLAGS = -I$(libpq_srcdir)
 PG_LIBS = $(libpq_pgport)
 
@@ -44,3 +52,25 @@ LIBS := $(filter-out -lxml2, $(LIBS))
 LIBS := $(filter-out -lxslt, $(LIBS))
 
 $(OBJS): pg_rman.h
+
+# Part related to documentation
+# Compile documentation as well is ASCIIDOC and XMLTO are defined
+ifneq ($(ASCIIDOC),)
+ifneq ($(XMLTO),)
+all: docs
+docs:
+	$(MAKE) -C doc/
+
+# Special handling for man pages, they need to be in a dedicated folder
+install: install-man
+
+install-man:
+	$(MKDIR_P) '$(DESTDIR)$(docdir)/$(docmoduledir)/man1/'
+	$(INSTALL_DATA) $(man_DOCS) '$(DESTDIR)$(docdir)/$(docmoduledir)/man1/'
+endif # XMLTO
+endif # ASCIIDOC
+
+# Clean up documentation as well
+clean: clean-docs
+clean-docs:
+	$(MAKE) -C doc/ clean
diff --git a/README b/README
@@ -23,13 +23,16 @@ Compiling pg_rman requires a PostgreSQL installation and can be done in
 two ways:
 
 1. Put pg_rman project directory inside PostgreSQL source tree as
-contrib/pg_rman, and use "make" to compile
+contrib/pg_rman, and use this command for compilation:
 
-or
+	$ cd $POSTGRES_SOURCE/contrib/pg_rman
+	$ make
 
 2. Keep the project directory as-is and use the PGXS development
 infrastructure provided by a PostgreSQL installation to perform the
-compilation: "make USE_PGXS=1"
+compilation:
+
+	$ make USE_PGXS=1
 
 In addition, you must have pg_config in $PATH.
 
@@ -44,7 +47,18 @@ pg_rman has been tested on Linux and Unix-based platforms.
 Documentation
 -------------
 
-All the documentation is written and maintained in pg_rman.txt.
+All the documentation is maintained in doc/ as text file, that is then
+fetched by asciidoc to generate automatically man pages and html
+documentation.
+
+In order to generate the documentation, the variables XMLTO and ASCIIDOC
+need to be set to proper values indicating where are located the binaries
+of respectively xmlto and asciidoc. An example of build is as follows:
+
+	$ make USE_PGXS=1 ASCIIDOC=asciidoc XMLTO=xmlto
+
+They could as well be set as environment variables for development
+purposes.
 
 Regression tests
 ----------------
diff --git a/doc/.gitignore b/doc/.gitignore
@@ -0,0 +1,4 @@
+# Documentation entries
+/*.html
+/*.xml
+/pg_rman.1
diff --git a/doc/Makefile b/doc/Makefile
@@ -0,0 +1,33 @@
+
+manpages = pg_rman.1
+
+EXTRA_DIST = pg_rman.txt Makefile $(manpages)
+
+htmls = pg_rman.html README.html
+
+# We have asciidoc and xmlto, so build everything and define correct
+# rules for build.
+ifneq ($(ASCIIDOC),)
+ifneq ($(XMLTO),)
+dist_man_MANS = $(manpages)
+doc_DATA = $(htmls)
+
+pg_rman.1: pg_rman.xml $(doc_DATA)
+	$(XMLTO) man $<
+
+%.xml: %.txt
+	$(ASCIIDOC) -b docbook -d manpage -o $@ $<
+
+%.html: %.txt
+	$(ASCIIDOC) -a toc -o $@ $<
+
+README.html: ../README
+	$(ASCIIDOC) -a toc -o $@ $<
+
+endif # XMLTO
+endif # ASCIIDOC
+
+clean:
+	rm -rf $(manpages) *.html *.xml
+
+.PHONY: clean
diff --git a/doc/pg_rman.txt b/doc/pg_rman.txt

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +# Documentation entries
 +/*.html
 +/*.xml
 +/pg_rman.1