Around p. 70-71 Html.get.datalink: several questions (should these be separate issues?). While I can claim some knowledge of most of the other BASIC! features, I'm entirely ignorant of what happens with a datalink. Having said that, . . . .

1. Current description says: " The returned data string will always start with a specific set of four characters." But 5 of the 6 sets of characters are 3-character strings. Is this right?
2. Are the character strings correct? (Is the fourth one FOR or FORM? How about the rest?)
3. There is no information about how to extract the information following the initial character strings. Should that be obvious to the BASIC! Programmer or is there some additional information needed?

Within the set of Bluetooth commands

bt.disconnect

Disconnects from the previous connected Bluetooth device and goes into the listen moded. Avoids having to use bt.close + bt.open to disconnect and wait for a new connection.

Around p. 65, the command: File.Size <size_nvar>, <Path_sexp> is discussed. The current text says:

The size, in bytes, of the file at <Path_sexp> will be returned in <size_nvar>.
The default path is “/sdcard/rfo-basic/data/”.

My question is what happens if there is no file at <Path_sexp>?

The description of the Gr.get.bmpixel command (around p. 102) is incomplete. Can you provide the ending?

Gr.get.bmpixel bitmap_ptr, x, y, alpha, red, green, blue

Returns the color data for the pixel of the specified bitmap at the specified x, y coordinate. The x and y values must not exceed

Around p. 69, the Byte.read.buffer command had an ambiguity in the description. The last sentence said: "If the end of file has been reached, the length string, len(buf$), will be zero." I changed it to: "If the end of file has been reached, the length string, len(<buffer_svar>), will be zero." Did I miss something?

In the manual for v01.70, on page 19, it says:

Line Continuation
A BASIC! source code line may be written on more than one physical line using the line continuation character “_”

Please change it to say something like this (feel free to improve my wording):

Line Continuation
A BASIC! source code line may be written on more than one physical line using the line continuation character-pair “//”. If "//" is the last thing on a line, except optional spaces, tabs, or a '%' comment, the line will be merged with the next line.
Note: this operations is implemented by a pre-processor which changes the source the code before it is run. If you have a syntax error in the merged line, it will show as one line in the error message, but it will still be multiple lines in the editor. Only the first physical line will be highlighted, regardless of which line the error is in.

In the example that follows, the "_" should be replaced with "//". I think a following inline comment or two would be illustrative as well.

For example, the code line:
    s$ = "The quick brown fox " + verb$ + " over " + count$ + " lazy dogs"
could be written as:
    s$ = "The quick brown fox " +//
        verb$ +     //       % what the fox did
        " over " +  //
        count$ +    //       % how many lazy dogs
        " lazy dogs"

Please note the simple upright double quotation marks. Don't use different open and close double quotation marks in the example if you can avoid them, since the BASIC! editor does not.

Later on, on pages 38 and 39, this note appears:

Note: these operations are implemented by a pre-processor which changes the source the code before it is run. If you have a syntax error in a line that contains these operators, the code line will look different.

Please add to the first (page 38, under Pre- and Post-Increment Operators):

You can not combine any of these operators with each other or with any assignment operator (=, +=, etc.).

And to the second (page 39, under Op Equal Assignment Operators):

If you use one of these operators, you can not use any of the Pre- and Post-Increment Operators on the same line.

The Gps.bearing command says: Returns the bearing in . All other returns indicate the units (decimal degrees, meters, meters/second). What are the units for the bearing?

I don't understand the text in the description of the HTML mode in the Speech to Text area, around p. 81. My difficulty is understanding the flow of information with the datalink command. In HTML mode, where is the "Listen" function initiated? The BASIC! program? Somewhere on the HTML page? At which point does the information go to the Google server? Obviously I'm entirely confused. If this will be clear to the programmer who is knowledgeable about speech-to-text, perhaps we shouldn't worry about it (or maybe provide a link to a more complete description).

There is a section in Appendix D, Preferences, that has not been merged into the manual.

Preferences is between Permissions and Launch at device boot.

