Re: Patch for listing runtime option details through server

Aizaz Ahmed writes:

> The attached patch adds the --long-help option to the server executable.

Conceptual comments:

If the option is named --long-help, I'd expect a longer version of
--help, which this is not. The name should probably involve "help"
and "config" to make it clearer what you get. (Personally, I think
"help" should go before the qualifying word, but there may be other
opinions.)

Do we really want to encode the notion of option categories into the
source code? This looks like a pretty large burden to me. Organizing
the documentation or the sample files in user-friendly ways is one
thing, but if I need to organize the code and new options along those
lines, I'm not sure.

If, on the other hand, we like the code to know about categories,
should this code be capable of generating the sample file
automatically?

I don't think we need two different machine formats -m and -M. The
machine isn't going to need the column headers anyway.

The help message should be printed by --help, not -h. In fact, I
don't think there should be a separate subhelp message. Users know
about --help, and that should give them all information about all
invocation modes right there.

Code comments:

To mark up string literals, where you use translatable(), there is
already a standard function gettext_noop() available.

When inserting lines into an existing help message, please observe the
style conventions (capitalization, punctuation, etc.) of the
surrounding lines.

There is already a file guc.c, why should there be a file pg_guc.c
now? That doesn't make sense; the names should be differentiated
better.

Why have various things been moved from guc.h to guc_vars.h, which
seems to just split things up uselessly?

Why are there long explanations in some cases only? Do you plan to
add others later? I also think the messages should be made more
consistent in various ways, but that can be done later.

Should options not for general use (e.g., session_auth_is_superuser)
be hidden from this tool? Are they? What other provisions of this
kind does this tool make?

The GucContext_names are not translatable. They aren't English words
either.

--
Peter Eisentraut peter_e(at)gmx(dot)net