[Octave-bug-tracker] [bug #34661] Confusing documentation for transpose operator: `x.''

[Rik]

Follow-up Comment #6, bug #34661 (project octave):

>>Do you agree this is better?

I'm not sure.  I think JWE was hoping for a comprehensive solution (although I
don't know how to implement that).  My solution would sprinkle @tex/@ifnottex
around the offending constructs and yours would sprinkle @verb.  In that sense
they are equivalent in impact.  Your solution has the benefit of being easier
to type so that probably wins out.  So, I'm fine with using @verb{} everywhere
there is a transpose symbol.  

For the particular instance of the operators, however, I dislike the phrasing
that gets constructed.  The current docstring for minus (x,y) is "This
function is equivalent to the expression x - y."  I know you wanted to reverse
it and write "This function is equivalent to the x - y expression." but this
feels odd to me in English.  This is a subtle, wording issue, and other may
not feel as strongly.  If that is the case then we can just go with it.

One idea would be to reverse the sentence completely and write "x - y is the
operator equivalent for this function".  This avoids having the operator
expression at the end where the period of the sentence boundary could possibly
be interpreted as belonging to the operator expression.

    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?34661>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/