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

 
 

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

Submitted by:  Doug Stewart <dastew>
Submitted on:  Thu 20 Jun 2013 09:27:09 PM UTC  
 
Category: Octave Forge PackageSeverity: 3 - Normal
Priority: 5 - NormalItem Group: Incorrect Documentation
Status: FixedAssigned to: Mike Miller <mtmiller>
Originator Name: DougOpen/Closed: Closed
Release: devOperating System: Any

Add a New Comment (Rich MarkupRich Markup):
   

You are not logged in

Please log in, so followups can be emailed to you.

 

(Jump to the original submission 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>
Project MemberIn charge of this item.
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>
Project MemberIn charge of this item.
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>
Project MemberIn charge of this item.
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>
Project 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:

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

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>
Project 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>
Project 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

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.

Rik <rik5>
Project 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>
Project 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 File(s):
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -unavailable- added by mtmiller (Posted a comment)
  • -unavailable- added by jwe (Posted a comment)
  • -unavailable- added by rik5 (Posted a comment)
  • -unavailable- added by dastew (Submitted the item)
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only project members can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    Follow 9 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Thu 23 Jan 2014 06:27:41 AM UTCmtmillerStatusConfirmed=>Fixed
      Open/ClosedOpen=>Closed
    Wed 31 Jul 2013 02:11:53 AM UTCmtmillerItem GroupRegression=>Incorrect 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
    Thu 20 Jun 2013 10:14:04 PM UTCrik5CategoryDocumentation=>Octave Forge Package
      Summaryprint_usage not working=>print_usage not working for some functions in signal Octave-Forge package
    Thu 20 Jun 2013 09:41:39 PM UTCrik5StatusNone=>Works For Me

    Back to the top


    Powered by Savane 3.1-cleanup