Improve usage docs

This allows cut&paste similar to VI's

CONTRIBUTING.md

@@ -64,3 +64,9 @@ and make post-collapse users much happier.
 It is frequently asked by would-be contributors whether I have tips for an
 optimal ramping up of skills. [I've put together a little document to answer
 that question](https://collapseos.org/skills.html).
+
+## No typo pull requests please
+
+Please, don't open pull requests to fix typos. See [issue #3][GH-3] for details.
+
+[GH-3]: https://github.com/hsoft/collapseos/pull/3

blk/000

@@ -12,5 +12,5 @@ block, it means that the next block continues the same kind of
 contents. Block numbers are abbreviated with prefix "B". "BX"
 means "block X".
 
-The master index of this filesystem is at B1. The Block editor
+The master index of this filesystem is at B1. You can navi-
-at B100 is a convenient way to navigate blocks.
+gate and edit blocks with the Visual Editor at B120.

blk/003

@@ -12,5 +12,5 @@ Contents
 
  5 Number literals              6 Compilation vs meta-comp.
  8 Interpreter I/O             11 Signed-ness
-14 Addressed devices           17 DOES>
+17 DOES>                       18 Disk blocks
-18 Disk blocks                                          (cont.)
+                                                        (cont.)

blk/005

@@ -1,8 +1,8 @@
 Number literals
 
-Traditional Forth often use HEX/DEC switches to go from decimal
+Traditional Forth often uses HEX/DEC switches to go from deci-
-to hexadecimal parsing. Collapse OS parses literals in a way
+mal to hexadecimal parsing. Collapse OS parses literals in a
-that is closer to C.
+way that is closer to C.
 
 Straight numbers are decimals, numbers starting with "0x"
 are hexadecimals (example "0x12ef"), "0b" prefixes indicate

blk/006

@@ -1,8 +1,8 @@
 Compilation vs meta-compilation
 
 Compilation vs meta-compilation. When you compile a word with
-"[COMPILE] foo", its straightforward: It writes down to HERE
+"[COMPILE] foo", it's straightforward: It writes the address
-wither the address of the word or a number literal.
+of word foo to HERE.
 
 When you *meta* compile, it's a bit more mind blowing. It
 fetches the address of the word specified by the caller, then
@@ -12,5 +12,3 @@ writes that number as a literal, followed by a reference to
 Example: ": foo [COMPILE] bar;" is the equivalent of ": foo bar
 ;" if bar is not an immediate. However, ": foo COMPILE bar ;"
 is the equivalent of ": foo ['] bar , ;". Got it?
-
-Meta-compile only works with real words, not number literals.

blk/008

@@ -8,7 +8,7 @@ During normal operations, C< is simply a buffered layer over
 KEY, which has the same behavior (but unbuffered). Before
 yielding any character, the C< routine fetches a whole line
 from KEY, puts it in a buffer, then yields the buffered line,
-one character at once.
+one character at a time.
 
 Both C< and KEY can be overridden by setting an alternate
 routine at the proper RAM offset (see B80). For example, C<

blk/014

@@ -1,16 +0,0 @@
-Addressed devices
-
-The adev unit provides a simple but powerful abstraction over
-C@ and C!: A@ and A!. These work the same way as C@ and C! (but
-for performance reasons, aren't used in core words), but are
-indirect calls.
-
-Upon initialization, the default to C@ and C!, but can be set
-to any word through A@* and A!*.
-
-On top of that, it provides a few core-like words such as
-AMOVE.
-
-Let's demonstrate its use through a toy example:
-
-                                                        (cont.)

blk/015

@@ -1,16 +0,0 @@
-(cont.)
-    > : F! SWAP 1 + SWAP C! ;
-    > 8 H@ DUMP
-    :54 0000 0000 0000 0000 ........
-    > 9 H@ A!
-    > 8 H@ DUMP
-    :54 0900 0000 0000 0000 ........
-    > ' F! A!* !
-    > 9 H@ 1 + A!
-    > 8 H@ DUMP
-    :54 090a 0000 0000 0000 ........
-    > H@ H@ 2 + 2 AMOVE
-    > 8 H@ DUMP
-    :54 090a 0a0b 0000 0000 ........
-    > 
-                                                        (cont.)

blk/016

@@ -1,16 +0,0 @@
-(cont.) Of course, you might want to end up using adev in this
-kind of ad-hoc way to have some kind of mapping function, but
-what you'll mostly want to to is to plug device drivers into
-those words.
-
-
-
-
-
-
-
-
-
-
-
-

blk/017

@@ -2,7 +2,7 @@ DOES>
 
 Used inside a colon definition that itself uses CREATE, DOES>
 transforms that newly created word into a "does cell", that is,
-a regular cell ( when called, puts the cell's addr on PS), but
+a regular cell (when called, puts the cell's addr on PS), but
 right after that, it executes words that appear after the
 DOES>.
 

blk/100

@@ -1,7 +1,7 @@
 Block editor
 
 This is an application to conveniently browse the contents of
-the disk blocks and edit them. You can load it with "102 LOAD".
+the disk blocks and edit them. You can load it with "105 LOAD".
 
 Browse mode: If you execute BROWSE, the Forth interpreter is
 replaced by browser's loop. Typing "Q" quits the browser.

blk/101

@@ -1,16 +1,16 @@
+There are two buffers, IBUF (insert buffer) and FBUF (find
+buffer). They are used as a typing target for the actions
+described below. They both have a peculiar logic: when typing
+is expected to fill a buffer, an empty value means "reuse
+previous value". For example, typing "I foo I " inserts
+"foofoo".
+
 T ( n -- ): select line n for editing.
-P xxx: put typed line on selected line.
+P xxx: put typed IBUF on selected line.
-U xxx: insert typed line on selected line.
+U xxx: insert typed IBUF on selected line.
-F xxx: find typed string in block.
+F xxx: find typed FBUF in block, starting from current
-I xxx: insert typed string at cursor.
+       position+1. If not found, don't move.
-E: Delete previously found string.
+I xxx: insert typed IBUF at cursor. "I" shadows core word. Use
-
+       "i" to access it.
-Note that "I" shadows core word. Use "i" to access core word.
+X ( n -- ): Delete X chars after cursor and place in IBUF.
-
+E: Run X with n = length of FBUF.
-
-
-
-
-
-
-

blk/102

@@ -1,14 +0,0 @@
-'? CASE NOT [IF] 51 52 LOADR+ [THEN] DROP ( B152-153 )
-'? FILL NOT [IF] 53 LOAD+ [THEN] DROP ( B155 )
-1 7 LOADR+
-: BROWSE
-    0 ACC ! L
-    BEGIN
-        KEY CASE
-            'Q' OF EXIT ENDOF
-            'B' OF B ENDOF
-            'N' OF N ENDOF
-            _NUM
-        ENDCASE
-    AGAIN
-;

blk/103

@@ -1,16 +0,0 @@
-CREATE ACC 0 ,
-: _LIST ." Block " DUP . NL LIST ;
-: _NUM
-    ACC @ SWAP _pdacc
-    IF _LIST 0 THEN
-    ACC !
-;
-: L BLK> @ _LIST ;
-: B BLK> @ 1- BLK@ L ;
-: N BLK> @ 1+ BLK@ L ;
-
-
-
-
-
-

blk/104

@@ -1,13 +0,0 @@
-( Cursor position in buffer. EDPOS/64 is line number )
-CREATE EDPOS 0 ,
-CREATE IBUF 64 ALLOT0
-CREATE FBUF 64 ALLOT0
-: _cpos BLK( + ;
-: _lpos 64 * _cpos ;
-: _pln ( lineno -- )
-    DUP _lpos DUP 64 + SWAP DO ( lno )
-        I EDPOS @ _cpos = IF '^' EMIT THEN
-        I C@ DUP 0x20 < IF DROP 0x20 THEN
-        EMIT
-    LOOP ( lno ) 1+ . ;
-: _zbuf 64 0 FILL ; ( buf -- )

blk/105

@@ -1,12 +1,14 @@
-: _type ( buf -- )
+'? CASE NOT [IF] 48 49 LOADR+ [THEN] DROP ( B153-154 )
-    C< DUP 0xd = IF 2DROP EXIT THEN SWAP DUP _zbuf ( c a )
+'? FILL NOT [IF] 50 LOAD+ [THEN] DROP ( B155 )
-    BEGIN ( c a ) C!+ C< TUCK 0x0d = UNTIL ( c a ) C! ;
+1 7 LOADR+
-( user-facing lines are 1-based )
+: BROWSE
-: T 1- DUP 64 * EDPOS ! _pln ;
+    0 ACC ! L
-: P IBUF _type IBUF EDPOS @ _cpos 64 MOVE BLK!! ;
+    BEGIN
-: _mvln+ ( ln -- move ln 1 line down )
+        KEY CASE
-    DUP 14 > IF DROP EXIT THEN
+            'Q' OF EXIT ENDOF
-    _lpos DUP 64 + 64 MOVE ;
+            'B' OF B ENDOF
-: _mvln- ( ln -- move ln 1 line up )
+            'N' OF N ENDOF
-    DUP 14 > IF DROP 15 _lpos _zbuf
+            _NUM
-    ELSE 1+ _lpos DUP 64 - 64 MOVE THEN ;
+        ENDCASE
+    AGAIN
+;

blk/106

@@ -1,5 +1,16 @@
-: _U ( U without P, used in VE )
+CREATE ACC 0 ,
-    15 EDPOS @ 64 / - 0 DO
+: _LIST ." Block " DUP . NL LIST ;
-        14 I - _mvln+
+: _NUM
-    LOOP ;
+    ACC @ SWAP _pdacc
-: U _U P ;
+    IF _LIST 0 THEN
+    ACC !
+;
+: L BLK> @ _LIST ;
+: B BLK> @ 1- BLK@ L ;
+: N BLK> @ 1+ BLK@ L ;
+
+
+
+
+
+

blk/107

@@ -1,10 +1,13 @@
-: _F ( F without _type and _pln. used in VE )
+( Cursor position in buffer. EDPOS/64 is line number )
-    FBUF EDPOS @ _cpos ( a1 a2 )
+CREATE EDPOS 0 ,
-    BEGIN
+CREATE IBUF 64 ALLOT0
-        C@+ ROT ( a2+1 c2 a1 ) C@+ ROT ( a2+1 a1+1 c1 c2 )
+CREATE FBUF 64 ALLOT0
-        = NOT IF DROP FBUF THEN ( a2 a1 )
+: _cpos BLK( + ;
-        TUCK C@ 0xd = ( a1 a2 f1 )
+: _lpos 64 * _cpos ;
-        OVER BLK) = OR ( a1 a2 f1|f2 )
+: _pln ( lineno -- )
-    UNTIL ( a1 a2 )
+    DUP _lpos DUP 64 + SWAP DO ( lno )
-    DUP BLK) < IF BLK( - FBUF + -^ EDPOS ! ELSE DROP THEN ;
+        I EDPOS @ _cpos = IF '^' EMIT THEN
-: F FBUF _type _F EDPOS @ 64 / _pln ;
+        I C@ DUP 0x20 < IF DROP 0x20 THEN
+        EMIT
+    LOOP ( lno ) 1+ . ;
+: _zbuf 64 0 FILL ; ( buf -- )

blk/108

@@ -1,15 +1,12 @@
-: _blen ( buf -- length of str in buf )
+: _type ( buf -- )
-    DUP BEGIN C@+ EOL? UNTIL -^ 1- ;
+    C< DUP 0xd = IF 2DROP EXIT THEN SWAP DUP _zbuf ( c a )
-: _rbufsz ( size of linebuf to the right of curpos )
+    BEGIN ( c a ) C!+ C< TUCK 0x0d = UNTIL ( c a ) C! ;
-    EDPOS @ 64 MOD 63 -^ ;
+( user-facing lines are 1-based )
-: i COMPILE I ; IMMEDIATE ( save overshadowed )
+: T 1- DUP 64 * EDPOS ! _pln ;
-: _I ( I without _pln and _type. used in VE )
+: P IBUF _type IBUF EDPOS @ _cpos 64 MOVE BLK!! ;
-    _rbufsz IBUF _blen 2DUP > IF
+: _mvln+ ( ln -- move ln 1 line down )
-        TUCK - ( ilen chars-to-move )
+    DUP 14 > IF DROP EXIT THEN
-        SWAP EDPOS @ _cpos 2DUP + ( ctm ilen a a+ilen )
+    _lpos DUP 64 + 64 MOVE ;
-        3 PICK MOVE- ( ctm ilen )
+: _mvln- ( ln -- move ln 1 line up )
-        NIP ( ilen )
+    DUP 14 > IF DROP 15 _lpos _zbuf
-    ELSE DROP ( ilen becomes rbuffsize )
+    ELSE 1+ _lpos DUP 64 - 64 MOVE THEN ;
-    THEN
-    DUP IBUF EDPOS @ _cpos ROT MOVE ( ilen ) EDPOS +! BLK!! ;
-: I IBUF _type _I EDPOS @ 64 / _pln ;

blk/109

@@ -1,9 +1,5 @@
-: X ( len -- , delete len chars after curpos )
+: _U ( U without P, used in VE )
-    EDPOS @ _cpos 2DUP + ( l a1 a1+l )
+    15 EDPOS @ 64 / - 0 DO
-    SWAP _rbufsz MOVE ( l )
+        14 I - _mvln+
-    ( get to next line - l )
+    LOOP ;
-    DUP EDPOS @ 0xffc0 AND 0x40 + -^ _cpos ( l a )
+: U _U P ;
-    SWAP 0 FILL
-    EDPOS @ 64 / _pln ;
-: E FBUF _blen X ;
-

blk/110

@@ -0,0 +1,10 @@
+: _F ( F without _type and _pln. used in VE )
+    FBUF EDPOS @ _cpos 1+ ( a1 a2 )
+    BEGIN
+        C@+ ROT ( a2+1 c2 a1 ) C@+ ROT ( a2+1 a1+1 c1 c2 )
+        = NOT IF DROP FBUF THEN ( a2 a1 )
+        TUCK C@ 0xd = ( a1 a2 f1 )
+        OVER BLK) = OR ( a1 a2 f1|f2 )
+    UNTIL ( a1 a2 )
+    DUP BLK) < IF BLK( - FBUF + -^ EDPOS ! ELSE DROP THEN ;
+: F FBUF _type _F EDPOS @ 64 / _pln ;

blk/111

@@ -0,0 +1,15 @@
+: _blen ( buf -- length of str in buf )
+    DUP BEGIN C@+ EOL? UNTIL -^ 1- ;
+: _rbufsz ( size of linebuf to the right of curpos )
+    EDPOS @ 64 MOD 63 -^ ;
+: i COMPILE I ; IMMEDIATE ( save overshadowed )
+: _I ( I without _pln and _type. used in VE )
+    _rbufsz IBUF _blen 2DUP > IF
+        TUCK - ( ilen chars-to-move )
+        SWAP EDPOS @ _cpos 2DUP + ( ctm ilen a a+ilen )
+        3 PICK MOVE- ( ctm ilen )
+        NIP ( ilen )
+    ELSE DROP ( ilen becomes rbuffsize )
+    THEN
+    DUP IBUF EDPOS @ _cpos ROT MOVE ( ilen ) EDPOS +! BLK!! ;
+: I IBUF _type _I EDPOS @ 64 / _pln ;

blk/112

@@ -0,0 +1,11 @@
+: icpy ( n -- copy n chars from cursor to IBUF )
+    IBUF _zbuf EDPOS @ _cpos IBUF ( n a buf ) ROT MOVE ;
+: X ( n -- )
+    DUP icpy EDPOS @ _cpos 2DUP + ( n a1 a1+n )
+    SWAP _rbufsz MOVE ( n )
+    ( get to next line - n )
+    DUP EDPOS @ 0xffc0 AND 0x40 + -^ _cpos ( n a )
+    SWAP 0 FILL
+    EDPOS @ 64 / _pln ;
+: E FBUF _blen X ;
+

blk/120

@@ -2,15 +2,15 @@ Visual Editor
 
 This editor, unlike the Block Editor (B100), is grid-based
 instead of being command-based. It requires the AT-XY, COLS
-and LINES words to be implemented.
+and LINES words to be implemented. If you don't have those,
+use the Block Editor.
 
 It is loaded with "125 LOAD" and invoked with "VE". Note that
-this also fully loads the Block Editor (B100).
+this also fully loads the Block Editor.
 
-This editor uses 17 lines. The top line is the status line and
+This editor uses 19 lines. The top line is the status line and
-the 16 others are contents lines. The content shown is that
+it's followed by 2 lines showing the contents of IBUF and
-of the currently selected block.
+FBUF (see B100). There are then 16 contents lines. The contents
+shown is that of the currently selected block.
 
-All keystrokes are directly interpreted by VE and have the
-effect described below.
                                                         (cont.)

blk/121

@@ -1,3 +1,6 @@
+All keystrokes are directly interpreted by VE and have the
+effect described below.
+
 Pressing a 0-9 digit accumulates that digit into what is named
 the "modifier". That modifier affects the behavior of many
 keystokes described below. The modifier starts at zero, but
@@ -5,12 +8,9 @@ most commands interpret a zero as a 1 so that they can have an
 effect.
 
 'g' selects the block specified by the modifier as the current
-block. Any change madde to the previously selected block is
+block. Any change made to the previously selected block is
 saved beforehand.
 
-'[' and ']' advance the selected block by modifier.
+'[' and ']' advances the selected block by "modifier".
 
-';' resets the modifier. 'q' quits.
+';' resets the modifier. 'q' quits.                     (cont.)
-
-'h' and 'l' move the cursor by "modifier" characters. 'j' and
-'k', by lines.                                          (cont.)

blk/122

@@ -1,16 +1,16 @@
+'h' and 'l' move the cursor by "modifier" characters. 'j' and
+'k', by lines.
+
 'H' goes to the beginning of the line, 'L' to the end.
 
-'w' moves forward by a word. 'b' moves backward by a word.
+'w' moves forward by "modifier" words. 'b' moves backward.
-'W' moves to end-of-word. 'B' moves backward to end-of-word.
+'W' moves to end-of-word. 'B', backwards.
 
-'I', 'F' and 'E' invoke the corresponding command from the
+'I', 'F', 'X' and 'E' invoke the corresponding command from the
 Block Editor (B100). Refer to documentation there.
 
 'o' inserts a blank line after the cursor. 'O', before.
 
 'D' deletes "modifier" lines at the cursor.
 
-
-
-
                                                         (cont.)

blk/123

@@ -1,11 +1,9 @@
-'f' puts the contents of your previous cursor movement into the
+'f' puts the contents of your previous cursor movement into
-find buffer. If that movement was a forward movement, it brings
+FBUF. If that movement was a forward movement, it brings the
-the cursor back where it was. This allows for an efficient
+cursor back where it was. This allows for an efficient combi-
-combination of movements and 'E'. For example, if you want to
+nation of movements and 'E'. For example, if you want to delete
-delete the next word, you type 'w', then 'f', then check your
+the next word, you type 'w', then 'f', then check your FBUF to
-"F" buffer to be sure, then press 'E'.
+be sure, then press 'E'.
-
-'X' deletes "modifier" characters following cursor.
 
 'R' goes into replace mode at current cursor position.
 Following keystrokes replace current character and advance

blk/125

@@ -1,3 +1,3 @@
 '? UPPER NOT [IF] 33 LOAD+ [THEN] DROP ( B158 )
--23 LOAD+ ( B102, block editor )
+-20 LOAD+ ( B105, block editor )
 1 6 LOADR+