mex function online help text

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

mex function online help text

Dan McMahill
Hello,

I'm using octave-3.2.4.  I have a compiled mex function which has been
installed to:
${prefix}/libexec/octave/3.2.4/site/oct/i686-pc-linux-gnu/wcalc-1.1/
bars_calc.mex

It works.  When I run octave, bars_calc() is available as a function
and does what I expect.

However, the online help does not  work.

octave-3.2.4:1> help bars_calc
error: help: `bars_calc' is not documented

yet I do have this file installed:
${prefix}/libexec/octave/3.2.4/site/m/wcalc-1.1/bars_calc.m

The top several lines of bars_calc.m look like the following.  The
first "%" line is the first line of the file.

%BARS_CALC        - Self and mutual inductance of a pair of parallel
rectangular bars
%
%  SYNOPSIS
%
%  [L1, L2, M, k] = bars_calc(a, b, l1, d, c, l2, E, P, l3, freq)
%
%  PARAMETERS
% ....

Any idea what I'm doing wrong?

Thanks
-Dan
_______________________________________________
Help-octave mailing list
[hidden email]
https://www-old.cae.wisc.edu/mailman/listinfo/help-octave
Reply | Threaded
Open this post in threaded view
|

Re: mex function online help text

Przemek Klosowski-7
On 03/31/2010 03:23 PM, Dan McMahill wrote:

> Hello,
>
> I'm using octave-3.2.4.  I have a compiled mex function which has been
> installed to:
> ${prefix}/libexec/octave/3.2.4/site/oct/i686-pc-linux-gnu/wcalc-1.1/
> bars_calc.mex
>
> It works.  When I run octave, bars_calc() is available as a function
> and does what I expect.
>
> However, the online help does not  work.
>
> octave-3.2.4:1>  help bars_calc
> error: help: `bars_calc' is not documented
>
> yet I do have this file installed:
> ${prefix}/libexec/octave/3.2.4/site/m/wcalc-1.1/bars_calc.m

I think that if you have a .m file and an .oct file, Octave
just reads the .oct file and doesn't touch .m. You seem to believe
that the doc subsystem reads the .m files anyway---maybe I missed
something but I didn't think that's how it works. Octave's own
functions include the documentation via the DEFUN_DLD macro:

DEFUN_DLD (issparse, args, ,
   "-*- texinfo -*-\n\
@deftypefn {Loadable Function} {} issparse (@var{expr})\n\
Return 1 if the value of the expression @var{expr} is a sparse matrix.\n\
@end deftypefn")
_______________________________________________
Help-octave mailing list
[hidden email]
https://www-old.cae.wisc.edu/mailman/listinfo/help-octave
Reply | Threaded
Open this post in threaded view
|

Re: mex function online help text

John W. Eaton
Administrator
On  1-Apr-2010, Przemek Klosowski wrote:

| On 03/31/2010 03:23 PM, Dan McMahill wrote:
| > Hello,
| >
| > I'm using octave-3.2.4.  I have a compiled mex function which has been
| > installed to:
| > ${prefix}/libexec/octave/3.2.4/site/oct/i686-pc-linux-gnu/wcalc-1.1/
| > bars_calc.mex
| >
| > It works.  When I run octave, bars_calc() is available as a function
| > and does what I expect.
| >
| > However, the online help does not  work.
| >
| > octave-3.2.4:1>  help bars_calc
| > error: help: `bars_calc' is not documented
| >
| > yet I do have this file installed:
| > ${prefix}/libexec/octave/3.2.4/site/m/wcalc-1.1/bars_calc.m
|
| I think that if you have a .m file and an .oct file, Octave
| just reads the .oct file and doesn't touch .m. You seem to believe
| that the doc subsystem reads the .m files anyway---maybe I missed
| something but I didn't think that's how it works. Octave's own
| functions include the documentation via the DEFUN_DLD macro:
|
| DEFUN_DLD (issparse, args, ,
|    "-*- texinfo -*-\n\
| @deftypefn {Loadable Function} {} issparse (@var{expr})\n\
| Return 1 if the value of the expression @var{expr} is a sparse matrix.\n\
| @end deftypefn")

MEX files don't have embedded doc strings.  If a .mex file and a .m
file with the same base name are present, then Octave should look for
the doc string in the .m file.  I thought this was working, but it
looks like it is not.  Please report the bug here:

  https://savannah.gnu.org/bugs/?func=additem&group=octave

Thanks,

jwe
_______________________________________________
Help-octave mailing list
[hidden email]
https://www-old.cae.wisc.edu/mailman/listinfo/help-octave
Reply | Threaded
Open this post in threaded view
|

Re: mex function online help text

David Bateman
In reply to this post by Przemek Klosowski-7
Przemek Klosowski-7 wrote
On 03/31/2010 03:23 PM, Dan McMahill wrote:
> Hello,
>
> I'm using octave-3.2.4.  I have a compiled mex function which has been
> installed to:
> ${prefix}/libexec/octave/3.2.4/site/oct/i686-pc-linux-gnu/wcalc-1.1/
> bars_calc.mex
>
> It works.  When I run octave, bars_calc() is available as a function
> and does what I expect.
>
> However, the online help does not  work.
>
> octave-3.2.4:1>  help bars_calc
> error: help: `bars_calc' is not documented
>
> yet I do have this file installed:
> ${prefix}/libexec/octave/3.2.4/site/m/wcalc-1.1/bars_calc.m