Around p. 70 Html.post:

Changed the parameter names from "url$" and "list" to and <list_nexp>. Idea is to make them consistent with rest of the parameters. Is that OK. Are they the proper form?

It seems to me that there is an inconsistency in how the manual treats logical numbers/values/expressions. It is clear that there are really only two kinds of value: numerical and string, but in various places (examples provided on request) the manual distinguishes logical expressions (wherever we see {lexp}) and variables (generally, but not always, as {Boolean_nvar}) from other numerical expressions and variables.

It seems to me to be useful to continue to make the distinction as long as we say clearly that logical variables and expressions are technically a form of numerical variables and expressions. I'd propose that we add the term {lvar} to replace {Boolean_nvar} wherever it (and its close relatives) appears, since we already use {lexp} quite liberally. This would clear up inconsistencies throughout the manual.

Basic will give RunTImeError: "Open Bluetooth BEFORE opening graphics." If...

gr.open 255,0,0,200
bt.open

If it is needed to close and open bluetooth while in graphics mode:
gr.front 0
bt.close
bt.open
gr.front 1

************* Disregard this issue for now ********************

The Paint object includes all paint related information in addition to the color. This includes font size, style and so forth. Each command that effects the current paint object (gr.color, gr.text.size, etc) first inherits the current paint and then modifies it to make a new paint object which then becomes the current paint object.

If you want to modify any of the paint characteristics of an object then you will need to create a current paint object with those parameters changed.

Code:
gr.color 255,0,255,0,0
gr.text.size 20
gr.text.align 2
gr.paint.get the_paint
gr.modify shot, "paint", the_paint

changes the current text size and alignment as well as the color.

In the descriptions of the RANDOMIZE and RND functions, would it be appropriate to use the phrase "pseudorandom number generator" somewhere? The point is not to emphasize the "pseudo" but simply to make it clear that we understand what it is we're doing.

Currently the overall description of the two encrypt/decrypt commands is "Encrypts and decrypts a string using a supplied password." Is this enough of a description? Should we identify the algorithm or process? Or perhaps provide a link to something that describes the process?

On page 44:

ASCII(<sexp>)
Returns the ASCII value of the first character of <sexp>. If <sexp> is an empty string ("") the value
returned will be 256.

Change it to:

ASCII(<sexp>)
Returns the ASCII value of the first character of <sexp>. A valid is ASCII value is between 0 and 255.
If <sexp> is an empty string ("") the value returned will be 256. For non-ASCII Unicode characters,
ASCII() returns invalid values; use UCODE() instead.

Right after that, add:

UCODE(<sexp>)
Returns the Unicode value of the first character of <sexp>. If <sexp> is an empty string ("") the
value returned will be 65536 (one more than the largest 16-bit Unicode value). For a valid ASCII
character, this function returns the same value as ASCII().

Would it help to add "(one more than the largest 8-bit ASCII value)" after "256" in the ASCII() paragraph?

I added this command when a forum user requested an inverse of the CHR$() function that would work for Unicode. UCODE() is always the the inverse of CHR$(): UCODE(CHR$(x) = x for all non-negative x < 65536 (hex 10000). ASCII() is also the inverse of CHR$(), but only for valid ASCII characters (x < 256). I don't know if that's worth saying or not. If it is, we may want to add a related comment to the CHR$() function description.

On page 128, change
from: The procedure for making a Shortcut Application
to: The procedure for making a Shortcut Application(Older versions of Android)

Add after step 13:

The procedure for making a Shortcut Application (Newer Versions of Android)

1. Select the Apps Page.
2. At the top of the screen, tap Widgets.
3. Scroll horizontally until you see the BASIC! icon that says Launcher Shortcuts.
4. Touch and hold that entry. It will be moved to the Home page.
5. Continue with step 8, above.

At the end of the first paragraph describing gr.bounded.touch, the last sentence is "The command will continue to return true as long as the screen remains touched." It isn't clear whether the sentence should read "The command will continue to return true as long as the screen remains touched and the touch is within the bounding rectangle." Should I make that change?

The final sentence in the Manual in the Bt.reconnect section ("The command cannot be used to reconnect to a device that was connected in the Listen Mode.") is not clear to me. Is there another way to say that?

In the narrative concerning BT around p. 76), the text talks about both bt.state and bt.status commands. From looking at the remainder of the section, and the meaning of the narrative, I've concluded that there is only one status command: bt.status, and I've changed the one mention of bt.state to bt.status. Please let me know if this is not correct.

