Re: more i18n/l10n issues

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

------- End of Forwarded Message