Thread: Local postgres manual
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?
--
Ben Hancock
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 Postgresthat 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 ofPostgres 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 organizationon 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.