bugGNU Octave - Bugs: bug #49526, "help slash": an easy...

 
 

bug #49526: "help slash": an easy way to discover what backslash does

Submitted by:  Colin Macdonald <cbm>
Submitted on:  Thu 03 Nov 2016 05:38:44 PM UTC  
 
Category: DocumentationSeverity: 1 - Wish
Priority: 3 - LowItem Group: Matlab Compatibility
Status: FixedAssigned to: None
Originator Name: Open/Closed: Closed
Release: devOperating System: Any

Add a New Comment(Rich Markup)
   

You are not logged in

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

 

Sun 15 Jan 2017 04:58:27 AM UTC, comment #5:

I made some small changes and pushed the changeset here (http://hg.savannah.gnu.org/hgweb/octave/rev/29c346ee7abe). Thanks for the patch, and I'm going to close this report now as fixed.

Rik <rik5>
Project Administrator
Sat 14 Jan 2017 12:38:52 AM UTC, comment #4:

Right, but then when I read "help slash", I would expect "help Broadcasting" to work, which of course it won't. So I guess my question is really "How do I reference the manual from a function's help text?".

Anyway, please commit it as-is if you are happy with it.

Colin Macdonald <cbm>
Fri 13 Jan 2017 11:27:11 PM UTC, comment #3:

The following

will create a hyperlink in the documentation when formatted as pdf. If you use 'help xxx' on the command line then the Texinfo is formatted for plain text so it will be something like "See Broadcasting", rather than a hyperlink. This is usually good enough. Do you want to amend slash.m or commit what you have as good enough?

Rik <rik5>
Project Administrator
Fri 13 Jan 2017 09:12:19 PM UTC, comment #2:

Ok, I've attached a patch (as well as my raw slash.m).

Could me merge as-is but of course I'm open to suggestions for improvement. Some thoughts:

1. I would be nice to xref from "help slash" to "doc broadcasting". How do I do that? I don't think @xref{broadcasting} would be the right thing.

2. Should I use "@DOCSTRING(slash)" to embed this in the manual, somewhere in "doc/interpreter/expr.txi"? Perhaps that could be part of a future improvement: e.g., it would be nice to have "\", "mldivide" (and the new "slash") together in one place in the manual (they are currently spread out).

(file #39468, file #39469)

Colin Macdonald <cbm>
Thu 03 Nov 2016 08:52:08 PM UTC, comment #1:

This is pretty easy to add. What is usually done is an m-file is created that has the name you want to find the help under (slash.m) and the file contains just a copyright, the help text, and a single BIST test to mark it as covered. The m-file is placed in scripts/help. For an example, look at ans.m which gives help about the built-in variable ans. The entire m-file is

If you can prepare such a file for the various slash operators then I will check it in.

The documentation that you found is in doc/interpreter/expr.txi. You could grab the part about the left division operator to begin populating the slash.m file.

Rik <rik5>
Project Administrator
Thu 03 Nov 2016 05:38:44 PM UTC, original submission:

Matlab has "help slash" which summarizes what "\", "/", ".\", and "./" do. Most important is backslash which briefly describes the algorithms used (e.g., Gaussian Elimination).

I often point people to "help slash" in my lecture notes or in a comment in a demo code. I don't know a similarly accessible bit of text in Octave. In particular, "help mldivide" doesn't say much.

We could just have "help slash" refer to "help mldivide" for details.

I did eventually find some useful text, copied below. But it wasn't obvious how to get to it from the command line (in particular, I found it by typing "doc mldivide" then scrolling up several screens.

Colin Macdonald <cbm>

 

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

Attach File(s):
   
   
Comment:
   

Attached Files
file #39468:  slash.m added by cbm (3KiB - application/vnd.wolfram.mathematica.package)

 

Depends on the following items: None found

Items that depend on this one: None found

 

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

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

    Date Changed By Updated Field Previous Value => Replaced By
    Sun 15 Jan 2017 04:58:27 AM UTCrik5StatusPatch Submitted=>Fixed
      Open/ClosedOpen=>Closed
    Fri 13 Jan 2017 11:27:11 PM UTCrik5StatusConfirmed=>Patch Submitted
    Fri 13 Jan 2017 09:12:19 PM UTCcbmAttached File-=>Added slash.m, #39468
      Attached File-=>Added add_help_slash_documentation.patch, #39469
    Thu 03 Nov 2016 08:52:08 PM UTCrik5Severity3 - Normal=>1 - Wish
      Priority5 - Normal=>3 - Low
      StatusNone=>Confirmed
      Summary"help slash": an easy way to discouver what backslash does=>"help slash": an easy way to discover what backslash does

    Back to the top


    Powered by Savane 3.1-cleanup1