Re: remove function class from docstrings in Octave-Forge

[Oliver Heimlich]

On 16.12.2015 22:26, Oliver Heimlich wrote:
> On 13.12.2015 22:00, Carlo De Falco wrote:
>> Hi,
>>
>> One of the tasks of the 2015 Codesprint 
>> was to remove function class from docstrings 
>> in Octave-Forge [1,2,3]. 
>>
>> If I recall correctly Rik accomplished this
>> with a Perl script.
>>
>> Rik, I think it would make sense to make such script available
>> so tha forge package maintainers can apply similar changes to 
>> their packages.
>>
>> What do you think?
> 
> Due to the extra formatting/postprocessing introduced in [4], the
> problem with the packages is that the documentation would look bad in
> old versions of Octave, which would have the “ -- : ” in front of every
> function declaration. Also we would need a similar change for the html
> output from the generate_html package.
> 
> Why don't we use standard Texinfo conventions?

FYI, I have implemented the Texinfo conventions for the interval package
in [5]. It was particularly easy and I like the extra information that
it provides. Before the change, every package function had the category
“Function File”.

The only “complicated” thing is that you cannot combine @def… commands
with @def…x commands of a different type. However, this is not a
limitation since you can use the more generic one of the two. For
example this is such a complicated case:

## @defop Method {@@infsup} eq (@var{A}, @var{B})
## @defopx Operator {@@infsup} address@hidden == @var{B}}

results in:

 -- Method on @infsup: eq (A, B)
 -- Operator on @infsup: A == B

I find this useful for Octave core too. However, in core we would use
@deftypefun most of the time and address@hidden Operator …” for the small
set of operators.

The complete list of @def… commands can be found in the Texinfo manual
[6]. I had no problems using any of them with Texinfo 5.2, Octave 3.8.2
and the generate_html package.

>> [1] 
>> http://wiki.octave.org/Remove_class_of_function_from_documentation_strings
>> [2] http://hg.savannah.gnu.org/hgweb/octave/rev/516bb87ea72e
>> [3] http://hg.savannah.gnu.org/hgweb/octave/rev/1142cf6abc0d
> [4] http://hg.savannah.gnu.org/hgweb/octave/rev/5e16d687a701
[5] http://hg.code.sf.net/p/octave/interval/rev/667eae3380a7
[6]
http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Definition-Commands.html