Add PostgreSQL home page to --help output

Started by Peter Eisentrautabout 6 years ago15 messageshackers

peter_e@gmx.net

about 6 years ago

Example:

initdb --help
...
Report bugs to <pgsql-bugs@lists.postgresql.org>.
PostgreSQL home page: <https://www.postgresql.org/>

I think this is useful. You see this nowadays in other packages as
well. See also
<https://www.gnu.org/prep/standards/standards.html#g_t_002d_002dhelp>
for a reference.

Autoconf already has a way to register the package home page and
propagate it, so I used that. That also makes it easier to change it
(see http: -> https:) or have third parties substitute their own contact
information without destroying translations.

While at it, I also did the same refactoring for the bug reporting
address (which was also recently changed, so this is a bit late, but who
knows what the future holds).

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

Daniel Gustafsson

daniel@yesql.se

about 6 years ago

In reply to: Peter Eisentraut (#1)

Re: Add PostgreSQL home page to --help output

On 11 Feb 2020, at 08:41, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:

Autoconf already has a way to register the package home page and propagate it, so I used that. That also makes it easier to change it (see http: -> https:) or have third parties substitute their own contact information without destroying translations.

+1, this change has the side benefit of aiding postgres forks who otherwise
have to patch all occurrences to avoid getting reports on the wrong list.

While at it, I also did the same refactoring for the bug reporting address (which was also recently changed, so this is a bit late, but who knows what the future holds).

Pardon my weak autoconf-skills, what does the inverted brackets (]foo[ as
opposed to [foo]) do in the below?

-Please also contact <pgsql-bugs@lists.postgresql.org> to see about
+Please also contact <]AC_PACKAGE_BUGREPORT[> to see about

cheers ./daniel

Peter Eisentraut

peter_e@gmx.net

about 6 years ago

In reply to: Daniel Gustafsson (#2)

Re: Add PostgreSQL home page to --help output

On 2020-02-11 10:34, Daniel Gustafsson wrote:

Pardon my weak autoconf-skills, what does the inverted brackets (]foo[ as
opposed to [foo]) do in the below?
-Please also contact<pgsql-bugs@lists.postgresql.org>  to see about
+Please also contact <]AC_PACKAGE_BUGREPORT[> to see about

AC_PACKAGE_BUGREPORT is an Autoconf macro, set up by AC_INIT. The call
above is in the context of

AC_MSG_ERROR([[ ... text ... ]])

The brackets are quote characters that prevent accidentally expanding a
token in the text as a macro. So in order to get AC_PACKAGE_BUGREPORT
expanded, we need to undo one level of quoting.

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

Daniel Gustafsson

daniel@yesql.se

about 6 years ago

In reply to: Peter Eisentraut (#3)

Re: Add PostgreSQL home page to --help output

On 12 Feb 2020, at 11:54, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:

On 2020-02-11 10:34, Daniel Gustafsson wrote:
Pardon my weak autoconf-skills, what does the inverted brackets (]foo[ as
opposed to [foo]) do in the below?
-Please also contact<pgsql-bugs@lists.postgresql.org>  to see about
+Please also contact <]AC_PACKAGE_BUGREPORT[> to see about
AC_PACKAGE_BUGREPORT is an Autoconf macro, set up by AC_INIT. The call above is in the context of

AC_MSG_ERROR([[ ... text ... ]])

The brackets are quote characters that prevent accidentally expanding a token in the text as a macro. So in order to get AC_PACKAGE_BUGREPORT expanded, we need to undo one level of quoting.

See also <https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/M4-Quotation.html#M4-Quotation> for more information.

Aha, that's what I was looking for in the docs but didn't find. Thanks for
sharing!

cheers ./daniel

Bruce Momjian

bruce@momjian.us

about 6 years ago

In reply to: Peter Eisentraut (#1)

Re: Add PostgreSQL home page to --help output

Sounds like a fine idea. But personally I would prefer it without the <>
around the it, just a url on a line by itself. I think it would be clearer,
look cleaner, and be easier to select to copy/paste elsewhere.

On Tue., Feb. 11, 2020, 02:42 Peter Eisentraut, <
peter.eisentraut@2ndquadrant.com> wrote:

Show quoted text

Example:

initdb --help
...
Report bugs to <pgsql-bugs@lists.postgresql.org>.
PostgreSQL home page: <https://www.postgresql.org/>

I think this is useful. You see this nowadays in other packages as
well. See also
<https://www.gnu.org/prep/standards/standards.html#g_t_002d_002dhelp>
for a reference.

Autoconf already has a way to register the package home page and
propagate it, so I used that. That also makes it easier to change it
(see http: -> https:) or have third parties substitute their own contact
information without destroying translations.

While at it, I also did the same refactoring for the bug reporting
address (which was also recently changed, so this is a bit late, but who
knows what the future holds).

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

Peter Eisentraut

peter_e@gmx.net

about 6 years ago

In reply to: Bruce Momjian (#5)

Re: Add PostgreSQL home page to --help output

On 2020-02-13 14:24, Greg Stark wrote:

Sounds like a fine idea. But personally I would prefer it without the <>
around the it, just a url on a line by itself. I think it would be
clearer, look cleaner, and be easier to select to copy/paste elsewhere.

I'm on the fence about this one, but I like the delimiters because it
would also work consistently if we put a URL into running text where it
might be immediately adjacent to other characters. So I was actually
going for easier to copy/paste here, but perhaps in other environments
it's not easier?

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

Daniel Gustafsson

daniel@yesql.se

about 6 years ago

In reply to: Peter Eisentraut (#6)

Re: Add PostgreSQL home page to --help output

On 20 Feb 2020, at 10:15, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:

On 2020-02-13 14:24, Greg Stark wrote:

Sounds like a fine idea. But personally I would prefer it without the <> around the it, just a url on a line by itself. I think it would be clearer, look cleaner, and be easier to select to copy/paste elsewhere.

I'm on the fence about this one, but I like the delimiters because it would also work consistently if we put a URL into running text where it might be immediately adjacent to other characters. So I was actually going for easier to copy/paste here, but perhaps in other environments it's not easier?

For URLs completely on their own, not using <> makes sense. Copy pasting <url>
into the location bar of Safari makes it load the url, but Firefox and Chrome
turn it into a search engine query (no idea about Windows browsers).

For URLs in running text it's not uncommon to have <> around the URL for the
very reason you mention. Looking at --help and manpages from random open
source tools there seems to be roughly a 50/50 split on using <> or not.

cheers ./daniel

Daniel Gustafsson

daniel@yesql.se

about 6 years ago

In reply to: Daniel Gustafsson (#7)

Re: Add PostgreSQL home page to --help output

On 20 Feb 2020, at 10:53, Daniel Gustafsson <daniel@yesql.se> wrote:

On 20 Feb 2020, at 10:15, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:

On 2020-02-13 14:24, Greg Stark wrote:

Sounds like a fine idea. But personally I would prefer it without the <> around the it, just a url on a line by itself. I think it would be clearer, look cleaner, and be easier to select to copy/paste elsewhere.

I'm on the fence about this one, but I like the delimiters because it would also work consistently if we put a URL into running text where it might be immediately adjacent to other characters. So I was actually going for easier to copy/paste here, but perhaps in other environments it's not easier?

For URLs completely on their own, not using <> makes sense. Copy pasting <url>
into the location bar of Safari makes it load the url, but Firefox and Chrome
turn it into a search engine query (no idea about Windows browsers).

For URLs in running text it's not uncommon to have <> around the URL for the
very reason you mention. Looking at --help and manpages from random open
source tools there seems to be roughly a 50/50 split on using <> or not.

RFC3986 discuss this in <https://tools.ietf.org/html/rfc3986#appendix-C>, with
the content mostly carried over from RFC2396 appendix E.

cheers ./daniel

Peter Eisentraut

peter_e@gmx.net

about 6 years ago

In reply to: Daniel Gustafsson (#8)

Re: Add PostgreSQL home page to --help output

On 2020-02-20 12:09, Daniel Gustafsson wrote:

On 20 Feb 2020, at 10:53, Daniel Gustafsson <daniel@yesql.se> wrote:

On 20 Feb 2020, at 10:15, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:

On 2020-02-13 14:24, Greg Stark wrote:

Sounds like a fine idea. But personally I would prefer it without the <> around the it, just a url on a line by itself. I think it would be clearer, look cleaner, and be easier to select to copy/paste elsewhere.

I'm on the fence about this one, but I like the delimiters because it would also work consistently if we put a URL into running text where it might be immediately adjacent to other characters. So I was actually going for easier to copy/paste here, but perhaps in other environments it's not easier?

For URLs completely on their own, not using <> makes sense. Copy pasting <url>
into the location bar of Safari makes it load the url, but Firefox and Chrome
turn it into a search engine query (no idea about Windows browsers).

For URLs in running text it's not uncommon to have <> around the URL for the
very reason you mention. Looking at --help and manpages from random open
source tools there seems to be roughly a 50/50 split on using <> or not.

RFC3986 discuss this in <https://tools.ietf.org/html/rfc3986#appendix-C>, with
the content mostly carried over from RFC2396 appendix E.

I think we weren't going to get any more insights here, so I have
committed it as is.

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

#10

Bruce Momjian

bruce@momjian.us

about 6 years ago

In reply to: Peter Eisentraut (#9)

Re: Add PostgreSQL home page to --help output

On Fri, Feb 28, 2020 at 02:02:17PM +0100, Peter Eisentraut wrote:

On 2020-02-20 12:09, Daniel Gustafsson wrote:

On 20 Feb 2020, at 10:53, Daniel Gustafsson <daniel@yesql.se> wrote:

On 20 Feb 2020, at 10:15, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:

On 2020-02-13 14:24, Greg Stark wrote:

Sounds like a fine idea. But personally I would prefer it without the <> around the it, just a url on a line by itself. I think it would be clearer, look cleaner, and be easier to select to copy/paste elsewhere.

I'm on the fence about this one, but I like the delimiters because it would also work consistently if we put a URL into running text where it might be immediately adjacent to other characters. So I was actually going for easier to copy/paste here, but perhaps in other environments it's not easier?

For URLs completely on their own, not using <> makes sense. Copy pasting <url>
into the location bar of Safari makes it load the url, but Firefox and Chrome
turn it into a search engine query (no idea about Windows browsers).

For URLs in running text it's not uncommon to have <> around the URL for the
very reason you mention. Looking at --help and manpages from random open
source tools there seems to be roughly a 50/50 split on using <> or not.

RFC3986 discuss this in <https://tools.ietf.org/html/rfc3986#appendix-C>, with
the content mostly carried over from RFC2396 appendix E.

I think we weren't going to get any more insights here, so I have committed
it as is.

Some new feedback. I find this output confusing since there is a colon
before the <>:

Report bugs to <pgsql-bugs@lists.postgresql.org>.
PostgreSQL home page: <https://www.postgresql.org/>

Does this look better (no colon)?

Report bugs to <pgsql-bugs@lists.postgresql.org>.
PostgreSQL home page <https://www.postgresql.org/>

or this (colon, no <>)?

Report bugs to <pgsql-bugs@lists.postgresql.org>.
PostgreSQL home page: https://www.postgresql.org/

or maybe this?

Report bugs: pgsql-bugs@lists.postgresql.org
PostgreSQL home page: https://www.postgresql.org/

or this?

Report bugs <pgsql-bugs@lists.postgresql.org>
PostgreSQL home page <https://www.postgresql.org/>

I actually have never seen URLs in <>, only email addresses. I think
using <> for URLs and emails is confusing because they usually have
different actions, unless we want to add mailto:

Report bugs <mailto:pgsql-bugs@lists.postgresql.org>
PostgreSQL home page <https://www.postgresql.org/>

Report bugs mailto:pgsql-bugs@lists.postgresql.org
PostgreSQL home page https://www.postgresql.org/

I kind of prefer the last one since the can both be pasted directly into
a browser.

--
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 +

#11

Bruce Momjian

bruce@momjian.us

about 6 years ago

In reply to: Bruce Momjian (#10)

Re: Add PostgreSQL home page to --help output

On Mon, Mar 16, 2020 at 05:55:26PM -0400, Bruce Momjian wrote:

Report bugs mailto:pgsql-bugs@lists.postgresql.org
PostgreSQL home page https://www.postgresql.org/

I kind of prefer the last one since the can both be pasted directly into
a browser.

Actually, I prefer:

Report bugs mailto:pgsql-bugs@lists.postgresql.org
PostgreSQL website https://www.postgresql.org/

--
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 +

#12

Alvaro Herrera

alvherre@2ndquadrant.com

about 6 years ago

In reply to: Bruce Momjian (#11)

Re: Add PostgreSQL home page to --help output

On 2020-Mar-16, Bruce Momjian wrote:

On Mon, Mar 16, 2020 at 05:55:26PM -0400, Bruce Momjian wrote:

Report bugs mailto:pgsql-bugs@lists.postgresql.org
PostgreSQL home page https://www.postgresql.org/

I kind of prefer the last one since the can both be pasted directly into
a browser.

Actually, I prefer:

Report bugs mailto:pgsql-bugs@lists.postgresql.org
PostgreSQL website https://www.postgresql.org/

Hmm, pasting mailto into the browser address bar doesn't work for me ...
it just goes to the lists.postgresql.org website (Brave) or sits there
doing nothing (Firefox). I was excited there for a minute.

If we're talking personal preference, I like the current output.

--
ï¿½lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

#13

Michael Paquier

michael@paquier.xyz

about 6 years ago

In reply to: Alvaro Herrera (#12)

Re: Add PostgreSQL home page to --help output

On Mon, Mar 16, 2020 at 09:10:25PM -0300, Alvaro Herrera wrote:

On 2020-Mar-16, Bruce Momjian wrote:

Actually, I prefer:

Report bugs mailto:pgsql-bugs@lists.postgresql.org
PostgreSQL website https://www.postgresql.org/

Hmm, pasting mailto into the browser address bar doesn't work for me ...
it just goes to the lists.postgresql.org website (Brave) or sits there
doing nothing (Firefox). I was excited there for a minute.

Pasting "mailto:pgsql-bugs@lists.postgresql.org" to Firefox 74.0 pops
up for me a window asking to choose an application able to send an
email. For example, with mutt, this would begin generating an email
sent to the address pasted.

If we're talking personal preference, I like the current output.

No strong opinion about one or the other.
--
Michael

#14

Bruce Momjian

bruce@momjian.us

about 6 years ago

In reply to: Alvaro Herrera (#12)

Re: Add PostgreSQL home page to --help output

bOn Mon, Mar 16, 2020 at 09:10:25PM -0300, Alvaro Herrera wrote:

On 2020-Mar-16, Bruce Momjian wrote:

On Mon, Mar 16, 2020 at 05:55:26PM -0400, Bruce Momjian wrote:

Report bugs mailto:pgsql-bugs@lists.postgresql.org
PostgreSQL home page https://www.postgresql.org/

I kind of prefer the last one since the can both be pasted directly into
a browser.

Actually, I prefer:

Report bugs mailto:pgsql-bugs@lists.postgresql.org
PostgreSQL website https://www.postgresql.org/

Hmm, pasting mailto into the browser address bar doesn't work for me ...
it just goes to the lists.postgresql.org website (Brave) or sits there
doing nothing (Firefox). I was excited there for a minute.

If we're talking personal preference, I like the current output.

Well, in Firefox it knows to use Thunderbird to send email because under
Firefox's Preferences/General/Applications, 'mailto' is set to "Use
Thunderbird", though it can be set to other applications. If no one
likes my changes, I guess we will just stick with what we have.

--
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 +

#15

Daniel Gustafsson

daniel@yesql.se

about 6 years ago

In reply to: Bruce Momjian (#14)

Re: Add PostgreSQL home page to --help output

On 19 Mar 2020, at 22:32, Bruce Momjian <bruce@momjian.us> wrote:

bOn Mon, Mar 16, 2020 at 09:10:25PM -0300, Alvaro Herrera wrote:

On 2020-Mar-16, Bruce Momjian wrote:

On Mon, Mar 16, 2020 at 05:55:26PM -0400, Bruce Momjian wrote:

Report bugs mailto:pgsql-bugs@lists.postgresql.org
PostgreSQL home page https://www.postgresql.org/

I kind of prefer the last one since the can both be pasted directly into
a browser.

Actually, I prefer:

Report bugs mailto:pgsql-bugs@lists.postgresql.org
PostgreSQL website https://www.postgresql.org/

Hmm, pasting mailto into the browser address bar doesn't work for me ...
it just goes to the lists.postgresql.org website (Brave) or sits there
doing nothing (Firefox). I was excited there for a minute.

If we're talking personal preference, I like the current output.

Well, in Firefox it knows to use Thunderbird to send email because under
Firefox's Preferences/General/Applications, 'mailto' is set to "Use
Thunderbird", though it can be set to other applications. If no one
likes my changes, I guess we will just stick with what we have.

I don't think mailto: URLs is a battle we can win, pasting it into Safari for
example yields this error message:

"This website has been blocked from automatically composing an email."

It also assumes that users will paste the bugreport email into something that
parses URLs and not straight into the "To:" field of their email client. I'm
not sure that assumption holds.

cheers ./daniel

Add PostgreSQL home page to --help output

Attachments: