Capitalization rules for docstring variables

[John W. Eaton]

On  9-Jan-2011, Rik wrote:

| I'm in the process of trying to harmonize the variable names used in
| documentation (@deftypefn ... @var{samplevar}) and the actual code
| (function ... (examplevar)).  This has mostly been easy, but one open issue
| is whether to also harmonize capitalization.
| 
| Ideally, I would like to have some consistency in the documentation and
| describe all vectors using the lower case set {x,y,z,t,w} and matrices
| using the upper case set {A,B,C,...}.  This is a fairly normal convention
| and leads to 'eig (A,B)' and 'dot (x,y)'.  The question is whether to
| harmonize capitalization between the documentation and the code.
| Capitalized identifiers are generally used in the code for environment
| variables like PAGER or EDITOR; but, I'm not sure there is an established
| general rule.  Plenty of the scripts in the linear-algebra directory, such
| as rank.m, use a capital A in the code to refer to the input argument.  Is
| this acceptable?  Is it acceptable only if the variable in question is
| short like this so it won't be confused with a global variable?
| 
| Attached are two jpegs taken from the pdf documentation.  The first example
| is the current situation where the variable is '@var{a}'.  The second was
| created with '@var{A}' which matches the code.  I find using the lower case
| letter looks a bit silly in the code or the documentation.

I generally prefer using all lower case for code.

Using all upper case for environment variables mimics what is usually
found in the shell PATH, PAGER, EDITOR, etc.

But I also understand that it is customary to write linear algebra
expressions with uppercase for matrices.  It doesn't bother me too
much that we use upper case for one letter variables.  However, since
makeinfo will change @var{a} to A, we have to be careful to avoid
using variables that differ only by case if they will appear in the
documentation.

I would definitely prefer to avoid CamelCase except in cases which are
forced on us by compatibility concerns (unfortunately, it seems that
this is happening more frequently as time goes by).

jwe