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.
|
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.
|
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:
|
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.
|
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{}
|
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?
|
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").
|
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.
|
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.
|
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)
|
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.
|
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.
|
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.
|
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.
|
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.
|