bugGNU Octave - Bugs: bug #63141, Octave shows warning on texinfo...

 
 

bug #63141: Octave shows warning on texinfo doc functions with more than one @seealso

Submitter:  John Donoghue <lostbard>
Submitted:  Fri 30 Sep 2022 05:35:16 PM UTC
   
 
Category:  Octave Function Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Other
Status:  Fixed Assigned to:  None
Originator Name:  lostbard Open/Closed:  * Closed
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Wed 05 Oct 2022 07:33:06 AM UTC, comment #8: 

The minimum change that we require is probably to change the pattern to account for the fact that regular expressions are greedy. This avoids issues if the @seealso isn't the very last element in a docstring.
While we are at it, it probably wouldn't hurt to allow multiple @seealso in a single docstring again to avoid possible regressions with docstrings that were interpreted correctly with previous versions of Octave.

I pushed the change to the default branch here:
https://hg.savannah.gnu.org/hgweb/octave/rev/2deb14b9ad27

Marking as ready for test.

For the remaining issue (missing new line after the @seealso in case some text appears after it), it might be better to track it in a separate report.

Markus Mützel <mmuetzel>
Group administrator
Tue 04 Oct 2022 09:35:50 PM UTC, comment #7: 

The processing code (in Perl) combines multiple lines of a single @seealso reference into one.

For example, I hacked up the @seealso reference in ls.m to appear on multiple lines and it works just fine


## @seealso{dir,
##          readdir, glob, what, stat, filesep, ls_command}


I don't really see a big disadvantage to having only one @seealso macro in a file and probably wouldn't change anything here.

Rik <rik5>
Group administrator
Sat 01 Oct 2022 12:10:19 PM UTC, comment #6: 

Previous versions of octave behaved the same for the line after the see also, so am guessing that a new line should be added if proceeding any additional text after the see also.

So you patch fixes the bug issue!

John Donoghue <lostbard>
Group Member
Sat 01 Oct 2022 12:07:18 PM UTC, comment #5: 

@seealso{mytest1,
         mytest2}

doesnt work either - although just says warning: help: Texinfo formatting filter exited abnormally


Using your patch it seems to work for 2 seealsos as well as the multiline with one exception, which may be an texinfo thing rather than a octave issue and require a new line for correct texinfo?

## -*- texinfo -*-
## @deftypefn  {} {} mytest()
## Some text
##
## @seealso{mytest1, test2}
## more text
## @end deftypefn

The see also then shows See also: mytest1, test2.  more text

John Donoghue <lostbard>
Group Member
Sat 01 Oct 2022 11:39:35 AM UTC, comment #4: 

Nevermind. This is probably caused in an entirely different part of the code.

Does the attached patch fix it for you? It might not be the most elegant solution. But it works for the example in comment #0 for me.

(file #53778)

Markus Mützel <mmuetzel>
Group administrator
Sat 01 Oct 2022 11:08:55 AM UTC, comment #3: 

Hmm. Reading the comments in the code, I'd guess that this part of the generating script is supposed to combine multiple @seealso lines:
https://hg.savannah.gnu.org/hgweb/octave/file/de6fc38c78c6/doc/interpreter/mk-doc-cache.pl#l81

          ## Change @seealso to private @xseealso macro
          if ($line =~ m'@seealso')
          {
            ## Combine @seealso macro spread over multiple lines
            while ($line !~ m/}$/) {  $line .= <$FH>;  }

            ## escape @ characters in old-style class names like @ftp
            $line =~ s/\@(\w)/\@\@$1/g;
            $line =~ s'@@seealso'@xseealso';
          }


But tbh, my Perl is close to non-existent. So, I don't really know what those commands do...
Maybe, it's meant to collect arguments that span over multiple lines?
Does something like the following work?

@seealso{mytest1,
         mytest2}


Markus Mützel <mmuetzel>
Group administrator
Fri 30 Sep 2022 09:04:43 PM UTC, comment #2: 

The real case where this occurs has 2 @seealso lines with multiple elements in each, and was probally made into 2 separate see alsos to not have a large line perhaps


John Donoghue <lostbard>
Group Member
Fri 30 Sep 2022 06:05:37 PM UTC, comment #1: 

IIUC, a help text that contains multiple @seealso should accumulate them in a single call to that macro. E.g., @seealso{mytest1, mytest2}.

Markus Mützel <mmuetzel>
Group administrator
Fri 30 Sep 2022 05:35:16 PM UTC, original submission:  

Example function file:


## -*- texinfo -*-
## @deftypefn  {} {} mytest()
## Some text
## @seealso{mytest1}
## @seealso{mytest2}
## @end deftypefn

function mytest()

endfunction


Running help mytest in octave 8 warns:


octave-help-nNpLl8:133: misplaced {
octave-help-nNpLl8:133: misplaced }
octave-help-nNpLl8:133: misplaced {
octave-help-nNpLl8:133: misplaced }
warning: help: Texinfo formatting filter exited abnormally; raw Texinfo source of help text follows...
'mytest' is a script from the file /home/jade/work/home/newhouse/mytest.m

 -- mytest()
     Some text

     See also: mytest1.  @seealsomytest2


It doesnt seem to have the warning in octave 7.2

John Donoghue <lostbard>
Group Member

 

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

Attach Files:
   
   
Comment:
   

Attached Files

 

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 mmuetzel (Posted a comment)
  • -email is unavailable- added by lostbard (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-10-15 rik5 StatusReady For Test Fixed
        Open/ClosedOpen Closed
    2022-10-05 mmuetzel StatusPatch Submitted Ready For Test
    2022-10-01 mmuetzel Attached File- Added bug63141_texinfo_seealso.patch, #53778
        StatusNone Patch Submitted

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code