Skip to content

Commit 3a912fc

Browse files
vitcppvitcpp
authored
Merge pull request #63 from vitcpp/doc-improve-1
Migrate doc generation to docbook/fop (postgresql approach)
2 parents 1c4a5f3 + 48c3d5e commit 3a912fc

28 files changed

+2381
-901
lines changed

Diff for: ‎.travis.yml

+1-2
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ dist: focal
1616
before_install:
1717
# extra apt.pg.o.sh options added in version 204, travis currently has 199 (2019-11-27)
1818
- sudo apt-get -qq update
19-
- sudo apt-get -y install postgresql-common libhealpix-cxx-dev docbook-dsssl docbook-xml openjade
19+
- sudo apt-get -y install postgresql-common libhealpix-cxx-dev docbook-xml docbook-xsl libxml2-utils xsltproc fop
2020

2121
install:
2222
- sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -p -v $PG_SUPPORTED_VERSIONS -i
@@ -40,4 +40,3 @@ script:
4040
- pg_virtualenv make USE_HEALPIX=0 crushtest
4141
- if test -s regression.diffs; then cat regression.diffs; exit 1; fi
4242
- make -C doc
43-
- sudo make -C doc install

Diff for: ‎Makefile

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
PGSPHERE_VERSION = 1.3.1
2-
EXTENSION = pg_sphere
1+
2+
include Makefile.common.mk
3+
34
RELEASE_SQL = $(EXTENSION)--$(PGSPHERE_VERSION).sql
45
USE_PGXS = 1
56
USE_HEALPIX =? 1

Diff for: ‎Makefile.common.mk

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#----------------------------------------------------------------------------
2+
#
3+
# pgSphere common definitions
4+
#
5+
#----------------------------------------------------------------------------
6+
7+
EXTENSION := pg_sphere
8+
PGSPHERE_VERSION := 1.3.1

Diff for: ‎doc/Makefile

+73-60
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,103 @@
11
#----------------------------------------------------------------------------
22
#
3-
# pgSphere documentation makefile
3+
# pgSphere documentation generation
44
#
55
#----------------------------------------------------------------------------
66

7-
USE_PGXS = 1
8-
ifdef USE_PGXS
9-
PG_CONFIG = pg_config
10-
PGXS := $(shell $(PG_CONFIG) --pgxs)
11-
include $(PGXS)
12-
else
13-
subdir = contrib/pg_sphere/doc
14-
top_builddir = ../../..
15-
include $(top_builddir)/src/Makefile.global
16-
include $(top_srcdir)/contrib/contrib-global.mk
7+
ifndef PGSPHERE_VERSION
8+
include ../Makefile.common.mk
9+
ifndef PGSPHERE_VERSION
10+
$(error PGSPHERE_VERSION is not set)
11+
endif
1712
endif
1813

19-
.SECONDARY:
20-
.NOTPARALLEL:
14+
ifndef FOP
15+
FOP = fop
16+
endif
2117

22-
ifndef COLLATEINDEX
23-
COLLATEINDEX = $(DOCBOOKSTYLE)/bin/collateindex.pl
18+
ifdef XMLLINT
19+
XMLLINT := $(XMLLINT) --nonet
20+
else
21+
XMLLINT = xmllint --nonet
2422
endif
2523

26-
ifndef JADE
27-
JADE = openjade
24+
ifdef XSLTPROC
25+
XSLTPROC := $(XSLTPROC) --nonet
26+
else
27+
XSLTPROC = xsltproc --nonet
2828
endif
29-
SGMLINCLUDE = -D $(srcdir)
3029

