bugGforth - Bugs: bug #44159, Some documentation suggestions

 
 

bug #44159: Some documentation suggestions

Submitter:  None
Submitted:  Mon 02 Feb 2015 05:33:30 PM UTC
   
 
Category:  None Severity:  3 - Normal
Item Group:  None Status:  Fixed
Privacy:  Public Assigned to:  paysan
Open/Closed:  Closed
* Mandatory Fields

Add a New Comment Rich Markup
   

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>
Group administrator
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 Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

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

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2015-12-19 paysan StatusNone Fixed
        Assigned toNone paysan
        Open/ClosedOpen Closed

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code