bugGNU Octave - Bugs: bug #59552, "help" does not display...

 
 

bug #59552: "help" does not display Contents.m file in @class or +namespace folders in the load path

Submitter:  Tasos Papastylianou <tpapastylianou>
Submitted:  Thu 26 Nov 2020 07:44:31 PM UTC
   
 
Category:  Interpreter Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Matlab Compatibility
Status:  Confirmed Assigned to:  None
Originator Name:  Open/Closed:  * Open
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Fri 27 Nov 2020 11:38:40 AM UTC, comment #2: 

Just to clarify, regarding Contents.m working for 'normal' folders my understanding was that if the folder was 'accessible' but not added 'itself 'to the path  (i.e. similar to how @ and + folders work), then help would find its contents.

However, I just checked with matlab, and this is not true for matlab either, it only works if you explicitly add the normal folder to the path.

The rest applies for @ and + folders though.
One extra point to note, if a class has a constructor of the same name, matlab shows the documentation for the constructor and seems to ignore the contents file.

Therefore the main missing functionality here is for + folders.

Also, there is no documentation anywhere in the octave project for this functionality, it may be useful to add this in the docs somewhere. (I think this is also the case for +folders in fact).

Tasos Papastylianou <tpapastylianou>
Fri 27 Nov 2020 10:06:29 AM UTC, comment #1: 

I tried with a Contents.m file in a "normal" folder in the load path and this seems to work as expected with 5.2.0 and 6.0.92:

>> addpath D:\SVN\Octave\bug59552_Contents
>> help bug59552_Contents
D:\SVN\Octave\bug59552_Contents\Contents.m:

 This is some text.


Additional help for built-in functions and operators is
available in the online version of the manual.  Use the command
'doc <topic>' to search the manual index.

Help and information about Octave is also available on the WWW
at https://www.octave.org and via the help@octave.org
mailing list.


I tried the same with a Contents.m file in a +namespace or @class folder, and the same does not work. It does work if I pass these folders with their full path to "help".
To check if this is a regression, I tried with 6.0.92, 5.2.0, 4.4.1 and 4.2.2 (those are the versions that are available to me atm), and it worked for none of them.
If this ever worked, it is broken for quite some time.

Fwiw, in Matlab R2020b where I placed a Contents.m file with different content in each of these folders:

>> dir D:\SVN\Octave\bug59552_Contents

+namespace1    .              ..             @class1        Contents.m     normal_folder

>> addpath D:\SVN\Octave\bug59552_Contents
>> help class1
class1 methods:

Contents - This is some text in a class folder.

>> help namespace1
  This is some text in a namespace folder.

>> help normal_folder

normal_folder not found.

Use the Help browser search field to search the documentation, or
type "help help" for help command options, such as help for methods.

>> help bug59552_Contents
  This is some text.


Markus Mützel <mmuetzel>
Group administrator
Thu 26 Nov 2020 07:44:31 PM UTC, original submission:  

It used to be that Octave supported Contents.m file functionality, similar to matlab (https://uk.mathworks.com/help/matlab/matlab_prog/create-a-help-summary-contents-m.html) such that if one called the help function for a folder name, this would display the contents of the Contents.m file contained within as the official documentation for the folder.

This was also the case for @class folders, as well as for +namespace folders (without the @ or + characters, as far as I'm aware?)

This functionality was definitely present in the past, I've used it myself, and there's evidence in the bug tracker too, e.g. see #40342 . I also note there are many official octave packages that make use of such a Contents.m file (e.g. matgeom).

Was this functionality removed at some point? Or is this a regression bug?


(For some background context on what triggered this bug report: https://stackoverflow.com/questions/65019819/how-do-i-make-octave-suggest-the-methods-of-my-class-when-i-hit-tab-and-show-the )

Tasos Papastylianou <tpapastylianou>

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by mmuetzel (Posted a comment)
  • -email is unavailable- added by tpapastylianou (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
    2020-11-27 mmuetzel Item GroupRegression Matlab Compatibility
        StatusNone Confirmed
        Release5.2.0 dev
        SummaryContents.m files no longer work. "help" does not display Contents.m file in @class or +namespace folders in the load path

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code