pgsql: Use DocBook XSL stylesheets for man page building This switches

Log Message:
-----------
Use DocBook XSL stylesheets for man page building

This switches the man page building process to use the DocBook XSL stylesheet
toolchain. The previous targets for Docbook2X are removed. configure has been
updated to look for the new tools. The Documentation appendix contains the
new build instructions. There are also a few isolated tweaks in the
documentation to improve places that came out strangely in the man pages.

Modified Files:
--------------
pgsql:
configure (r1.651 -> r1.652)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/configure?r1=1.651&r2=1.652)
configure.in (r1.607 -> r1.608)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/configure.in?r1=1.607&r2=1.608)
pgsql/config:
docbook.m4 (r1.10 -> r1.11)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/config/docbook.m4?r1=1.10&r2=1.11)
pgsql/doc/src/sgml:
Makefile (r1.119 -> r1.120)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/Makefile?r1=1.119&r2=1.120)
docguide.sgml (r1.76 -> r1.77)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/docguide.sgml?r1=1.76&r2=1.77)
postgres.sgml (r1.89 -> r1.90)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/postgres.sgml?r1=1.89&r2=1.90)
stylesheet-man.xsl (r1.1 -> r1.2)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/stylesheet-man.xsl?r1=1.1&r2=1.2)
trigger.sgml (r1.57 -> r1.58)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/trigger.sgml?r1=1.57&r2=1.58)
pgsql/doc/src/sgml/ref:
analyze.sgml (r1.26 -> r1.27)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/ref/analyze.sgml?r1=1.26&r2=1.27)
pgsql/src:
Makefile.global.in (r1.254 -> r1.255)
(http://anoncvs.postgresql.org/cvsweb.cgi/pgsql/src/Makefile.global.in?r1=1.254&r2=1.255)

Peter Eisentraut wrote:
> Log Message:
> -----------
> Use DocBook XSL stylesheets for man page building
>
> This switches the man page building process to use the DocBook XSL stylesheet
> toolchain. The previous targets for Docbook2X are removed. configure has been
> updated to look for the new tools. The Documentation appendix contains the
> new build instructions. There are also a few isolated tweaks in the
> documentation to improve places that came out strangely in the man pages.

Excellent work, thanks.

I'm wondering if dropping SPI_* manpages is really what we want. Maybe
we could add them to man section 3? I know I've wanted to have them a
couple of times.

Not sure about dblink.

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

On Wednesday 05 August 2009 02:43:19 Alvaro Herrera wrote:
> I'm wondering if dropping SPI_* manpages is really what we want. Maybe
> we could add them to man section 3? I know I've wanted to have them a
> couple of times.
>
> Not sure about dblink.

This was just the status quo. We could add more manpages, sure. (I'm
interested in pgbench, in particular.) It just needs someone to go through
the generated output and verify that it is sane.

Peter Eisentraut wrote:
> On Wednesday 05 August 2009 02:43:19 Alvaro Herrera wrote:
> > I'm wondering if dropping SPI_* manpages is really what we want. Maybe
> > we could add them to man section 3? I know I've wanted to have them a
> > couple of times.
> >
> > Not sure about dblink.
>
> This was just the status quo. We could add more manpages, sure. (I'm
> interested in pgbench, in particular.) It just needs someone to go through
> the generated output and verify that it is sane.

Oh, great. I'll have a look at SPI pages.

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

petere(at)postgresql(dot)org (Peter Eisentraut) writes:
> Use DocBook XSL stylesheets for man page building

I tried "make man" on my Fedora 10 machine. It built stuff, but:

* I see it claiming to be making manpages for the SPI functions and
dblink functions, eg

Note: meta manvol : no refentry/refmeta/manvolnum dblink_connect
Note: meta manvol : see http://docbook.sf.net/el/manvolnum dblink_connect
Note: Writing man1/dblink_connect.1

but no output file actually appears. And why is it dropping this stuff
in section 1, wouldn't 3 be more appropriate?

* The section-7 man pages are back to being created with all-upper-case
file names. I thought we'd agreed not to do that.

regards, tom lane

Tom Lane wrote:

> * I see it claiming to be making manpages for the SPI functions and
> dblink functions, eg
>
> Note: meta manvol : no refentry/refmeta/manvolnum dblink_connect
> Note: meta manvol : see http://docbook.sf.net/el/manvolnum dblink_connect
> Note: Writing man1/dblink_connect.1
>
> but no output file actually appears. And why is it dropping this stuff
> in section 1, wouldn't 3 be more appropriate?

I'm working on fixing this (the SPI part).

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Tom Lane wrote:
> petere(at)postgresql(dot)org (Peter Eisentraut) writes:
> > Use DocBook XSL stylesheets for man page building
>
> I tried "make man" on my Fedora 10 machine. It built stuff, but:
>
> * I see it claiming to be making manpages for the SPI functions and
> dblink functions, eg
>
> Note: meta manvol : no refentry/refmeta/manvolnum dblink_connect
> Note: meta manvol : see http://docbook.sf.net/el/manvolnum dblink_connect
> Note: Writing man1/dblink_connect.1
>
> but no output file actually appears. And why is it dropping this stuff
> in section 1, wouldn't 3 be more appropriate?

Committed -- the dblink pages are still the same though.

The reason the files they don't show up is that they are being
removed by a "rm" call in the makefile. And they are in section 1
because they are missing a <manvolnum> tag.

The SPI pages could use some SEE ALSO entries, but I ran out of time
halfway through writing that. Maybe later.

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

On Wednesday 05 August 2009 21:02:27 Tom Lane wrote:
> * The section-7 man pages are back to being created with all-upper-case
> file names. I thought we'd agreed not to do that.

The agreement was not to change it two minutes before the release.

In practice it shouldn't matter. None of the more modern man page building
tools I surveyed actually supported downcasing the file names. If there is a
strong argument in favor, I can work on fixing it.

On Wednesday 05 August 2009 22:34:45 Alvaro Herrera wrote:
> The reason the files they don't show up is that they are being
> removed by a "rm" call in the makefile. And they are in section 1
> because they are missing a <manvolnum> tag.

The old tool dropped man pages without manvolnum, the new tool generates them
with a default section. There is no standard that says which is right.

Peter Eisentraut wrote:
> Log Message:
> -----------
> Use DocBook XSL stylesheets for man page building

So, continuing with this seemingly endless saga :-(

I'm working on fixing the script that generates the snapshots. I have
fixed the script so that it works on my machine, but Stefan reports that
it fails on developer.postgresql.org with:

http://docbook.sourceforge.net/release/xsl/current/manpages/inline.xsl:1: parser error : Start tag expected, '<' not found
HTTP/1.1 504 Gateway Time-out
^
compilation error: file http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl line 36 element include
xsl:include : unable to load http://docbook.sourceforge.net/release/xsl/current/manpages/inline.xsl
gmake[3]: *** [man-stamp] Error 5
gmake[3]: Leaving directory `/usr/local/pgsql/snapshot/pgsql/doc/src/sgml'
gmake[2]: *** [man] Error 2
gmake[2]: Leaving directory `/usr/local/pgsql/snapshot/pgsql/doc/src'
gmake[1]: *** [man] Error 2
gmake[1]: Leaving directory `/usr/local/pgsql/snapshot/pgsql/doc'
gmake: *** [man] Error 2

His complaint is that we're now depending on a random website to be up
and reachable to generate the manpages :-( Is there a way we can have
the necessary stylesheets locally?

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera wrote:
> Peter Eisentraut wrote:
>> Log Message:
>> -----------
>> Use DocBook XSL stylesheets for man page building
>
> So, continuing with this seemingly endless saga :-(
>
> I'm working on fixing the script that generates the snapshots. I have
> fixed the script so that it works on my machine, but Stefan reports that
> it fails on developer.postgresql.org with:
>
> http://docbook.sourceforge.net/release/xsl/current/manpages/inline.xsl:1: parser error : Start tag expected, '<' not found
> HTTP/1.1 504 Gateway Time-out
> ^
> compilation error: file http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl line 36 element include
> xsl:include : unable to load http://docbook.sourceforge.net/release/xsl/current/manpages/inline.xsl
> gmake[3]: *** [man-stamp] Error 5
> gmake[3]: Leaving directory `/usr/local/pgsql/snapshot/pgsql/doc/src/sgml'
> gmake[2]: *** [man] Error 2
> gmake[2]: Leaving directory `/usr/local/pgsql/snapshot/pgsql/doc/src'
> gmake[1]: *** [man] Error 2
> gmake[1]: Leaving directory `/usr/local/pgsql/snapshot/pgsql/doc'
> gmake: *** [man] Error 2
>
>
> His complaint is that we're now depending on a random website to be up
> and reachable to generate the manpages :-( Is there a way we can have
> the necessary stylesheets locally?

yeah . having the doc builds depend on the availabilty of some random
external website is fairly problematic and feels really wrong(and not an
improvement in general at all)

Stefan

On Saturday 15 August 2009 00:20:27 Alvaro Herrera wrote:
> I'm working on fixing the script that generates the snapshots. I have
> fixed the script so that it works on my machine, but Stefan reports that
> it fails on developer.postgresql.org with:
>
> http://docbook.sourceforge.net/release/xsl/current/manpages/inline.xsl:1:
> parser error : Start tag expected, '<' not found HTTP/1.1 504 Gateway
> Time-out
> ^
> compilation error: file
> http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
> line 36 element include xsl:include : unable to load
> http://docbook.sourceforge.net/release/xsl/current/manpages/inline.xsl
> gmake[3]: *** [man-stamp] Error 5
> gmake[3]: Leaving directory `/usr/local/pgsql/snapshot/pgsql/doc/src/sgml'
> gmake[2]: *** [man] Error 2
> gmake[2]: Leaving directory `/usr/local/pgsql/snapshot/pgsql/doc/src'
> gmake[1]: *** [man] Error 2
> gmake[1]: Leaving directory `/usr/local/pgsql/snapshot/pgsql/doc'
> gmake: *** [man] Error 2
>
>
> His complaint is that we're now depending on a random website to be up
> and reachable to generate the manpages :-( Is there a way we can have
> the necessary stylesheets locally?

Sure, you just have to install them correctly. ;-)

xsltproc looks for a catalog file in /etc/xml/catalog that ultimately links to
the place where the local installation is to be found. I guess the FreeBSD
port installation, or whatever you have there, fails to do this correctly.

On Fri, Aug 14, 2009 at 10:34 PM, Stefan
Kaltenbrunner<stefan(at)kaltenbrunner(dot)cc> wrote:
>> His complaint is that we're now depending on a random website to be up
>> and reachable to generate the manpages :-(  Is there a way we can have
>> the necessary stylesheets locally?
>
> yeah . having the doc builds depend on the availabilty of some random
> external website is fairly problematic and feels really wrong(and not an
> improvement in general at all)

Hasn't this always been the case? When building the installers, I
occasionally have 'make html' fail because it can't reach sourceforge
(iirc).

--
Dave Page
EnterpriseDB UK: http://www.enterprisedb.com

On lör, 2009-08-15 at 09:53 +0100, Dave Page wrote:
> On Fri, Aug 14, 2009 at 10:34 PM, Stefan
> Kaltenbrunner<stefan(at)kaltenbrunner(dot)cc> wrote:
> >> His complaint is that we're now depending on a random website to be up
> >> and reachable to generate the manpages :-( Is there a way we can have
> >> the necessary stylesheets locally?
> >
> > yeah . having the doc builds depend on the availabilty of some random
> > external website is fairly problematic and feels really wrong(and not an
> > improvement in general at all)
>
> Hasn't this always been the case? When building the installers, I
> occasionally have 'make html' fail because it can't reach sourceforge
> (iirc).

Only when you use an XSL-based toolchain, which make html has never
been. You might have observed with with the HTMLHelp build.

On 8/15/09, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:
> On lör, 2009-08-15 at 09:53 +0100, Dave Page wrote:
>> On Fri, Aug 14, 2009 at 10:34 PM, Stefan
>> Kaltenbrunner<stefan(at)kaltenbrunner(dot)cc> wrote:
>> >> His complaint is that we're now depending on a random website to be up
>> >> and reachable to generate the manpages :-( Is there a way we can have
>> >> the necessary stylesheets locally?
>> >
>> > yeah . having the doc builds depend on the availabilty of some random
>> > external website is fairly problematic and feels really wrong(and not an
>> > improvement in general at all)
>>
>> Hasn't this always been the case? When building the installers, I
>> occasionally have 'make html' fail because it can't reach sourceforge
>> (iirc).
>
> Only when you use an XSL-based toolchain, which make html has never
> been. You might have observed with with the HTMLHelp build.
>

Sorry, yes - 'make htmlhelp' is what I meant.

--
Dave Page
EnterpriseDB UK: http://www.enterprisedb.com