Migrate doc generation to docbook/fop (postgresql approach)

.travis.yml

@@ -16,7 +16,7 @@ dist: focal
 before_install:
   # extra apt.pg.o.sh options added in version 204, travis currently has 199 (2019-11-27)
   - sudo apt-get -qq update
-  - sudo apt-get -y install postgresql-common libhealpix-cxx-dev docbook-dsssl docbook-xml openjade
+  - sudo apt-get -y install postgresql-common libhealpix-cxx-dev docbook-xml docbook-xsl libxml2-utils xsltproc fop
 
 install:
   - sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -p -v $PG_SUPPORTED_VERSIONS -i
@@ -40,4 +40,3 @@ script:
   - pg_virtualenv make USE_HEALPIX=0 crushtest
   - if test -s regression.diffs; then cat regression.diffs; exit 1; fi
   - make -C doc
-  - sudo make -C doc install

Makefile

@@ -1,5 +1,6 @@
-PGSPHERE_VERSION = 1.3.1
-EXTENSION        = pg_sphere
+
+include Makefile.common.mk
+
 RELEASE_SQL      = $(EXTENSION)--$(PGSPHERE_VERSION).sql
 USE_PGXS         = 1
 USE_HEALPIX      =? 1

Makefile.common.mk

@@ -0,0 +1,8 @@
+#----------------------------------------------------------------------------
+#
+# pgSphere common definitions
+#
+#----------------------------------------------------------------------------
+
+EXTENSION        	:= pg_sphere
+PGSPHERE_VERSION 	:= 1.3.1

doc/Makefile

@@ -1,90 +1,103 @@
 #----------------------------------------------------------------------------
 #
-# pgSphere documentation makefile
+# pgSphere documentation generation
 #
 #----------------------------------------------------------------------------
 
-USE_PGXS = 1
-ifdef USE_PGXS
-PG_CONFIG = pg_config
-PGXS := $(shell $(PG_CONFIG) --pgxs)
-include $(PGXS)
-else
-subdir = contrib/pg_sphere/doc
-top_builddir = ../../..
-include $(top_builddir)/src/Makefile.global
-include $(top_srcdir)/contrib/contrib-global.mk
+ifndef PGSPHERE_VERSION
+include ../Makefile.common.mk
+ifndef PGSPHERE_VERSION
+$(error PGSPHERE_VERSION is not set)
+endif
 endif
 
-.SECONDARY:
-.NOTPARALLEL:
+ifndef FOP
+FOP = fop
+endif
 
-ifndef COLLATEINDEX
-COLLATEINDEX = $(DOCBOOKSTYLE)/bin/collateindex.pl
+ifdef XMLLINT
+XMLLINT := $(XMLLINT) --nonet
+else
+XMLLINT = xmllint --nonet
 endif
 
-ifndef JADE
-JADE = openjade
+ifdef XSLTPROC
+XSLTPROC := $(XSLTPROC) --nonet
+else
+XSLTPROC = xsltproc --nonet
 endif
-SGMLINCLUDE = -D $(srcdir)
 
