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:  Patch Reviewed Assigned to:  None
Originator Name:  Nicholas Jankowski Open/Closed:  Open
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)

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 #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 2 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    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