Clean up some doco typos, non-updated stuff and add clarity

[RigTig]

In working through the forth.asm, I have found numerous comments and bits of documentation that are useful and relevant. Occasionally, I found some to have typographical errors, and some comments to be not very helpful. None of the following save any bytes, nor runtime, but they might just save a user or reader a little angst trying to figure it out.

1. In forth.asm and in each globinf.inc, the line regarding WORDS_LINKCHAR needs to have the following two words added: PAD $"
2. In forth.asm and in each globinf.inc, the line regarding WORDS_LINKMISC, is better to drop mention of words SEE DUMP WORDS, so the comment reads '; Link composing words >CHAR _TYPE dm+ .ID >NAME
3. In forth.asm and in each globinf.inc, the line regarding WORDS_LINKRUNTI needs to have the following three words added: (+loop) $"| ."|
4. In forth.asm and in each globinf.inc, the line regarding WORDS_LINKCOMP needs to have the following three words removed: last $"| ."| and the following two words added: ?UNIQUE $COMPILE
5. In forth.asm and in each globinf.inc, the line regarding WORDS_LINKINTER needs to have the following five words removed: tmp eval NAME> INTER? $COMPILE and the following eight words added: 'eval TIB 'PROMPT EXTRACT PARSE CUPPER NAME? ^h. Since the list is so long, I suggest sorting into alphabetical sequence.
6. In forth.asm and in each globinf.inc, the line regarding WORDS_EXTRADEBUG needs to have the following word removed: SEE and the following word added: >NAME
7. In forth.asm and in each globinf.inc, the line regarding WORDS_EXTRACORE needs to have the typo =0 changed to 0=
8. For ACCEPT, it is not obvious that the buffer is a line buffer rather than a stream buffer. Recommend change description comment to:

   
   ;       Accept one line of characters to input
   ;       buffer. Return with actual count.

You can confirm the line buffer nature of TIB by looking at the behaviour of such words as \ . Knowing what kind of buffer is important to us for dumping stuff into that buffer other than by serial character input.
9. For QUERY, it is not obvious that the buffer is a line buffer rather than a stream buffer. Recommend change description comment to:

; Accept one line from input stream to ; terminal input buffer.

End of list for now. These have been found over the past couple of weeks. If I find more, than I'll raise as new issue.

[TG9541]

For sure there are many typos in comments and docs, and I'm happy that native English speakers now provide corrections (or as some of my Indian colleagues would say: "please do the needful"). As for the costs of copy-and-paste, I'd like to propose removing the word lists from all globconf.inc files (the lists in forth.asm are easier to track).

[TG9541]

I just committed changes to forth.asm.

Sorting a list of words can be done with the following line:

cat | gawk 'BEGIN {RS=" "} 1' | sort | uniq -u | gawk '{a = a " " $0} END {print a}'

I'm looking into how to best clean up the globconf.inc mess.

[RigTig]

Cutting and dicing the forth.asm cake with the increasing number of platforms and options is becoming a bit of a nightmare. I was (and still am) impressed that so many variations on a theme could be handled at all. My suggestion at this time is to leave the hardware-specific options in the current globinf.inc files and have all the 'personal preference' options either only in forth.asm, or in a .inc file in the topmost folder with forth.asm. My preference is another .inc file, so that changes to forth.asm are for corrections, updates, etc.

I suggest that we need to look at reducing the number of options. One way I can think of is to put the changes in as eForth code, even allowing for redefinitions. Most of the time, the extra space taken up is not a project-breaker issue. If it does get to be critical for space, perhaps that is the time to just cut back to core, and add what the project needs. Or, the developer can edit the forth.asm to get just what they need at flash time.

Even Dr. Ting has typos, and transcription errors are a part of normal life for programmers and documenters. I am pleased that I can help at all. I still reckon it is fun when I get that 'Aha' moment when clarity appears in the mist of confusion.

I must sadly admit that I have only one language, and that comes with Australian idioms. For example, in one earlier comment, I found that I had written that I was 'dragging the chain' before I edited it out. It means being slow and lacking energy, and derives from the practice that convicts with a ball and chain were supposed to carry their ball and chain when they were on the move, but a tired and worn-out prisoner might just let the chain drag on the ground.

[TG9541]

I guess you're right: the forth core, and higher words should be split in at least two files. A criteria might be "what can be done in barebones.fs isn't core" but OR is where I draw the line ;-). I think that this also would facilitate an ITC implementation .

Selecting features on a "per project" basis is a good idea. I've been thinking of writing an automated "Build-a-Forth" service. With the help of Docker containers the security aspects should be manageable.

And finally (off topic): learning languages is a life-long journey for 2nd language speakers, and sometimes it does strange things to your first language.It's an experience I wouldn't want to miss (it actually has some similarities to learning Forth).