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 Jun 20 21:27:09 2013  
Category: Octave Forge PackageSeverity: 3 - Normal
Priority: 5 - NormalItem Group: 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 Jan 23 06:27:41 2014, comment #11:

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


Mike Miller <mtmiller>
Project AdministratorIn charge of this item.
Wed Jul 31 02:11:53 2013, 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 AdministratorIn charge of this item.
Thu Jun 20 23:06:52 2013, 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 AdministratorIn charge of this item.
Thu Jun 20 22:53:28 2013, 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 Jun 20 22:52:21 2013, 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 Jun 20 22:50:44 2013, 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 Jun 20 22:27:58 2013, 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 Jun 20 22:14:04 2013, 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 Jun 20 22:11:01 2013, comment #3:

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

Doug Stewart <dastew>
Thu Jun 20 22:02:53 2013, 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 Jun 20 21:41:39 2013, 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 Jun 20 21:27:09 2013, original submission:

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

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

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
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 Stewart <dastew>


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

Attach File(s):

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 Jan 23 06:27:41 2014mtmillerStatusConfirmed=>Fixed
    Wed Jul 31 02:11:53 2013mtmillerItem 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
    Thu Jun 20 22:14:04 2013rik5CategoryDocumentation=>Octave Forge Package
      Summaryprint_usage not working=>print_usage not working for some functions in signal Octave-Forge package
    Thu Jun 20 21:41:39 2013rik5StatusNone=>Works For Me

    Back to the top

    Powered by Savane 3.1-cleanup1