bugGNU Octave - Bugs: bug #36524, Upgrade defun macro to accept...

 
 

bug #36524: Upgrade defun macro to accept non-double-quoted string for DOCSTRING

Submitter:  Rik <rik5>
Submitted:  Tue 22 May 2012 04:12:32 PM UTC
   
 
Category:  Configuration and Build System Severity:  2 - Minor
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Fri 01 Jul 2016 02:19:56 AM UTC, comment #4: 

It's been a week or so, everything seems to still be working, closing as fixed.

Mike Miller <mtmiller>
Group Member
Wed 22 Jun 2016 06:50:58 PM UTC, comment #3: 

Can this issue about docstrings be closed now?

Rik <rik5>
Group administrator
Tue 21 Jun 2016 08:33:16 PM UTC, comment #2: 

I committed a changeset for this because I think it's worth doing to make editing docstrings easier, but it's big and disruptive.  Many patches may fail if they touch docstrings.

http://hg.savannah.gnu.org/hgweb/octave/rev/112b20240c87

John W. Eaton <jwe>
Group administrator
Sun 01 May 2016 10:31:52 AM UTC, comment #1: 

Another reason to do this would be to allow conditional text within the docstring, based on which HAVE_... macros are defined.
Treating the docstring as a C string would allow


"first part"
#ifdef HAVE_...
"middle part"
#endif
"final part"


but since these are parsed by sed instead being treated as C strings, this introduces a spurious pair of double quotes.

The patch for bug #45654 would benefit from that, since functionality depends on HAVE_SETPGID.  Things such as graphics_toolkit may also benefit from being able to provide installation-specific help.

One solution may be to use sed to extract a short section of C/cpp code containing a printf to generate the .df file, though that may be rather slow.

Severity: Wishlist -> Minor

Lachlan Andrew <lachlan>
Tue 22 May 2012 04:12:32 PM UTC, original submission:  

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.


Rik <rik5>
Group administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by mtmiller (Posted a comment)
  • -email is unavailable- added by jwe (Posted a comment)
  • -email is unavailable- added by lachlan (Posted a comment)
  • -email is unavailable- added by rik5 (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2016-07-01 mtmiller StatusReady For Test Fixed
        Open/ClosedOpen Closed
    2016-06-22 rik5 StatusNone Ready For Test
    2016-06-22 lachlan DependenciesRemoved dependency from bugs #45654 -
    2016-05-01 lachlan Severity1 - Wish 2 - Minor
    2016-04-30 lachlan Dependencies- bugs #45654 is dependent

    Back to the top

    Powered by Savane 3.13-cf05.
    Corresponding source code