More uniform standard for naming of scalars, vectors, and matrices in documentation and code?

maintainers
#1

I’m considering a project to make the documentation more uniform by using standard names and case for scalars, vectors, and matrices. My proposal, similar to what Matlab does, is that matrices are uppercase and begin with A, B, … We mostly do this for the linear algebra core functions, but not everywhere.

Scalars and vectors would be lowercase and generally chosen from the set of x, y, z, t, w.

This would also involve renaming variables in m-files so the that the code matched the documentation.

Pros:

  • Matches many linear algebra textbook conventions
  • Uniform documentation would make it easy to understand new functions
  • One could tell at a glance whether a matrix or scalar was desired input

Cons:

  • Work required to convert core functions

Any opinions on whether this is a good idea to pursue?

#2

I like this idea and think this is a good first step towards a more comprehensible manual. When going through all functions, I also would like to add more comprehensible usage examples for each function. This involves changing a documentation practice, replacing the ill-formatted @result{} construct, which is in both senses annoying:

  1. It looks different in different output formats bug #59564.
  2. Unreadable doc source code (need to count spaces to get it right).
## @example
## @group
## fliplr ([1, 2; 3, 4])
##      @result{}  2  1
##          4  3
## @end group
## @end example

vs.

## @example
## @group
## fliplr ([1, 2; ...
##          3, 4])
## @end group
## @end example
## @indentedblock
## @verbatim
## ans =
##
##    2   1
##    4   3
## @end verbatim
## @end indentedblock

The second part looks longer, but this is due to Texinfo. At least the output can simply be copied from the interpreter output, also the HTML output, which I assume to be the most used one (online and in the doc widget), looks far more comprehensible to me :slightly_smiling_face:

HTML

image
image708×472 21.5 KB

PDF

image
image909×519 41.9 KB

INFO

image
image801×422 24.6 KB

#3

One thing to consider here is that Texinfo is the GNU standard for documentation and it seems to recommend using this style. In fact, it offers several glyphs for making the documentation “clearer” including @result, @expansion (for variable or macro expansion), @print (for printed result), @error (for error messages), and @equiv (for equivalence). We don’t have to use these, but let me suggest that one option would be to have @result{} appear alone on a line. Then there would be very little issue with spacing in Texinfo nor with the fact that the glyph might be expanded to one or two characters depending on output format.

Using your example,

## fliplr ([1, 2; 3, 4])
##      @result{}
##          2  1
##          4  3

becomes

      fliplr ([1, 2; 3, 4])
           =>
               2  1
               4  3

That’s one possible resolution. But, I do think that new users would be better off seeing exactly what the interpreter produces. Some of them will cut and paste example code and run it, for example. They might think something is wrong with their version of Octave if it doesn’t produce exactly what is in the documentation. As an example of that change,

## @example
## @group
## fliplr ([1, 2; 3, 4])
## ans =
## 
##    2   1
##    4   3
## @end group
## @end example

produces

          fliplr ([1, 2; 3, 4])
          ans =

             2   1
             4   3

which looks pretty good to me. It also doesn’t require the @indentblock or @verbatim tags.

Eliminating the @result macro from the documentation would be an even bigger project than just renaming some of the variables. Let’s see if there are some more comments on this proposal before adopting it.

#4

Agree, maybe we leave this out of the scope for the start. Too ambitious projects are most likely to fail :sweat:

Do you have an agenda for the start or just let’s get hands dirty and track our progress here :wink:

#5

I thought I’d wait a few more days to see if there are any other comments. After that, I would work on one subdirectory at a time in the scripts/ directory. That makes a convenient unit, and if there are other volunteers we can spread the work out easily by handing off a subdirectory like “elfun” or “geometry” to whomever comes along.

#6

For example, please remember the Doctest package makes use of texinfo semantics like the @result tag. Would be nice to consult or run doctest to make sure doc changes still allow tests to pass.

#7

Besides scalars, vectors, and matrices, I’d like to consider using fcn for functions. Or maybe we should be even more explicit and write hfcn for function handles? Right now the documentation is mixed in usage and sometimes uses f, fun, func all to refer to a function.

#8

I like hfcn to indicate a function handle as opposed to, e.g., a function name.

#9

Yes, this would distinguish between a matrix or scalar but would confuse a scalar and a vector. Because a vector is also a matrix, I would prefer using capital letters for vectors. A simple convention could distinguish between a vector and a multi-dimentional matrix: A, B, … for matrices and I, J, … for vectors.

#10

An issue with this is that I, and J are the complex constants in Octave. In some cases it might be clear from the context that a complex number is intended, such as 3 + 5*I, but in others, such as A*I + J, it can be confusing to decide whether this is a matrix/vector equation or an attempt to make A a complex number and add one to it.

#11

Okay, so better yet, use X, Y, Z for vectors, x, y, z for scalars. I really don’t care what letter. My point is that a vector is not a scalar; it is a one-dimensional matrix, and if there are only two choices (upper vs lower case), then a vector should look like a matrix, not a scalar.