"Extensive use of goto in your program should be generally avoided, because
it consumes excessive system resources. It's present in Rfo basic for compatibility reasons
with old basic dialects.
You should use structured elements like do..until while...repeat ....
in conjunction with f_n.break, etc.
Especially in the case of gotos from inside a IF/ELSE/FOR block to code outside of the block. It consumes many system resources.
This practice may lead your program to a run time error: "Stack overflow. See manual about use of GOTO."

Please add:

socket.client.close

• Closes an open client side connection

socket.client.server.ip

• returns the IP of the server that this client is connected to.

Looks like we need to be clearer about how '' in ARRAY.LOAD and LIST.ADD is different from '' everywhere else. I'd hoped to avoid this, but Nick tried a clever application of '~' in the tutorial and it didn't work.

Referring to v01.71:

On page 19, first paragraph after the "Line Continuation" heading, add:

This behavior is slightly different in the Array.load and List.add commands; see the descriptions of those commands for details.

On page 30, near the top, just before the examples, after "ending the line with the “~” character.", add:

The "~" character may be used between parameters, where a comma would normally appear. It may not be used to split a parameter across multiple lines.

On page 32, near the bottom, just before the examples, same change as on page 30.

As always, feel free to improve my wording.

In the two paragraphs about Drawing into Bitmaps (around p. 92), we do not say when the bitmap.draw command needs to be executed. I would infer it should be between the gr.bitmap.drawinto.start command and the gr.bitmap.drawinto.end command, but that is not said explicitly? Is it true? In either case (true or false) we probably should say where the bitmap.draw command should be included.

Some commands in the manual begin with a lower-case alpha character and some begin with an upper-case alpha character. For example, we have ftp.close (and all other ftp.* commands) but we also have Html.close (and all other Html.* commands). Is there a pattern here? A reason why some should be upper case and others lower case? If there is no particular reason, perhaps I could make all commands look the same way. And if so, is there a preference for initial upper or initial lower?

Around p. 72 Third paragraph of TCP/IP Sockets starts with "Most people who use a FTP/IP . . . ." Should that be TCP/IP?

Add after "Editor Autoindent" on page 23:

Base Drive
Some Android devices have more than one external storage devices. BASIC! will use the system suggested device as its base drive. The base drive is the device where the BASIC! “rfo-basic” directory is located. The “rfo-basic” directory is where BASIC!’s programs and data are stored. If you want to use a different storage device as BASIC!’s base drive, you can change it here.
If your device does have more than one external storage device they will be listed here. Tap the device you want to use as the base directory and press the BACK key. You will then be given the choice to immediately restart BASIC! with the new base drive or waiting and doing the restart yourself.

Note: If you have created a shortcut with files in one base directory but try to execute that shortcut while using a different base directory, the shortcut will fail to execute. You will get an error message.

Unless I'm doing something wrong, when I use the format:
Sql.new_table DB_Pointer_nvar, DB_Name_sexp, Table_Name_sexp, C1$, C2$

I get a table with the name specified in DB_Name_sexp
and columns named Table_Name_sexp, C1$, C2$.

The onConsoleTouch: and consoleTouch.Resume are not marked for indexing and thus do not appear in the command list.

onGRTouch: is currently marked as ontouch. It should be remarked.
Gr.onGRTouch.Resume is currently marked at onTouchResume. It should be remarked.

The sensor table (page 115 in v01.72) should have another line for "Relative Humidity". The Type is 12.

