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
hereand 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@redhat.com
2323 Yonge Street, Suite #300
Toronto, Ontario   M4P 2C9