Re: adding a TOC to the psql reference page
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 wrote: > On Thu, Apr 30, 2020 at 08:48:09PM +, 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 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.
Re: adding a TOC to the psql reference page
On Thu, Apr 30, 2020 at 3:17 PM Bruce Momjian wrote: > On Thu, Apr 30, 2020 at 08:48:09PM +, 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.
Re: adding a TOC to the psql reference page
Bruce Momjian writes: > On Thu, Apr 30, 2020 at 08:48:09PM +, 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
Re: adding a TOC to the psql reference page
On Thu, Apr 30, 2020 at 08:48:09PM +, 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 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 +