Fine, I’ll get off my soapbox now. You are now $0.02 richer. :laughing:

#12

In my scripts, I often use a double capital for matrices with dim 2+ and single a capital for vectors, e.g AA*B = C.

#13

One problem is that we don’t have a choice between upper and lower case for documentation in text format. The underlying documentation system is GNU Texinfo. A variable is marked with the macro @var{variable_name}. There are processors that read raw documentation with Texinfo markup and then produce various outputs including text, HTML, and PDF. The processor for text interprets the @var macro as capitalization so @var{x} or @var{X} are both rendered as X.

This leaves using name choices as a way of distinguishing between matrices, vectors, and scalars. That name choice could be restrictions in range (for example, matrices are in the range A-C, vectors in the range X-Z, scalars in the range ???), or they could be a naming convention such as @Pantxo suggested where matrices use a doubled letter and vectors use a single letter, or we could have a naming convention with a ‘m’ suffix for matrices and ‘v’ suffix’ for vectors. There are probably some other choices that are worth considering.

#14

Why not use some color convention lets say -
white(or grayish in white background) : scalar
violet :vector
green : matrix
also it would be good feature if implemented in octave cli

#15

This might be a possibility for the GUI. Unfortunately, the terminal in which the CLI runs might or might not support this feature. In general, the conservative design approach is not to assume that the terminal supports color. For example, on UNIX the ls command is one of the very few that supports and does something reasonable with colors. But, even there the colors are turned off by default and have to be explicitly enabled with a command-line option because so few terminals support it.

One possible idea that can be taken from this is that in the GUI, the output format for help might be changed to HTML. The terminal widget for Octave is going to be re-designed for the 7.0.0 release so if we changed it to be HTML then colors and better formatting would come naturally.

However, for the CLI I still believe we are saddled with naming conventions as the only way for distinguishing scalars, vectors, and matrices.

#16

Unfortunately the Discourse system did not allow me to send a private response to an e-mail from @dblake so I’ll just answer it here.

In the OP, you suggest making a distinction between matrices and scalars and vectors by using upper case for the first and lower case latter two. Now, in your last post, you say that “we don’t have a choice between upper and lower case” because either " @var{x} or @var{X} are both rendered as X .

Then you go on to say that “we could have a naming convention with a ‘m’ suffix for matrices and ‘v’ suffix for vectors.” How is it that we can now use lower case letters?

So which is it? Can we use lower case variables or not?

Sorry, that was me typing quickly. All variables will be transformed to upper case by the @var macro so the suffixes would render as ‘M’ and ‘V’ in plaintext format. In HTML and PDF format the case is preserved, so those formats can benefit from a naming convention that uses case. However, a really common usage is that you are trying to use a new-to-you Octave function. You try calling it and it throws an error. The next thing you do is type help function_name rather than looking for the PDF manual which is somewhere in /usr/share/doc. And this brings up the plaintext version of the documentation which enforces uppercase.

#17

Now that we are in the 2020s instead of the 1980s, we could fix the help function to display nicely typeset help in the GUI help window (or even directly in the terminal window) and only display the old-style Info output if actually running Octave in a plain-text terminal window.

I’m not sure about what to do to distinguish between matrix, vector, and scalar symbols. In linear algebra textbooks, uppercase usually indicates a matrix with lowercase indicating either a vector or scalar, depending on context. I would expect to see things like

Ax = b
det (A - \lambda I)

etc. rather than

AA X = B
det (AA - \lambda II)

#18

I also grew accustomed to read single uppercase letters as matrices in nicely formatted text (like in the pdf manual). Without further context, it would be surprising if they meant vectors instead.
I sometimes saw little arrows on top of lower case letters to indicate that they are used for vectors. But I guess that is not an option for the terminal window or for a context where they are actual variables in code (which IIUC is what we are talking about)

I kind of like Rik’s original proposal. I don’t think that there are many places where a vector or a scalar could be confused. If there are, it would probably be straight-forward to point that out in the docstring.
But maybe sometimes, longer variable names might be more informative to get the gist of it already by reading the function definition. Those might be as short as x0 or y0 to indicate that these are starting values, or alpha or phi to indicate that these are angles, …
Also, I wouldn’t mind if we kept something like sin (x). Reading this is more familiar than e.g. sin (A) even if the argument to the sine function might be a matrix. (Maybe the criterium is that this is not a “real” matrix function but applies to each element individually?)

#19

I like this as well and wasn’t going to change it. When it is an element-by-element function Matlab also seems to agree and writes Y = sin(X). Most algebra (not linear algebra) uses x for the input and y for the output so the equation of a line is y = m*x + b. I think we should keep that convention.

#20

The GUI already has the ability to display HTML which looks better. If you type doc function_name it opens the HTML version of the documentation in an embedded reader. The capitalization suggestions I made at the start would show through in this format. So, we’re not that far off from some sort of solution. But, getting this to work in the Command Window, or in the CLI terminal, is going to be more work. Before taking that on task it would be useful to determine if this is indeed a priority for the 7.0 release. There’s already a Discourse thread on what those goals should be here: Goals for the next release.