Re: postgres --help-config

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.

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

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

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

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

>
> ------------------------------------------------------------
> Name: preload_libraries
> Context: postmaster
> Group: Resource Usage / Kernel Resources
> Type: string
> Default value:
> Description: shared libraries to preload into server
>
> ------------------------------------------------------------
> Name: fsync
> Context: sighup
> Group: Write-Ahead Log / Settings
> Type: Boolean
> Default value: true
> Description: force synchronization of updates to disk
> The server will use the fsync() system call in several places to make sure that updates are physically written to disk. This insures that a database cluster will recover to a consistent state after an operating system or hardware crash.
> ------------------------------------------------------------
>
> vs.
>
>
> Name: preload_libraries
> Context: postmaster
> Group: Resource Usage / Kernel Resources
> Type: string
> Default value:
> Description: shared libraries to preload into server
>
> Name: fsync
> Context: sighup
> Group: Write-Ahead Log / Settings
> Type: Boolean
> Default value: true
> Description: force synchronization of updates to disk
> The server will use the fsync() system call in several places to make sure that updates are physically written to disk. This insures that a database cluster will recover to a consistent state after an operating system or hardware crash.
>
> 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.

Regards to all,
Fernando

--
Fernando Nasser
Red Hat - Toronto E-Mail: fnasser(at)redhat(dot)com
2323 Yonge Street, Suite #300
Toronto, Ontario M4P 2C9