Author |
Topic: Suggestions for the Manual (Read 1373 times) |
|
mohsen
New Member
member is offline
Gender: 
Posts: 39
|
 |
Suggestions for the Manual
« Thread started on: Nov 20th, 2008, 7:12pm » |
|
Suggestions for the Manual:
1. Possible Errors:
It would be good if at the end of each Keyword description page a paragraph is added "Possible Errors" which would list specific errors associated with that keword only.
Things like:
Bad use of array
Missing #
Missing ENDIF
Missing TO
etc.
2. will follow.
|
|
 Logged
|
|
|
|
mohsen
New Member
member is offline
Gender:
Posts: 39
|
|
Re: Suggestions for the Manual
« Reply #1 on: Nov 20th, 2008, 7:50pm » |
|
2. Page 396
Syntax for Keyword RETURN missing.
See page 396
Suggest following to be added:
ON MOVE [LOCAL] <stmt> { : <stmt> } : RETURN
ON MOUSE [LOCAL] <stmt> { : <stmt> } : RETURN
ON MOVE [LOCAL] <stmt> { : <stmt> } : RETURN
ON SYS [LOCAL] <stmt> { : <stmt> } : RETURN
ON TIME [LOCAL] <stmt> { : <stmt> } : RETURN
DEF PROC<name>[( [RETURN] <s-var>|<n-var> { , [RETURN] <s-var>|<n-var> } ) ]
DEF FN<name>[( [RETURN] <s-var>|<n-var> { , [RETURN] <s-var>|<n-var> } ) ]
which appear under the other associated Keywords.
Note: above DEF Syntax includes the [RETURN] keyword which is not indicated in the Manual's Syntax for the Keyword DEF.
|
|
Logged
|
|
|
|
mohsen
New Member
member is offline
Gender:
Posts: 39
|
|
Re: Suggestions for the Manual
« Reply #2 on: Nov 20th, 2008, 7:59pm » |
|
3. Page 240 (DATA Keyword)
Suggest to add the following statements:
In order to be recognised by the interpreter, the DATA statement, should be the first on a line.
If DATA is encountered during programme execution, the rest of the line is ignored.
|
|
Logged
|
|
|
|
admin
Administrator
member is offline
Posts: 1145
|
|
Re: Suggestions for the Manual
« Reply #3 on: Nov 20th, 2008, 9:46pm » |
|
Quote:| Syntax for Keyword RETURN missing. Suggest following to be added |
|
Your suggestion makes rather a nonsense of the use of hyperlinks in the manual. Since the section on RETURN has links to the sections on ON MOVE, ON MOUSE etc. it's wasteful and unnecessary to duplicate the information under RETURN as well. If you did that everywhere, the manual would be twice as long as it is.
In any case, the syntax for the RETURN statement is fully and accurately stated already: it is RETURN!
One reason for a printed manual not being available is its dependence on hyperlinks, which can't be solved by tweaks of the sort you have proposed. The entire manual would have to be restructured from beginning to end if it was to make sense on paper.
Richard.
|
|
Logged
|
|
|
|
mohsen
New Member
member is offline
Gender:
Posts: 39
|
|
Re: Suggestions for the Manual
« Reply #4 on: Nov 20th, 2008, 11:05pm » |
|
on Nov 20th, 2008, 9:46pm, Richard Russell wrote:Your suggestion makes rather a nonsense of the use of hyperlinks in the manual.
Richard.
|
|
What hyperlinks? There are no hyperlinks in the manual !!! Not even a single one.
|
|
Logged
|
|
|
|
mohsen
New Member
member is offline
Gender:
Posts: 39
|
|
Re: Suggestions for the Manual
« Reply #5 on: Nov 20th, 2008, 11:28pm » |
|
on Nov 20th, 2008, 9:46pm, Richard Russell wrote:In any case, the syntax for the RETURN statement is fully and accurately stated already: it is RETURN!
Richard.
|
|
I do not accept your statement that the Syntax for RETURN statement is what is indicated on page 396 by simply stating
Syntax:
RETURN.
If you are to apply that logic then please correct the Syntax for the Keyword BY, which currently reads:
DRAW BY <numeric>,<numeric>
FILL BY <numeric>,<numeric>
MOVE BY <numeric>,<numeric>
PLOT BY <numeric>,<numeric>
and replace it with the single word "BY". The user then should go look up the usage under the Keywords DRAW, FILL, MOVE and PLOT.
The same would also need to be corrected for the other Keywords such as FILL, THEN, etc.
It is just inconsistent to find on one page an example and/or a syntax of how the keyword is associated with other statements and at another place, the user needs to search for keyword usage on different pages.
|
|
Logged
|
|
|
|
admin
Administrator
member is offline
Posts: 1145
|
|
Re: Suggestions for the Manual
« Reply #6 on: Nov 21st, 2008, 08:48am » |
|
Quote:| There are no hyperlinks in the manual !!! Not even a single one. |
|
Both the HTML and CHM (HTML Help) versions of the manual have hundreds, probably thousands, of internal links. They are vitally dependent on them, as I said.
I notice you keep referring to page numbers. The only version of the manual which has page numbers is the PDF file, intended for those who insist on having a printed copy. If you're trying to read the PDF version on screen don't do that, it's entirely unsuitable for that purpose.
Always use the CHM version for reading locally or the HTML version for reading on line.
Quote:| If you are to apply that logic then please correct the Syntax for the Keyword BY |
|
BY is not a statement. I suggest you investigate the difference between a statement and a keyword.
You obviously wish that BB4W and its documentation were different from what they are. That is your prerogative, but since neither of them are going to change it is simply a recipe for continued disappointment on your part. Perhaps you would be happier using Virtual Acorn (or VRPC) or Brandy rather than BBC BASIC for Windows.
If you are sufficiently dissatisfied with BB4W that you would like your payment to be refunded please let me know privately.
Richard.
|
|
Logged
|
|
|
|
mohsen
New Member
member is offline
Gender:
Posts: 39
|
|
Re: Suggestions for the Manual
« Reply #7 on: Nov 21st, 2008, 11:07am » |
|
on Nov 21st, 2008, 08:48am, Richard Russell wrote:BY is not a statement. I suggest you investigate the difference between a statement and a keyword.
Richard. |
|
I did not say that "BY" is a statement. Please indicate where I said so.
The RETURN keyword is a statement but also a Modifier in the PROC/FN parameter list. Which I understand that you do not acknowledge that and therefore the reason it is not listed as part of the DEFPROC/DEFFN.
Nevermind, as you stated before, you do not have the time, resources, motivations, etc. to correct or improve the application and that the application life has ended in 2006, I can understand your frustration from the responses.
By the way, this thread is intended as "Suggestions" to the manual. They are not obligations, and do not mean that you personally have to do changes. May be someone else could do that.
It could also be of help or interest to others.
You are not obligated to answer and respond to every message.
Do not always assume that those who point things to your work to correct or suggest are your enemies or are dissatisfied, you may be surprised when you know the truth.
I do not believe it is professional from a supplier to tell the customer : "it is my way or the highway, do not make comments, or else here is your money back".
|
|
Logged
|
|
|
|
admin
Administrator
member is offline
Posts: 1145
|
|
Re: Suggestions for the Manual
« Reply #8 on: Nov 21st, 2008, 12:44pm » |
|
Quote:| I did not say that "BY" is a statement. Please indicate where I said so. |
|
You implied it, in comparing its syntax description with that of RETURN. RETURN is a statement; its syntax can be expressed accurately and completely by the single word RETURN. BY isn't a statement; its syntax can only be described in the context of the statements with which it is used. That is why the syntax descriptions differ; there is no inconsistency between them.
Quote:| Nevermind, as you stated before, you do not have the time, resources, motivations, etc. to correct or improve the application and that the application life has ended in 2006 |
|
The application hopefully has a lot of life left in it. I take the strong view that a programming language is strengthened, not weakened, by being stable and not being frequently 'updated'. It is far more valuable for me to spend my time supporting the language than by modifying it.
Most Acorn versions of BBC BASIC were committed to ROM, and cannot be updated. That doesn't stop them still being widely used.
I am absolutely determined to "correct" the application as and when any bugs are identified. None of the comments you have made amount to a bug or fault being present.
Quote:| You are not obligated to answer and respond to every message. |
|
I am, to the extent that I don't want what I believe to be unjustified criticisms to go unchallenged.
Quote:| I do not believe it is professional from a supplier to tell the customer : "it is my way or the highway, do not make comments, or else here is your money back". |
|
What alternative do I have? I don't like to have dissatisfied customers. In over seven years of BBC BASIC for Windows being on the market I have never before received such a sustained barrage of criticism of the product and its documentation.
We truly live in a topsy-turvy world if you consider my (genuine) offer to refund your payment to be "unprofessional".
Richard.
|
|
Logged
|
|
|
|
|
