bugGNU Octave - Bugs: bug #57085, [octave forge] (io) Comment notes...

 
 

bug #57085: [octave forge] (io) Comment notes in helptext examples?

Submitter:  Andrew Janke <apjanke>
Submitted:  Sat 19 Oct 2019 09:47:25 PM UTC
   
 
Category:  Octave 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
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Tue 01 Sep 2020 05:43:53 PM UTC, comment #6: 

I was just searching through the tracker and seeing how many bug reports we had in various categories...

John W. Eaton <jwe>
Group administrator
Tue 01 Sep 2020 05:36:26 PM UTC, comment #5: 

(Thanks JWE for reminding me of this bug report by fixing the title)

@Andrew:
The refactoring has been done quite a while ago + released + next release and I'm planning to make another release (2.6.2) somewhere in the next weeks.
So if you still want to supply patches, please do.
I'll see what I can do myself in the mean time, but as there were already two releases w/o complaints seen here I suppose the priority is not high. OTOH it doesn't look very complicated, it's just a matter of going through the user-visible code base.

Hmmm, looks like several other OF package may need this as well.

Philip Nienhuis <philipnienhuis>
Group Member
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>
Group Member
Sun 20 Oct 2019 07:26:49 PM UTC, comment #3: 

Yep doctest it is.

Philip Nienhuis <philipnienhuis>
Group 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>
Group 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 jwe (Updated the item)
  • -email is unavailable- added by apjanke (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 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2020-09-01 jwe Summary[io] Comment notes in helptext examples? [octave forge] (io) Comment notes in helptext examples?
    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.13-4448.
    Corresponding source code