Local postgres manual

On Fri, Nov 3, 2023 at 06:18:19AM -0700, Ben Hancock wrote:

Hi all:

Does Postgres come with a local, full version of the manual installed
by default anywhere (i.e. akin to what is available on the website, but
in man, info, or plain-text format)? When I invoke `man postgres`, I do
get a very useful - but limited - manual page, which has references to
chapters. For example:

OPTIONS
postgres accepts the following command-line arguments. For a
detailed discussion of the options consult Chapter 20. ...

Of course, I can pull up a browser and find the manual, or consult a
local PDF if I have a graphical display. But sometimes it may be convenient
to view the the manual for the version of Postgres that is on the system,
right there. Does one exist?

Well, that's a good question, and a new question for me. I poked though
the doc makefile and it turns out that:

make postgres.txt

creates such a file. Here is the PG 16 version:

https://momjian.us/expire/postgres-16.txt

Let me know if you want a different Postgres version.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Nov 3, 2023, at 9:18 AM, Ben Hancock <lists@benghancock.com> wrote:

Hi all:

Does Postgres come with a local, full version of the manual installed
by default anywhere (i.e. akin to what is available on the website, but
in man, info, or plain-text format)? When I invoke `man postgres`, I do
get a very useful - but limited - manual page, which has references to chapters. For example:

OPTIONS
postgres accepts the following command-line arguments. For a
detailed discussion of the options consult Chapter 20. ...

Of course, I can pull up a browser and find the manual, or consult a
local PDF if I have a graphical display. But sometimes it may be convenient to view the the manual for the version of Postgres that is on the system, right there. Does one exist?

In addition to Bruce Momjian’s suggestion, I’ll add that you can make an HTML version of the manual from the source code. This is what I use and it works great for me.

Cheers
Philip

On Fri, Nov 3, 2023 at 09:39:46AM -0400, Philip Semanchuk wrote:

On Nov 3, 2023, at 9:18 AM, Ben Hancock <lists@benghancock.com> wrote:

Hi all:

Does Postgres come with a local, full version of the manual installed
by default anywhere (i.e. akin to what is available on the website, but
in man, info, or plain-text format)? When I invoke `man postgres`, I do
get a very useful - but limited - manual page, which has references to chapters. For example:

OPTIONS
postgres accepts the following command-line arguments. For a
detailed discussion of the options consult Chapter 20. ...

Of course, I can pull up a browser and find the manual, or consult a
local PDF if I have a graphical display. But sometimes it may be convenient to view the the manual for the version of Postgres that is on the system, right there. Does one exist?

In addition to Bruce Momjian’s suggestion, I’ll add that you can make an HTML version of the manual from the source code. This is what I use and it works great for me.

Yes, we can do HTML too as a single file, postgres.html. What I don't
see is man page output for anything but the references pages, and as
separate files. It might be possible to convert the HTML to man format
using something like html2man.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

i think Ben Hancock
want something like https://en.cppreference.com/w/Cppreference:Archives

On Nov 3, 2023, at 9:45 AM, Bruce Momjian <bruce@momjian.us> wrote:

On Fri, Nov 3, 2023 at 09:39:46AM -0400, Philip Semanchuk wrote:

In addition to Bruce Momjian’s suggestion, I’ll add that you can make an HTML version of the manual from the source code. This is what I use and it works great for me.

Yes, we can do HTML too as a single file, postgres.html. What I don't
see is man page output for anything but the references pages, and as
separate files. It might be possible to convert the HTML to man format
using something like html2man.

Yes, ISTR there’s an all-in-one-page option, but the HTML that I built is in individual pages that mirror the organization on postgresql.org which works great for me. Sorry I don’t remember the exact command I used but it was very straightforward, nothing tricky at all. Maybe as simple as `make install-docs`?

Cheers
Philip

On 11/3/23 06:33, Bruce Momjian wrote:

But sometimes it may be convenient to view the the manual for the
version of Postgres that is on the system, right there. Does one
exist?

Well, that's a good question, and a new question for me. I poked
though the doc makefile and it turns out that:

make postgres.txt

creates such a file. Here is the PG 16 version:

https://momjian.us/expire/postgres-16.txt

Let me know if you want a different Postgres version.

Thanks very much Bruce - this is really helpful! I've never taken a look
at that makefile but will do so.

I will say that, as the manual is quite large, a local GNU Info version
would be great to be able to traverse different sections, etc, more
easily. If that doesn't exist already, I wonder if a tool like `pandoc`
could be employed to generate that.

As others on the thread have suggested, building or fetching the HTML
locally may also work. In terminal environment, I suppose one could use
`lynx` or similar to navigate around.

- Ben

Ben Hancock <lists@benghancock.com> writes:

I will say that, as the manual is quite large, a local GNU Info version
would be great to be able to traverse different sections, etc, more
easily. If that doesn't exist already, I wonder if a tool like `pandoc`
could be employed to generate that.

That's exactly what the postgres.txt file Bruce mentioned is.

# single-page text
postgres.txt: postgres.html
$(PANDOC) -t plain -o $@ $<

These variant doc forms aren't terribly well (or at all) documented,
but the doc/src/sgml Makefile knows how to create a number of them.

regards, tom lane

On Fri, Nov 3, 2023 at 03:58:05PM -0400, Tom Lane wrote:

Ben Hancock <lists@benghancock.com> writes:

I will say that, as the manual is quite large, a local GNU Info version
would be great to be able to traverse different sections, etc, more
easily. If that doesn't exist already, I wonder if a tool like `pandoc`
could be employed to generate that.

That's exactly what the postgres.txt file Bruce mentioned is.

# single-page text
postgres.txt: postgres.html
$(PANDOC) -t plain -o $@ $<

These variant doc forms aren't terribly well (or at all) documented,
but the doc/src/sgml Makefile knows how to create a number of them.

I tried:

pandoc -t texinfo -o postgresql.info postgres.html

but couldn't figure out how to access it via 'info'. I was able to get
the man page looking good with:

make postgres.html &&
pandoc -t man -o postgresql.1 postgres.html &&
sed -n '1,${p;/^\.SH "NAME"/q}' /u/postgres/man/man1/postgres.1 |
sed 's/POSTGRES/POSTGRESQL/' > /u/postgres/man/man1/postgresql.1 &&
cat postgresql.1 >> /u/postgres/man/man1/postgresql.1 &&
rm postgresql.1

I pulled the formatting from postgres.1; without that the formatting
was 80-column and poor. I think it doesn't define .TH and that makes it
look bad.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.