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

[Hartmut]

URL:
  <https://savannah.gnu.org/bugs/?61824>

                 Summary: [octave forge] (image) texinfo help texts in
classdef files
                 Project: GNU Octave
            Submitted by: hardy
            Submitted on: Fri 14 Jan 2022 01:28:50 PM UTC
                Category: Octave Forge Package
                Severity: 3 - Normal
                Priority: 5 - Normal
              Item Group: Documentation
                  Status: None
             Assigned to: None
         Originator Name: 
        Originator Email: 
             Open/Closed: Open
                 Release: other
         Discussion Lock: Any
        Operating System: Any

    _______________________________________________________

Details:

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.






    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?61824>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/