bugGNU Octave - Bugs: bug #61824, [octave forge] (image) texinfo...

 
 

bug #61824: [octave forge] (image) texinfo help texts in classdef files

Submitter:  Hartmut <hardy>
Submitted:  Fri 14 Jan 2022 01:28:50 PM UTC
   
 
Category:  Octave Package Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Wont Fix Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * other Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Mon 17 Jan 2022 09:10:23 PM UTC, comment #7: 

Thanks @Avinoma. I think this bug report can be closed, now.

Hartmut <hardy>
Mon 17 Jan 2022 10:55:43 AM UTC, comment #6: 
Avinoam Kalma <avinoam>
Group Member
Mon 17 Jan 2022 07:18:54 AM UTC, comment #5: 

You are right, that's a pity.

What do you think about then just:

  • Add a short(er) statement to the NEWS file: In Octave versions 5 and older the installation of this image package version will issue several "doc_cache_create" warnings. Nevertheless the image package will work fine on those systems, except for not showing the "help" text of the mentioned functions.


  • Close this issue then.


I think it is better for those older Octave versions to have the new classdef functions of the new image package version including this minor problem, compared to not having them at all.

Hartmut <hardy>
Mon 17 Jan 2022 06:04:08 AM UTC, comment #4: 


Somehow the doc function does not work well with function from packages.

I have tried "doc fspecial", but did not see the documentation, though "help fspecial" is working

Avinoam Kalma <avinoam>
Group Member
Sun 16 Jan 2022 09:11:07 PM UTC, comment #3: 

@Avinoam: Since you tried my suggested change of order (seecomment #0) and it did not help, and since there does not seem to be a known workaround (see bug #43047), I would suggest the following:

  • Could you (or me, whoever finds the time earlier) please verify that "doc affine2d" works properly in older Octave versions where "help affine2d" does not work.


  • We should then just add a short sentence to the NEWS file. Something like this: In Octave versions 5 and older the installation of this image package version will issue several "doc_cache_create" warnings. Nevertheless the image package will work fine on those systems. Just use "doc" instead of "help" in order to see the help text of the affected functions.


  • We then close this issue here.



Hartmut <hardy>
Sat 15 Jan 2022 04:25:58 PM UTC, comment #2: 

I do not know the answer to @Hartmut question about changing the code structure of our classdef,
but I would like to comment that I saw the error message


"warning: doc_cache_create: unusable help text found in file 'affine2d'"


in versions 4.2.0, 4.4.0, and 5.2.0.
It was solved in 6.10.
It's related to bug #53874 and bug #43047, which were solved in 2020.

Avinoam Kalma <avinoam>
Group Member
Fri 14 Jan 2022 01:30:09 PM UTC, comment #1: 

(adding people to cc)

Hartmut <hardy>
Fri 14 Jan 2022 01:28:50 PM UTC, original submission:  

We now have the very first "real" function in the image package, that uses classdef: affine2d.m (as well as affine.m and affine3d.m)

The code structure of this file currently looks like this:


## copyright
## statement

classdef affine2d < affine

## -*- texinfo -*-
## help
## text

... (code) ...


This works fine in current Octave versions. But in older Octave versions (e.g. in Octave 4.2.2, which is still supported by the image package) this generates a warning message during package installation and it also makes the help text unusable after installation. (The function itself is still usable,though):


warning: doc_cache_create: unusable help text found in file 'affine2d"


I have observed this on a Windows installation of Octave 4.2.2., this probably also comes with a pre-bundled and older version of texinfo. But it would still be nice to have the image package install there just fine.

The above general code structure seems also to be used in core Octave's m-files that use classdef. For example weboptions.m.

Question, would it be OK to change the code structure of our classdef file to the following one:


## copyright
## statement

## -*- texinfo -*-
## help
## text

classdef affine2d < affine

... (code) ...


Or would this movement from the "classdef" code line to after the texinfo block raise any problems afterwards in older, current or future versions of Octave? I would appreciate any comments.


Hartmut <hardy>

 

(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 avinoam (Posted a comment)
  • -email is unavailable- added by hardy
  • -email is unavailable- added by hardy
  • -email is unavailable- added by hardy (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 5 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-01-18 avinoam StatusConfirmed Wont Fix
        Open/ClosedOpen Closed
    2022-01-15 avinoam StatusNone Confirmed
    2022-01-14 hardy Carbon-Copy- Added avinoam
        Carbon-Copy- Added carandraug

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code