[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: remove function class from docstrings in Octave-Forge
From: |
Oliver Heimlich |
Subject: |
Re: remove function class from docstrings in Octave-Forge |
Date: |
Thu, 17 Dec 2015 07:33:10 +0100 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Icedove/38.4.0 |
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