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

 
 

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

Submitter:  Colin Macdonald <cbm>
Submitted:  Thu 03 Nov 2016 05:38:44 PM UTC
   
 
Category:  Documentation Severity:  1 - Wish
Priority:  3 - Low Item Group:  Matlab Compatibility
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
   

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


@xref{Broadcasting}


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


## Copyright (C) 2006-2016 John W. Eaton
##
## This file is part of Octave.
##
## Octave is free software; you can redistribute it and/or modify it
## under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 3 of the License, or (at
## your option) any later version.
##
## Octave is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with Octave; see the file COPYING.  If not, see
## <http://www.gnu.org/licenses/>.

## -*- texinfo -*-
## @defvr {Automatic Variable} ans
## The most recently computed result that was not explicitly assigned to a
## variable.
##
## For example, after the expression
##
## @example
## 3^2 + 4^2
## @end example
##
## @noindent
## is evaluated, the value returned by @code{ans} is 25.
## @end defvr


## Mark file as being tested.  No real test needed for a documentation .m file
%!assert (1)


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



8.3 Arithmetic Operators
========================

----8<----

X \ Y
     Left division.  This is conceptually equivalent to the expression

          inverse (x) * y

     but it is computed without forming the inverse of X.

     If the system is not square, or if the coefficient matrix is
     singular, a minimum norm solution is computed.


Colin Macdonald <cbm>

 

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

Attach Files:
   
   
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
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by cbm (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 9 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2017-01-15 rik5 StatusPatch Submitted Fixed
        Open/ClosedOpen Closed
    2017-01-13 rik5 StatusConfirmed Patch Submitted
    2017-01-13 cbm Attached File- Added slash.m, #39468
        Attached File- Added add_help_slash_documentation.patch, #39469
    2016-11-03 rik5 Severity3 - Normal 1 - Wish
        Priority5 - Normal 3 - Low
        StatusNone Confirmed
        Summary&quot;help slash&quot;: 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.13-02a9.
    Corresponding source code