Обсуждение: adding a TOC to the psql reference page
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 Thank you!!!
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.