[Bug-gforth] [bug #44159] Some documentation suggestions

[anonymous]

URL:
  <http://savannah.gnu.org/bugs/?44159>

                 Summary: Some documentation suggestions
                 Project: Gforth
            Submitted by: None
            Submitted on: Mon 02 Feb 2015 17:33:30 UTC
                Category: None
                Severity: 3 - Normal
              Item Group: None
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any

    _______________________________________________________

Details:

3.2 Syntax

"leave away" -- This would normally be "leave out" or "omit" in English.

3.15 Local variables

"you can leave the away" -- Better would be "you can omit the"

3.27 Files

The list of five easy steps should probably be rewritten as:

  1. Open an ASCII text file for input

  2. Open a file for output

  3. Read the input file until a string matches (or some other
     condition is met)

  4. Write some lines from input (modified or not) to output

  5. Close the files.
  
  
3.29 Execution Tokens

see foo -- should be see foo1

3.35 Advanced Macros

In the matrix example "line" should read "row" (matrices are usually referred
to as having rows and columns).

3.37 Wordlists and Search Order

"Assignment: Define `>order ( wid -- )' with adds `wid' as first
searched wordlist to the search order."  Here "with" should be "which".

4.1 The Text Interpreter

"If the group of characters matches an entry in the name dictionary, the name
dictionary provides the text interpreter with information that allows the text
interpreter perform some actions."  Here the word "to" should be inserted
before "perform some actions".

4.2 Stacks, postfix notation and parameter passing

"More precisely, it adds two number together and produces a result."  Here
"number" should read "numbers".

"You can act-out the behaviour of `+'" Here there is no need for
the hyphen, "act out" is fine.

"The text interpreter looks up the word `clearstacks' and executes it; it
tidies up the stacks and removes any entries that may have been left on it by
earlier examples."  Since the manual later refers to a number of stacks, it
would be good to know which stacks are cleared by clearstacks.  If it is more
than one (and I think it includes at least the data stack and the fp stack)
the wording should read "left on them by earlier examples".  

4.3 Your first Forth definition

: add-two dup . ." + 2 =" 2 + . ;

would be better as:

: add-two dup . ." + 2 = " 2 + . ;

so that a space separates "=" from the sum in the output (purely cosmetic).

4.4 How does that work?

"The first special thing that it does prevents the text interpreter from ever
seeing the characters `add-two'."  I suggest "that it does is to prevent"
would be better.

"One category of words don't get compiled."  Again, I sugget "Certain kinds of
words do not get compiled." sounds more natural in English.

"Words don't behave in such a regular way" -- I think this is
missing the word "always", i.e. "words don't always behave in such a regular
way".

"At the time that `word1' (and therefore `show-state') are executed, the
system is interpreting." -- Here "are executed" should be "is executed" since
the subject of the verb is word1, a singular noun.

"The effect of executing it are to display the value of `state' at the time
that the definition of `word2' is being defined." -- Similarly, this should
read "The effect... is to display..."

4.6 Review

"The relationship between the "interpretation semantics" and
"compilation semantics" for a word depend upon the way in which the word was
defined" -- Should read "The relationship... depends upon".

5.5.4 Numeric comparison

u2=<u1<u3 or: u3=<u2 and u1 is not in [u3,u2)

I found this explanation of the word "within" puzzling, not least
because it uses the symbol "=<" rather than "<=".  I suggest that the two
possibilities :

        u2 < u3 and u1 in [u2, u3) or: 
        u2 >= u3 and u1 not in [u3, u2)

are equivalent and clearer.

5.6.5 Stack pointer manipulation

OBSOLETE alias of `sp0' -- I am not sure what the OBSOLETE alias
refers to, since the name of the word seems to be sp0. The same for rp0 and
lp0 in this section.

Appendix A, B, etc -- These are called Anhang in the manual.







    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?44159>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/