31-
ALLSGML := $(wildcard $(srcdir)/*.sgm)
30+
override XSLTPROCFLAGS += \
31+
--path stylesheets --path img --path . \
32+
--stringparam pg_sphere.version '$(PGSPHERE_VERSION)' \
33+
--stringparam pg.version '$(PGSPHERE_VERSION)'
3234

33-
ifdef DOCBOOKSTYLE
34-
CATALOG = -c $(DOCBOOKSTYLE)/catalog
35-
endif
35+
XMLINCLUDE = --path .
36+
ALLSGML := $(wildcard *.sgm)
37+
ALLIMAGES := $(wildcard img/*.jpg)
3638

37-
COLLATEINDEX := $(PERL) $(COLLATEINDEX) -f -g
39+
all: html pdf
3840

41+
.PHONY: all html pdf clean
3942

40-
all : html
43+
# This line fixes the error like:
44+
# No rule to make target 'pg_sphere.control'
45+
.PHONY: pg_sphere.control
4146

42-
.PHONY: html pdf ps
47+
version.xml:
48+
@echo $(PGSPHERE_VERSION) > version.xml
4349

44-
XMLDCL = declaration/xml.dcl
50+
pg_sphere-full.xml: version.xml
51+
pg_sphere-full.xml: pg_sphere.xml $(ALLSGML)
52+
$(XMLLINT) $(XMLINCLUDE) --output $@ --noent --valid $<
4553

46-
html : pg_sphere.xml $(ALLSGML) pg_sphere.dsl
47-
@rm -f *.html
48-
@rm -rf html
49-
mkdir html
50-
mkdir html/img
51-
cp img/*.jpg img/*.png html/img
52-
cp pg_sphere.css html
53-
$(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -b UTF-8 -d pg_sphere.dsl -i html -t sgml $(XMLDCL) $<
54-
mv *.html html
54+
#------------------------------------------------------------------------------
55+
# HTML
56+
#------------------------------------------------------------------------------
5557

56-
pg_sphere.tex : pg_sphere.xml $(ALLSGML) pg_sphere.dsl
57-
$(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d pg_sphere.dsl -i print -t tex -o $@ $(XMLDCL) $<
58+
XSLTPROC_HTML_MULTIPAGE_FLAGS := --stringparam img.src.path ''
59+
XSLTPROC_HTML_SINGLEPAGE_FLAGS := --stringparam img.src.path ''
5860

59-
pdf : jadetex.cfg pg_sphere.pdf
61+
html: html-singlepage html-multipage
6062

61-
pg_sphere.pdf: pg_sphere.tex
62-
@rm -f $*.aux $*.log $*.out
63-
pdfjadetex $<
64-
pdfjadetex $<
65-
pdfjadetex $<
63+
html-multipage: stylesheets/stylesheet.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
64+
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_MULTIPAGE_FLAGS) $(wordlist 1,2,$^)
65+
mkdir -p html/img
66+
cp $(ALLIMAGES) html/img
6667

67-
ps : pg_sphere.ps
68+
html-singlepage: pg_sphere-$(PGSPHERE_VERSION).html
6869

69-
pg_sphere.ps: pg_sphere.pdf
70-
pdftops $< $@
70+
pg_sphere-$(PGSPHERE_VERSION).html: stylesheets/stylesheet-html-nochunk.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
71+
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_SINGLEPAGE_FLAGS) -o $@ $(wordlist 1,2,$^)
7172

72-
pg_sphere.dsl : pg_sphere.dsl-dist
73-
cp $< $@
73+
#------------------------------------------------------------------------------
74+
# PDF
75+
#------------------------------------------------------------------------------
7476

75-
jadetex.cfg : jadetex.cfg-dist
76-
cp $< $@
77+
pdf: pg_sphere-${PGSPHERE_VERSION}-A4.pdf pg_sphere-${PGSPHERE_VERSION}-US.pdf
7778

79+
pg_sphere-$(PGSPHERE_VERSION)-A4.pdf: pg_sphere.A4.fo
80+
$(FOP) -v -fo $< -pdf $@
7881

82+
pg_sphere-$(PGSPHERE_VERSION)-US.pdf: pg_sphere.US.fo
83+
$(FOP) -v -fo $< -pdf $@
7984

80-
##
81-
## Clean
82-
##
85+
pg_sphere.A4.fo: stylesheets/stylesheet-fo.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
86+
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type A4 -o $@ stylesheets/stylesheet-fo.xsl pg_sphere-full.xml
8387

84-
clean distclean maintainer-clean:
85-
# HTML
86-
rm -rf html pg_sphere.dsl
87-
# print
88-
rm -f *.rtf *.tex *.dvi *.aux *.log *.ps *.pdf *.out *.fot jadetex.cfg
89-
# img
90-
make clean -C img
88+
pg_sphere.US.fo: stylesheets/stylesheet-fo.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
89+
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type USLetter -o $@ stylesheets/stylesheet-fo.xsl pg_sphere-full.xml
90+
91+
#------------------------------------------------------------------------------
92+
# Cleanup
93+
#------------------------------------------------------------------------------
94+
95+
clean distclean:
96+
rm -rf ./html
97+
rm -f version.xml
98+
rm -f pg_sphere-full.xml
99+
rm -f pg_sphere.A4.fo
100+
rm -f pg_sphere.US.fo
101+
rm -f pg_sphere-$(PGSPHERE_VERSION).html
102+
rm -f pg_sphere-$(PGSPHERE_VERSION)-A4.pdf
103+
rm -f pg_sphere-$(PGSPHERE_VERSION)-US.pdf

Diff for: ‎doc/appendixes.sgm

+2-2
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
</listitem>
2020
<listitem>
2121
<para>
22-
This version is compatible to <application>PostgreSQL</application> 8.4
22+
This version is compatible to <application>PostgreSQL</application> 8.4
2323
</para>
2424
</listitem>
2525
</itemizedlist>
@@ -66,5 +66,5 @@
6666
</listitem>
6767
</itemizedlist>
6868
</sect2>
69-
69+
7070
</sect1>

Diff for: ‎doc/constructors.sgm

+29-30
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
<sect1 id="construct">
2-
<title>
3-
Constructors
4-
</title>
1+
<chapter id="construct">
2+
<title>Constructors</title>
3+
54
<para>
65
Constructors within <application>pgSphere</application> are
76
functions needed to create spherical data types from other data
@@ -14,7 +13,7 @@
1413
mentioned here.
1514
</para>
1615

17-
<sect2 id="contr.spoint">
16+
<sect1 id="contr.spoint">
1817
<title>
1918
Point
2019
</title>
@@ -44,9 +43,9 @@
4443
</programlisting>
4544
</example>
4645

47-
</sect2>
46+
</sect1>
4847

49-
<sect2 id="contr.strans">
48+
<sect1 id="contr.strans">
5049
<title>
5150
Euler transformation
5251
</title>
@@ -90,9 +89,9 @@
9089
</programlisting>
9190
</example>
9291

93-
</sect2>
92+
</sect1>
9493

95-
<sect2 id="contr.scircle">
94+
<sect1 id="contr.scircle">
9695
<title>
9796
Circle
9897
</title>
@@ -110,7 +109,7 @@
110109
returns a spherical circle with center at
111110
<parameter>center</parameter> and a radius
112111
<parameter>radius</parameter> in radians. The circle radius has
113-
to be larger than or equal to zero but less or equal to 90&deg;.
112+
to be larger than or equal to zero but less or equal to 90&deg;.
114113
Otherwise, this function returns an error.
115114
</para>
116115
<example>
@@ -134,18 +133,18 @@
134133
</programlisting>
135134
</example>
136135

137-
</sect2>
136+
</sect1>
138137

139-
<sect2 id="contr.sline">
138+
<sect1 id="contr.sline">
140139
<title>
141140
Line
142141
</title>
143142
<para>
144143
The input of spherical lines using Euler transformation and
145-
length is quite circumstantial (see <xref linkend="dt.sline"/>).
144+
length is quite circumstantial (see <xref linkend="dt.sline"/>).
146145
For short lines it is easier to input a line specifying the
147146
beginning and the end of the line.
148-
</para>
147+
</para>
149148
<funcsynopsis>
150149
<funcprototype>
151150
<funcdef><function>sline</function></funcdef>
@@ -155,13 +154,13 @@
155154
</funcsynopsis>
156155
<para>
157156
If the distance between <parameter>begin</parameter> and
158-
<parameter>end</parameter> is 180&deg; (&pgr;), this function
159-
returns an error because the location of the line is undefined.
157+
<parameter>end</parameter> is 180&deg; (&pg_pgr;), this function
158+
returns an error because the location of the line is undefined.
160159
However, if longitudes of <parameter>begin</parameter> and
161160
<parameter>end</parameter> are equal,
162161
<application>pgSphere</application> assumes a meridian and
163162
returns the corresponding spherical line.
164-
</para>
163+
</para>
165164
<example id="const.line.1">
166165
<title>A line created using begin and end of line</title>
167166
<simpara>
@@ -212,9 +211,9 @@
212211
<![CDATA[(1 row)]]>
213212
</programlisting>
214213
</example>
215-
</sect2>
214+
</sect1>
216215

217-
<sect2 id="contr.sellipse">
216+
<sect1 id="contr.sellipse">
218217
<title>
219218
Ellipse
220219
</title>
@@ -238,7 +237,7 @@
238237
radii of the ellipse in radians. If the major radius is smaller
239238
than minor radius, <application>pgSphere</application> swaps the
240239
values automatically. The last parameter
241-
<parameter>incl</parameter> is the inclination angle in radians.
240+
<parameter>incl</parameter> is the inclination angle in radians.
242241
For more informations about ellipses, see <xref
243242
linkend="dt.sellipse"/>.
244243
</para>
@@ -263,9 +262,9 @@
263262
<![CDATA[(1 row)]]>
264263
</programlisting>
265264
</example>
266-
</sect2>
265+
</sect1>
267266

268-
<sect2 id="contr.spoly">
267+
<sect1 id="contr.spoly">
269268
<title>
270269
Polygon
271270
</title>
@@ -318,9 +317,9 @@
318317
<![CDATA[(1 row)]]>
319318
</programlisting>
320319
</example>
321-
</sect2>
320+
</sect1>
322321

323-
<sect2 id="contr.spath">
322+
<sect1 id="contr.spath">
324323
<title>
325324
Path
326325
</title>
@@ -371,9 +370,9 @@
371370
</programlisting>
372371
</example>
373372

374-
</sect2>
373+
</sect1>
375374

376-
<sect2 id="contr.sbox">
375+
<sect1 id="contr.sbox">
377376
<title>
378377
Coordinates range
379378
</title>
@@ -403,9 +402,9 @@
403402
<![CDATA[sql> SELECT sbox ( spoint '(0d,0d),(10d,10d)' );]]>
404403
</programlisting>
405404
</example>
406-
</sect2>
405+
</sect1>
407406

408-
<sect2 id="contr.smoc">
407+
<sect1 id="contr.smoc">
409408
<title>
410409
<type>smoc</type>
411410
</title>
@@ -449,6 +448,6 @@
449448
<para>
450449
creates an <type>smoc</type> of the given order covering the spoly
451450
</para>
452-
</sect2>
451+
</sect1>
453452

454-
</sect1>
453+
</chapter>

0 commit comments

Comments
 (0)