Re: remove function class from docstrings in Octave-Forge

[Rik]

On 12/17/2015 04:42 AM, address@hidden wrote:

Subject:

Re: remove function class from docstrings in Octave-Forge

From:

Oliver Heimlich <address@hidden>

Date:

12/16/2015 10:33 PM

To:

address@hidden

List-Post:

<mailto:address@hidden>

Content-Transfer-Encoding:

quoted-printable

Precedence:

list

MIME-Version:

1.0

References:

<address@hidden> <address@hidden>

In-Reply-To:

<address@hidden>

Message-ID:

<address@hidden>

Content-Type:

text/plain; charset=utf-8

Message:

2

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

The problem with our previous usage of the @deftypefn was only partially caused by our choice of names--"Mapper Function", "Command", "Loadable Function", etc.  The real issue, that you came across, is that Texinfo expects that each definition is for one thing alone.  The categories that are built in to Texinfo are functions, commands, operators, methods, and variables.  But in Octave, every function is also a command; The interpreter doesn't care.  We tried to document that, for example, in the help text for 'ls'

 -- Command:  ls
 -- Command:  ls FILENAMES
 -- Command:  ls OPTIONS
 -- Command:  ls OPTIONS FILENAMES
 -- Function File: LIST = ls (...)
 
But really this seemed more verbose and ultimately confusing than just presenting a list of calling templates which the user can choose from.

 -- ls
 -- ls FILENAMES
 -- ls OPTIONS
 -- ls OPTIONS FILENAMES
 -- LIST = ls (...)

I backported the change to __makeinfo__.m which changes ' -- : ' to ' -- ' onto the stable branch here (http://hg.savannah.gnu.org/hgweb/octave/rev/a7ebc9815d71).  This won't affect existing documentation, but if anyone wants to change over Octave Forge packages to match core they will display correctly in 4.0.1.

For those who want to convert a file there is a simple one-line perl script you can use at the shell.

perl -i.bak -pe 's/address@hidden(x?\s+){[^}]+}/address@hidden/' FILES

Where FILES is a space separated list of files or a shell glob pattern like '*.m' or '*.cc'.  It makes a backup copy of the original file in filename.bak which you can revert to if there was any problem, although I didn't have any troubles with the core files.

--Rik