bugGNU Octave - Bugs: bug #56557, Formatted input documentation...

 
 

bug #56557: Formatted input documentation missing float info and location instructions unclear

Submitted by:  Nicholas Jankowski <nrjank>
Submitted on:  Wed 26 Jun 2019 06:21:01 PM UTC  
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Nicholas Jankowski Open/Closed:  Closed
Release:  5.1.0 Operating System:  Any

Add a New Comment (Rich Markup)
   

You are not logged in

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

 

( Jump to the original submission)

Tue 10 Sep 2019 09:26:41 PM UTC, comment #15: 

I pushed this change on the default branch:

https://hg.savannah.gnu.org/hgweb/octave/rev/918a3df652c3

I cleaned up the commit message a bit (no need to repeat the file name for each function or section changed), moved the mentioned reference, stripped trailing whitespace, and used our usual Texinfo conventions for code examples.

Mike Miller <mtmiller>
Project Administrator
Tue 10 Sep 2019 09:10:14 PM UTC, comment #14: 

whoops. good catch, thanks.  yes, that is what I intended v2->v3 copy/paste error.

Nicholas Jankowski <nrjank>
Tue 10 Sep 2019 08:40:42 PM UTC, comment #13: 

I've made some small corrections to this latest patch and was about to push it, but I noticed that you added a link to "Table of Input Conversions" in the "Output Conversion Syntax" page instead of the "Input Conversion Syntax" page. If I move that change is that what you intended?

Mike Miller <mtmiller>
Project Administrator
Tue 10 Sep 2019 08:00:45 PM UTC, comment #12: 

v3 patch attached that makes the doc changes and leaves in reference to the %E and %G specifiers, as those have now been enabled and a patch pushed in the linked, and now closed bug report.

