From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 25172 invoked by alias); 9 Nov 2005 19:19:57 -0000 Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org Received: (qmail 25160 invoked by uid 22791); 9 Nov 2005 19:19:54 -0000 Received: from romy.inter.net.il (HELO romy.inter.net.il) (192.114.186.66) by sourceware.org (qpsmtpd/0.30-dev) with ESMTP; Wed, 09 Nov 2005 19:19:54 +0000 Received: from HOME-C4E4A596F7 (IGLD-84-228-243-133.inter.net.il [84.228.243.133]) by romy.inter.net.il (MOS 3.5.8-GR) with ESMTP id CYD81193 (AUTH halo1); Wed, 9 Nov 2005 21:19:47 +0200 (IST) Date: Wed, 09 Nov 2005 19:19:00 -0000 Message-Id: From: Eli Zaretskii To: Andrew STUBBS CC: gdb@sources.redhat.com In-reply-to: <4371D9A6.40109@st.com> (message from Andrew STUBBS on Wed, 09 Nov 2005 11:12:38 +0000) Subject: Re: $argc variable Reply-to: Eli Zaretskii References: <436A0BD2.5080505@st.com> <20051107001800.GF19200@nevyn.them.org> <436F35E9.4070808@st.com> <20051107133538.GA2331@nevyn.them.org> <43709E94.4070004@st.com> <4371D9A6.40109@st.com> X-SW-Source: 2005-11/txt/msg00208.txt.bz2 > Date: Wed, 09 Nov 2005 11:12:38 +0000 > From: Andrew STUBBS > Cc: gdb@sources.redhat.com > > Eli Zaretskii wrote: > > Btw, Andrew, why do you post patches to gdb@sources.redhat.com, rather > > than to gdb-patches@ ? The latter is the right place. > > I post patches to gdb-patches@ and other messages to gdb@ which, in this > case, has a patch as a follow up. Should I switch list as soon as I have > a patch? That seems a little disconnected to me, but I see your point. I > originally posted the new options I had to gdb@ because I thought they > might be a little more controversial - I also called them RFC. Patches should go to gdb-patches. If you want to discuss possible changes, start the discussion on gdb-patches. > > Upper case is not the problem: makeinfo produces an uppercase word > > from @var since time immemoriam, so anyone who's used to read Info > > manuals is already used to that. > > I would respectfully suggest that manuals should be written for those > that do NOT know what they are doing. A user who reads an Info manual for the first time should read the Info introduction (which is the first menu item of the global DIR menu). There's more to Info conventions than just this one. The reason for the choice of @var translation is that Info is for text terminals which don't support slanted typefaces (which is how @var looks in print and in HTML). > > The problem here is that it's simply wrong to use @var in this case, > > because $arg0 etc. are literal strings, to be used verbatim in the > > actual script, not placeholders that stand for something else. So > > your change is correct, although for the wrong reasons. ;-) > > Well, I would have been happy with the wrong mark-up if the end > type-face had been right - it just depends on your point of view ;) My point of view is to use right Texinfo conventions ;-) > >>-via @var{$arg0@dots{}$arg9}. A trivial example: > > > > > > However, there _is_ something wrong here: the $ part should be outside > > @var, since it's a literal character: > > > > via @code{$@var{arg0}@dots{}$@var{arg9}}. > > Err, haven't you just put back the @var, and therefore upper case, that > we just agreed shouldn't be there? Sorry, I started to write different text, then realized I was in error, but failed to erase the wrong text. Please re-read my message as it _should_ have been written, below. Sorry for the confusion. > >>+via @code{$arg0@dots{}$arg9}. A trivial example: > >> > >> @smallexample > >> define adder > >> print $arg0 + $arg1 + $arg2 > >>+end > >> @end smallexample > > > > > > In the example, I would suggest to use something other than arg0 etc., > > to avoid confusion with arg0..arg9 as placeholders in the paragraph > > where you wanted to remove @var. > > But this is an example of how to use $arg0 ?!?!? See above: this text shouldn't have been sent. > >>+@kindex $argc > > > > > > I'd replace this with "@cindex arguments for user-defined function". > > Replace or augment? Replace. > I considered adding a kindex for $arg0...$arg9. This isn't useful: having several index entries that begin with identical substrings and point to the same page in the manual has only one effect: it makes the index larger. > I agree that a concept should be added, but how about: > > @cindex user-defined functions, argument passing This is good. Here's what I _intended_ to send: Date: Wed, 09 Nov 2005 01:19:28 +0200 From: Eli Zaretskii To: Andrew STUBBS CC: gdb@sources.redhat.com Subject: Re: $argc variable > Date: Tue, 08 Nov 2005 12:48:20 +0000 > From: Andrew STUBBS > Cc: GDB List Btw, Andrew, why do you post patches to gdb@sources.redhat.com, rather than to gdb-patches@ ? The latter is the right place. > In the documentation I changed a '@var' to '@code' because @var makes it > upper case in the info and I thought that misleading. Upper case is not the problem: makeinfo produces an uppercase word from @var since time immemoriam, so anyone who's used to read Info manuals is already used to that. The problem here is that it's simply wrong to use @var in this case, because $arg0 etc. are literal strings, to be used verbatim in the actual script, not placeholders that stand for something else. So your change is correct, although for the wrong reasons. ;-) > +@kindex $argc I'd replace this with "@cindex arguments for user-defined function". Other than that, the documentation patch is okay with me. Thanks.