bugGNU Octave - Bugs: bug #39303, signal package: convert all...

 
 

bug #39303: signal package: convert all functions to proper texinfo or usage docstrings

Submitter:  Doug Stewart <dastew>
Submitted:  Thu 20 Jun 2013 09:27:09 PM UTC
   
 
Category:  Octave Package Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  mtmiller
Originator Name:  Doug 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

Thu 23 Jan 2014 06:27:41 AM UTC, comment #11: 

This bug has been fixed, the fix will be part of the next signal package release.

http://sf.net/p/octave/signal/ci/2959f2

Mike Miller <mtmiller>
Group Member
Wed 31 Jul 2013 02:11:53 AM UTC, comment #10: 

Since the listed examples are all from the signal package, I'm retitling this to better reflect what should be fixed. The bug seems to be that functions calling print_usage should start with either @deftypefn or usage lines.

Mike Miller <mtmiller>
Group Member
Thu 20 Jun 2013 11:06:52 PM UTC, comment #9: 

FYI, I do plan to convert all help text in the signal package to the Texinfo format for the next release.

Mike Miller <mtmiller>
Group Member
Thu 20 Jun 2013 10:53:28 PM UTC, comment #8: 

Or maybe I'm wrong about it printing the first block of the help text.  It looks like it is just printing the @deftypefn{,x} lines.

John W. Eaton <jwe>
Group administrator
Thu 20 Jun 2013 10:52:21 PM UTC, comment #7: 

The idea is that if your using the "plain text" help format then the first line of your help text should be a Usage line.  In my old version of butter from 1.0.11 the code is written like this:


  if (nargin>4 || nargin<2) || (nargout>4 || nargout<2)
    usage ("[b, a] or [z, p, g] or [a,b,c,d] = butter (n, W [, 'ftype'][,'s'])");
  end


In this case print_usage is never called.  Solution #1 would be to copy this usage note and make it the first line of the butter.m help text like so


## Usage: [b, a] or [z, p, g] or [a,b,c,d] = butter (n, W [, 'ftype'][,'s'])\n
##\n


Solution #2 would be to stop using print_usage() and revert to usage().

Solution #3 would be to rewrite the documentation as a Texinfo, instead of plain text, document.  This would be the best in the long run as Texinfo produces nicer documentation in pdf and HTML format.

Rik <rik5>
Group administrator
Thu 20 Jun 2013 10:50:44 PM UTC, comment #6: 

The print usage function is intended to work properly with docstrings that are formatted with Texinfo markup.

The idea is that print_usage displays the @deftypfn{,x} lines plus the first part of the help text, up to the first blank line.  That first part of the help text should be a short summary stating what the function does.

I think the right way to fix this problem is to fix the docstring to use Texinfo markup and perhaps make a note of this requirement in the print_usage docstring.

John W. Eaton <jwe>
Group administrator
Thu 20 Jun 2013 10:27:58 PM UTC, comment #5: 

If you remove the space then it prints out up to the double /n/n
which is no help at all.  With the space in it prints out the first 80 chars. How do we get all the help text????

Doug Stewart <dastew>
Thu 20 Jun 2013 10:14:04 PM UTC, comment #4: 

Okay, I found the problem.  It is with the butter.m file.

The start of the help text is


## Generate a butterworth filter.\n
## Default is a discrete space (Z) filter.\n
## \n


print_usage prints either 1) the help text until the first double newline "\n\n", 2) all of the text if it is short, or 3) the first 80 characters if the help text is long.

In this case, the comment characters '##' are stripped but that still leaves a space at the beginning of the line so that "\n \n" doesn't match.

I don't know if this is the greatest, but the solution is simply to remove the space in butter.m.


## Generate a butterworth filter.\n
## Default is a discrete space (Z) filter.\n
##\n


Rik <rik5>
Group administrator
Thu 20 Jun 2013 10:11:01 PM UTC, comment #3: 

I also see that step uses ## -*- texinfo -*-
and  butter does not!

Doug Stewart <dastew>
Thu 20 Jun 2013 10:02:53 PM UTC, comment #2: 

Good point. I now see that step works OK from the control pkg.
So  it might be just the signal pkg.

Doug Stewart <dastew>
Thu 20 Jun 2013 09:41:39 PM UTC, comment #1: 

Do you have an example that uses core Octave?  butter() is from an Octave-Forge package.  It's possible that something has happened in the package rather than in Octave.  I'm running an ancient version of the signal package, 1.0.11, and print_usage() works for me.

Rik <rik5>
Group administrator
Thu 20 Jun 2013 09:27:09 PM UTC, original submission:  

doug@doug-desktopq4:~/octave-comp/octave$ hg id
3d981b47be42 tip
When I type butter I get
"
 butter
error: Invalid call to butter.  Correct usage is:

 Generate a butterworth filter.
 Default is a discrete space (Z) filter.

 [b,a
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.
"
the [b,a    should have much more info.

also for cheby1
"
cheby1
error: Invalid call to cheby1.  Correct usage is:

 Generate an Chebyshev type I filter with Rp dB of pass band ripple.

 [b, a] =
Additional help for built-in functions and operators is
"


and other functions also.

I traced it to
which get_help_text
'get_help_text' is a built-in function from the file libinterp/interpfcn/help.cc


when I do:
help butter    the help text is properly displayed
I am using the gui
Doug


Doug Stewart <dastew>

 

(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 mtmiller (Posted a comment)
  • -email is unavailable- added by jwe (Posted a comment)
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by dastew (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 9 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2014-01-23 mtmiller StatusConfirmed Fixed
        Open/ClosedOpen Closed
    2013-07-31 mtmiller Item GroupRegression Documentation
        StatusWorks For Me Confirmed
        Assigned toNone mtmiller
        Summaryprint_usage not working for some functions in signal Octave-Forge package signal package: convert all functions to proper texinfo or usage docstrings
    2013-06-20 rik5 CategoryDocumentation Octave Package
        Summaryprint_usage not working print_usage not working for some functions in signal Octave-Forge package
    2013-06-20 rik5 StatusNone Works For Me

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code