|
From: | Rik |
Subject: | Re: remove function class from docstrings in Octave-Forge |
Date: | Fri, 18 Dec 2015 20:07:20 -0800 |
On 12/17/2015 04:42 AM,
address@hidden wrote:
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 |
[Prev in Thread] | Current Thread | [Next in Thread] |