(file #47482)

Nicholas Jankowski <nrjank>
Tue 10 Sep 2019 01:08:42 AM UTC, comment #11: 

bug #56869 created to deal with the capitalized  specifies.  Was decided to enable the specifies for compatibility. Will mod this patch to add %E %G back to the text.

Nicholas Jankowski <nrjank>
Sat 07 Sep 2019 08:02:14 PM UTC, comment #10: 

ok. new patch attached. style corrections made as you indicated.

only changed the doc text, didn't change any of the function docstrings. they can keep pointing to page 1 of that section. added explanatory and linkning text to that and following pages, along with an example, similar to how the Formatted Output pages are presented.

Decided to still removed the %E %G for now. I'll create an incompatability bug report, and they can easily be added back in if/when that functionality gets added.

(file #47464)

Nicholas Jankowski <nrjank>
Sat 07 Sep 2019 06:29:21 PM UTC, comment #9: 

finally getting back to this.

looking for instances of %E and %G, they only appear in the Formatted Output section (where they work) and the Table of Input Conversions page (where I was going to trim them out).

I verified that they produce an error in Octave. Then I checked Matlab 2019a. Matlab treats them the same as %e and %g, similar to what Octave's original help text says they sholuld do. 

So, I could delete the refernces to %E and %G as planned, but that appears to actually be a Matlab incompatibility bug.  The fact that it's always been there makes me think it was intended to be there all along.

I'm going to suggest I make the change patched below, leave in the %E and %G, make the other docstring changes, and then create a separate bug report about the formatted input matlab incompatibility.

Nicholas Jankowski <nrjank>
Wed 03 Jul 2019 11:53:34 PM UTC, comment #8: 

Will update the patch, look for occurrences of the %E %G, and add a suggested change for the docstrings

Nicholas Jankowski <nrjank>
Wed 03 Jul 2019 11:20:13 PM UTC, comment #7: 

I see. The '%E' and '%G' conversion specifiers aren't valid in Octave for the scanf input functions, maybe they were once upon a time or maybe it was a copy and paste error from output to input. We should delete them from the manual.

Is this the complete set of changes you want to make to the manual, or do you want to update the references in the individual docstrings also? If so we can do all of the changes in one commit.

Can you format the commit message like this

Add missing info on float input conversions (bug #56557)

* doc/interpreter/io.txi (Numeric Input Conversions): Add text for float input
conversion specifiers.

Note the extra line break, use of imperative present tense "add" instead of past tense "added", the manual section in parentheses as the relevant section of the file, and no leading slash in front of "doc".

Mike Miller <mtmiller>
Project Administrator
Fri 28 Jun 2019 02:05:09 AM UTC, comment #6: 

patch attached for a line or two of text on Numeric Input Conversions page.

(file #47141)

Nicholas Jankowski <nrjank>
Fri 28 Jun 2019 01:37:31 AM UTC, comment #5: 

I was referring mainly to the fact that in the Table of Input Conversions it lists "‘%e’, ‘%f’, ‘%g’, ‘%E’, ‘%G’", and that the latter two also behave identically to the other three.

Nicholas Jankowski <nrjank>
Thu 27 Jun 2019 04:23:07 PM UTC, comment #4: 

Yes, the %f, %g, and %e specifiers are identical for input. When you say "or caps", do you mean %F? That's not the way I read the Matlab help page, when it says

>  Input fields can contain any of the following (not case sensitive)


To me that means that it will process "inf", "Inf", or "INF" in the input stream as the same value.

It's worth pointing out that the doc string for 'printf' also says to "See the Formatted Output section" for more information, so I think the same treatment should probably be applied to both.

Mike Miller <mtmiller>
Project Administrator
Wed 26 Jun 2019 08:11:31 PM UTC, comment #3: 

2 - is the Octave behavior the same as Matlab for floating point inputs? according to matlab help there is no difference between specifying the %e, %f, and %g (or caps) options for input. It just pulls the number in as a double.

If so that could be a fairly small few-line add to the numeric input conversion page.  (1996, huh? impressive)

1 - there's a little useful info at the bottom, but mostly it just repeats the info just read in the help file. if the fscanf help tells me I can go there to find a description of the syntax, it would be better to point to 14.2.12  "Input Conversion Syntax". if it's missing an important detail form the 14.2.11 maybe that could be added to 14.2.12

Nicholas Jankowski <nrjank>
Wed 26 Jun 2019 06:57:52 PM UTC, comment #2: 

1. I think it's trying to refer to the "Formatted Input" section and all following related sections. The way it's written there isn't really one section that can be linked to, it's all sections 14.2.12 through 14.2.15. There is also some useful information in 14.2.11 that describes how formatting and white space are handled in the scanf-style functions.

2. It's been that way since the beginning. The "Numeric Input Conversions" section has never included floating point conversion specifiers, and the table has always referred to that section. See the initial revision in 1996 at https://hg.savannah.gnu.org/hgweb/octave/rev/b1a56412c385#l30.963

I'm sure ideas for reorganization would be welcome.

Mike Miller <mtmiller>
Project Administrator
Wed 26 Jun 2019 06:28:05 PM UTC, comment #1: 

it seems the Output Conversions pages earlier in that section have separately titled pages for integer and floating point output conversions (Table of Output Conversions, Integer Conversions, Floating-Point Conversions, Other Output Conversions). Should that be the same convention for input conversion?

Nicholas Jankowski <nrjank>
Wed 26 Jun 2019 06:21:01 PM UTC, original submission:  

two related documentation items here:

1 - In the help for fscanf, it says "See the Formatted Input section of the GNU Octave manual for a complete description of the syntax of the template string."

the "Formatted Input" doc page just has the docstrings for fscanf, scanf, and sscanf, with fscanf telling you to "See the Formatted Input section of the GNU Octave manual for a complete description of the syntax of the template string. " 

seems a bit circular. the following pages contain information about an input Template string spread over a few pages. Perhaps a link to the Input Conversion Syntax or Table of Input Conversions page would be better?

2 - on the Table of Input Conversions page, the line for float inputs

‘%e’, ‘%f’, ‘%g’, ‘%E’, ‘%G’
Matches an optionally signed floating-point number. See Numeric Input Conversions.

the Numeric Input Conversions page only has the Int conversions description. it stops before any of the float conversions, and the next page goes right to the string input conversions.

Did the float info get stripped off of that page at some point?  google brings up the 4.2.1 doc pages which show the same issue.  Is there an older version that has the missing text description that can be copied back into the current docs? or did they used to be on a different page?

Nicholas Jankowski <nrjank>

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #47482:  add_float_format_info_to_docs_v3.diff added by nrjank (3KiB - application/octet-stream - v3 - retains %E %G references)
file #47464:  add_float_format_info_to_docs_v2.diff added by nrjank (3KiB - application/octet-stream - adds flots to Numeric Input Table, adds explanatory text to other sections, removes ref to %E %G)
file #47141:  add_float_format_info_to_docs.diff added by nrjank (1KiB - application/octet-stream - adds float info to Numeric Input Table doc page)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by nrjank (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 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2019-09-10 mtmiller StatusPatch Reviewed => Fixed
        Open/ClosedOpen => Closed
    2019-09-10 nrjank Attached File- => Added add_float_format_info_to_docs_v3.diff, #47482
    2019-09-07 nrjank Attached File- => Added add_float_format_info_to_docs_v2.diff, #47464
    2019-07-03 mtmiller StatusNone => Patch Reviewed
    2019-06-28 nrjank Attached File- => Added add_float_format_info_to_docs.diff, #47141

    Back to the top


    Powered by Savane 3.5