Re: $argc variable

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Wed, 09 Nov 2005 11:12:38 +0000
> From: Andrew STUBBS <andrew.stubbs@st.com>
> 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 <eliz@gnu.org>
    To: Andrew STUBBS <andrew.stubbs@st.com>
    CC: gdb@sources.redhat.com
    Subject: Re: $argc variable

    > Date: Tue, 08 Nov 2005 12:48:20 +0000
    > From: Andrew STUBBS <andrew.stubbs@st.com>
    > Cc: GDB List <gdb@sources.redhat.com>

    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.