From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13710 invoked by alias); 20 Feb 2005 05:02:23 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 13494 invoked from network); 20 Feb 2005 05:02:11 -0000 Received: from unknown (HELO romy.inter.net.il) (192.114.186.66) by sourceware.org with SMTP; 20 Feb 2005 05:02:11 -0000 Received: from zaretski (pns03-208-119.inter.net.il [80.230.208.119]) by romy.inter.net.il (MOS 3.5.6-GR) with ESMTP id AOP82884 (AUTH halo1); Sun, 20 Feb 2005 07:01:55 +0200 (IST) Date: Sun, 20 Feb 2005 15:31:00 -0000 From: "Eli Zaretskii" To: Nick Roberts Message-ID: <01c51709$Blat.v2.4$4a3292a0@zahav.net.il> Content-Transfer-Encoding: 7BIT Content-Type: text/plain; charset=ISO-8859-1 CC: gdb-patches@sources.redhat.com In-reply-to: <16919.53411.753668.336933@farnswood.snap.net.nz> (message from Nick Roberts on Sun, 20 Feb 2005 12:49:55 +1300) Subject: Re: [PATCH: gdb/mi + doco] -var-update Reply-to: Eli Zaretskii References: <16919.7660.144228.334687@farnswood.snap.net.nz> <01c5167f$Blat.v2.4$9a7a6f60@zahav.net.il> <16919.53411.753668.336933@farnswood.snap.net.nz> X-SW-Source: 2005-02/txt/msg00210.txt.bz2 > From: Nick Roberts > 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.