postgres --help-config

Where should I start on this? :-)

The implementation of postgres --help-config has several issues:

o it has options added "just in case someone ever need them"
o it has capital letters to negate, which we have never used
before
o uses GNU message reporting style
o there was little discussion about how this should work

Its biggest "plus" is that it isn't documented :-) --- because the API
might change in the next release, and no one wants to stand up for this.

If Red Hat didn't do so much for PostgreSQL by hiring Tom and others, I
would be more upset, but putting something in for the convenience of
some Red Hat tool isn't something I would like to see happen regularly,
and I think we can all agree on that.

I can't even put a mention on the TODO that this has to be cleaned up
because I would then advertise it. I will put it on my personal list
and we can discuss how this is supposed to for for 7.5.

---------------------------------------------------------------------------

Tom Lane wrote:
> Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
> > [ some questions about --help-config ]
>
> I got this reply from Fernando Nasser of Red Hat. I suggested he should
> post it for himself, but since he hasn't yet...
>
> regards, tom lane
>
> > ------- Forwarded Message
> >
> > Date: Tue, 30 Sep 2003 11:24:50 +0200 (CEST)
> > From: Peter Eisentraut <peter_e(at)gmx(dot)net>
> (...)
> >
> > OK, but does this tool actually need all of the following features:
> >
> > -G -- do not group by category
> > both -m and -M -- machine-readable output with and without header
> > human-readable output
> >
> > Were some of these just added for "completeness"? With what rationale?
> >
>
>
> -m and -M
>
> The utility we designed and possibly any other that wants to process the
> output will find it easier to process a more regularly formed output
> instead of one that was embellished for human viewing. The reason for
> having one with and one without headings is that in some circumstances
> the utility designer may want to use the headers to make her/his table
> headers and others may prefer to have pre-defined table headers. The
> guy who wrote our window used -M while I would have liked him to use -m
> (but -M was faster to do and he was on a hurry).
>
> -G
>
> The -G (using the Unix convention of negating things with capital
> letters) is what we use. This option is probably what will be used for
> generating the postgresql.conf default file automatically.
> As we were not adding a facility for our use but for other tool
> developers as well and we thought that some may want to process it in
> different ways we made it an option. We don't object making it a side
> effect of using -m or -M.
>
>
>
> > Also, --help-config 'foo' outputs all parameters matching 'foo' somewhere
> > in the string, not only 'foo'. I think that is a misdesign.
> >
>
> It works like locate (or slocate). I believe some other Unix utilities
> do the same. Unix commands are mostly 'misdesigned' I admit.
>
> I had a '-re' which accepted a regular expression. With that re-added
> one could make the --help-config 'foo' works like Peter wants. But I
> would put that for a vote: I wouldn't be surprised if Peter were in a
> minority on this issue.
>
>
> >>postgresql.conf. The "long" descriptions were what the GUI tool wants.
> >
>
> Tom, actually the tool (as I believe from previous experience with
> command line help facilities) needs both.
>
> The short description shows up in summaries where you have a list of
> options and not much space. The long description shows up in specific
> help commands, as tooltips etc., whenever the user wants and you can
> provide more information.
>
> >
> > Most parameters don't have long descriptions, so that doesn't seem right.
> >
>
> When the meaning is obvious there is no need to re-state it. There may
> be cases where a better description should be written and it is only
> empty because nobody yet knows exactly what it does, or could not come
> up with a proper description (whenever a description was available in
> the documentation the field was filled).
>
>
> > Also, in many cases where there is a long description, it was copied out
> > of the documentation, with the short description being the first sentence
> > and the long description being the rest. The result is that in some cases
> > the long description doesn't make sense in isolation. I would like that
> > to be clarified.
> >
>
> This is a GNU trick to avoid repeating the same text (from the short
> description) in the long description. I believe it is from Richard
> Stallman's time. It is used in several GNU tools, for instance the GNU
> GDB debugger (which uses just one field and makes the first sentence or
> line the short description). The idea is that the long description is
> formed by the concatenation of the two.
>
> --
> Fernando Nasser
> Red Hat Canada Ltd. E-Mail: fnasser(at)redhat(dot)com
> 2323 Yonge Street, Suite #300
> Toronto, Ontario M4P 2C9
>
> ------- End of Forwarded Message
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 4: Don't 'kill -9' the postmaster
>

--
Bruce Momjian | http://candle.pha.pa.us
pgman(at)candle(dot)pha(dot)pa(dot)us | (610) 359-1001
+ If your life is a hard drive, | 13 Roberts Road
+ Christ can be your backup. | Newtown Square, Pennsylvania 19073