I think that if you have a .m file and an .oct file, Octave
just reads the .oct file and doesn't touch .m. You seem to believe
that the doc subsystem reads the .m files anyway---maybe I missed
something but I didn't think that's how it works.
No, this is not the issue. The mex-interface includes no means to have a help string in the source code of the function. This is true even in Matlab. To include a help string you must have both a mex-file and a dot-m file with the same basename. In that case the mex-file with be used as the function and the dot-m file for the help string. Typically the dot-m has a small function definition like

function varargout = bar_calc (varargin)
   error ("bar_calc: Not available");
end

as well so that you can be sure that your mex-file version of the code is being used.

Cheers
David


Reply | Threaded
Open this post in threaded view
|

Re: mex function online help text

Dan McMahill
In reply to this post by John W. Eaton
John W. Eaton wrote:

> On  1-Apr-2010, Przemek Klosowski wrote:
>
> | On 03/31/2010 03:23 PM, Dan McMahill wrote:
> | > Hello,
> | >
> | > I'm using octave-3.2.4.  I have a compiled mex function which has been
> | > installed to:
> | > ${prefix}/libexec/octave/3.2.4/site/oct/i686-pc-linux-gnu/wcalc-1.1/
> | > bars_calc.mex
> | >
> | > It works.  When I run octave, bars_calc() is available as a function
> | > and does what I expect.
> | >
> | > However, the online help does not  work.
> | >
> | > octave-3.2.4:1>  help bars_calc
> | > error: help: `bars_calc' is not documented
> | >
> | > yet I do have this file installed:
> | > ${prefix}/libexec/octave/3.2.4/site/m/wcalc-1.1/bars_calc.m
> |
> | I think that if you have a .m file and an .oct file, Octave
> | just reads the .oct file and doesn't touch .m. You seem to believe
> | that the doc subsystem reads the .m files anyway---maybe I missed
> | something but I didn't think that's how it works. Octave's own
> | functions include the documentation via the DEFUN_DLD macro:
> |
> | DEFUN_DLD (issparse, args, ,
> |    "-*- texinfo -*-\n\
> | @deftypefn {Loadable Function} {} issparse (@var{expr})\n\
> | Return 1 if the value of the expression @var{expr} is a sparse matrix.\n\
> | @end deftypefn")
>
> MEX files don't have embedded doc strings.  If a .mex file and a .m
> file with the same base name are present, then Octave should look for
> the doc string in the .m file.  I thought this was working, but it
> looks like it is not.  Please report the bug here:
>
>   https://savannah.gnu.org/bugs/?func=additem&group=octave
>

Thanks for the quick reply.  I'm pretty certain that this was working
but it has been a few years since I had last tried.

Bug report filed.

-Dan


_______________________________________________
Help-octave mailing list
[hidden email]
https://www-old.cae.wisc.edu/mailman/listinfo/help-octave
Reply | Threaded
Open this post in threaded view
|

Re: mex function online help text

Luca Citi
In reply to this post by Przemek Klosowski-7
I think Dan expects octave to read the documentation form the m file because
this is what matlab does. I found this thread for the same reason.
Do you think it is possible to implement the same in octave?
Octave should look for the documentation the way it does now but, in case no
documentation is found for the mex file, also look for the shadowed m file.
The help could warn the user about this fact with a message like:
`myfun' is a function from the file `myfun.mex'
which is undocumented, the following help comes form the shadowed file `myfun.m'

Thanks,
Luca


_______________________________________________
Help-octave mailing list
[hidden email]
https://www-old.cae.wisc.edu/mailman/listinfo/help-octave
Reply | Threaded
Open this post in threaded view
|

Re: mex function online help text

John W. Eaton
Administrator
On 19-Nov-2010, Luca Citi wrote:

| I think Dan expects octave to read the documentation form the m file because
| this is what matlab does. I found this thread for the same reason.
| Do you think it is possible to implement the same in octave?
| Octave should look for the documentation the way it does now but, in case no
| documentation is found for the mex file, also look for the shadowed m file.
| The help could warn the user about this fact with a message like:
| `myfun' is a function from the file `myfun.mex'
| which is undocumented, the following help comes form the shadowed file `myfun.m'

There is no way to put help text in a .mex file like there is for a
.oct file.

The current development version of Octave will find the help text for
a .mex function if it is in a separate .m file.

jwe
_______________________________________________
Help-octave mailing list
[hidden email]
https://www-old.cae.wisc.edu/mailman/listinfo/help-octave