Re: -var-info-path-expression

[Eli Zaretskii <eliz at gnu dot org>]

> From: Vladimir Prus <ghost@cs.msu.su>
> Date: Fri, 31 Aug 2007 22:52:47 +0400
> Cc: gdb-patches@sources.redhat.com
> 
> > > +For example, if @var{a} is an array, and variable object
> > > +@var{A} was created for @var{a}, then we'll get this output:
> > 
> > It's wrong to use @var in this context: here, `a' and `A' are literal
> > symbols, they do not stand for something else.  So you should use
> > @code, not @var.
> 
> So, @var is not for programming language variables (like docbook's varname),
> but rather a placeholder (like docbook's replaceable)?

Yes, it's a placeholder.  It's for the cases when you want to say
things like

     frobnicate FILE

and FILE is to be replaced by an actual filename when this command is
used.

There's one borderline case where @var is used, although you could
have said that its argument is not a placeholder: when you describe a
prototype of a function:

  int foo (char *bar, struct something *baz);

(This example is for C/C++, but similar examples exist in other
languages that support functions with arguments.)  The Texinfo @def*
constructs render the arguments in the @var typeface, for example.  In
these cases, we will give "bar" and "baz" the @var markup, because
they are formal parameters of the function, and will be replaced by
something else when the function is actually called.  The tricky
aspect of this is that when you describe the parameters from _outside_
of the function, e.g. tell someone how to call it, you should use
@var, while for the description of the _inside_, like when you tell
how it works and cite certain parts of its code, those same symbols
should be in @code, because inside the function they are literal
symbols.

It is these borderline cases, as well as the name of the markup (which
mentally reminds you of the word "variable"), which cause confusion
about its usage.