adding a TOC to the psql reference page

On Thu, Apr 30, 2020 at 08:48:09PM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/app-psql.html
Description:

Since https://www.postgresql.org/docs/current/app-psql.html is quite long,
it would be nice to add a detailed table of contents at its beginning, in
order to:

- allow for easier browsing

- allow to reference individual psql options, meta-commands, variables,
prompts and environment variables by using their respective id attribute

Yes, I can see the value in that, but I don't think we do that for any
other SQL comments. Would doing it just for psql make sense?

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Bruce Momjian <bruce@momjian.us> writes:

On Thu, Apr 30, 2020 at 08:48:09PM +0000, PG Doc comments form wrote:

Since https://www.postgresql.org/docs/current/app-psql.html is quite long,
it would be nice to add a detailed table of contents at its beginning,

Yes, I can see the value in that, but I don't think we do that for any
other SQL comments. Would doing it just for psql make sense?

psql's reference page is so much longer than any other command's that
I think this is perfectly reasonable. However, we do have to worry
about what will happen in man-page-format output.

regards, tom lane

On Thu, Apr 30, 2020 at 3:17 PM Bruce Momjian <bruce@momjian.us> wrote:

On Thu, Apr 30, 2020 at 08:48:09PM +0000, PG Doc comments form wrote:

Since https://www.postgresql.org/docs/current/app-psql.html is quite

long,

it would be nice to add a detailed table of contents at its beginning, in
order to:

- allow for easier browsing

- allow to reference individual psql options, meta-commands, variables,
prompts and environment variables by using their respective id attribute

Yes, I can see the value in that, but I don't think we do that for any
other SQL comments. Would doing it just for psql make sense?

Yes.

Other parts of the documentation have TOC sections so its not like we don't
do it ever. And even if by general rule the applications don't get a TOC
(there isn't one that I'm aware of) psql would still warrant an exception
given its position as the primary user interface to the system and the
extensiveness of the documentation itself (a byproduct of being the primary
user interface).

David J.

For SQL commands that are:

- heavily used, and

- structurally involved

i'd say yes (`CREATE TABLE` comes to mind); otherwise, don't bother.

The above selection criteria are subjective, so consensus should be
gathered.

On Fri, May 1, 2020 at 12:16 AM Bruce Momjian <bruce@momjian.us> wrote:

On Thu, Apr 30, 2020 at 08:48:09PM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/app-psql.html
Description:

Since https://www.postgresql.org/docs/current/app-psql.html is quite

long,

it would be nice to add a detailed table of contents at its beginning, in
order to:

- allow for easier browsing

- allow to reference individual psql options, meta-commands, variables,
prompts and environment variables by using their respective id attribute

Yes, I can see the value in that, but I don't think we do that for any
other SQL comments. Would doing it just for psql make sense?

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

--
All work and no play makes George go astray.