Horton

Thread

  1. Local postgres manual

    Ben Hancock <lists@benghancock.com> — 2023-11-03T13:18:19Z

    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

  2. Re: Local postgres manual

    Bruce Momjian <bruce@momjian.us> — 2023-11-03T13:33:37Z

    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.

  3. Re: Local postgres manual

    Philip Semanchuk <philip@americanefficient.com> — 2023-11-03T13:39:46Z

    
> 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

  4. Re: Local postgres manual

    Bruce Momjian <bruce@momjian.us> — 2023-11-03T13:45:52Z

    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.

  5. Re: Local postgres manual

    jian he <jian.universality@gmail.com> — 2023-11-03T13:47:50Z

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

  6. Re: Local postgres manual

    Philip Semanchuk <philip@americanefficient.com> — 2023-11-03T14:06:59Z

    
> 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

  7. Re: Local postgres manual

    Ben Hancock <lists@benghancock.com> — 2023-11-03T19:16:35Z

    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

  8. Re: Local postgres manual

    Tom Lane <tgl@sss.pgh.pa.us> — 2023-11-03T19:58:05Z

    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

  9. Re: Local postgres manual

    Bruce Momjian <bruce@momjian.us> — 2023-11-04T01:59:38Z

    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.