Hi,
I've been trying for 3 weeks now -in my spare time- to use gForth.
I have made the CVS version compile and I am now using it.
I would like to share some of my feelings about your project.
First, some words of background about me.
As a lot of software guys today, I guess most, I haven't even heard of
Forth. At least among those come to programming in the 90's. I am here
because I have lately developed an embedded system, based on a Linux
system. In the course of this project I felt there were a lack in my
software toolbox. C - and C-like language, just wasn't enough, specially
during hardware prototyping. After having made my mind about the
functionalities I missed, I settled to seek on the Net which solution
were actually existing. It turned out that this solution may be Forth.
As I told you, I am very new to Forth. I do know some other programming
languages and environment. I found learning Forth with gForth a lot more
frustrating than I expected.
Yes, this language is very peculiar in regard of others, but I found
some nice tutorials to learn the basis of the stack management and it
wasn't so big a deal to understand. No. The real problem is that the
gForth Manual is too much incomplete, and the source code badly organized.
I recently decided to make a software that would embed .fi binary files
in C-like declaration. I then looked in the documentation about managing
file, and read the related section in the tutorial.
I quote some :
<<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.
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 ), of its
parameters, how it reacts when some things goes bad ( unexpected end of
file ). And, of course, no actual example of how to use it in the best way.
I would like to quote now the equivalent Linux's libc manual page about
read().
SYNOPSIS
#include <unistd.h>
ssize_t read(int fd, void *buf, size_t count);
DESCRIPTION
read() attempts to read up to count bytes from file descriptor fd
into the buffer starting at buf.
If count is zero, read() returns zero and has no other results.
If count is greater than SSIZE_MAX, the result is unspecified.
RETURN VALUE
On success, the number of bytes read is returned (zero
indicates end of file), and the file position is advanced by this
number. It is not an error if this number is smaller than the number of
bytes requested; this may happen for example because fewer bytes are
actually available right now (maybe because we were close to
end-of-file, or because we are reading from a pipe, or from a terminal),
or because read() was interrupted by a signal. On error, -1 is
returned, and errno is set appropriately. In this case it is left
unspecified whether the file position (if any) changes.
... more
Do you see my point ? This manual contains everything somebody that has
read "C for dummies" has to know to efficiently use read() in its
software. He doesn't have to guess how to use it ( in C it would be a
fatal flaw ). The information are so efficiently retrieved that one
even doesn't have to _remember_.
I certainly don't learn by heart every function I use. I am too dumb for
that. While programming I always have an open instance of "info libc" or
equivalent to quickly fetch the information I need. There is simply too
many different languages, libraries and environments to jam my memory
with the content of the manuals. That is why a manual is done for.
Another example of a good documentation. This comes from Python. Part of
the success of Python is probably because it is so easy to learn because
it is nicely documented.
read( [size])
Read at most size bytes from the file (less if the read hits EOF before
obtaining size bytes). If the size argument is negative or omitted, read
all data until EOF is reached. The bytes are returned as a string
object. An empty string is returned when EOF is encountered immediately.
(For certain files, like ttys, it makes sense to continue reading after
an EOF is hit.) Note that this method may call the underlying C function
fread() more than once in an effort to acquire as close to size bytes as
possible. Also note that when in non-blocking mode, less data than what
was requested may be returned, even if no size parameter was given.
Once again it provides everything one has to know on the use, the
parameters, the return value and possible side-effects.
and not (another example from gforth manual) :
`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. People who
don't know Forth are now the vast majority of the programmer. Is that to
say they don't _deserve_ to learn Forth ? I don't think so.
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.
I have seen references about gForth for embedded controller but no
tutorial or documentation about it. There is maybe whole sides of the
system that are undocumented and thus useless.
That's my point. gForth is cleverly built, it is an impressive piece of
engineering, no doubt. But the better technical solution is both useless
and dismissive when the documentation isn't up to. Given the present
state of the domentation there is a high probability that a newcomer
gives up gForth and even the language as a whole. I almost did.
I send this mail intead of giving up because I nonetheless think gForth
is still worth I learn to master it. By the way, these flaws are not too
hard to fix. I would suggest the following as a rule of thumb :
* 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.
* 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.
* 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. There is already a lot of good general purpose scripting
language to do programming in a standard OS environment. I for a one
wouldn't bother to learn a new one only for this aim.
As I already stated I quite like gForth. This mail is not intended to be
a gratuitous bashing of your work. On the contrary I think I pointed
what is already a limiting factor against a wider use of your work.
I am also willing to help.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