-ALLSGML := $(wildcard $(srcdir)/*.sgm)
+override XSLTPROCFLAGS += \
+	--path stylesheets --path img --path . \
+	--stringparam pg_sphere.version '$(PGSPHERE_VERSION)' \
+	--stringparam pg.version '$(PGSPHERE_VERSION)'
 
-ifdef DOCBOOKSTYLE
-CATALOG = -c $(DOCBOOKSTYLE)/catalog
-endif
+XMLINCLUDE = --path .
+ALLSGML := $(wildcard *.sgm)
+ALLIMAGES := $(wildcard img/*.jpg)
 
-COLLATEINDEX := $(PERL) $(COLLATEINDEX) -f -g
+all: html pdf
 
+.PHONY: all html pdf clean
 
-all   : html
+# This line fixes the error like:
+# No rule to make target 'pg_sphere.control'
+.PHONY: pg_sphere.control
 
-.PHONY: html pdf ps
+version.xml:
+	@echo $(PGSPHERE_VERSION) > version.xml
 
-XMLDCL = declaration/xml.dcl
+pg_sphere-full.xml: version.xml
+pg_sphere-full.xml: pg_sphere.xml $(ALLSGML)
+	$(XMLLINT) $(XMLINCLUDE) --output $@ --noent --valid $<
 
-html  : pg_sphere.xml $(ALLSGML) pg_sphere.dsl
-	@rm -f *.html
-	@rm -rf html
-	mkdir html
-	mkdir html/img
-	cp img/*.jpg img/*.png html/img
-	cp pg_sphere.css html
-	$(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -b UTF-8 -d pg_sphere.dsl -i html  -t sgml $(XMLDCL) $<
-	mv *.html html
+#------------------------------------------------------------------------------
+# HTML
+#------------------------------------------------------------------------------
 
-pg_sphere.tex : pg_sphere.xml $(ALLSGML) pg_sphere.dsl
-	$(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d pg_sphere.dsl -i print -t tex -o $@ $(XMLDCL) $<
+XSLTPROC_HTML_MULTIPAGE_FLAGS := --stringparam img.src.path ''
+XSLTPROC_HTML_SINGLEPAGE_FLAGS := --stringparam img.src.path ''
 
-pdf : jadetex.cfg pg_sphere.pdf
+html: html-singlepage html-multipage
 
-pg_sphere.pdf: pg_sphere.tex
-	@rm -f $*.aux $*.log $*.out
-	pdfjadetex $<
-	pdfjadetex $<
-	pdfjadetex $<
+html-multipage: stylesheets/stylesheet.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
+	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_MULTIPAGE_FLAGS) $(wordlist 1,2,$^)
+	mkdir -p html/img
+	cp $(ALLIMAGES) html/img
 
-ps : pg_sphere.ps
+html-singlepage: pg_sphere-$(PGSPHERE_VERSION).html
 
-pg_sphere.ps: pg_sphere.pdf
-	pdftops $< $@
+pg_sphere-$(PGSPHERE_VERSION).html: stylesheets/stylesheet-html-nochunk.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
+	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_SINGLEPAGE_FLAGS) -o $@ $(wordlist 1,2,$^)
 
-pg_sphere.dsl : pg_sphere.dsl-dist
-	cp $< $@
+#------------------------------------------------------------------------------
+# PDF
+#------------------------------------------------------------------------------
 
-jadetex.cfg : jadetex.cfg-dist
-	cp $< $@
+pdf: pg_sphere-${PGSPHERE_VERSION}-A4.pdf pg_sphere-${PGSPHERE_VERSION}-US.pdf
 
+pg_sphere-$(PGSPHERE_VERSION)-A4.pdf: pg_sphere.A4.fo
+	$(FOP) -v -fo $< -pdf $@
 
+pg_sphere-$(PGSPHERE_VERSION)-US.pdf: pg_sphere.US.fo
+	$(FOP) -v -fo $< -pdf $@
 
-##
-## Clean
-##
+pg_sphere.A4.fo: stylesheets/stylesheet-fo.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
+	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type A4 -o $@ stylesheets/stylesheet-fo.xsl pg_sphere-full.xml
 
-clean distclean maintainer-clean:
-# HTML
-	rm -rf html pg_sphere.dsl
-# print
-	rm -f *.rtf *.tex *.dvi *.aux *.log *.ps *.pdf *.out *.fot jadetex.cfg
-# img
-	make clean -C img
+pg_sphere.US.fo: stylesheets/stylesheet-fo.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
+	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type USLetter -o $@ stylesheets/stylesheet-fo.xsl pg_sphere-full.xml
+
+#------------------------------------------------------------------------------
+# Cleanup
+#------------------------------------------------------------------------------
+
+clean distclean:
+	rm -rf ./html
+	rm -f version.xml
+	rm -f pg_sphere-full.xml
+	rm -f pg_sphere.A4.fo
+	rm -f pg_sphere.US.fo
+	rm -f pg_sphere-$(PGSPHERE_VERSION).html
+	rm -f pg_sphere-$(PGSPHERE_VERSION)-A4.pdf
+	rm -f pg_sphere-$(PGSPHERE_VERSION)-US.pdf

doc/appendixes.sgm

@@ -19,7 +19,7 @@
           </listitem>
           <listitem>
             <para>
-              This version is compatible to <application>PostgreSQL</application> 8.4 
+              This version is compatible to <application>PostgreSQL</application> 8.4
             </para>
           </listitem>
         </itemizedlist>
@@ -66,5 +66,5 @@
           </listitem>
         </itemizedlist>
       </sect2>
-        
+
     </sect1>

doc/constructors.sgm

@@ -1,7 +1,6 @@
-    <sect1 id="construct">
-        <title>
-            Constructors
-        </title>
+<chapter id="construct">
+ <title>Constructors</title>
+
         <para>
           Constructors within <application>pgSphere</application> are
           functions needed to create spherical data types from other data
@@ -14,7 +13,7 @@
           mentioned here.
         </para>
 
-        <sect2 id="contr.spoint">
+        <sect1 id="contr.spoint">
           <title>
             Point
           </title>
@@ -44,9 +43,9 @@
             </programlisting>
           </example>
 
-        </sect2>
+        </sect1>
 
-        <sect2 id="contr.strans">
+        <sect1 id="contr.strans">
           <title>
             Euler transformation
           </title>
@@ -90,9 +89,9 @@
             </programlisting>
           </example>
 
-        </sect2>
+        </sect1>
 
-        <sect2 id="contr.scircle">
+        <sect1 id="contr.scircle">
           <title>
             Circle
           </title>
@@ -110,7 +109,7 @@
             returns a spherical circle with center at
             <parameter>center</parameter> and a radius
             <parameter>radius</parameter> in radians.  The circle radius has
-            to be larger than or equal to zero but less or equal to 90&deg;. 
+            to be larger than or equal to zero but less or equal to 90&deg;.
             Otherwise, this function returns an error.
           </para>
           <example>
@@ -134,18 +133,18 @@
            </programlisting>
          </example>
 
-        </sect2>
+        </sect1>
 
-        <sect2 id="contr.sline">
+        <sect1 id="contr.sline">
           <title>
             Line
           </title>
           <para>
             The input of spherical lines using Euler transformation and
-            length is quite circumstantial (see <xref linkend="dt.sline"/>). 
+            length is quite circumstantial (see <xref linkend="dt.sline"/>).
             For short lines it is easier to input a line specifying the
             beginning and the end of the line.
-          </para>              
+          </para>
           <funcsynopsis>
             <funcprototype>
               <funcdef><function>sline</function></funcdef>
@@ -155,13 +154,13 @@
           </funcsynopsis>
           <para>
             If the distance between <parameter>begin</parameter> and
-            <parameter>end</parameter> is 180&deg; (&pgr;), this function
-            returns an error because the location of the line is undefined. 
+            <parameter>end</parameter> is 180&deg; (&pg_pgr;), this function
+            returns an error because the location of the line is undefined.
             However, if longitudes of <parameter>begin</parameter> and
             <parameter>end</parameter> are equal,
             <application>pgSphere</application> assumes a meridian and
             returns the corresponding spherical line.
-          </para>               
+          </para>
           <example id="const.line.1">
             <title>A line created using begin and end of line</title>
             <simpara>
@@ -212,9 +211,9 @@
 <![CDATA[(1 row)]]>
             </programlisting>
           </example>
-        </sect2>
+        </sect1>
 
-        <sect2 id="contr.sellipse">
+        <sect1 id="contr.sellipse">
           <title>
             Ellipse
           </title>
@@ -238,7 +237,7 @@
             radii of the ellipse in radians. If the major radius is smaller
             than minor radius, <application>pgSphere</application> swaps the
             values automatically.  The last parameter
-            <parameter>incl</parameter> is the inclination angle in radians. 
+            <parameter>incl</parameter> is the inclination angle in radians.
             For more informations about ellipses, see <xref
             linkend="dt.sellipse"/>.
           </para>
@@ -263,9 +262,9 @@
 <![CDATA[(1 row)]]>
             </programlisting>
           </example>
-        </sect2>
+        </sect1>
 
-        <sect2 id="contr.spoly">
+        <sect1 id="contr.spoly">
           <title>
             Polygon
           </title>
@@ -318,9 +317,9 @@
 <![CDATA[(1 row)]]>
             </programlisting>
           </example>
-        </sect2>
+        </sect1>
 
-        <sect2 id="contr.spath">
+        <sect1 id="contr.spath">
           <title>
             Path
           </title>
@@ -371,9 +370,9 @@
             </programlisting>
           </example>
 
-        </sect2>
+        </sect1>
 
-        <sect2 id="contr.sbox">
+        <sect1 id="contr.sbox">
           <title>
             Coordinates range
           </title>
@@ -403,9 +402,9 @@
 <![CDATA[sql> SELECT sbox ( spoint '(0d,0d),(10d,10d)' );]]>
             </programlisting>
           </example>
-        </sect2>
+        </sect1>
 
-        <sect2 id="contr.smoc">
+        <sect1 id="contr.smoc">
           <title>
             <type>smoc</type>
           </title>
@@ -449,6 +448,6 @@
           <para>
             creates an <type>smoc</type> of the given order covering the spoly
           </para>
-        </sect2>
+        </sect1>
 
-    </sect1>
+</chapter>