bugGforth - Bugs: bug #44159, Some documentation suggestions

 
 

bug #44159: Some documentation suggestions

Submitted by:  None
Submitted on:  Mon 02 Feb 2015 05:33:30 PM UTC  
 
Category: NoneSeverity: 3 - Normal
Item Group: NoneStatus: Fixed
Privacy: PublicAssigned to: Bernd Paysan <paysan>
Open/Closed: Closed

Add a New Comment(Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

Sat 19 Dec 2015 09:46:13 PM UTC, comment #1:

Thanks; finally got around to insert your corrections into the documentation.

Bernd Paysan <paysan>
Project AdministratorIn charge of this item.
Mon 02 Feb 2015 05:33:30 PM UTC, original submission:

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.

Anonymous

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach File(s):
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -unavailable- added by paysan (Posted a comment)
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    Follow 3 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Sat 19 Dec 2015 09:46:13 PM UTCpaysanStatusNone=>Fixed
      Assigned toNone=>paysan
      Open/ClosedOpen=>Closed

    Back to the top


    Powered by Savane 3.1-cleanup1