It is currently Tue Jun 27, 2017 10:32 am



Welcome
Welcome to rfobasic

You are currently viewing our boards as a guest, which gives you limited access to view most discussions and access our other features. By joining our free community, you will have access to post topics, communicate privately with other members (PM), respond to polls, upload content, and access many other special features. In addition, registered members also see less advertisements. Registration is fast, simple, and absolutely free, so please, join our community today. **You are not required to provide truthful information to any registration questions. Be whomever you wish to be.!


Post new topic Reply to topic  [ 4 posts ] 
Author Message
 Post subject: A great improvement would be
Unread postPosted: Sun Jun 18, 2017 8:45 pm 
Offline

Joined: Thu Jun 01, 2017 1:40 pm
Posts: 9
The manual would be greatly improved by utilization of a standard approach.

For purposes if command reference typically expects to encounter three points of information for each command.

The command prototype. This will state in standard terms the command instantiation along with accepted variables and expected format and data types

{boolean} PRINT {"<string literal>" {,|;|+} <string object>}
Not this.
Print {<exp> {,|;}}

This is a crude and likely incorrect example. I attempted to use a format that is close to the manual's.

The next bit of information expected would be a detailed description of the command and its parameters. Notice in the example I indicated a return type. This should be one of the details included. Not simply the how but also the why. By reading this section the programer should have no questions about the operation of the command.

The third and most useful section sould be a live code example. Something the programmer can copy into their source code and run. The example should not be simplistic but should utilize all of the commands parameters. Typically one should expect to see multiple examples used in as many situations the designers intended.

Finally I am not comfortable with the general layout of the book. Some of the first things Encountered are arrays and array handlers. While I may agree that arrays are an important aspect of any language, I would try to explain data types and operators first.


Top
 Profile  
 
 Post subject: Re: A great improvement would be
Unread postPosted: Mon Jun 19, 2017 12:25 am 
Offline

Joined: Tue Dec 04, 2012 10:50 am
Posts: 659
Location: UK
jmrott wrote:
Finally I am not comfortable with the general layout of the book. Some of the first things Encountered are arrays and array handlers. While I may agree that arrays are an important aspect of any language, I would try to explain data types and operators first.

There's always a conflict between writing a reference manual in which things might be alphabetic (resulting in arrays coming first?) and tutorial. And for the latter, at what level to start. And whether to point out quirky features that might be unique to this dialect.

But then, who starts from scratch?

Mike.


Top
 Profile  
 
 Post subject: Re: A great improvement would be
Unread postPosted: Mon Jun 19, 2017 1:57 am 
Offline
User avatar

Joined: Wed Jul 10, 2013 8:11 am
Posts: 359
Hi jmrott,

jmrott wrote:

The third and most useful section sould be a live code example. Something the programmer can copy into their source code and run. The example should not be simplistic but should utilize all of the commands parameters. Typically one should expect to see multiple examples used in as many situations the designers intended.


Yes, that can be very useful.

What do you think about command dependent links in the manual to an online example offer.
But in any case someone have to choose the right examples. There are a lot in example programm delivered with BASIC!, in the forum and shared programs on the ftp server.

Are you able to support us. We can only offer work, ideas and a little applause. ;)

Happy coding
Gregor


Top
 Profile  
 
 Post subject: Re: A great improvement would be
Unread postPosted: Thu Jun 22, 2017 5:41 am 
Offline
User avatar

Joined: Sat Dec 08, 2012 2:14 am
Posts: 1147
Location: From Blighty
Well, there is no reason why a user contributed manual could not exist? If you had time you perhaps could do this yourself? I started a command reference guide, I made no promises though -- it's not been touched in ages...

Another aspect is the project developers with whom I am not speaking on their behalf, are extremely busy. I visit the forum almost daily, so have picked up on a lot of what is said.

I remember joking about a Borland manual here once, 'cos it really sent me to 'boreland'. I thought I'd start off with a cup of coffee first. But I ended up opening a bottle of wine in excruciating agony to kill the monotonous pain...

I think the current manual is written well, and we have program examples too in the Sample_Programs folder.

I think a lot of users here could contribute more to this project, that includes myself.

There's no reason myself that I couldn't go through my code snippets and at least for now put up suggestions here to add to the Sample_Programs folder.

Mog


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 4 posts ] 


Who is online

Users browsing this forum: No registered users and 1 guest


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
suspicion-preferred