pg.ddx.io  pgsql-general@postgresql.org mailing list archive  
help / color / mirror / Atom feed
Local postgres manual
9+ messages / 5 participants
[nested] [flat]

* Local postgres manual
@ 2023-11-03 13:18  Ben Hancock <lists@benghancock.com>
  0 siblings, 2 replies; 9+ messages in thread

From: Ben Hancock @ 2023-11-03 13:18 UTC (permalink / raw)
  To: PostgreSQL-General <pgsql-general@lists.postgresql.org>

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





^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Local postgres manual
@ 2023-11-03 13:33  Bruce Momjian <bruce@momjian.us>
  parent: Ben Hancock <lists@benghancock.com>
  1 sibling, 1 reply; 9+ messages in thread

From: Bruce Momjian @ 2023-11-03 13:33 UTC (permalink / raw)
  To: Ben Hancock <lists@benghancock.com>; +Cc: PostgreSQL-General <pgsql-general@lists.postgresql.org>

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.





^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Local postgres manual
@ 2023-11-03 13:39  Philip Semanchuk <philip@americanefficient.com>
  parent: Ben Hancock <lists@benghancock.com>
  1 sibling, 1 reply; 9+ messages in thread

From: Philip Semanchuk @ 2023-11-03 13:39 UTC (permalink / raw)
  To: Ben Hancock <lists@benghancock.com>; +Cc: PostgreSQL-General <pgsql-general@lists.postgresql.org>



> 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




^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Local postgres manual
@ 2023-11-03 13:45  Bruce Momjian <bruce@momjian.us>
  parent: Philip Semanchuk <philip@americanefficient.com>
  0 siblings, 2 replies; 9+ messages in thread

From: Bruce Momjian @ 2023-11-03 13:45 UTC (permalink / raw)
  To: Philip Semanchuk <philip@americanefficient.com>; +Cc: Ben Hancock <lists@benghancock.com>; PostgreSQL-General <pgsql-general@lists.postgresql.org>

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.





^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Local postgres manual
@ 2023-11-03 13:47  jian he <jian.universality@gmail.com>
  parent: Bruce Momjian <bruce@momjian.us>
  1 sibling, 0 replies; 9+ messages in thread

From: jian he @ 2023-11-03 13:47 UTC (permalink / raw)
  To: Bruce Momjian <bruce@momjian.us>; +Cc: Philip Semanchuk <philip@americanefficient.com>; Ben Hancock <lists@benghancock.com>; PostgreSQL-General <pgsql-general@lists.postgresql.org>

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





^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Local postgres manual
@ 2023-11-03 14:06  Philip Semanchuk <philip@americanefficient.com>
  parent: Bruce Momjian <bruce@momjian.us>
  1 sibling, 0 replies; 9+ messages in thread

From: Philip Semanchuk @ 2023-11-03 14:06 UTC (permalink / raw)
  To: Bruce Momjian <bruce@momjian.us>; +Cc: Ben Hancock <lists@benghancock.com>; PostgreSQL-General <pgsql-general@lists.postgresql.org>



> 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




^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Local postgres manual
@ 2023-11-03 19:16  Ben Hancock <lists@benghancock.com>
  parent: Bruce Momjian <bruce@momjian.us>
  0 siblings, 1 reply; 9+ messages in thread

From: Ben Hancock @ 2023-11-03 19:16 UTC (permalink / raw)
  To: pgsql-general@lists.postgresql.org

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





^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Local postgres manual
@ 2023-11-03 19:58  Tom Lane <tgl@sss.pgh.pa.us>
  parent: Ben Hancock <lists@benghancock.com>
  0 siblings, 1 reply; 9+ messages in thread

From: Tom Lane @ 2023-11-03 19:58 UTC (permalink / raw)
  To: Ben Hancock <lists@benghancock.com>; +Cc: pgsql-general@lists.postgresql.org

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





^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Local postgres manual
@ 2023-11-04 01:59  Bruce Momjian <bruce@momjian.us>
  parent: Tom Lane <tgl@sss.pgh.pa.us>
  0 siblings, 0 replies; 9+ messages in thread

From: Bruce Momjian @ 2023-11-04 01:59 UTC (permalink / raw)
  To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Ben Hancock <lists@benghancock.com>; pgsql-general@lists.postgresql.org

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.





^ permalink  raw  reply  [nested|flat] 9+ messages in thread


end of thread, other threads:[~2023-11-04 01:59 UTC | newest]

Thread overview: 9+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-11-03 13:18 Local postgres manual Ben Hancock <lists@benghancock.com>
2023-11-03 13:33 ` Bruce Momjian <bruce@momjian.us>
2023-11-03 19:16   ` Ben Hancock <lists@benghancock.com>
2023-11-03 19:58     ` Tom Lane <tgl@sss.pgh.pa.us>
2023-11-04 01:59       ` Bruce Momjian <bruce@momjian.us>
2023-11-03 13:39 ` Philip Semanchuk <philip@americanefficient.com>
2023-11-03 13:45   ` Bruce Momjian <bruce@momjian.us>
2023-11-03 13:47     ` jian he <jian.universality@gmail.com>
2023-11-03 14:06     ` Philip Semanchuk <philip@americanefficient.com>

This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox