bugGNU Octave - Bugs: bug #52774, help for continuation marker has...

 
 

bug #52774: help for continuation marker has strange extraneous statement

Submitter:  Dan Sebald <sebald>
Submitted:  Mon 01 Jan 2018 04:05:20 AM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Thu 04 Jan 2018 06:33:23 AM UTC, comment #3: 

@Dan: I pushed your cset unmodified on to the development branch here (http://hg.savannah.gnu.org/hgweb/octave/rev/dc25a0dc7800).

I modified help.m not to print out the directory for help on '...' in this cset (http://hg.savannah.gnu.org/hgweb/octave/rev/85ace8208635).

I added an explanation of '\' as a string continuation marker in this cset (http://hg.savannah.gnu.org/hgweb/octave/rev/d8ed90ecd4fd).

Marking as fixed and closing report.

p.s. There are so many graphic properties that, if possible, it would be better to put them in their own index entirely.  You could open up another bug report about how to improve things there if you want.

Rik <rik5>
Group administrator
Tue 02 Jan 2018 10:32:58 AM UTC, comment #2: 

Ah, OK:


octave:14> x = "Continuing ...
warning: '...' continuations in double-quoted character strings are obsolete and will not be allowed in a future version of Octave; please use '\' instead
> here"
x = Continuing here


Thanks.  I suppose it is worthwhile adding a short note to the "help \" for this, i.e., "Also continuation marker in double-quote strings".  However, there's an ongoing discussion of potential new double-quote string feature/behavior, so it might be wise to hold off adding such a thing because in not too long of time such a statement might just be cruft that I and other forget about.

On the other hand, I think it is alright to simply put a reference in the manual so that the Operator Index has an extra page number associated with \ continuation marker.  In fact, all I needed to do was change @cindex to @opindex.  And if the \ continuation marker is deprecated, the index reference will go away when removing the associated paragraph from the manual.

I'm attaching a changeset that cleans up several items in the octave.pdf manual.  I made liberal use of the Texinfo command @sortas to move all the messy symbol entries at the start of Concept Index to other places that would be logical starts for a reader, e.g., both .octaverc and ~/.octaverc now go under "octaverc" but have the same appearance so it is clear what they refer to.  I also added a copy more page numbers to those entries directing to the command-line switches that disable loading them at startup.

All of the command-line options -W, --eval, etc. have been moved to "options, Octave command".  They look nice there and have context rather than loosely sitting at the start of the Concept Index.  The -W and --eval index entries were missing.  There was an extraneous -? entry for an apparently deprecated equivalent to --help and -h that I removed.

The source of those three strange functions at the start of Function Index was a broken @deftypefnx format in xticks.m and xticklabels.m that was missing the {} for cases where the function doesn't return an output.  I also fixed the other similar script files, but they aren't input to the user manual...maybe they are used for generating the online-help though.

With that, it looks pretty nice.  I wonder about the graphics properties entries that are automatically generated.  There is a big list of them, and it actually isn't too difficult to look through the way they are.  But because of they are organized by "figure", "image", etc. the property groups are strewn through the Concept Index.  We could consider organizing all of those properties into their own index.  Or maybe put them all under "properties" using @sortas creatively inside genpropdoc.m.

(file #42787)

Dan Sebald <sebald>
Tue 02 Jan 2018 01:37:09 AM UTC, comment #1: 

About "help \", maybe it is because using continuation marker \ outside of double quoted strings is deprecated and will be removed from a future version of Octave, and Octave suggests us to use ... instead of \

Anonymous
Mon 01 Jan 2018 04:05:20 AM UTC, original submission:  

In https://savannah.gnu.org/bugs/?52772 I noted the ... and \ continuation "operators" in the PDF user manual.  In the online help there are also some issues.  The ... has an extraneous bit about the director "/home" in it.  I.e.,


octave:5> help("...")
'...' is the directory /home

 -- ...
     Continuation marker.

     Joins current line with following line.


I launched octave from two levels deep in the above example so it is apparently going back two levels.  The main issue is the directory printout.  I think this is another example of the similar issue with "help ./" solved here

https://savannah.gnu.org/bugs/?func=detailitem&item_id=50034#comment8


The secondary issue is simply that "help \" doesn't mention the possible use as a continuation marker, just the division operator:


octave:6> help('\')

 -- \
     Left division operator.

     See also: .\, /, ldivide, mldivide.


Dan Sebald <sebald>

 

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

Attach Files:
   
   
Comment:
   

Attached Files

 

Depends on the following items: None found

Digest:
   bug dependencies.

 

Carbon-Copy List
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by sebald (Submitted the item)
  •  

    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 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2018-01-04 rik5 StatusNone Fixed
        Open/ClosedOpen Closed
    2018-01-03 siko1056 Dependencies- bugs #52772 is dependent
    2018-01-02 sebald Attached File- Added octave-manual_texinfo_cleanup-djs2018jan01.patch, #42787

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code