Re: [PATCH: gdb/mi + doco] -var-update

["Eli Zaretskii" <eliz@gnu.org>]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Sun, 20 Feb 2005 12:49:55 +1300
> Cc: gdb-patches@sources.redhat.com
> 
>  > > !      error (_("Unknown value for PRINT_VALUES: must be: 0 or \"--no-values\", 1 or \"--all-values\""));
>  > 
>  > Please remove "--no-values" and "--all-values" from this string.  They
>  > are literal strings that must not be translated, and in addition they
>  > are used several times elsewhere in the code.  So I suggest to have
>  > them defined only once, as const char [], and the rest of code use
>  > those const strings; e.g., in the above case, use %s in the string and
>  > pass the strings as additional arguments to the `error' function.
> 
> Why would they be translated?

Because they are part of a string that is an argument to the _()
macro.  Such strings are extracted by the gettext package into a
message catalog, which is then used by translators to prepare
translations for those strings.  A translator looking at a string such
as

   Unknown value for PRINT_VALUES: must be: 0 or "--no-values", 1 or "--all-values\

could erroneously decide that "--all-values" and "--no-values" need to
be translated as well, if he/she doesn't know MI too well.

> Do you mean something like:
> 
> const char novalues[] = "\"--no-values\"";
> const char allvalues[] = "\"--all-values\";"
> 
> error (_("Unknown value for PRINT_VALUES: must be: 0 or %s, 1 or %s",
>        novalues, allvalues));

Yes.

>  > Also, didn't we decide to leave the messages emitted by MI
>  > untranslatable?
> 
> Are you referring to the underscore with brackets? [ _() ]

Yes.

> I'm not familiar with this device but this line has been cut and pasted from
> mi_cmd_var_list_children and all the other error messages in MI have it too.

If other messages are marked up with _(), then this is okay.  But I
still think the const char [] strings should be defined once and used
elsewhere in this function.

>  > >   @smallexample
>  > > !  -var-update [@var{print-values}] @{@var{name} | "*"@}
>  > >   @end smallexample
>  > >   
>  > >   Update the value of the variable object @var{name} by evaluating its
>  > >   expression after fetching all the new values from memory or registers.
>  > > ! A @samp{*} causes all existing variable objects to be updated.  With
>  > > ! just a single argument or with an optional preceding argument of 0 or
>  > > ! @code{--no-values}, prints only the names of the variables.  With an
>  > > ! optional preceding argument of 1 or @code{--all-values}, also prints
>  > > ! their values.
>  > 
>  > This text should refer to @var{print-values} you used inside
>  > @smallexample, otherwise it is not clear what should be used in its
>  > stead.
> 
> I'm not sure what you mean here.

The usage description used @var{print-values}, which is a variable
parameter, but the text does not refer to @var{print-values}.  A
reader will not understand what to put instead of @var{print-values}
if you don't mention it.

>  > Also, I find the choice of "--all-values" unfortunate.  The opposite
>  > of "--no-values" is something like "--with-values" or
>  > "--print-values", not "--all-values".
> 
> If it was a CLI command I would agree but the exact syntax of MI commands only
> has to be referred to by developers and not remembered by users.

In this case, users==developers.  Mnemonic names matter even for
developers of GDB front ends.

> I've used "--all-values" because, in the case of -var-list-children there is a
> third possibility: "--simple-values" and, to me, it seems simpler to have only
> three values for print_values (mi-cmds.h):
> 
> enum print_values {
>    PRINT_NO_VALUES,
>    PRINT_ALL_VALUES,
>    PRINT_SIMPLE_VALUES
> };

I see the reason, but I think it is not important enough to use
"--all-values".  Anyway, the switch text does not need to be similar
to the enum name, even if you use PRINT_ALL_VALUES in the enum.

>  > I'd suggest to have an example that uses a specific name instead of
>  > "*".  Examples should show typical usage; if you want to show special
>  > cases, show them _in_addition_ to typical ones.
> 
> I've just adapted the previous example, but if you mean replace:
> 
> > + -var-update --all-values *
> 
> with
> 
> > + -var-update --all-values var1
> 
> that's no problem.

Yes, that'd be good.