In the section on the Editor, we learn that the line continuation character is the underscore "_". Beginning in the section on Arrays, continuing at least into the section on Lists, we learn that the line continuation character is the tilde "~". Are both correct (I know I could try them out and find out), but I'm wondering whether this is a problem. If there is a difference in usage between them, what is the difference?

Under the auspices of Basic issues 1 and 62, I've changed one socket command and added three new ones (but not the one named in the issue title!).

Socket.server.connect (on page 74 in v01.72 manual) has changed.

The command now has an optional "wait" parameter: Socket.server.connect {<wait_nexp>}

The second sentence of the description is no longer complete: It says, "This command will not return until a connection is made with a Client." Now, if the optional numeric parameter evaluates to 0, the command completes immediately. If the parameter has any other value, or does not exist, the command waits until the connection is made. Effectively, the default value of the parameter is 1. Usually the default is a preferred value, but in this case it is chosen for backward compatibility and the preferred value is 0.

Suggested wording, with the format taken from BT.connect:

The optional "wait" parameter determines if the command waits until a connection is made with a Client. If no parameter is given, or if the parameter value is non-zero, the command waits for the connection. If the parameter evaluates to 0, the command completes immediately. Use Socket.server.status to determine when the connection is made.

I'd like to say somewhere that it is "better" to set the parameter to 0 and monitor status. "Better" here means safer, or more robust, since it can avoid a problem if the program exits with no connection made. Would something like that go here, or in the opening section on TCP/IP Sockets -- again, the precedent might be the Bluetooth section.

It seems like there is a missing section of the description of Bt.open (around p. 77). Using the parameter can determine whether to "listen for a secure or insecure connection. If no parameter is given or if the parameter is 1, then a secure connection request will be listened for. Otherwise, an insecure connection will be listened for."

What if the programmer wants the device to listen for any connection--secure or insecure? It would seem like that might be an option, after which the programmer might (but might not) wish to check for whether the connection that has been opened is secure or insecure. Of course there might be something in the underlying BT code that doesn't permit it, but in either case, it would seem useful to add a few sentences. If it can be done, how; if it can't be done, why.

BT.status command, on page 79 in v01.72, lists connection status values. I changed the command in December (Basic issue 47) and missed the change in the manual.

Before 0= Nothing going on, please insert -1= Bluetooth not enabled.

In the second paragraph of gr.screen width (around p. 94), we say "This command should be executed after the execution of any gr.orientation command. This is because the gr.orientation command swaps the height and width." The second sentence does not really answer the question of why the first sentence is true. At least it doesn't to me. It seems like there's a missing sentence or two.

From the BASIC! forum by jMarc

Paul, I noticed today the "Using a user function as a parameter for a user function call" workaround is still in the manual (page 49 of the 01.70 version). That was put in to cover the "function as parameter" anomaly paulon0n found. We got that fixed last month, so the workaround can come out of the manual now.

You say that if a file is to be opened for read, <File_table_nvar> will be set to -1. Are there any errors associated with "write" or "append"? In other words, if a file is to be opened for append, is it an error if the file doesn't exist? What happens if a file being opened for write already exists?

If bt.open in graphics mode (after gr.open), insert a "pause 500" statement after the bt.open.

The Gps.bearing command says: Returns the bearing in . All other returns indicate the units (decimal degrees, meters, meters/second). What are the units for the bearing?

For the various trig functions, are the angles measured in degrees or radians? I understand that one can convert from one to the other, but shouldn't we say what the expected units are?

in v01.70:
"gr.bitmap.draw Object_ptr, bitmap_ptr, x , w
Creates and inserts a bitmap object into the Object List. The bitmap will be drawn with its upper left corner at the provided (x,y) coordinates."

Should be gr.bitmap.draw Object_ptr, bitmap_ptr, x , y instead of w

The text concerning ThinkFree Office Mobile Viewer (current full name of the free version) around p. 79, in the description of the Browse command may be in error. The current version of the free version does not appear to support all the files claimed on p. 79, According to the Google Play description, "Updated Version shows office related files only". I'm going to install it and see.

