\i and \ir separated by \if now...

On Wed, May 9, 2018 at 02:25:28PM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

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

While I get that we want alphabetical order an exception for \i and \ir
seems warranted; or maybe make \ir part of the \i meta command description -
\i[r] or \include[_relative]

Uh, why would we list \ir before the simpler \i?

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

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

Uh, why would we list \ir before the simpler \i?

I believe the OP was complaining that the current order is:

\i or \include filename
(text)
\if expression
\elif expression
\else
\endif
(longer text)
\ir or \include_relative filename
(text)

and that before it was:

\i or \include filename
(text)
\ir or \include_relative filename
(text)

So that the request is to merge \ir into the \i section (not before \i but part of that discusstion) rather than being separated by the comparatively longer section for \if
E-MAIL CONFIDENTIALITY NOTICE:
The contents of this e-mail message and any attachments are intended solely for the addressee(s) and may contain confidential and/or legally privileged information. If you are not the intended recipient of this message or if this message has been addressed to you in error, please immediately alert the sender by reply e-mail and then delete this message and any attachments. If you are not the intended recipient, you are notified that any use, dissemination, distribution, copying, or storage of this message or any attachment is strictly prohibited.

"Vianello, Daniel A" <Daniel.Vianello@charter.com> writes:

Uh, why would we list \ir before the simpler \i?

So that the request is to merge \ir into the \i section (not before \i but part of that discusstion) rather than being separated by the comparatively longer section for \if

It was, in fact, like that initially. Peter E. changed it in commit
0d9bdbcaae0, without any discussion that I remember seeing. I've never
been very happy with "alphabetical order trumps all other considerations"
as a documentation rule, and this seems like a good example of why not.

regards, tom lane

On 27.05.18 05:08, Tom Lane wrote:

"Vianello, Daniel A" <Daniel.Vianello@charter.com> writes:

Uh, why would we list \ir before the simpler \i?

So that the request is to merge \ir into the \i section (not before \i but part of that discusstion) rather than being separated by the comparatively longer section for \if

It was, in fact, like that initially. Peter E. changed it in commit
0d9bdbcaae0, without any discussion that I remember seeing. I've never
been very happy with "alphabetical order trumps all other considerations"
as a documentation rule, and this seems like a good example of why not.

The rule is, alphabetical order trumps no consideration. ;-)

I can see the point here. Merging \i and \ir into one item (with two
<term>s) might make sense. However, someone doing a mental binary
search across a man page would surely be confused if they don't find \ir
after \if. The question is, are they coming to the page to look up \ir,
or are they coming there to learn about groups of related commands?
Another way to associate \i and \ir is with "see also" type references.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On Saturday, July 7, 2018, Peter Eisentraut <
peter.eisentraut@2ndquadrant.com> wrote:

On 27.05.18 05:08, Tom Lane wrote:

"Vianello, Daniel A" <Daniel.Vianello@charter.com> writes:

Uh, why would we list \ir before the simpler \i?

So that the request is to merge \ir into the \i section (not before \i

but part of that discusstion) rather than being separated by the
comparatively longer section for \if

It was, in fact, like that initially. Peter E. changed it in commit
0d9bdbcaae0, without any discussion that I remember seeing. I've never
been very happy with "alphabetical order trumps all other considerations"
as a documentation rule, and this seems like a good example of why not.

The rule is, alphabetical order trumps no consideration. ;-)

I can see the point here. Merging \i and \ir into one item (with two
<term>s) might make sense.

This seems like the most desirable outcome and steps around the
alphabetical discussion quite cleanly.

However, someone doing a mental binary

search across a man page would surely be confused if they don't find \ir
after \if. The question is, are they coming to the page to look up \ir,
or are they coming there to learn about groups of related commands?

Some of each. A initial set of summary tables grouped by functionality and
with anchor links to the descriptions would serve both parties better but
is beyond the scope of this gripe which can be solved within the current
format easily enough.

Another way to associate \i and \ir is with "see also" type references.

Seems overkilll for this specific situation.

David J.