bugGNU Octave - Bugs: bug #57085, [io] Comment notes in helptext...

 
 

bug #57085: [io] Comment notes in helptext examples?

Submitted by:  Andrew Janke <apjanke>
Submitted on:  Sat 19 Oct 2019 09:47:25 PM UTC  
 
Category:  Octave Forge Package Severity:  2 - Minor
Priority:  3 - Low Item Group:  Documentation
Status:  Postponed Assigned to:  None
Originator Name:  Open/Closed:  Open
Release:  other Operating System:  Any

Add a New Comment (Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

Thu 24 Oct 2019 06:31:38 PM UTC, comment #4: 

@Andrew: I'll let you know when I'm a bit further. Shouldn't be more than just one or a few weeks.

Status -> Postponed

Philip Nienhuis <philipnienhuis>
Project Member
Sun 20 Oct 2019 07:26:49 PM UTC, comment #3: 

Yep doctest it is.

Philip Nienhuis <philipnienhuis>
Project Member
Sun 20 Oct 2019 01:41:23 PM UTC, comment #2: 

I'll wait until you have your refactoring done, and then submit patches. Sounds like it would be a lot to keep track of if we do it all now.

Is it the "doctest" package you're referring to about helptext as test cases? https://octave.sourceforge.io/doctest/index.html

Andrew Janke <apjanke>
Sun 20 Oct 2019 01:23:01 PM UTC, comment #1: 

Good idea.

Currently I'm busy combining the xls and ods functions into one set, including the texinfo headers (which happens to be most of the actual work).
So this very moment may be too early; but if you can provide patches I'll incorporate them later (diffs rather than csets, please, otherwise I'll have a lot of work figuring out rejects).

There is also an attempt to have examples in the help texts serve as test cases and/or demos; I don't know the status of it but IIRC it was already working fine.
To adapt to this has also been on my mind for some time, but I haven't thought about it very deeply.

I'm setting priority to Low and severity to Minor.

Philip Nienhuis <philipnienhuis>
Project Member
Sat 19 Oct 2019 09:47:25 PM UTC, original submission:  

In the io package, in the function helptext, examples are formatted like this:

     Examples:

            A = xls2oct (xls1, '2nd_sheet', 'C3:AB40');
            (which returns the numeric contents in range C3:AB40 in worksheet
            '2nd_sheet' from a spreadsheet file pointed to in pointer struct xls1,
            into numeric array A)

            [An, xls2, status] = xls2oct (xls2, 'Third_sheet');

Plain prose is mixed in with code. What do you think about reformatting them as comments inside the examples? Like this:

     Examples:

            # returns the numeric contents in range C3:AB40 in worksheet
            # '2nd_sheet' from a spreadsheet file pointed to in pointer struct xls1,
            # into numeric array A
            A = xls2oct (xls1, '2nd_sheet', 'C3:AB40');

            [An, xls2, status] = xls2oct (xls2, 'Third_sheet');

Might help with readability, and then you can highlight multiple lines worth of example code and "Run selection", and it'll wok.

Andrew Janke <apjanke>

 

(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 apjanke (Submitted the item)
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only project members can vote.

     

     

     

    Follow 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2019-10-24 philipnienhuis StatusNone => Postponed
    2019-10-20 philipnienhuis Severity3 - Normal => 2 - Minor
        Priority5 - Normal => 3 - Low

    Back to the top


    Powered by Savane 3.5