Building the PostgreSQL docs on Windows

PostgreSQL documentation is in DocBook format. In my experience, this is far from trivial to get working on any platform where it isn't installed by the default packages - and even worse if it's installed by default but in the wrong version.

Turns out on Windows it's both better and worse - it's definitly harder than a pre-installed system, but a lot easier than one with the wrong version installed. Here are some step-by-step instructions for how to do it in a way that uses only pre-made binary packages of the required tools. It's a manual build not integrated with the pg Makefile, but it's a start... First of all, decide on a root for the docbook installation. In my case, I chose f:\docbook. Download and uncompress the following files:

  • ActiveState Perl, installed anywhere and present in the PATH
  • OpenJade 1.3.1-2 binaries, uncompress to f:\docbook\openjade-1.3.1.
  • DocBook DTD 4.2, uncompress to f:\docbook\docbook.
  • DocBook DSSSL 1.79, uncompress to f:\docbook\docbook-dsssl-1.79.
  • ISO character entities, uncompress to f:\docbook\docbook.

With this done, some files in the docbook directory need renaming. Create a .bat file named r.bat (or whatever, really) in the docbook\docbook directory that looks like this:

@echo off
for %25%25f in (ISO*) do (
set foo=%25%25f
ren !foo! !foo:~0,3!-!foo:~3!.gml
)

And execute this file using:

cmd /v /c r.bat

That done, step into your PostgreSQL installation tree in doc\src\sgml. Run the following commands (beware of linebreaks!):

set SGML_CATALOG_FILES=f:\docbook\openjade-1.3.1\dsssl\catalog;f:\docbook\docbook\docbook.cat

perl f:\docbook\docbook-dsssl-1.79\bin\collateindex.pl -f -g -o bookindex.sgml -N

perl mk_feature_tables.pl YES ..\..\..\src\backend\catalog\sql_feature_packages.txt ..\..\..\src\backend\catalog\sql_features.txt > features-supported.sgml

perl mk_feature_tables.pl NO ..\..\..\src\backend\catalog\sql_feature_packages.txt ..\..\..\src\backend\catalog\sql_features.txt > features-unsupported.sgml

f:\docbook\openjade-1.3.1\bin\openjade -V draft-mode -wall -wno-unused-param -wno-empty -D . -c f:\docbook\docbook-dsssl-1.79\catalog -d stylesheet.dsl -i output-html -t sgml postgres.sgml

perl f:\docbook\docbook-dsssl-1.79\bin\collateindex.pl -f -g -i 'bookindex' -o bookindex.sgml HTML.index

f:\docbook\openjade-1.3.1\bin\openjade -V draft-mode -wall -wno-unused-param -wno-empty -D . -c f:\docbook\docbook-dsssl-1.79\catalog -d stylesheet.dsl -i output-html -t sgml postgres.sgml

Yes, it runs the build twice. That's to generate the indexes. If you have changed your docs, you usually don't need to re-run that part - just run the final openjade call over and over again.

This is all run outside of msys, with no requirements at all on either mingw or cygwin.


Conferences

I speak at and organize conferences around Open Source in general and PostgreSQL in particular.

Upcoming

Stockholm PUG 2016/3
Jun 16, 2016
Stockholm, Sweden
PGDay UK 2016
Jul 05, 2016
London, UK
PG Day'16 Russia
Jul 6-8, 2016
St Petersburg, Russia
Stockholm PUG 2016/4
Aug 31, 2016
Stockholm, Sweden
Postgres Open
Sep 13-16, 2016
Dallas, USA
PGConf.EU 2016
Nov 1-Jan 4, 2016
Tallinn, Estonia

Past

PGCon
May 17-21, 2016
Ottawa, Canada
Pycon Sweden
May 9-10, 2016
Stockholm, Sweden
Stockholm PUG 2016/2
Apr 26, 2016
Stockholm, Sweden
PGConf.US
Apr 18-20, 2016
New York, USA
pgDay Paris
Mar 31, 2016
Paris, France
More past conferences