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

 
 

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

Submitted by:  Clem <clemwang>
Submitted on:  Wed 26 Oct 2011 09:15:09 PM UTC  
 
Category: NoneSeverity: 3 - Normal
Priority: 5 - NormalItem Group: Documentation
Status: FixedAssigned to: Jordi Gutiérrez Hermoso <jordigh>
Originator Name: ClemOpen/Closed: Closed
Release: 3.4.3Operating System: Mac OS

Add a New Comment(Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

(Jump to the original submission 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>
Project 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:

instead of placing them inside the macro definition.

John W. Eaton <jwe>
Project 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.

Sample usage:

Rik <rik5>
Project 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>
Project 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>
Project 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>
Project 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>
Project AdministratorIn charge of this item.
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>
Project 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>
Project 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>
Project AdministratorIn charge of this item.
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.

Rik <rik5>
Project 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>
Project 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>
Project 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>
Project AdministratorIn charge of this item.
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:

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 File(s):
   
   
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
  • -unavailable- added by jwe (Posted a comment)
  • -unavailable- added by rik5 (Posted a comment)
  • -unavailable- added by jordigh (Posted a comment)
  • -unavailable- added by clemwang (Submitted the item)
  • -unavailable- added by clemwang (Confusing: equivalent to `x.''.)
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only project members can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    Follow 8 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Tue 01 Nov 2011 06:23:16 PM UTCrik5StatusConfirmed=>Fixed
      Open/ClosedOpen=>Closed
    Fri 28 Oct 2011 05:34:29 AM UTCjordighAttached File-=>Added docstrings.patch, #24225
    Thu 27 Oct 2011 05:02:32 PM UTCrik5SummaryConfusing: equivalent to `x.\'\'.=>Confusing documentation for transpose operator: `x.''
    Thu 27 Oct 2011 04:50:50 AM UTCjordighStatusNone=>Confirmed
      Assigned toNone=>jordigh
      Release3.4.0=>3.4.3
    Wed 26 Oct 2011 09:15:09 PM UTCclemwangCarbon-Copy-=>Added clemwang

    Back to the top


    Powered by Savane 3.1-cleanup1