pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedadding a TOC to the psql reference page
5+ messages / 5 participants
[nested] [flat]
* adding a TOC to the psql reference page
@ 2020-04-30 20:48 PG Doc comments form <noreply@postgresql.org>
2020-04-30 22:16 ` Re: adding a TOC to the psql reference page Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 5+ messages in thread
From: PG Doc comments form @ 2020-04-30 20:48 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: grgbnc@gmail.com
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!!!
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: adding a TOC to the psql reference page
2020-04-30 20:48 adding a TOC to the psql reference page PG Doc comments form <noreply@postgresql.org>
@ 2020-04-30 22:16 ` Bruce Momjian <bruce@momjian.us>
2020-04-30 22:21 ` Re: adding a TOC to the psql reference page Tom Lane <tgl@sss.pgh.pa.us>
2020-04-30 22:26 ` Re: adding a TOC to the psql reference page David G. Johnston <david.g.johnston@gmail.com>
2020-04-30 23:04 ` Re: adding a TOC to the psql reference page grg bnc <grgbnc@gmail.com>
0 siblings, 3 replies; 5+ messages in thread
From: Bruce Momjian @ 2020-04-30 22:16 UTC (permalink / raw)
To: grgbnc@gmail.com; pgsql-docs@lists.postgresql.org
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 +
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: adding a TOC to the psql reference page
2020-04-30 20:48 adding a TOC to the psql reference page PG Doc comments form <noreply@postgresql.org>
2020-04-30 22:16 ` Re: adding a TOC to the psql reference page Bruce Momjian <bruce@momjian.us>
@ 2020-04-30 22:21 ` Tom Lane <tgl@sss.pgh.pa.us>
2 siblings, 0 replies; 5+ messages in thread
From: Tom Lane @ 2020-04-30 22:21 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: grgbnc@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: adding a TOC to the psql reference page
2020-04-30 20:48 adding a TOC to the psql reference page PG Doc comments form <noreply@postgresql.org>
2020-04-30 22:16 ` Re: adding a TOC to the psql reference page Bruce Momjian <bruce@momjian.us>
@ 2020-04-30 22:26 ` David G. Johnston <david.g.johnston@gmail.com>
2 siblings, 0 replies; 5+ messages in thread
From: David G. Johnston @ 2020-04-30 22:26 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: grgbnc@gmail.com; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: adding a TOC to the psql reference page
2020-04-30 20:48 adding a TOC to the psql reference page PG Doc comments form <noreply@postgresql.org>
2020-04-30 22:16 ` Re: adding a TOC to the psql reference page Bruce Momjian <bruce@momjian.us>
@ 2020-04-30 23:04 ` grg bnc <grgbnc@gmail.com>
2 siblings, 0 replies; 5+ messages in thread
From: grg bnc @ 2020-04-30 23:04 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2020-04-30 23:04 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-04-30 20:48 adding a TOC to the psql reference page PG Doc comments form <noreply@postgresql.org>
2020-04-30 22:16 ` Bruce Momjian <bruce@momjian.us>
2020-04-30 22:21 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-04-30 22:26 ` David G. Johnston <david.g.johnston@gmail.com>
2020-04-30 23:04 ` grg bnc <grgbnc@gmail.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