Skip to content

Commit 3568f70

Browse files
vitcppvitcpp
committed
Migrate doc generation to docbook/fop (postgresql approach)
The document generation was redesigned to use the same approach as postgresql does. It uses fop for printable doc generation and xsltproc for html generation. Postgresql stylesheets are used (with some minor changes). Fixed version propagation when generating the doc. Now, the version is placed in Makefile.common.mk file that is used in doc generation process. The following make rules were implemented: - make pdf (generates printable doc in A4 and US Letter format) - make pg_sphere-<VERSION>-A4.pdf (generate the printable doc in A4) - make pg_sphere-<VERSION>-US.pdf (generate the printable doc in USLetter) - make html (generates single-page and multi-page html) - make html-singlepage (generate single-page html only) - make html-multipage (generate multi-page html only)
1 parent 1c4a5f3 commit 3568f70

26 files changed

+2376
-887
lines changed

‎Makefile‎

Lines changed: 3 additions & 2 deletions
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

‎Makefile.common.mk‎

Lines changed: 8 additions & 0 deletions
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

‎doc/Makefile‎

Lines changed: 71 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,16 @@
11
#----------------------------------------------------------------------------
22
#
3-
# pgSphere documentation makefile
3+
# pgSphere documentation generation
44
#
55
#----------------------------------------------------------------------------
66

7+
ifndef PGSPHERE_VERSION
8+
include ../Makefile.common.mk
9+
ifndef PGSPHERE_VERSION
10+
$(error PGSPHERE_VERSION is not set)
11+
endif
12+
endif
13+
714
USE_PGXS = 1
815
ifdef USE_PGXS
916
PG_CONFIG = pg_config
@@ -16,75 +23,89 @@ include $(top_builddir)/src/Makefile.global
1623
include $(top_srcdir)/contrib/contrib-global.mk
1724
endif
1825

19-
.SECONDARY:
20-
.NOTPARALLEL:
26+
ifndef FOP
27+
FOP = fop
28+
endif
2129

22-
ifndef COLLATEINDEX
23-
COLLATEINDEX = $(DOCBOOKSTYLE)/bin/collateindex.pl
30+
ifdef XMLLINT
31+
XMLLINT := $(XMLLINT) --nonet
32+
else
33+
XMLLINT = $(missing) xmllint
2434
endif
2535

26-
ifndef JADE
27-
JADE = openjade
36+
ifdef XSLTPROC
37+
XSLTPROC := $(XSLTPROC) --nonet
38+
else
39+
XSLTPROC = $(missing) xsltproc
2840
endif
29-
SGMLINCLUDE = -D $(srcdir)
3041

31-
ALLSGML := $(wildcard $(srcdir)/*.sgm)
42+
override XSLTPROCFLAGS += \
43+
--path stylesheets --path img --path . \
44+
--stringparam pg_sphere.version '$(PGSPHERE_VERSION)' \
45+
--stringparam pg.version '$(PGSPHERE_VERSION)'
3246

33-
ifdef DOCBOOKSTYLE
34-
CATALOG = -c $(DOCBOOKSTYLE)/catalog
35-
endif
47+
XMLINCLUDE = --path .
48+
ALLSGML := $(wildcard *.sgm)
49+
ALLIMAGES := $(wildcard img/*.jpg)
3650

37-
COLLATEINDEX := $(PERL) $(COLLATEINDEX) -f -g
51+
.PHONY: all html pdf
3852

53+
all: version.ent html pdf
3954

40-
all : html
55+
version.xml:
56+
@echo $(PGSPHERE_VERSION) > version.xml
4157

42-
.PHONY: html pdf ps
58+
pg_sphere-full.xml: version.xml
59+
pg_sphere-full.xml: pg_sphere.xml $(ALLSGML)
60+
$(XMLLINT) $(XMLINCLUDE) --output $@ --noent --valid $<
4361

44-
XMLDCL = declaration/xml.dcl
62+
#------------------------------------------------------------------------------
63+
# HTML
64+
#------------------------------------------------------------------------------
4565

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
66+
XSLTPROC_HTML_MULTIPAGE_FLAGS := --stringparam img.src.path ''
67+
XSLTPROC_HTML_SINGLEPAGE_FLAGS := --stringparam img.src.path ''
5568

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) $<
69+
html: html-singlepage html-multipage
5870

59-
pdf : jadetex.cfg pg_sphere.pdf
71+
html-multipage: stylesheets/stylesheet.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
72+
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_MULTIPAGE_FLAGS) $(wordlist 1,2,$^)
73+
mkdir -p html/img
74+
cp $(ALLIMAGES) html/img
6075

61-
pg_sphere.pdf: pg_sphere.tex
62-
@rm -f $*.aux $*.log $*.out
63-
pdfjadetex $<
64-
pdfjadetex $<
65-
pdfjadetex $<
76+
html-singlepage: pg_sphere-$(PGSPHERE_VERSION).html
6677

67-
ps : pg_sphere.ps
78+
pg_sphere-$(PGSPHERE_VERSION).html: stylesheets/stylesheet-html-nochunk.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
79+
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_SINGLEPAGE_FLAGS) -o $@ $(wordlist 1,2,$^)
6880

69-
pg_sphere.ps: pg_sphere.pdf
70-
pdftops $< $@
81+
#------------------------------------------------------------------------------
82+
# PDF
83+
#------------------------------------------------------------------------------
7184

72-
pg_sphere.dsl : pg_sphere.dsl-dist
73-
cp $< $@
85+
pdf: pg_sphere-${PGSPHERE_VERSION}-A4.pdf pg_sphere-${PGSPHERE_VERSION}-US.pdf
7486

75-
jadetex.cfg : jadetex.cfg-dist
76-
cp $< $@
87+
pg_sphere-$(PGSPHERE_VERSION)-A4.pdf: pg_sphere.A4.fo
88+
$(FOP) -v -fo $< -pdf $@
7789

90+
pg_sphere-$(PGSPHERE_VERSION)-US.pdf: pg_sphere.US.fo
91+
$(FOP) -v -fo $< -pdf $@
7892

93+
pg_sphere.A4.fo: stylesheets/stylesheet-fo.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
94+
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type A4 -o $@ stylesheets/stylesheet-fo.xsl pg_sphere-full.xml
7995

80-
##
81-
## Clean
82-
##
96+
pg_sphere.US.fo: stylesheets/stylesheet-fo.xsl pg_sphere-full.xml version.xml $(ALLIMAGES)
97+
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type USLetter -o $@ stylesheets/stylesheet-fo.xsl pg_sphere-full.xml
8398

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
99+
#------------------------------------------------------------------------------
100+
# Cleanup
101+
#------------------------------------------------------------------------------
102+
103+
clean distclean:
104+
rm -rf ./html
105+
rm -f version.xml
106+
rm -f pg_sphere-full.xml
107+
rm -f pg_sphere.A4.fo
108+
rm -f pg_sphere.US.fo
109+
rm -f pg_sphere-$(PGSPHERE_VERSION).html
110+
rm -f pg_sphere-$(PGSPHERE_VERSION)-A4.pdf
111+
rm -f pg_sphere-$(PGSPHERE_VERSION)-US.pdf

‎doc/constructors.sgm‎

Lines changed: 29 additions & 30 deletions
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)