Document Binary and Prefix separately from operatorAttributes

[d-torrance]

They also exist as names of optional arguments to method and findProgram, respectively, but this wasn't evident in the html documentation.

[mahrud]

I don't follow the reasoning. Can't you document [method, Binary], [findProgram, Prefix], etc?

[d-torrance]

Right now, this is what we get running help on one of these things:

i1 : help Binary

o1 = Binary -- a hashtable with information about Macaulay2 operators
     ****************************************************************

     Synopsis
     ========

       * Usage: 
             operatorAttributes
       * Outputs:
           * an experimental hash table that give information about "operators"
             in the Macaulay2 language

     Description
     ===========

     Meanings of the symbols used:
       * "Flexible" -- user defined methods may be installed
       * "Binary" -- it's a binary operator
       * "Prefix" -- it's a prefix unary operator
       * "Postfix" -- it's a postfix unary operator
     We intend to add parsing precedences to this table and eliminate
     "seeParsing".

     Functions with optional argument named Binary :
     ===============================================

       * "method(...,Binary=>...)" -- see "method" -- make a new method function

     For the programmer
     ==================

     The object "Binary" is a "symbol".

It at least mentions the relationship to method towards the end, but it's confusing seeing the operatorAttributes stuff if you're just looking for method info.

It's worse when you try to view the html documentation -- viewHelp Binary pulls up the operatorAttributes page, with no mention of of method, and the Binary link just sends us right back to operatorAttributes.

[method, Binary] and [findProgram, Prefix] are already documented and send you to the right place, but I don't know how well-known that syntax is for most users. Plus I think it will help for discoverability when clicking around the html documentation. For example, with a couple clicks, we'll be able to get from method to operatorAttributes since they share Binary.

[mahrud]

Wouldn't a better solution be to just remove the documentation for Flexible, Binary, Prefix, Postfix and let the code in Macaulay2Doc/options.m2 autogenerate a page for it? I don't understand the point of adding a separate documentation for Binary and Prefix.

[d-torrance]

I thought about, too. The problem is that since operatorAttributes isn't a function or method, the code in Macaulay2Doc/options.m2 doesn't find Flexible or Postfix at all, and the default documentation it generates for Binary and Prefix doesn't mention operatorAttributes.

I suppose we could do something more general, and instead of just looking for symbols as optional arguments, look for them in other places as well. But this particular case seemed a little out of the ordinary -- they're the keys of the values of some hash table.

[mahrud]

I guess I'd rather see them listed under "symbols used as the name or value of an optional argument", and they currently are not.

Is it really necessary that the documentation for "Binary" list "operatorAttributes"? I feel like the other way (operatorAttributes mentioning Binary) is how people would find this.

[d-torrance]

That makes sense -- I'm fine with letting the options.m2 code generate default documentation for Binary and Prefix that doesn't mention operatorAttributes.

[mahrud]

I (not strongly) feel like while we're at it Flexible and Postfix should also move, no? The handling of immutable symbols could be improved a lot I think.

[d-torrance]

The options.m2 code won't pick them up since they're not optional arguments of any functions. Are you suggesting manually documenting them?

[mahrud]

They can be added manually: https://github.com/Macaulay2/M2/blob/ec9e9ac60ed4a8e791448942202f077a88a87e15/M2/Macaulay2/packages/Macaulay2Doc/options.m2#L19

Or we can add a similar code to generate automatic documentation for undocumented immutable symbols. In general, unless they're 100% tied to one particular purpose, I think I'm in favor of symbols having generic documentation.

[d-torrance]

That sounds good to me. I'll open a new PR in a moment.