Into the section with onBackKey, etc around page 54...

onConsoleTouch:
Tapping on any line on the output Console that has text on it will cause control to be transferred to this label. Note that touch must be some printed line of text. Any line of text. It can not be an empty area of the screen.

The primary intent of this interrupt is provide a means of allowing the user to asynchronously interrupt an executing BASIC! program (not in graphics mode) for some purpose. A common purpose would be to have the program request input via an INPUT statement. See the Sample File, f35_bluetooth.bas, for an example of this.

For detecting screen touches while in graphics mode, use onGRtouch:

onConsoleTouch: must stand alone on the line.

consoleTouch.Resume
Resumes execution at the point in the BASIC! program where the touch occurred.

In addition, all mentions of "onTouch" should be changed to "onGRtouch"

The third sentence of gr.camera.select (around p. 104) seems incomplete:

"Gr.camera.select 1|2

"Selects the Back (1) or Front(2) camera in devices with two cameras. The default camera is the back (opposite the screen) camera. If the only camera is a Front Camera (as in the Nexus 7) then it will be the default camera."

It would seem that if a device has only one camera (back or front) then that will be the camera selected, independently of what is selected in the command. Is this true? If so, then we should say it more-or-less that way. If it's not true, we should say more about it.

On p. 99 in the discussion of onGRTouch, the escape command is "gr.onTouch.Resume". Should that be renamed gr.onGRTouch.Resume for consistency or any other reason?

You're all caught up -- no open issues -- so I have to open a new one for you. I gotta tell you, you're doing a great job. The manual looks really good.

I've added two commands. I think they should go in after Sql.next, but that's only a suggestion.

Sql.query.length <Length_nvar> <Cursor_nvar>
Report the number of records returned by a previous Query command, Given the Cursor returned by a Query, the command writes the number of records into <Length_nvar>. This command can not be used after all of the data has been read.
Sql.query.position <Position_nvar> <Cursor_nvar>
Report the record number most recently read using the Cursor of a Query command. Given the Cursor returned by a Query, the command writes the position of the Cursor into <Position_nvar>. Before the first Next command, the Position is 0. It is incremented by each Next command. A Next command after the last row is read sets its Done variable to true and resets the Cursor to 0. The Cursor can no longer be used, and this command can no longer be used with that Cursor.

In the middle of page 98 (v01.70 edition) this appears:

Traditional italics can be best imitated with n = -0.25gr.text.underline Boolean

The sentence should end at the "-0.25". The "gr.text.underline Boolean" should be a heading just like "gr.text.skew n" before and "gr.text.strike Boolean" after.

In the middle of page 100, this heading appears:

gr.bitmap.draw Object_ptr, bitmap_ptr, x , w

The "w" at the end should be a "y".

On page 93:

gr.screen width, height
Returns the screen's width and height in the variables. This command should be executed
after (not before) any gr.orientation command. This is because the gr.orientation command
swaps the height and width.

Please change it to:

gr.screen width, height {, density }
Returns the screen's width and height, and optionally its density, in the variables. The density,
in dots per inch (dpi), is a standardized Android density value (usually 120, 160, or 240 dpi),
and not necessarily the real physical density of the screen.

This command should be executed after (not before) any gr.orientation command. This is
because the gr.orientation command swaps the height and width.

In the description (around p. 104) we note that some cameras (like the one in the N7) do not have a built-in Camera Interface. If the device does not have any installed camera apps, then what happens when gr.camera.shoot bm_ptr is executed?

Forum user MrAl strikes again!

For reasons apparently well-understood by some, but not by me, the atan2 function takes the coordinate parameters in "y, x" order. MrAl determined it experimentally. The Java documentation agrees.

So: page 43 of the v01.71 manual, function ATAN2, header reads:
ATAN2 (<nexp_x>, <nexp_y>)

but should read
ATAN2 (<nexp_y>, <nexp_x>)

The descriptive text is unchanged, that is, "... coordinates (x, y) to ..." is correct.