Capitalization rules for docstring variables

[Rik]

1/9/11

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.

--Rik

rank_example1.jpg
Description: JPEG image

rank_example2.jpg
Description: JPEG image