Thread: Re: [COMMITTERS] pgsql: Use DocBook XSL stylesheets for man page building This switches

petere@postgresql.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@postgresql.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.