Restored from previous forum. Originally posted by fred.
Dear PureBasic Users,
I've read somewhere than the PureBasic doc is not good etc... I do my best to write it as complete as possible, but:
- I'm not english (so writing english doc is long to me and full of mistake)
- I know PureBasic perfectly (so I write bad doc assuming than such and such stuffs are obvious)
PureBasic is now over 500 commands, v3.30 will have a Linux version updated (currently working on it) and it would be cool to have a v3.30 doc which rocks. I've setuped a CVS directory (cvs.purebasic.com) where all the docs are in raw format. To know more about CVS, read the help in cvs.purebasic.com/Help/CvsHelp.txt.
If some of you want really help, I can create an account on the cvs directory, allowing to commit changes to any files on the cvs. CVS allows several users working on the same file at the same time, which is a great stuff.
The jobs for now are:
- Spell check the english docs
- Continues the french translation (60% done) and spell check current french one (but should be rather ok).
- Add an example for example commands
- All the stuffs you could imagine
If you're seriously interrested, contact me directly at [url]mailto:fred@purebasic.com[/url]
Thanks in advance !
Fred - AlphaSND
Documentation Help
-
BackupUser
- PureBasic Guru
- Posts: 16777133
- Joined: Tue Apr 22, 2003 7:42 pm
Restored from previous forum. Originally posted by Justin.
If you are on the works i suggest to follow the standard scheme for the functions, like msdn, VB, Delphi..
This makes the help file much more readable, i understand that is a lot of work to rewrite the help file, just an opinion.
Something like:
Description
what the function does
Sintax
here goes the function syntax..
Parameters
separate description of each parameter
Returns
return value
Remarks
additional explanation if any
Example
just if the help file is really oriented to beginners, but examples of some functions are always needed.
Edited by - Justin on 25 June 2002 15:17:44
Edited by - Justin on 27 June 2002 11:34:39
If you are on the works i suggest to follow the standard scheme for the functions, like msdn, VB, Delphi..
This makes the help file much more readable, i understand that is a lot of work to rewrite the help file, just an opinion.
Something like:
Description
what the function does
Sintax
here goes the function syntax..
Parameters
separate description of each parameter
Returns
return value
Remarks
additional explanation if any
Example
just if the help file is really oriented to beginners, but examples of some functions are always needed.
Edited by - Justin on 25 June 2002 15:17:44
Edited by - Justin on 27 June 2002 11:34:39
-
BackupUser
- PureBasic Guru
- Posts: 16777133
- Joined: Tue Apr 22, 2003 7:42 pm
Restored from previous forum. Originally posted by tinman.
And Fred, that link did not work - I had to go to cvs.purebasic.com then manually go through the links.
--
It's not minimalist - I'm increasing efficiency by reducing input effort.
(Win98first ed. + SP1, PB3.20)
Edited by - tinman on 25 June 2002 15:15:12
Yep, just don't spell it like that thoughSomething like:
Sintax
And Fred, that link did not work - I had to go to cvs.purebasic.com then manually go through the links.
--
It's not minimalist - I'm increasing efficiency by reducing input effort.
(Win98first ed. + SP1, PB3.20)
Edited by - tinman on 25 June 2002 15:15:12
-
BackupUser
- PureBasic Guru
- Posts: 16777133
- Joined: Tue Apr 22, 2003 7:42 pm
Restored from previous forum. Originally posted by Justin.
i'm not English
just go to msdn and look for a description of any api function, simply that is the way it should look, any good programming language follows that template.
ex:
http://msdn.microsoft.com/library/defau ... owtext.asp
i'm not English
just go to msdn and look for a description of any api function, simply that is the way it should look, any good programming language follows that template.
ex:
http://msdn.microsoft.com/library/defau ... owtext.asp
-
BackupUser
- PureBasic Guru
- Posts: 16777133
- Joined: Tue Apr 22, 2003 7:42 pm
Restored from previous forum. Originally posted by MrVainSCL.
Hello all
Yes, i agree with Justin... Surely it would be a lot of work to have finaly such a great documentation... But it would help at least all users and esp. newbies!
PIII450, 256MB Ram, 6GB HD, RivaTNT, DirectX8.1, SB AWE64, Win2000 + all Updates...
greetz
MrVainSCL! aka Thorsten
Hello all
Yes, i agree with Justin... Surely it would be a lot of work to have finaly such a great documentation... But it would help at least all users and esp. newbies!
PIII450, 256MB Ram, 6GB HD, RivaTNT, DirectX8.1, SB AWE64, Win2000 + all Updates...
greetz
MrVainSCL! aka Thorsten
-
BackupUser
- PureBasic Guru
- Posts: 16777133
- Joined: Tue Apr 22, 2003 7:42 pm
Restored from previous forum. Originally posted by Stan.
Hi,
My grain of salt ...
The online documentation of PB has been vastly improved, even if we still
ask for more ...
If we could have the same in an editable format (RichText or even plain text),
it would be easier to correct it or add examples (at least for me cos' I am
an old man better at proofreading printed things and I have no web access at
home ... yes I have tried to convince my boss that the PB Doc. is an important
issue with no luck so far ... ).
Sure it would not bridge the gap, unless some of the gurus around find a way
to switch back and forth between the online help (html or chm?) and the text
format, and more importantly someone is willing to coordinate the whole thing
(no, not me ... I could just help with the French spellchecking).
The problem of newbies is very difficult to solve, shall we assume that they
have at least some knowledge about Basic or programming at large and just need
to know the peculiarities of PB, or that it's their first shot at programming ?
The same goes for the APIs ...
Hu, looks like I open more questions than I can solve ...
Stan.
Since I attended an MS course, my programs no longer have bugs ... just hidden "features" !! [ PB. registered user ]
Hi,
My grain of salt ...
The online documentation of PB has been vastly improved, even if we still
ask for more ...
If we could have the same in an editable format (RichText or even plain text),
it would be easier to correct it or add examples (at least for me cos' I am
an old man better at proofreading printed things and I have no web access at
home ... yes I have tried to convince my boss that the PB Doc. is an important
issue with no luck so far ... ).
Sure it would not bridge the gap, unless some of the gurus around find a way
to switch back and forth between the online help (html or chm?) and the text
format, and more importantly someone is willing to coordinate the whole thing
(no, not me ... I could just help with the French spellchecking).
The problem of newbies is very difficult to solve, shall we assume that they
have at least some knowledge about Basic or programming at large and just need
to know the peculiarities of PB, or that it's their first shot at programming ?
The same goes for the APIs ...
Hu, looks like I open more questions than I can solve ...
Stan.
Since I attended an MS course, my programs no longer have bugs ... just hidden "features" !! [ PB. registered user ]
-
BackupUser
- PureBasic Guru
- Posts: 16777133
- Joined: Tue Apr 22, 2003 7:42 pm
Restored from previous forum. Originally posted by tinman.
The second would be some sort of "here's how to program using PureBasic". You could go through libraries/topics in detail (starting from very basics of programming) and give examples of full programs and explain how they work step by step.
This second document could go up to and include a chapter on "how to use the API functions from PB" but I don't think it would be worthwhile trying to teach the API in the PB docs. The OS developer documentation should be used for that. Otherwise the PB documentation could end up being a 500Mb download
The same goes for a chapter on "using inline ASM in PB". Would you really try to teach assembly language?
Anyway, just my opinion.
--
It's not minimalist - I'm increasing efficiency by reducing input effort.
(Win98first ed. + SP1, PB3.20)
Seems to me there needs to be 2 sets of documents. The first is a reference manual, like the one which have now - it simply tells you the information you need when you look up a topic.The problem of newbies is very difficult to solve, shall we assume that they
have at least some knowledge about Basic or programming at large and just need
to know the peculiarities of PB, or that it's their first shot at programming ?
The same goes for the APIs ...
The second would be some sort of "here's how to program using PureBasic". You could go through libraries/topics in detail (starting from very basics of programming) and give examples of full programs and explain how they work step by step.
This second document could go up to and include a chapter on "how to use the API functions from PB" but I don't think it would be worthwhile trying to teach the API in the PB docs. The OS developer documentation should be used for that. Otherwise the PB documentation could end up being a 500Mb download
The same goes for a chapter on "using inline ASM in PB". Would you really try to teach assembly language?
Anyway, just my opinion.
--
It's not minimalist - I'm increasing efficiency by reducing input effort.
(Win98first ed. + SP1, PB3.20)
-
BackupUser
- PureBasic Guru
- Posts: 16777133
- Joined: Tue Apr 22, 2003 7:42 pm
Restored from previous forum. Originally posted by fred.
Fred - AlphaSND
Look at cvs.purebasic.com, all the docs are in plain text form . And you will see the almost finished french translation...If we could have the same in an editable format (RichText or even plain text),
it would be easier to correct it or add examples (at least for me cos' I am
an old man better at proofreading printed things and I have no web access at
home ... yes I have tried to convince my boss that the PB Doc. is an important
issue with no luck so far ... ).
Fred - AlphaSND
-
BackupUser
- PureBasic Guru
- Posts: 16777133
- Joined: Tue Apr 22, 2003 7:42 pm
Restored from previous forum. Originally posted by tinman.
Sorry for all the questions
--
It's not minimalist - I'm increasing efficiency by reducing input effort.
(Win98first ed. + SP1, PB3.20)
Hey Fred, any explanation of the tags (@SupportedOS, etc) in those plaintext files? Can other ones be added so things like Justin's suggestions for headings can automatically be put into the final doc formats? Oh, and has the mailing list been set up yet? I sent a mail to it today and haven't got anything back (not even a "you're not subscribed here, go away"Look at cvs.purebasic.com, all the docs are in plain text form . And you will see the almost finished french translation...
Sorry for all the questions
--
It's not minimalist - I'm increasing efficiency by reducing input effort.
(Win98first ed. + SP1, PB3.20)
-
BackupUser
- PureBasic Guru
- Posts: 16777133
- Joined: Tue Apr 22, 2003 7:42 pm
Restored from previous forum. Originally posted by tinman.
*Cough* Oops, I appear to have accidently posted in this thread again to see if Fred will notice the questions in my above post
And a couple more:
Who here has CVS access?
Does the CVS mailing list work for anyone?
Can we have access to the tool used to convert the PB docs from the @token style to other file formats?
Cheers
--
It's not minimalist - I'm increasing efficiency by reducing input effort.
(Win98first ed. + SP1, PB3.20)
*Cough* Oops, I appear to have accidently posted in this thread again to see if Fred will notice the questions in my above post
And a couple more:
Who here has CVS access?
Does the CVS mailing list work for anyone?
Can we have access to the tool used to convert the PB docs from the @token style to other file formats?
Cheers
--
It's not minimalist - I'm increasing efficiency by reducing input effort.
(Win98first ed. + SP1, PB3.20)
-
BackupUser
- PureBasic Guru
- Posts: 16777133
- Joined: Tue Apr 22, 2003 7:42 pm
Restored from previous forum. Originally posted by fred.
The mailing list is '[url]mailto:cvsmailing@purebasic.com'.[/url] It's reserved to CVS developper (like you. To subscribe: mailto:cvsmailing_request@purebasic.com?subject=subscribe.
Who here has CVS access?
6 users has a CVS access, which is enough for now (thanks to all)
Does the CVS mailing list work for anyone?
It will
Can we have access to the tool used to convert the PB docs from the @token style to other file formats?
Yes, it's DocMaker.exe, located in your 'PureLibrary SDK' drawer. A RTF version can be asked on demand. The sources will be made public when cleaned.
An AmigaGuide version works too.
Fred - AlphaSND
The mailing list is '[url]mailto:cvsmailing@purebasic.com'.[/url] It's reserved to CVS developper (like you
. To subscribe: mailto:cvsmailing_request@purebasic.com?subject=subscribe.Who here has CVS access?
6 users has a CVS access, which is enough for now (thanks to all)
Does the CVS mailing list work for anyone?
It will
Can we have access to the tool used to convert the PB docs from the @token style to other file formats?
Yes, it's DocMaker.exe, located in your 'PureLibrary SDK' drawer. A RTF version can be asked on demand. The sources will be made public when cleaned.
An AmigaGuide version works too.
Fred - AlphaSND
-
BackupUser
- PureBasic Guru
- Posts: 16777133
- Joined: Tue Apr 22, 2003 7:42 pm