Re: postgres --help-config

Fernando Nasser wrote:
> Bruce,
>
> Before I comment on your suggestions, I would like to mention that many of the
> things below were added on request by the few people who cared to comment on it.
> Aizaz spent most of his time changing here and there to accommodate these
> requests. Anyway, we know we can't satisfy all, but I wish people would be more
> timely when criticizing things. Aizaz is away until May and left thinking
> everything was under control. And we developed a very nice tool that depends on
> this feature confident that we could count on it.

I understand this is not ideal timing. However, open source is
certainly very fluid and it is hard when someone adds something and then
isn't available for later adjustments.

I knew you were adding --help-config, but I didn't realize the extent of
the "features". The commit message is:

revision 1.1
date: 2003/07/04 16:41:21; author: tgl; state: Exp;
Add --help-config facility to dump information about GUC parameters
without needing a running backend. Reorder postgresql.conf.sample
to match new layout of runtime.sgml. This commit re-adds work lost
in Wednesday's crash.

which I thought was a single option, which we all knew was needed, not
six additional options for output format. Also, with no documention, or
a posted list of the flags you wanted to add (at least I never saw it),
it was easy to miss.

Imagine SRA wanted some features added to work better with their admin
tool --- if all the companies did that, PostgreSQL could become a
bloated mess.

> Bruce Momjian wrote:> Tom Lane wrote:
> >
> > First, the default output should have the sorted field first. It
> > appears the default is to sort by context:
> >
> > postgres --help-config
> >
> > That should be the first printed field. However, I see you can sort by
> > Group, so maybe group should always be first --- that seems most
> > logical.
> >
>
> Whatever you do to the human-readable output, please don't change the -M/-m
> format. It makes it harder to write code to parse these things if the fields
> keep changing positions.
>
> Someone is supposed to write an utility to create the sample postgresql.conf
> file from the output as well. I believe this tool would use it without the -G
> so that is why we have the -G option. Also, it was deemed better for the user
> readable output to have it grouped (it is easier to check with the documentation
> as well when it is being reviewed).

We don't normally add things until someone is ready to do the actual
coding --- only then do we know what they will really want.

> > The documentation I see is the command-line help in the C file:
> >
> > printf(gettext("Usage:\n %s --help-config [OPTION]... [NAME]\n\n"), progname);
> > printf(gettext("General Options:\n"));
> > printf(gettext(" NAME output information about parameters matching this name\n"));
> > printf(gettext(" -g GROUP output information about parameters matching this group\n"));
> > printf(gettext(" -l list available parameter groups\n"));
> > printf(gettext(" -h show this help, then exit\n"));
>
> We don't use the ones above.
>
> > printf(gettext("\nOutput Options:\n"));
> > printf(gettext(" -G do not group by category\n"));
> > printf(gettext(" -m machine-friendly format: tab separated fields\n"));
> > printf(gettext(" -M same as -m, but header with column names is suppressed\n"));
> >
>
> We do use these.
>
> > I don't see any value to most of these parameters, and the "add them in
> > case they might need them" has never been our philosophy, so I don't see
> > why we should add them at this point. Can we just get minimal
> > functionality and see what people ask for --- they might ask for
> > something completely different from what we have spec'ed out here, and
> > if they do, we will have to remove existing options to meet their needs,
> > or maintain a bloat of options. You know I have no problems adding
> > options to make common tasks easier for our users, but we have no usage
> > cases yet to know what they want.
> >
>
> Our GUI tool uses only -G and -M (we may need to resort to -m soon, so we would
> like that one to be preserved as well).
>
> The remaining ones are related to its use as a command line utility and meant to
> produce readable output. I guess some options were indeed requested to limit
> the amount of info printed. BTW, it was a separate utility at that time:
> pg_guc. Aizaz was asked to transform it into a postgres --help-config option.

I think --help-config needs to be a postgres flag, but the output format
flags should be in a separate utility, perhaps not one we ship with
PostgreSQL. I would not have a problem with a separate tool, perhaps in
the src/tools directory, that would parse the output into all sorts of
formats. I am just learning Perl, but I bet I could do it. The
advantage of a src/tools script is that it is isolated, doesn't have to
be documented as thoroughly, and can even be adjusted from release to
release.

> > What would make sense is to always output sorted by Group/Name, and see
> > how that works for folks.
>
> Please don't do it for -M/-m. It may unnecessarily increase the response time
> of GUI tools and add to the server load. The client can always sort or store it
> the way it wants.

You are worried about response time on a tool that parses output? Seems
it would be much clearer to run postgres --help-config, load that into a
perl array, then do the sorting and output as desired.

> > I also didn't think the dashed lines were
> > needed --- they seemed to clutter the output:
> >
>
> This seems to be a question of personal preference. But as I said, we only use
> the -M/-m output in our tool.

> > An output that uses --help-config, and takes no flags seems like the way
> > to go at this point. If people want specific entries, they can page
> > through them with less, or use a tool to extract them from the text file
> > --- the output is in a very clear format.
> >
>
> Parsing human-readable output is not very good for the tools though. Too hard
> to parse and more subject to change. I don't mind much what happens to the
> human-readable output, but I would need the -M/-m (with -G, separate or
> automatically assumed) to be preserved.
>
> > I would also indent the text description (last line) to line up with the
> > other data fields.
> >
>
> That sounds like a good idea for improvement. I don't see why it can't be done
> as an enhancement patch any time in the future. Again, please do not change the
> -M/-m output. Formatting will be done by the proper window widgets in that case
> and can vary with the situation. An unchanged description string is important.

Let me be clear on this --- your tools is not part of the PostgreSQL
community. We are not required to allow any of this functionality
unless the community decides they want it. The major argument for
keeping it, in my mind, is to be helpful to Red Hat.

My current idea is to keep --help-config as readable output, add
--help-config-raw as machine-readable output, document those, and remove
all the additional flags.

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