bugGNU Octave - Bugs: bug #34661, Confusing documentation for...

 
 

bug #34661: Confusing documentation for transpose operator: `x.''

Submitter:  Clem <clemwang>
Submitted:  Wed 26 Oct 2011 09:15:09 PM UTC
   
 
Category:  None Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  jordigh
Originator Name:  Clem Open/Closed:  * Closed
Release:  * 3.4.3 Operating System:  * Mac OS
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Tue 01 Nov 2011 06:23:16 PM UTC, comment #14: 

JWE, thanks for the hint on the macro.

I have coded a new @xcode macro to be used where the transpose operator ends an @code block; I've updated the documentation cache scripts to process the new macro; The docstrings for functions with operator equivalents have been rewritten based on Jordi's phrasing; The remaining instances of transpose operators ending code blocks have been marked with the new @xcode macro.

The changeset is here (http://hg.savannah.gnu.org/hgweb/octave/rev/990762e784fe).  The bug reporter will need to build from source or wait until the 3.6 release of Octave scheduled for December 2011 to see the fix.

Rik <rik5>
Group administrator
Tue 01 Nov 2011 05:05:29 PM UTC, comment #13: 

You can avoid the spacing problem by placing the conditionals around the macro definition instead of placing them inside the macro definition:


@ifinfo
@macro xcode {arg}
\arg\
@end macro
@end ifinfo
@ifnotinfo
@macro xcode {arg}
@code{\arg\}
@end macro
@end ifnotinfo


instead of placing them inside the macro definition.

John W. Eaton <jwe>
Group administrator
Mon 31 Oct 2011 09:13:18 PM UTC, comment #12: 


>>Is there a reason to not have @xcode{} simply expand to @code in all formats except Info?


I don't think so, which is why I prefer the @tex/@ifnottex construction over @verb because it uses the @code macro where it can.  I suppose it would be even better to use @ifinfo/@ifnotinfo since that is more specific.

The bolding is not true bolding, but rather the effect of @code in the pdf output for my machine.  The glyphs of the fixed width font chosen by @code have heavier serifs and make the code segment seem slightly bold with respect to the thinner serifs of ordinary text.

Here is my stab at the required macro.  It is almost right, however the expansion always adds a space after the end of the macro in the Info output.  This means to use it the word following the macro has to abut the closing curly brace.  It looks a little weird and it doesn't allow for having @xcode at the end of the sentence because a space would be inserted before the period.  If someone is handier with Texinfo maybe they can figure out how to do better.


@c The following macro works around a situation where the Info/plain text
@c expansion of the @code{XXX} macro is `XXX'.  The use of the apostrophe
@c can be confusing if the code segment itself ends with a transpose operator.
@macro xcode {arg}
@ifinfo
\arg\
@end ifinfo
@ifnotinfo
@code{\arg\}
@end ifnotinfo
@end macro


Sample usage:


code 1 is @xcode{XXX}and code 2 is @xcode{YYY}


Rik <rik5>
Group administrator
Mon 31 Oct 2011 05:59:09 PM UTC, comment #11: 

Is there a reason to not have @xcode{} simply expand to @code in all formats except Info?  PDF, DVI, and HTML output should already be using a typewriter font for @code.  I don't see why we should use a bold font for some code snippets but not others.  As far as I know, then only problem is with the use of `' to quote @code (and @samp, I think) bits in Info output.

John W. Eaton <jwe>
Group administrator
Mon 31 Oct 2011 05:18:35 PM UTC, comment #10: 

Summarizing the discussion:

1) Add @xcode macro to the beginning of octave.texi
     Macro can expand to either @iftex/@ifnottex or @verb.  The
     primary disadvantage of the former, its length and clutter,
     is removed by using the @xcode macro.  It's primary advantage
     is using a bold font to mark the code in pdf documentation
     which @verb does not do.

2) Rephrase documentation for functions which mimic operators to:
   "This function and @xcode{...} are equivalent."

3) Replace remaining 9 occurrences of @code which end in transpose
   operator with @xcode{}

Rik <rik5>
Group administrator
Fri 28 Oct 2011 07:01:39 PM UTC, comment #9: 

Jordi, yes, this is better.

But could we still use a macro so we can use markup like @xcode instead of @verb?

John W. Eaton <jwe>
Group administrator
Fri 28 Oct 2011 06:25:21 PM UTC, comment #8: 

How about phrasing it "this function and @verb{_x.'_} are equivalent."? The @verb thing is pretty concise, works as intended in HTML, PDF, and plain text, is short, and there is no awkward mathematical English syntax (which as you know does exist, e.g. "the Green's function").

Jordi Gutiérrez Hermoso <jordigh>
Group Member
Fri 28 Oct 2011 05:46:12 PM UTC, comment #7: 

I don't think there are any ASCII quoting characters that would be good and have any less potential for confusion since most are used in the Octave language in some way.

@verb would be OK visually, but that removes the @code info from the source.  I prefer the idea of logical markup over visual if possible.

However you want to fix this, I think it might be best to define a Texinfo macro in octave.texi so we can use something like @xcode{} in the sources.  Then we can decide whether that should always use @verb or some @if construct.

