marcuslee
08-09-2008, 02:59
I've mentioned it passing in some other posts, so I guess I will address it directly here. I'm only majorly familiar with one other basic language: Liberty Basic. In my opinion, ThinBasic out does LB in many respects, though I think LB is a nice programming language, and their support is wonderful just like ThinBasic. One area that LB out shines TB is their help file.
Here is an online version of their help file for reference:
http://www.libertybasicuniversity.com/lb4help/
Of course, LB can't do as much as TB, so I wouldn't expect the TB help file to be 100% correct and up-to-date all the time. But, there seems to be many gaps. In my humble opinion, at a very minimum for each keyword, function, equate there should be a general description and the form of the syntax. At times when the syntax isn't clear or there are many things that can be done with the keyword, function or equate, there probably needs to be at least one example. More than one example would be nice as well ... if the extra examples help.
I know this is a momumental task. But, the help file is the only flaw I see with ThinBasic. There are somethings that you may not like, so you may choose another language for that reason, but there is nothing wrong with TB ... except for the help file.
However, I am not going to gripe without offering a solution. I am willing to spend some time fixing this. I'll be the first to admit that I am a very amateur programmer, but I am willing to write some help file pages from information I get from this forum. I would be willing to submit page additions or corrections for approval. Or, if it isn't me actually writing the articles for the help file, I am more than willing to suggest such additions or corrections.
But, my suggestions are numerous, so I don't want to inundate this forum. With that in mind, I will start my project by listing the pages that need something right here in this message. I will give a brief explanation of what I think is missing. I don't expect everything to be fixed. There is way too much to do that. But, it will give us a place to start.
General Observations
I started looking at the top of the alphabetical index. I quickly noticed that there doesn't seem to be a page to describe the use of predefined equates. I think this could be done on one page total or one page per module ... with examples of how to use some of the more common ones but definitely examples for the ones that are unique and/or don't work like the others work. I will not list individual equates in this list.
If someone has written a good example using a keyword, function, etc ... it would be helpful to be listed in the help file. Or, at least a link to where it is posted on the forum would be nice.
Pages that introduce a module mention keywords but don't list any.
Specific Observations
#DEF / %DEF
[o]Good description and syntax
Just a question that would be helpful if answered in help file:
[o]what is the difference between % and # versions?
#INCLUDEDIR
[o]No Description
[o]No Syntax
I assume this is used to include all the files of a certain directory, but the help file gives no clues as to its purpose.
animate_play
[o]No information whatsoever
[o]misspelled in the index
animate_open
[o]No information whatsoever
animate_stop
[o]No information whatsoever
app
[o]Only contains a description, no further details.
[o]Might be helpful to contain links to the mentioned functions.
APP_MutexClose AND APP_MutexCreate
[o]Maybe it's just me, but there should be a definition of what a mutex is ... either on these pages or with its own introduction page.
APP_Source AND APP_Script pages
[o]Is there a difference between Source and Script versions?
[o]Either way, it might be helpful to have a remark stating the difference or the sameness.
APP_SourceVersion
[o]The syntax section doesn't contain the Source version.
appendtotop
[o]Do you mean "Before" when you say in the description: "adding new text to the top current one" ?
[o]If so, you may want to word this description this way: "Change the text in a dialog control adding the new text before the current text." (suggested changes are in bold)
[o]This suggestion also applies to: CONTROL_AppendText
Array (I don't know why this one isn't being displayed correctly!)
[o]Only contains a description, no further details.
[o]Might be helpful to contain links to the mentioned functions.
attach AND bar
[o]An example might be helpful with this one. Maybe an example of the entire menu structure of a dialog.
[o]The example could be on its own page, and all the menu element pages could link to it.
BIFF
[o]The page links to an empty page of equates.
[o]If there aren't any equates for this module, that part of the phrase probably should be there, not to mention the empty page.
[o]More information on what type of excel files are created using BIFF might be helpful.
[o]Examples showing how to use this would be helpful.
thinBundle
[o]More description of how this works is missing. But, of course, you say that in the help file, so it's not so bad. ;)
CALL DWORD
[o]The description is there but simple. Even with the example (which is good), I couldn't follow what CALL DWORD does. A little more detailed description might be in order.
CALL_IfExists
[o]The documentation on this one is fine ... except it might be helpful in the remark section if a description of when this function call might be preferred. Why would you use it? What type of situation?
check (Get and Set)
[o]Possible variable values would be helpful.
CHOOSE and CHOOSE$
[o]An example showing how this might be used would be nice. It seems this would work well with having the user choose something or having something evaluted with a function or other expression.
client DESKTOP
[o]Is this similar to screen resolution? A little more detail might be helpful here.
COM
[o]Except for a little description on the intro page, there is NO INFO on COM.
[o]None of the function pages have any information that I can see.
[o]However, there is an equate page! ???
Command Line
[o]What are the optional parameters?
common dialogs
[o]No info what so ever!
Console
[+]There are several console function pages that have no info:
[o]Alloc
[o]AreFileApisANSI
[o]attach
[o]disableCtrlC
[o]enableCtrlC
[o]free
[o]generateCtrlEvent
[o]getCP
[o]getCurrentFontIndex
[o]getNumberOfMouseButtons (This one is probably self-explanatory ... but it doesn't matter.)
[o]getOutputCP
[o]getProgressbarChar
[o]getStdHandle
[o]setActiveScreenBuffer
[o]setCP
[o]setFileApisToANSI
[o]setFileApisToOEM
[o]setOuputCP
[o]setProgressbarChar
[o]setStdHandle
controls
[o]No info, no lists, no nothing!
CreateFont
[o]No info, no lists, no nothing!
[+]TO BE CONTINUED ...
_________________________________________________
I think that is enough for right now. I can pick up the list with the D's another time.
Once again I would like to reiterate that I am not asking all of these things to be fixed. In fact, I am offering to help fix them in some fashion or form. Just let me know what you would like me to do. Remember: discussing some of these things in the forums will give me or someone else ample material to write descriptions, syntaxes and the like. I can submit them in whatever form you would like.
If the help file is updated in this fashion, there is ABSOLUTELY NOTHING holding thinBasic back from becoming the best Basic programming language ever ... in my humble opinion.
Mark :-\
Here is an online version of their help file for reference:
http://www.libertybasicuniversity.com/lb4help/
Of course, LB can't do as much as TB, so I wouldn't expect the TB help file to be 100% correct and up-to-date all the time. But, there seems to be many gaps. In my humble opinion, at a very minimum for each keyword, function, equate there should be a general description and the form of the syntax. At times when the syntax isn't clear or there are many things that can be done with the keyword, function or equate, there probably needs to be at least one example. More than one example would be nice as well ... if the extra examples help.
I know this is a momumental task. But, the help file is the only flaw I see with ThinBasic. There are somethings that you may not like, so you may choose another language for that reason, but there is nothing wrong with TB ... except for the help file.
However, I am not going to gripe without offering a solution. I am willing to spend some time fixing this. I'll be the first to admit that I am a very amateur programmer, but I am willing to write some help file pages from information I get from this forum. I would be willing to submit page additions or corrections for approval. Or, if it isn't me actually writing the articles for the help file, I am more than willing to suggest such additions or corrections.
But, my suggestions are numerous, so I don't want to inundate this forum. With that in mind, I will start my project by listing the pages that need something right here in this message. I will give a brief explanation of what I think is missing. I don't expect everything to be fixed. There is way too much to do that. But, it will give us a place to start.
General Observations
I started looking at the top of the alphabetical index. I quickly noticed that there doesn't seem to be a page to describe the use of predefined equates. I think this could be done on one page total or one page per module ... with examples of how to use some of the more common ones but definitely examples for the ones that are unique and/or don't work like the others work. I will not list individual equates in this list.
If someone has written a good example using a keyword, function, etc ... it would be helpful to be listed in the help file. Or, at least a link to where it is posted on the forum would be nice.
Pages that introduce a module mention keywords but don't list any.
Specific Observations
#DEF / %DEF
[o]Good description and syntax
Just a question that would be helpful if answered in help file:
[o]what is the difference between % and # versions?
#INCLUDEDIR
[o]No Description
[o]No Syntax
I assume this is used to include all the files of a certain directory, but the help file gives no clues as to its purpose.
animate_play
[o]No information whatsoever
[o]misspelled in the index
animate_open
[o]No information whatsoever
animate_stop
[o]No information whatsoever
app
[o]Only contains a description, no further details.
[o]Might be helpful to contain links to the mentioned functions.
APP_MutexClose AND APP_MutexCreate
[o]Maybe it's just me, but there should be a definition of what a mutex is ... either on these pages or with its own introduction page.
APP_Source AND APP_Script pages
[o]Is there a difference between Source and Script versions?
[o]Either way, it might be helpful to have a remark stating the difference or the sameness.
APP_SourceVersion
[o]The syntax section doesn't contain the Source version.
appendtotop
[o]Do you mean "Before" when you say in the description: "adding new text to the top current one" ?
[o]If so, you may want to word this description this way: "Change the text in a dialog control adding the new text before the current text." (suggested changes are in bold)
[o]This suggestion also applies to: CONTROL_AppendText
Array (I don't know why this one isn't being displayed correctly!)
[o]Only contains a description, no further details.
[o]Might be helpful to contain links to the mentioned functions.
attach AND bar
[o]An example might be helpful with this one. Maybe an example of the entire menu structure of a dialog.
[o]The example could be on its own page, and all the menu element pages could link to it.
BIFF
[o]The page links to an empty page of equates.
[o]If there aren't any equates for this module, that part of the phrase probably should be there, not to mention the empty page.
[o]More information on what type of excel files are created using BIFF might be helpful.
[o]Examples showing how to use this would be helpful.
thinBundle
[o]More description of how this works is missing. But, of course, you say that in the help file, so it's not so bad. ;)
CALL DWORD
[o]The description is there but simple. Even with the example (which is good), I couldn't follow what CALL DWORD does. A little more detailed description might be in order.
CALL_IfExists
[o]The documentation on this one is fine ... except it might be helpful in the remark section if a description of when this function call might be preferred. Why would you use it? What type of situation?
check (Get and Set)
[o]Possible variable values would be helpful.
CHOOSE and CHOOSE$
[o]An example showing how this might be used would be nice. It seems this would work well with having the user choose something or having something evaluted with a function or other expression.
client DESKTOP
[o]Is this similar to screen resolution? A little more detail might be helpful here.
COM
[o]Except for a little description on the intro page, there is NO INFO on COM.
[o]None of the function pages have any information that I can see.
[o]However, there is an equate page! ???
Command Line
[o]What are the optional parameters?
common dialogs
[o]No info what so ever!
Console
[+]There are several console function pages that have no info:
[o]Alloc
[o]AreFileApisANSI
[o]attach
[o]disableCtrlC
[o]enableCtrlC
[o]free
[o]generateCtrlEvent
[o]getCP
[o]getCurrentFontIndex
[o]getNumberOfMouseButtons (This one is probably self-explanatory ... but it doesn't matter.)
[o]getOutputCP
[o]getProgressbarChar
[o]getStdHandle
[o]setActiveScreenBuffer
[o]setCP
[o]setFileApisToANSI
[o]setFileApisToOEM
[o]setOuputCP
[o]setProgressbarChar
[o]setStdHandle
controls
[o]No info, no lists, no nothing!
CreateFont
[o]No info, no lists, no nothing!
[+]TO BE CONTINUED ...
_________________________________________________
I think that is enough for right now. I can pick up the list with the D's another time.
Once again I would like to reiterate that I am not asking all of these things to be fixed. In fact, I am offering to help fix them in some fashion or form. Just let me know what you would like me to do. Remember: discussing some of these things in the forums will give me or someone else ample material to write descriptions, syntaxes and the like. I can submit them in whatever form you would like.
If the help file is updated in this fashion, there is ABSOLUTELY NOTHING holding thinBasic back from becoming the best Basic programming language ever ... in my humble opinion.
Mark :-\