Edit of a Page from a Microsoft Manual



 I've been reading technical manuals for many years - mostly IBM mainframe computer manuals,

 but also PC manuals for DOS and Windows.


 The worst manual I've ever seen is the "Microsoft Visual Basic 6.0 Language Reference"

 manual for Windows. Besides not containing an index, much of the manual is written as if it were

 an abridged Reader's Digest book on Astral Projection or New Age philosophy. It uses questionable

 terminology such as the passive "Input function" rather than READ or GET, and "opened for Binary

 mode" which is a meaningless phrase (but not a phrase I can fix here). 


 Many of the entries are too short. You're left thinking that you understand the entry, then realize later

 that you don't really understand it at all because they've left out important parts of the explanation,

 and used examples instead of definitions. It is vacuous; it is the written form of vaporware.


 Here's an attempt to edit (rewrite) the text for one entry: The "INPUT Function."

 This called for unusually heavy, industrial-strength editing, knowledge, and research.


                 Dave = yellow

              Microsoft = gray 



 My version of the INPUT Function based on what I think Microsoft is trying to say.


 INPUT Function  (Read Characters)


 (Note: See also LINE INPUT #,  INPUT #,  INPUTB, and GET functions.

 INPUTB returns all data read - not just "characters" read).



 Reads data from a file opened for Input or Binary mode, and moves valid ASCII

 characters to an input area.


 Valid ASCII characters are printable or displayable characters. They range from decimal 32

 to decimal 126 in the ASCII character set, and include all alphabetic and numeric characters,

 spaces, punctuation, carriage returns, and linefeeds. All other data is ignored and not moved

 to the input area.


The INPUT function acts as a "read characters" operation. 





 input-area = INPUT(character-count, [#]filenumber)






    Required. This is the input area for the operation, and must be defined as a String Variable.



    Required. This may be any valid numeric expression.

    It represents the number of characters (not bytes) to read into the input area.

    If fewer characters remain to be read than character-count, then only those

    characters are moved to the input area, and the length of the input-area is adjusted

    by the system.



    Optional. Used for compatability with previous releases of BASIC.



    Required. Any integer from 1-99 representing an open file.





 Unlike the INPUT # statement, the INPUT function returns all of the characters it reads,

 including commas, carriage returns, linefeeds, quotation marks, and leading spaces.

 For this reason, large quantities of data can be read with 1 INPUT statement and can be

 properly displayed or printed as-is, but cannot be properly displayed or printed as-is if

 INPUT # is used (since spacing and new-line indications are lost).


 For files opened for Input mode, the system indicates end-of-file by setting EOF to True. 

 The input-area length and contents are not changed when EOF is processed.


 For files opened for Binary mode [1], EOF is not set by the system to indicate end-of-file. 

 The LOF and LOC functions should be used instead, to determine end-of-file. If the file is

 read "until EOF = True" in Binary mode, end-of-file will not be indicated, and the program will

 attempt to read past the end of file, causing an error. If EOF must be used to indicate

 end-of-file for a Binary mode file, then GET should be used instead of INPUT.


 Data read with the INPUT function has typically been created with the PRINT # or PUT statements.





 This example uses the INPUT function to read 80 characters at a time from a file and move it

 to the screen display area. Non-character data is bypassed by the system, and not moved to the

 input area.


 Private Myinputarea as String       ' Define the input area.

 Myinputarea = ""                    ' Clear the input area (set to null).

 DispArea = ""                       ' Clear the screen display area.

 Open "TESTFILE" for Input as #3     ' Open the file for Input.

 Do While Not EOF(3)                 ' Loop until end of file.

    Myinputarea = INPUT(80, #3)      ' Read 80 characters from File #3

                                     '   into Myinputarea.

    FileLen = LEN(Myinputarea)       ' Get the length of the input area.

    If Filelen > 0 then              ' If we have data...

      DispArea = DispArea & Myinputarea 'Append it to the screen disp area.

 Loop                                ' Go read again.

 Close #3                            ' Close the file. 



 QBASIC Notes:

 QBASIC equivalent: INPUT$.

  In QBASIC, the INPUT function reads input from the keyboard only - not from files.



 [Note 1: "Binary mode" is another meaningless term used in this manual. I can't fix that here.]



 ---End of Dave's version---






The following item is Microsoft's version of that item.

Does it fully explain the INPUT Function?  Hardly...


It does not address the following questions with clarity and thoroughness:

 The answers to these questions are all things a programmer would need to know in order to

 program properly. This is closer to a Cliff-Notes or abridged version of the manual, when it

 purports to be (and is) the full, official version. It is the worst manual I've ever seen.



 Original Microsoft version, from the VB6 Language Reference Manual, page 520, copyright 1998.


 Input Function


 Returns String containing characters from a file opened in Input or Binary mode.




 Input(number, [#]filenumber)


 The Input function has these parts:


 Part              Description


 number         Required. Any valid numeric expression specifying the number of

                      characters to return.


 filenumber    Required. Any valid file number.





 Data read with the Input function is usually written to a file with Print # or Put. Use this

 function only with files opened in Input or Binary mode.


 Unlike the Input # statement, the Input function returns all of the characters it reads,

 including commas, carriage returns, linefeeds, quotation marks, and leading spaces.


 With files opened for Binary access, an attempt to read through the file using the Input

 function until EOF returns True generates an error. Use the LOF and Loc functions

 instead of EOF when reading binary files with Input, or use Get when using the EOF



    Note: Use the InputB function for byte data contained within text files. With InputB,

    number specifies the number of bytes to return rather than the number of characters to



 See Also


 Input # Statement




 This example uses the Input function to read one character at a time from a file and print

 it to the Immediate window. This example assumes that TESTFILE is a text file with a few

 lines of sample data.


 Dim MyChar

 Open "TESTFILE" for Input as #1      ' Open file.

 Do While Not EOF(1)                  ' Loop until end of file.

    MyChar = Input(1, #1)             ' Get one character.

    Debug.Print MyChar                ' Print to the Immediate window.


 Close #1                             ' Close file.



 ---End of Microsoft's version---