Rik, the fix would be in makeinfo, not texinfo.tex.  TeX already does something reasonable by using a typewriter font.  It's only the Info output that has trouble since it only outputs ASCII and can't give visual clues using fonts.

I don't much like the idea of rewording things.  Saying "x-y expression" also seems awkward to me.

How much effort do you want to put into solving this minor problem?  We have real bugs to fix.

Also, I expect that eventually we won't care much about what the plain text output looks like as we will probably be displaying help text in some better way that will allow font differences to be used to give visual cues about things like @code.

John W. Eaton <jwe>
Group administrator
Fri 28 Oct 2011 05:26:47 PM UTC, comment #6: 


>>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.

Rik <rik5>
Group administrator
Fri 28 Oct 2011 05:34:29 AM UTC, comment #5: 

I think this is the wrong fix. I prepared a changeset (attached) that uses @verb instead and rewrites a few sentences so that the @verb'ed phrases aren't at the end of a sentence. Do you agree this is better?

(file #24225)

Jordi Gutiérrez Hermoso <jordigh>
Group Member
Thu 27 Oct 2011 05:44:03 PM UTC, comment #4: 

JWE, you may be able to re-define the @code{} macro somewhere in texinfo.tex in the directory above doc/interpreter.  However, I see this as a specific problem with the transpose operator and not a general problem of getting @code to change its ways based on what is inside the macro.

For reference, there are 9 occurrences of a transpose operator at the end of an @code{} macro.  I'm lazy and would just change these occurrences rather than fighting with Texinfo.  My 2 cents.


expr.texi:640:@code{x'}.
expr.texi:783:@code{x.'}.
linalg.texi:826:then a factorization of @code{@var{A}+@var{x}*@var{y}.'} can be obtained
linalg.texi:1262:@code{@var{UR} * @var{TR} * @var{UR}' = @var{U} * @var{T} * @var{U}'} and
linalg.texi:1431:such that @code{a*u == u*h+rk*ek'}, in which @code{rk =
linalg.texi:1432:a*u(:,k)-u*h(:,k)}, and @code{ek'} is the vector
sparse.texi:709:@code{@var{A}+@var{A}'} if @var{A} in not symmetric.  The optional
sparse.texi:1762:Factorize @code{@var{S} * @var{S}'}.
sparse.texi:1765:Factorize @code{@var{S}'}


Rik <rik5>
Group administrator
Thu 27 Oct 2011 05:07:23 PM UTC, comment #3: 

Rik, that fixes the problem in only one spot.  I'm sure there are many others.  I'd rather not splatter conditionals all throughout the documentation, but instead somehow fix @code to do something better for our purposes when generating Info output.

John W. Eaton <jwe>
Group administrator
Thu 27 Oct 2011 05:02:32 PM UTC, comment #2: 

Jordi,

I just checked in a change (http://hg.savannah.gnu.org/hgweb/octave/rev/1d97688f8522) that applies the Texinfo @code{} markup only when the output is Tex (such as PDF).  For text output there is no markup (no `...').  You can do more if you like or consider this resolved and close the bug.

Rik <rik5>
Group administrator
Thu 27 Oct 2011 04:50:50 AM UTC, comment #1: 

Yeah, it's a problem with how texinfo generates plain text documents. I'm looking into another way to render this that looks good both in plain text, pdf, and HTML.

Thanks for reporting.

Jordi Gutiérrez Hermoso <jordigh>
Group Member
Wed 26 Oct 2011 09:15:09 PM UTC, original submission:  

Fortunately, I already know what the transpose function does, but if I didn't, the Octave help for the transpose() function would be confusing.  You should not use quotes to quote an expression that uses quotes   Similarly, the use of a period as end-of-sentence indicator near a dot symbol is a bad idea:



help transpose
`transpose' is a built-in function

 -- Built-in Function:  transpose (X)
     Return the transpose of X.  This function is equivalent to `x.''.

     See also: ctranspose


I know that
   transpose(x)
is equivalent to:
   x.'

A person new to Octave and Linear Algebra could misunderstand that line to say transpose(x) is:

`x.''.

or even:

`x.".
(double quote instead of two single quotes).




I suspect that this has ramifications to the style used in the Octave help.  Another confusing use of quotes and periods is with help times

This function is equivalent to `x .* y'.



I think examples would be nice too.

Clem <clemwang>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #24225:  docstrings.patch added by jordigh (8KiB - text/x-diff)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by jwe (Posted a comment)
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by jordigh (Posted a comment)
  • -email is unavailable- added by clemwang (Submitted the item)
  • -email is unavailable- added by clemwang (Confusing: equivalent to `x.''.)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 8 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2011-11-01 rik5 StatusConfirmed Fixed
        Open/ClosedOpen Closed
    2011-10-28 jordigh Attached File- Added docstrings.patch, #24225
    2011-10-27 rik5 SummaryConfusing: equivalent to `x.\'\'. Confusing documentation for transpose operator: `x.''
    2011-10-27 jordigh StatusNone Confirmed
        Assigned toNone jordigh
        Release3.4.0 3.4.3
    2011-10-26 clemwang Carbon-Copy- Added clemwang

    Back to the top

    Powered by Savane 3.13-cf05.
    Corresponding source code