bugGNU Octave - Bugs: bug #66428, doc_cache_create shows warnings...

 
 

bug #66428: doc_cache_create shows warnings "misplaced {"

Submitter:  None
Submitted:  Fri 08 Nov 2024 12:27:26 PM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Unexpected Error or Warning
Status:  Fixed Assigned to:  None
Originator Name:  Andy Originator Email:  -email is unavailable-
Open/Closed:  * Closed Release:  * 9.2.0
Release:  Operating System:  * Any
Fixed Release:  10.1.0 Planned Release:  9.3.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Tue 25 Feb 2025 11:44:26 PM UTC, comment #7: 

I found a better regular expression pattern which preserves the help text for keywords like '#' and also preserves documentation for the keyword persistent.  See https://hg.savannah.gnu.org/hgweb/octave/rev/cf3b0d01b3aa.

This will be a part of the 10.1 release of Octave.

Marking as Fixed and closing report.

Rik <rik5>
Group administrator
Tue 25 Feb 2025 10:57:14 PM UTC, comment #6: 

I can confirm the issue with "help persistent".  Re-opening bug.

Rik <rik5>
Group administrator
Tue 25 Feb 2025 10:29:08 PM UTC, comment #5: 

On MacOS/Homebrew with makeinfo 7.2:

octave:2> help persistent
octave-help-sGnKfy:146: misplaced {
octave-help-sGnKfy:146: misplaced }
octave-help-sGnKfy:146: misplaced {
octave-help-sGnKfy:146: misplaced }
octave-help-sGnKfy:151: @bye seen before @end deftypefn
octave-help-sGnKfy:146: misplaced {
octave-help-sGnKfy:146: misplaced }
octave-help-sGnKfy:146: misplaced {
octave-help-sGnKfy:146: misplaced }
octave-help-sGnKfy:151: @bye seen before @end deftypefn
warning: help: Texinfo formatting filter exited abnormally; raw Texinfo source of help text follows...

 -- persistent VAR
     Declare variables as persistent.

     A variable that has been declared persistent within a function will
     retain its contents in memory between subsequent calls to the same
     function.  The difference between persistent variables and global
     variables is that persistent variables are local in scope to a
     particular function and are not visible elsewhere.

     See also: global.  @end deftypefn @c ## FIXME: Can't have duplicate
     DOCSTRING entries.  The function properties() @c ## already has a
     docstring which overrides this keyword definition.  @c ## If this
     is fixed, place \x1d char before keyword "properties".  @c ##
     properties @c ## @c libinterp/parse-tree/oct-parse.yy @c ## -*-
     texinfo -*- @c ## @deftypefn properties

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.


Dmitri.
--

Dmitri A. Sergatskov <dasergatskov>
Sat 30 Nov 2024 04:43:53 PM UTC, comment #4: 

It was pushed to stable and merged to default.  This fixes the issue with Octave core documentation.  Individual packages, such as "image", might have problems that need to be corrected in their documentation sources.

Rik <rik5>
Group administrator
Sat 30 Nov 2024 02:59:22 AM UTC, comment #3: 

Did it get pushed to dev as well?
Does the fix affect octave's own docs, or packages'  too?
I see lots (more than 100) installing "image" package.

Dmitri.
--

Dmitri A. Sergatskov <dasergatskov>
Mon 25 Nov 2024 09:21:30 PM UTC, comment #2: 

This was quite the saga for just 4 help strings which exhibit this behavior.  I did find a fix and pushed it to the stable branch (https://hg.savannah.gnu.org/hgweb/octave/rev/d54dc3265ef0) which will be release in version 9.3.

Marking as Fixed and closing report.

Rik <rik5>
Group administrator
Mon 25 Nov 2024 06:22:05 PM UTC, comment #1: 

Confirmed.

Unfortunately, this is quite complex to resolve because there is an interaction between the text, a Perl script, _makeinfo_ Octave script, and Texinfo.

I will have to think about this more.

Rik <rik5>
Group administrator
Fri 08 Nov 2024 12:27:26 PM UTC, original submission:  

GNU Octave Version: 9.2.0 (hg id: f7f956555e4a)
Operating System: MINGW32_NT-6.2 Windows 6.2  x86_64

>> system ("makeinfo --version")

texi2any (GNU texinfo) 7.1

edit _makeinfo_.m:187 to comment delete so the temporary file isn't deleted


[text, format] = get_help_text ("#")
[ntext, status] = __makeinfo__ (text, "plain text");


returns

text =
@deftypefn {} {} #
Begin comment character.
@seealso{%, #@\{}
@end deftypefn

format = texinfo
>> [ntext, status] = __makeinfo__ (text, "plain text");
C:\Users\XXX\AppData\Local\Temp\octave-help-wytAMc:132: misplaced { (possibly involving @xseealso)
C:\Users\XXX\AppData\Local\Temp\octave-help-wytAMc:132: misplaced { (possibly involving @xseealso)


file octave-help-wytAMc line 130:133

@deftypefn {} {} #
Begin comment character.
@xseealso{%, #@@\{}
@end deftypefn


For me it looks like there is some problem escaping {.

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Conventions.html

says that {} have to be escaped with @, not \

but I don't know texinfo good enough. I haven't tested this on GNU/Linux yet so perhaps it's a problem with the specific texi2any which comes with MXE Octave


Anonymous

 

(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 dasergatskov (Posted a comment)
  • -email is unavailable- added by rik5 (Posted a comment)
  •  

    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 13 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2025-02-27 rik5 Open/ClosedOpen Closed
    2025-02-25 rik5 StatusIn Progress Fixed
        Fixed Release9.3.0 10.1.0
    2025-02-25 rik5 StatusFixed In Progress
        Open/ClosedClosed Open
    2024-11-25 rik5 StatusConfirmed Fixed
        Open/ClosedOpen Closed
        Fixed ReleaseNone 9.3.0
        Planned ReleaseNone 9.3.0
    2024-11-25 rik5 CategoryNone Documentation
        Item GroupNone Unexpected Error or Warning
        StatusNone Confirmed
        Operating SystemMicrosoft Windows Any

    Back to the top

    Powered by Savane 3.15-e6e5.
    Corresponding source code