Re: more i18n/l10n issues

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

------- End of Forwarded Message