public inbox for [email protected]  

help / color / mirror / Atom feed

From: Peter Eisentraut <[email protected]>
To: pgsql-docs <[email protected]>
Subject: some notes on man page build
Date: Sun, 17 Aug 2014 10:03:24 -0400
Message-ID: <[email protected]> (raw)
List-Unsubscribe: <mailto:[email protected]?body=unsub%20pgsql-docs>

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 protected];
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 protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

view thread (2+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected]
  Subject: Re: some notes on man page build
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox