8000 Migrate doc generation to docbook/fop (postgresql approach) by vitcpp · Pull Request #63 · postgrespro/pgsphere · GitHub
[go: up one dir, main page]
Skip to content

Migrate doc generation to docbook/fop (postgresql approach) #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Sep 18, 2023
Merged

Migrate doc generation to docbook/fop (postgresql approach) #63

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3568f70
Migrate doc generation to docbook/fop (postgresql approach)
vitcpp Sep 13, 2023
46c805c
Fix doc generation with default target
vitcpp Sep 13, 2023
5cd8211
Update travis.ci to support docbook/fop doc generation
vitcpp Sep 13, 2023
c5731c9
Set FOP variable default value
vitcpp Sep 13, 2023
d59496c
Disable install/installcheck targets in doc/Makefile
vitcpp Sep 14, 2023
48c3d5e
Add final linefeed, remove some trailing whitespaces
vitcpp Sep 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
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)
  • Loading branch information
@vitcpp
vitcpp committed Sep 15, 2023
commit 3568f70f17dabab828abc2da528d83056b65a868
5 changes: 3 additions & 2 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
8 changes: 8 additions & 0 deletions Makefile.common.mk
View file 8000
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
#----------------------------------------------------------------------------
#
# pgSphere common definitions
#
#----------------------------------------------------------------------------

EXTENSION := pg_sphere
PGSPHERE_VERSION := 1.3.1
121 changes: 71 additions & 50 deletions doc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,16 @@
#----------------------------------------------------------------------------
#
# pgSphere documentation makefile
# pgSphere documentation generation
#
#----------------------------------------------------------------------------

ifndef PGSPHERE_VERSION
include ../Makefile.common.mk
ifndef PGSPHERE_VERSION
$(error PGSPHERE_VERSION is not set)
endif
endif

USE_PGXS = 1
ifdef USE_PGXS
PG_CONFIG = pg_config
Expand All @@ -16,75 +23,89 @@ include $(top_builddir)/src/Makefile.global
include $(top_srcdir)/contrib/contrib-global.mk
endif

.SECONDARY:
.NOTPARALLEL:
ifndef FOP
FOP = fop
endif

ifndef COLLATEINDEX
COLLATEINDEX = $(DOCBOOKSTYLE)/bin/collateindex.pl
ifdef XMLLINT
XMLLINT := $(XMLLINT) --nonet
else
XMLLINT = $(missing) xmllint
endif

ifndef JADE
JADE = openjade
ifdef XSLTPROC
XSLTPROC := $(XSLTPROC) --nonet
else
XSLTPROC = $(missing) xsltproc
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
.PHONY: all html pdf

all: version.ent html pdf

all : html
version.xml:
@echo $(PGSPHERE_VERSION) > version.xml

.PHONY: html pdf ps
pg_sphere-full.xml: version.xml
pg_sphere-full.xml: pg_sphere.xml $(ALLSGML)
$(XMLLINT) $(XMLINCLUDE) --output $@ --noent --valid $<

XMLDCL = declaration/xml.dcl
#------------------------------------------------------------------------------
# HTML
#------------------------------------------------------------------------------

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

pg_sphere.tex : pg_sphere.xml $(ALLSGML) pg_sphere.dsl
$(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d pg_sphere.dsl -i print -t tex -o $@ $(XMLDCL) $<
html: html-singlepage html-multipage

pdf : jadetex.cfg pg_sphere.pdf
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

pg_sphere.pdf: pg_sphere.tex
@rm -f $*.aux $*.log $*.out
pdfjadetex $<
pdfjadetex $<
pdfjadetex $<
html-singlepage: pg_sphere-$(PGSPHERE_VERSION).html

ps : pg_sphere.ps
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.ps: pg_sphere.pdf
pdftops $< $@
#------------------------------------------------------------------------------
# PDF
#------------------------------------------------------------------------------

pg_sphere.dsl : pg_sphere.dsl-dist
cp $< $@
pdf: pg_sphere-${PGSPHERE_VERSION}-A4.pdf pg_sphere-${PGSPHERE_VERSION}-US.pdf

jadetex.cfg : jadetex.cfg-dist
cp $< $@
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 $@

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
##
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

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
#------------------------------------------------------------------------------
# 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
59 changes: 29 additions & 30 deletions doc/constructors.sgm
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -14,7 +13,7 @@
mentioned here.
</para>

<sect2 id="contr.spoint">
<sect1 id="contr.spoint">
<title>
Point
</title>
Expand Down Expand Up @@ -44,9 +43,9 @@
</programlisting>
</example>

</sect2>
</sect1>

<sect2 id="contr.strans">
<sect1 id="contr.strans">
<title>
Euler transformation
</title>
Expand Down Expand Up @@ -90,9 +89,9 @@
</programlisting>
</example>

</sect2>
</sect1>

<sect2 id="contr.scircle">
<sect1 id="contr.scircle">
<title>
Circle
</title>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand Down Expand Up @@ -212,9 +211,9 @@
<![CDATA[(1 row)]]>
</programlisting>
</example>
</sect2>
</sect1>

<sect2 id="contr.sellipse">
<sect1 id="contr.sellipse">
<title>
Ellipse
</title>
Expand All @@ -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>
Expand All @@ -263,9 +262,9 @@
<![CDATA[(1 row)]]>
</programlisting>
</example>
</sect2>
</sect1>

<sect2 id="contr.spoly">
<sect1 id="contr.spoly">
<title>
Polygon
</title>
Expand Down D4A8 Expand Up @@ -318,9 +317,9 @@
<![CDATA[(1 row)]]>
</programlisting>
</example>
</sect2>
</sect1>

<sect2 id="contr.spath">
<sect1 id="contr.spath">
<title>
Path
</title>
Expand Down Expand Up @@ -371,9 +370,9 @@
</programlisting>
</example>

</sect2>
</sect1>

<sect2 id="contr.sbox">
<sect1 id="contr.sbox">
<title>
Coordinates range
</title>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -449,6 +448,6 @@
<para>
creates an <type>smoc</type> of the given order covering the spoly
</para>
</sect2>
</sect1>

</sect1>
</chapter>
Loading
0