This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
Re: [PATCH: gdb/mi + doco] -var-update
> 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.