SimpleIDE User Guide
jazzed
Posts: 11,803
Hi All,
We are trying to firm up documentation this week. Attached is a SimpleIDE User Guide in .pdf form.
Please review and comment.
Thanks,
--Steve
We are trying to firm up documentation this week. Attached is a SimpleIDE User Guide in .pdf form.
Please review and comment.
Thanks,
--Steve
Comments
We're trying to get GCC to beta, and the team (mindrobots, jazzed, David Betz, Dave Hein, Daniel Harris, and others) really need our support. Since our customers love to help out we'll offer some encouragement to do exactly that.
Produce 10-20 comments (error corrections, grammatical improvements, constructive suggestions and solutions - write a bit yourself?) of your original feedback and we'll send you a Ping))) or Propeller Proto Board. Steve will decide what to do with each comment. No duplicative efforts of other's comments.
Post your comments in this thread. Provide your comments in your ONE response, editing it as you see appropriate (I don't want to comb the thread for multiple comments from a single person please).
The deal expires today at 3 pm Pacific. I know - it's tough!
Thanks,
Ken Gracey
Thanks Jazzed. Will let you know how a total n00b gets through it
I just looked through & noticed a few tiny questions. I might be wrong so trash it if they don't make sense:
Personally, I really dislike the multi-size font peppered throughout, starting on page 1 with "Table of Contents". The small letters are too small.
Here's what I found in spelling and grammar:
p 7 if necessary. in the properties necessary, in change period to comma
p 15 to the clip-board. (TWO INSTANCES) clipboard no hyphen
p 16 Typically clicking this button will also Typically , clicking add comma
p 16 Increases the editor font by %20 (TWO INSTANCES) 20%
p 19 based on the open file like found in file as found in
p 19 can'tt be built and run can't
p 19 in the project folder pr a specified per or for
p 20 files also known as header files typically (also known as header files) add paren
p 21 left click on the file-name. filename or file name no -
p 23 Typially typically
p 27 Boards having only SRAM will only boot stand-alone it the code can be if
p 28 in a comment like described above. comment as described above
I will read it again more thoroughly a bit later.
Hope that sort of thing is what you were after.
Sorry about the scan being funny.
p 1 "This guide is not comprehensive". What is missing from it? A scope section would be helpful.
p 6 "It allows setting critical folders, general properties, and highlights." Also, critical is a bit severe. And what are highlights?
p 6 "The backslash '\' folder separators used in Windows is replaced by '/' by the IDE."
p 8 "The SimpleIDE Properties dialog window controls are the same regardless of user's operating systems."
p 10 "If you see the ASC board type, it will be good enough for most 5MHz Propeller board tests." should be "The ASC board type is suitable for most 5MHz Propeller boards."
p 10 "There is practically no difference between HUB and ASC for simple programs like hello." But the difference is...?
p 10 The last two sentences of the second to last paragraph should be "Some boards, such as the HYDRA and the SPINSTAMP, use a different speed clock crystal."
p 11 Remove "The rescan button looks like this:" and just put the image at the end of the previous sentence.
p 11 "Bluetooth serial port programming...is not recommended at this point." When will it be, why, and where can I find out more on this?
p 11 On the "not fast enough to catch the first few hello lines", can that be quatified?
p 12 First paragraph, does the terminal buffer the incomming data when the disable in active?
p 13 There are [ code ] tags in the text. Intended? Unclear, even when on page 14 it is mentioned.
p 14 "If you want to store the program permanently". How permanently? It's unclear for a novice if it's write once or many.
p 15 "Many features of the IDE... need explanation". These two sentences are white noise, and doesn't contribute to understanding of the IDE.
p 15 For the bullet items that don't have a picture you should insert a blank image so that the line spacing is even.
p 16 Does the find/replace support any pattern matching? What about special characters (newline, tab, etc.)?
p 16 "%20" should be "20%".
p 19 "can'tt" (double "t")
p 21-22 The capitalization on the first word after the colon is inconsistent.
p 22 "Do not delete the top file - it has a special meaning". What is the special meaning? A link/reference would be helpful
p 22 "this is the same as a left click on the file name."
p 25 "The program will compile without this __<library?>_____
p 25 "LMM programs can run M*N threads on N COGS" What is M?
p 27 "External RAM boards are generally boards that have external SRAM, SPI-SRAM, or SDRAM". Generally, or always?
p 29 "When a Propeller-GCC program is loaded on the hardware, it is done with the propeller-load loader program." should be "A Propeller-GCC program is loaded onto the hardware with the propeller-load program." (the loader is debatable too, but I think it's redundant).
p 29 "http://www.parallax.com/propellergcc/ has more information." should be More information can be found at http://www.parallax.com/propellergcc/".
p 30 I think the discussion on the back button is noise (not useful), but if you want to keep it then I would remove "This means" from the second sentence.
p 30 "There have been many enhancements and bug fixes since the last update."
In general:
- A different font (monospaced) should be used for code names, etc.*
- I wouldn't use color for the headings. It makes it look poor when printed on a B/W printer (too faint). If you do use color, it should be the same or distinctly different (ref. p 27)
- A link or picture comparison of all board types would be nice for those who don't know what each board is.
- I would put a light grey background on the code sections to set them apart. Also, code should be indented (like a quoted block).
- Section numbering would be helpful to provide references to others.
- In general, throughout the document when you mention something but don't go into detail, you should provide a refernce on where to find that information (ex. "... when selected tell the IDE that certain functions will be performed (see sections 3.4 and 4.2.1)." (pg 23))
- For the list of icons, I think it would also be helpful to have all the icons on a single page, with the name and a reference to where more information can be found.
- A "How to Read the Document" section would be helpful, with subsections for beginner users and advanced users.
- I would also give the document a version number, and when changes are made add each important change to the revisions table.
--- I think the most important next step would be to divide everything into sections that allow users to easily scan through the document. As it is, the entire document seems to be on continuous section without differentiation.
*This is especially important because the document seems to use CAPS for anything not body text, but the things in caps are filenames, program types, commands, code, and other things. It's easier to classify a particular word if it looks like the category. Professional programming books all do this.
I like the "If you really need to use tabs, you can use another editor." I use tabs
Have you considered latex? I've found that writing my documents that way make it much easier to have very professional looking typesetting with minimal effort.
Anyway, it would also be good to switch to latex so that you can put the document on the source code control site. Since latex is just a plain text .tex file it works out really well. You can also put a PDF up there too (but it just gets replaced on every commit, instead of diff'd).
However, I'm going to post a work in progress for comments. Don't bother to mention that the empty sections need filling in. That is obvious. On the other hand, if you can think of topics that need to be added or if you think any of what is written needs more or better explanation than I've provided please feel free to comment. I don't know if these comments will qualify you for one of Ken's prizes but they'll certainly help improve the final PropGCC product.
I've attached a very early draft of the propeller-load manual. Please post your comments and suggestions.
Thanks,
David
Some of the general comments that I posted above apply to Loader.pdf. Although I see that you have added section numbering.
p 3 "The Propeller Loader (propeller-load) is a command line program you can use ..." ps: the sentence is a bit run-on...
p 3 "In other words The default board configuration uses..."
p 3 "...makes use of variable patching (as described in section xxx) then the board type..."
p 3,4 I don't notice any difference between the four example commands... (except for the words ", into external memory" <- note the misplaced comma)
p 4 "The -e option only makes sense when ..." Question: what happens when it does not "make sense"?
p 5 "... by first looking in" Question: is there a folder precedence? What if two matches are found?
p 6 "This requires that the external memory be non-volatile. In other words, it must be flash memory." What about other non-volatile memories?
p 8 Why would a user want to use the -S flag?
General comments:
- subsub sections (x.x.x) look odd when they are italicized. Italics are generally used for emphasis.
- There are some early attempts at word level typographic formatting within the paragraphs, but it is a bit inconsistent. I assume this is already on the fixing board.
- The -P option is useful, but can't you test for a Propeller chip on each port? I think that would be very beneficial.
- On linux, I use the command "ls /dev/*USB* to find the USB ports. If I have only one propeller connected then it's port is the only result. The -p option could do something similar (so the port doesn't have to be specifically specified).
- I'm not terribly familiar with command line parameters, but isn't it usually the case that when the option is "-t<baud>" that it is expected to have a space between the flag and the value? This seems like a source of bugs for professional developers.
- I assume all this will be going into a man page format as well?
And I don't know if it's just me, but when I try to copy and paste from the PDF it puts each word onto a seperate line: My guess is that it MS Word using some odd encoding for the spaces, but I don't know.
--Steve
Each of you may gladly e-mail me with your preference (Propeller Proto Board or Ping))) and I'll have Jim send it to you on Tuesday. Include your shipping address. Make it easy for me, like this:
erco berserko
123 Melamine Road
Plywood City, CA
Choice: Propeller Proto Board
My e-mail kgracey@parallax.com
Thanks,
Ken Gracey
It is my way of saying thanks to Steve for spending so much time helping try to fix my problems a few months ago.
Besides shipping to Australia is probably astronomical!
Such exciting times ahead for the prop
...you...you mean I actually won something this time?!?!
WooooooHOOOOOOOO!!!
Nah, you worked for it Dave and earned the free Ping))) you requested. We appreciate the help.
To the others: drop me a line with your preferences.
Great weekend to all -
Ken Gracey
What do you believe it takes for Propeller GCC to be more mature?
Stating an open ended opinion does not help.
Thanks,
--Steve
- A mention of who the PropGCC project is for. Developers? Students? Everybody? I'm going to assume that PropGCC will become Parallax's new flagship language, and be used for teaching.
- The documentation needs to be considerably improved. The two documents posted in this thread are a start, but overall PropGCC is missing:
--- Diagrams/Graphs/Charts: visuals make it easy to quickly get a sense of what is happening, and to compare possibilities. There's many possibilities for what information can be represented in graphs, but off the top of my head: memory model types, speed comparisons, and the download sequence.
--- A book. Mature projects have books, both tutorial books and reference books.
--- Complete code examples. Many of the features that are explained in the wiki and elsewhere only have code snippets, and not an example that can be downloaded and run.*
--- An introduction page. I can't find any tutorial that starts from the very beginning, and is designed to get a user up and running from beginning to advanced.
--- Explanation/examples for common functions (ie, things the Obex does for spin) such as PWM(servos and motors), serial (I2C, SPI, UART, 1 wire), ADC/DAC, video and audio, keyboard/mouse, LEDs, RAM, steppers motors, etc.
--- There needs to be some sort of reading order for the information posted. Something that says "Start here!" and continues from simple to advanced.
--- How to interface existing Spin/PASM code with PropGCC. It says TBD on the wiki for this...
--- The Threads section of the library.html file is a bit sparse. What are "spin locks"? How do you specify that two threads run in the same cog? What about concurrent driver access (ie, is STDIO thread safe in this context?).
- There needs to be a debugger of some sort, in my opinion. I see that is scheduled for release with Propeller 2
- I think floating point can be optimized, although I don't know if that conflicts with the C standard way of doing things. I don't really have any data to back up this change, except for the comments at wiki:: PropGccTightMemory and the F32 32 bit floating point object seem to indicate that speed and memory could be improved.
- The driver code (as documented here) doesn't seem very flexible. The driver definition only allows for a single port. What about the 4 port serial driver now available? From the driver definition, it can only have one set of File I/O operators. And, not every driver option will fit into the file I/O model. What about adding memory mapping I/O drivers?
*I see that there is a demos download, but that's not the same as having a library with all the functionality in there, along with a standardized documentation format, and the explanation to go along with it.
For refrence, I'm getting all of my information from the PropGCC Google code site (namely the wiki) and the two documents posted in this thread.
One of the biggest issues that I see is that the multicore aspects of the Propeller is practically ignored with PropGCC. There seems to be almost no explanation of how to do things in parallel, and how to figure out how many cores your program uses. Isn't the parallelism one of the main selling points of the Propeller?
In conclusion, I like the way that PropGCC is being developed, and I'm excited about the possibilities. I just don't think it is mature enough for me or the general public to use yet.
Thanks. That's very helpful. All the comments in this thread are very helpful too.
Everyone please understand that I can't comment on all the comments and finish the doc in a reasonable amount of time too.
Cody,
Here's a response which I believe is positive and I hope will be interpreted that way.
First I should note that we are moving all documentation efforts out of the Wiki (inconvenient) and to HTML source documentation. We are developing the Propeller-GCC Beta site to host this and other information as a one-stop shop.
Second, the documentation has slowly started appearing and the subject of this thread is one of the first reviews of such documentation.
Library documentation will be HTML and Latex sourced from Doxygen markup.
Third, here's where we stand according to the order you have listed in summary and in details below.
1. Nearing beta
2. Target Demographic
3. Documentation
4. Debugger
5. Floating Point
6. Driver Code.
7. Multi-core Aspects
Details:
1. Nearing beta:
Our GCC beta entry criteria is:
- Fully functional GCC compiler. Done.
GCC is ANSI-C 89 + most of C99 spec compliant.
- Fully functional tool chain except gdb. Done.
GDB is over budget for the P1 phase.
- Fully functional loader. Done.
Loader we have one more "nice to have" loader feature to finish.
- Standard C library ANSI-C freestanding compliant. Done.
Many hosted library API's are also included.
- Some Integrated Development Environment to make programming easy. Mostly done.
- Propeller-GCC packages available for Mac, Linux, Windows. Waiting for library documentation.
- Full propeller hardware and standard C library API documentation. Not done. See below.
2. Target Demographic
The Parallax Education team is responsible for the student/teacher demographic.
3. Documentation
We are working on the introduction page.
We have many code examples. The quality of documentation you and I both expect from Parallax on code examples is up to Parallax and we have discussed this. This is up to Parallax.
Also Parallax has requested that common libraries not needed for Propeller GCC basic function not be included in the distribution. This will grow along with Parallax documentation.
There will not be a book for a very long time if at all. That being said, I have often thought there should be a book and have started an outline, but I'm not a writer.
We have examples of interfacing with SPIN/PASM. There is also a document in progress for this.
We have examples of using pthreads. There is a document in progress for this. Pthreads require standard stdio drivers and delay routines (no waitcnt) and is an advanced subject.
4. Debugger
5. Floating point
6. Driver Code.
7. Multi-core Aspects
Finally, thanks to everyone who has tried Propeller-GCC so far in it's Alpha phase. The purpose has been to get more of our forum friends using it so that we can feel more comfortable about it when Beta starts.
Cody, the kind of feedback you have given is very valuable. New user input is always more interesting than experienced users' input.
Thanks,
--Steve
Great, now EVERYONE knows my address. I gotta leave Plywood City!