Subject: some notes on man page build

From: Peter Eisentraut <[email-masked]>
Date: Sun, 17 Aug 2014 10:03:24 -0400

I want to put some notes out of my head and on the record regarding the
docbook-xsl stylesheets and the man page build.

The release builds currently use version 1.76.1, because that's what's
in Debian stable on borka.  That works fine.  I didn't look into older
versions recently, so let's make sure we use at least that one.

In
<http://www.postgresql.org/message-id/[email-masked]>
is asked for an upgrade to 1.78.1, which is the current upstream
release, because I wanted this bug fixed:

http://sourceforge.net/p/docbook/bugs/1233/

It turned out, however, that it introduced these two bugs

http://sourceforge.net/p/docbook/bugs/1321/
http://sourceforge.net/p/docbook/bugs/1322/

These are fixed upstream, but there hasn't been a new release in a while.

So the strategy going forward is to keep using 1.76.1 until borka gets
upgraded (or are we going to use wheezy-lts?).  If it does get upgraded
and Debian jessie ships with 1.78.1, we'll need to decide about either
downgrading back to 1.76.1 or taking whatever new release might be out
there at the time.  We should not ship a release built with 1.78.1.

Besides that, there are a few stylesheet bugs/shortcomings that we carry
local workarounds for.  These are

http://sourceforge.net/p/docbook/bugs/1058/
http://sourceforge.net/p/docbook/bugs/1239/
http://sourceforge.net/p/docbook/bugs/1245/
http://sourceforge.net/p/docbook/bugs/1340/

The difference is merely that some bugs are easier to work around
locally than others.  We might eventually remove these local workarounds
once the fixed stylesheet versions are ubiquitous.  But there isn't
really a standard way to require a minimum stylesheet version, so it's
not clear yet how to do that.

Btw., the way I test this is something like

cd doc/src/sgml
make man
mkdir build-1
mv man? build-1/
rm man-stamp
# make stylesheet changes
make man
mkdir build-2
mv man? build-2/
diff -IGenerator -ur build-1 build-2

(The -I option skips hunks that are different merely because the version
embedded in the output is different.)

To use a different stylesheet version, edit stylesheet-man.xsl and
change the line

<xsl:import
href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"/>

You can replace "current" by a specific version number such as "1.76.1"
or also "snapshot", to use the current development version.  Our you can
replace the whole http URL with a local file URL.

-- 
Sent via pgsql-docs mailing list ([email-masked])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

---

From: Magnus Hagander <[email-masked]>
Date: Sun, 17 Aug 2014 16:09:35 +0200

> there at the time.  We should not ship a release built with 1.78.1.

We haven't actually decided if we're going to go wheezy-lts or jessie.
I would guess we'll be sticking to wheezy-lts at least for some time,
mainly to cut down the work ofh aving to upgrade boxes. However, if
there is a specific reason a box would be better off on jessie, we
will upgrade it (not necessarily right after jessie is released of
course, it will take some time to prepare the infrastructure to deal
with that version, and right now we don't have a pressing need so it
won't be on day 1).

We can of course also use this specific package from backports
assuming the fixed version is in jessie (in which case it should be
available as a wheezy backport I think). But all that is of course
irrelevant until there has actually been a release into either jessie
*or* wheezy with the fixin it :)

-- 
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/