bugGNU Octave - Bugs: bug #38392, Texinfo 5.0 breaks documentation

 
 

bug #38392: Texinfo 5.0 breaks documentation

Submitter:  Stefan Husmann <haawda>
Submitted:  Sat 23 Feb 2013 10:23:50 PM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Stefan Husmann Open/Closed:  * Closed
Release:  * dev Operating System:  * GNU/Linux
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Wed 01 May 2013 02:51:40 AM UTC, comment #10: 

OP confirmed this is now working, closing as fixed.

Mike Miller <mtmiller>
Group Member
Tue 30 Apr 2013 03:32:10 AM UTC, comment #9: 

I am not getting any @deftypefn errors or warnings building the documentation, on revision 3ce0c312a40b. I have built it with both the texinfo 5.0 release and from texinfo svn trunk. All issues fixed?

Mike Miller <mtmiller>
Group Member
Sat 27 Apr 2013 10:10:37 PM UTC, comment #8: 

texinfo 4.13a should not have that issue.

Stefan Husmann <haawda>
Sat 27 Apr 2013 06:45:03 PM UTC, comment #7: 

Do you know which version(s) of texinfo the current Octave 3.6.4 build does work with? I'm getting the same texinfo error when trying to build Octave 3.6.4 under Homebrew on Mac OS X 10.8.3 and 10.7.5, which come with texinfo 4.8.

