Re: variable names in manual

[Carsten Dominik <carsten.dominik@gmail.com>]

On 26 apr. 2013, at 01:48, Suvayu Ali <fatkasuvayu+linux@gmail.com> wrote:

> On Thu, Apr 25, 2013 at 07:37:25PM -0400, Greg Minshall wrote:
>> sorry about that.  i was going to ask about the variable names in the
>> current (8.x) documentation being in upper case.  (then, wanted to check
> 
> [...chomp...chomp...chomp...]
> 
>> but, it means that placing the cursor over the name and hitting C-h v
>> doesn't default to that name.  (and, i've always found that a convenient
>> way to navigate.)
>> 
>> so, just curious is it might make sense to revert to lower case names.
> 
> I wasn't aware of this change!  I would agree with Greg here.


I suspect that the cases you are talking about here are due
to incorrect use of the texinfo command @var{}.  This should
only be used for metasyntactical variables, when they stand
for something else in a description. 

Here is an example from the current manual.

  You can customize this behavior using the option
  @var{org-table-use-standard-references}.} to use another, more general
  representation that looks like this:
  @example
  @@@var{row}$@var{column}
  @end example

The first use of @var is incorrect, @code should be used here.  But the use in @var{row} and @var{column} is correct.

I believe that a while ago we did use @var and @code correctly, but someone went through and changed the @code{org-...} to @var{org-...} at some point.  We need to change this back.

- Carsten





> 
> -- 
> Suvayu
> 
> Open source is the future. It sets us free.
>