[Octave-bug-tracker] [bug #36524] Upgrade defun macro to accept non-double-quoted string for DOCSTRING

[Rik]

URL:
  <http://savannah.gnu.org/bugs/?36524>

                 Summary: Upgrade defun macro to accept non-double-quoted
string for DOCSTRING
                 Project: GNU Octave
            Submitted by: rik5
            Submitted on: Tue 22 May 2012 09:12:32 AM PDT
                Category: Configuration and Build System
                Severity: 1 - Wish
                Priority: 5 - Normal
              Item Group: Documentation
                  Status: None
             Assigned to: None
         Originator Name: 
        Originator Email: 
             Open/Closed: Open
         Discussion Lock: Any
                 Release: dev
        Operating System: Any

    _______________________________________________________

Details:

>From an e-mail exchange with JWE there was a proposal to expand the current
DEFUN macro to accept a simple string for the DOCSTRING portion of the macro. 
This would make entering and editing of the documentation easier as we could
drop the excessive backslashing that is currently required.


Longer term, what do you think about changing the way we handle doc
strings for built-in functions from what we have now to something like

  DEFUN (atan2, args, ,
         doc: /* -*- texinfo -*-
  @deftypefn {Mapping Function} {} atan2 (@var{y}, @var{x})
  Compute atan (@var{y} / @var{x}) for corresponding elements of @var{y}
  and @var{x}.  Signal an error if @var{y} and @var{x} do not match in size
  and orientation.
  @end deftypefn  */)

Emacs (from which I copied the idea for the DEFUN macro in the first
place) made a change like this some years ago.  The big advantage is
that the doc strings don't have to use C-style backslash quoting, so
are much easier to edit.  Instead of having these strings compiled
into the interpreter, they would be stored in a file that is installed
along with Octave and loaded as needed.  The file would be indexed by
function name, like the DOCSTRINGS files we have now, except possibly
with pre-computed offsets to make searching faster (Emacs also does
this).

This change would only affect built-in functions.  Dynamically loaded
.oct files would still work the same as they do now.






    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?36524>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/