Sylvain Nahas wrote: > <<3.26.1 Open file for input > -------------------------- > > s" foo.in" r/o open-file throw Value fd-in>> > > Whoosh. That's all. What is it supposed to mean ? I would expect a > tutorial aimed at beginners ( this is what a tutorial is supposed to be > ) to describe the meaning of each words, how they sequentially lead to > the desired result. The above sentence is a bit ... terse.
>From the start of the tutorial: |The intended way to use this tutorial is that you work through it |while sitting in front of the console, take a look at the examples and |predict what they will do, then try them out; if the outcome is not as |expected, find out why (e.g., by trying out variations of the |example), so you understand what's going on. It is also intended for people who also know another programming language. I think that if you know how to deal with files in another programming language, and have worked through the tutorial that far, you should be able to predict what the example does. If not, look up the reference section on files. However, admittedly the link to the reference section is missing (fixed now), and the reference section is not as descriptive as it should be. > Now, the code in the tutorial doesn't really do what I want. It reads > _lines_ . I wanted to read characters. I guessed that to do it was > probably the word _read-file_ that had to be used. So I came to the > "references" And here is what the reference manual says about read-file. > > <<`read-file' c-addr u1 wfileid - u2 wior file > "read-file" >> > > And that's absolutely all. No description of what it is supposed to do, > even one line ( remember, I _guessed_ it was what I needed ), Well, you guessed right. And yes, that part should be improved. Volunteers welcome. In the meantime, you can look up standard words like READ-FILE in the standard document: <http://www.complang.tuwien.ac.at/forth/dpans-html/dpansf.htm> > `swap' w1 w2 - w2 w1 core "swap" > > _I_ now know how to understand this sentence. But I was at first > confounded. Remember, I am talking of people new to Forth. This is from the reference part. People new to Forth should work through the Tutorial and/or the Introduction. At that point, they should know SWAP. But assuming they don't, the description above is still complete when combined with the knowledge about interpreting stack effects (described in the first section of the chapter Words), and especially when looking at the section headings (Words - stack manipulation - data stack). There may be people who prefer a more verbose description, but that is a matter of taste. There are other reference works that are more verbose (e.g., the standard); maybe these works are more to your taste. After all, the necessary source code of the word is swap ( w1 w2 -- w2 w1 ) core So do we really need more documentation? > But there is worse. As I told to you I wanted to write a "fi2c" program. > As I wasn't able to find useful information in the manual about > "read-file" I resolved to search for example of its use in existing > code. And what did I find ? A fi2c.fs program. The fact it doesn't work > with the current version is not relevant. How comes haven't heard of it > before ? > A grep in the source directory proved me there is _no_ reference of this > command anywhere, especially in the manual. > The source file itself is not documented : no information how to run it, > etc . Besides this is true for most of the files of the source. Most of the files in the source are compiled into the gforth executables or the gforth.fi image (or used for building that), so if you do a regular startup of Gforth, you don't need to "run" these files. If you want to look something up in these files, you can do it with "make TAGS" and then use Emacs' tags-search, or grep as you have done, or just browse through the files in classic "Use the source, Luke" style. Some of the other files are described in various places. Concerning stuff used for embedded systems (e.g., fi2c.fs), that is extremely underdocumented: The authors of these peaces of code are not the most prolific writers, and there are apparently no volunteers who know enough about this stuff that they can write about it. So if you want to do embedded work, and want good documentation, Gforth may not be the right system for you (at least at this time). > * leave no word definition in the manual without at least a clear > english sentence explaining what it does. Usually more than a sentence > is needed for non-trivial words. As discussed above, I think you have a taste for more verbosity than I have; but certainly READ-LINE deserves more documentation than it has now. > * include in the manual simple examples that explain how to use the > words. If not, give a link to an actual code in the source that use it > in an interesting way. The best examples are those that can simply be > cut and paste to build its own sofware: this increase one's productivity. That's certainly a good idea. Any volunteers for doing that work? > * document the source so that a newcomer has a chance to understand it. > Sources will be the next thing after the manual a newcomer will turn to. > * reference in the manual each tools that is available in the distribution > * add manuals and tutorials that explain how to use your system in the > domain where it shines most, embedded system and microcontrollers > programmation. Also good ideas, but somebody has to do it. > I am also willing to help. Great. Send me an ssh2 public key, so we can give you an account on one of our machines. - anton --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