(I'm building it without FLTK and getting the error. When built with FLTK, the error doesn't happen. I don't know why this interaction happens.)

Andrew Janke <andrewjanke>
Mon 25 Feb 2013 04:44:51 AM UTC, comment #6: 

I pushed one more changeset which should fix the last warning (http://hg.savannah.gnu.org/hgweb/octave/rev/9720ecf8d257).

The @deftypefn errors, however, will need someone to rewrite each documentation string that uses @deftypefn separated from @deftypefnx.  To find the function that needs editing look at the error line in plot.texi, for example plot.texi:2810.  If you search backwards in the file for @deftypefn you will find


@deftypefn {Function File} {} daspect (@var{data_aspect_ratio})


and above that there will be a Texinfo comment line which begins with '@c' which says where the documentation string came from.  In this case the line is


@c daspect scripts/plot/daspect.m


which says which m-file needs rewriting.

Rik <rik5>
Group administrator
Sun 24 Feb 2013 05:57:58 PM UTC, comment #5: 

Thank you. Indeed many of the issues are fixed for me with your changeset.

The remaining ones are that ones using the mentioned using @deftypefn and @deftypefnx. These are the ones causing the build to stop. There are two more warnings.


./plot.texi:2810: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2813: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2816: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2819: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2833: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2836: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2839: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2842: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:6636: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:7487: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:7489: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:7493: must be after `@deftypefn' to use `@deftypefnx'
./set.texi:154: must be after `@deftypefn' to use `@deftypefnx'
./poly.texi:86: must be after `@deftypefn' to use `@deftypefnx'
./poly.texi:658: must be after `@deftypefn' to use `@deftypefnx'
./poly.texi:663: must be after `@deftypefn' to use `@deftypefnx'
./signal.texi:473: must be after `@deftypefn' to use `@deftypefnx'
./signal.texi:477: must be after `@deftypefn' to use `@deftypefnx'
./signal.texi:482: must be after `@deftypefn' to use `@deftypefnx'
./audio.texi:150: must be after `@deftypefn' to use `@deftypefnx'
./audio.texi:154: must be after `@deftypefn' to use `@deftypefnx'
./audio.texi:157: must be after `@deftypefn' to use `@deftypefnx'
./audio.texi:160: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2893: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2911: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2914: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2982: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2985: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2988: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2993: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:3006: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:3518: warning: node `Printing and Saving Plots' is next for `Multiple Plot Windows' in menu but not in sectioning
./plot.texi:4089: warning: node `Multiple Plot Windows' is prev for `Printing and Saving Plots' in menu but not in sectioning


Stefan Husmann <haawda>
Sun 24 Feb 2013 03:22:17 PM UTC, comment #4: 

I pushed a changeset which fixes most of the issues reported (http://hg.savannah.gnu.org/hgweb/octave/rev/8899c785cc99). 

However Octave is using a syntax with @deftypefn and @deftypefnx separated by multiple lines of documentation.  This has been perfectly legal syntax in the past and modifying all of those occurrences is an invasive project.

Is the problem really that the documentation won't finish building?  Or is the issue that warnings are being emitted during the build?  We can live with warnings being printed and just ignore them.

Rik <rik5>
Group administrator
Sun 24 Feb 2013 03:08:55 PM UTC, comment #3: 

The function help text is not included directly in the manual texinfo pages. Instead they are linked to the actual functions help text. You will see things such as


@DOCSTRING(plotyy)


which means include the plotyy documentation here. You'll have to track down which ones are causing the problem. See on the autogenerated files to what functions they belong.

Carnë Draug <carandraug>
Group Member
Sat 23 Feb 2013 11:34:56 PM UTC, comment #2: 

The fixes are far from being obvious to me. Most of the files affected are autogenerated. F.i. there is no occurrence of @deftypefnx in plot.txi.

Stefan Husmann <haawda>
Sat 23 Feb 2013 10:27:17 PM UTC, comment #1: 

Can you prepare a patch? The fixes all seem obvious.

Jordi Gutiérrez Hermoso <jordigh>
Group Member
Sat 23 Feb 2013 10:23:50 PM UTC, original submission:  

After my distro Arch Linux switched to Texinfo 5.0, the documentation cannot be built freshly.


octave.texi:93: warning: @end should only appear at a line beginning
./strings.texi:1155: @itemx must follow @item
./io.texi:1458: warning: @table has text but no @item
./plot.texi:2810: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2813: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2816: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2819: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2833: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2836: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2839: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:2842: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:3250: @itemx must follow @item
./plot.texi:3265: @itemx must follow @item
./plot.texi:4304: @itemx must follow @item
./plot.texi:4308: @itemx must follow @item
./plot.texi:6491: @itemx must follow @item
./plot.texi:6495: @itemx must follow @item
./plot.texi:6499: @itemx must follow @item
./plot.texi:6637: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:7488: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:7490: must be after `@deftypefn' to use `@deftypefnx'
./plot.texi:7494: must be after `@deftypefn' to use `@deftypefnx'
./set.texi:154: must be after `@deftypefn' to use `@deftypefnx'
./poly.texi:86: must be after `@deftypefn' to use `@deftypefnx'
./poly.texi:658: must be after `@deftypefn' to use `@deftypefnx'
./poly.texi:663: must be after `@deftypefn' to use `@deftypefnx'
./signal.texi:473: must be after `@deftypefn' to use `@deftypefnx'
./signal.texi:477: must be after `@deftypefn' to use `@deftypefnx'
./signal.texi:482: must be after `@deftypefn' to use `@deftypefnx'
./audio.texi:150: must be after `@deftypefn' to use `@deftypefnx'
./audio.texi:154: must be after `@deftypefn' to use `@deftypefnx'
./audio.texi:157: must be after `@deftypefn' to use `@deftypefnx'
./audio.texi:160: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:838: warning: command @dots does not accept arguments
./system.texi:1262: warning: @itemx should not begin @table
./system.texi:1264: @itemx must follow @item
./system.texi:2894: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2912: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2915: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2983: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2986: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2989: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:2994: must be after `@deftypefn' to use `@deftypefnx'
./system.texi:3007: must be after `@deftypefn' to use `@deftypefnx'
./tips.texi:301: warning: @item missing argument
./tips.texi:304: warning: @item missing argument
./tips.texi:307: warning: @item missing argument
./tips.texi:310: warning: @item missing argument
./tips.texi:313: warning: @item missing argument
./plot.texi:3518: warning: node `Printing and Saving Plots' is next for `Multiple Plot Wi
ndows' in menu but not in sectioning
./plot.texi:4089: warning: node `Multiple Plot Windows' is prev for `Printing and Saving
Plots' in menu but not in sectioning


Stefan Husmann <haawda>

 

(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

Digest:
   bug dependencies.

 

Carbon-Copy List
  • -email is unavailable- added by mtmiller (Posted a comment)
  • -email is unavailable- added by andrewjanke (Posted a comment)
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by jordigh (Posted a comment)
  • -email is unavailable- added by haawda (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 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2013-05-02 mtmiller Dependencies- bugs #38865 is dependent
    2013-05-01 mtmiller StatusNone Fixed
        Open/ClosedOpen Closed

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code