Significantly updated Command Guide. Still a work in progress. A couple of new screen shots which are used in the Command Guide.

.Docs/Command Guide.md

@@ -2,7 +2,9 @@
 
 This Guide provides information on all the A2osX commands and utilities.  This Guide helps you not only learn the purpose of each command but also what options a command supports and what arguments it either supports or requires.
 
-A2osX comes with a nice variety of system, file, network and data utilities or what we refer to as external commands.  This just means that each of the following commands or utilities is built as a separate BIN or executable file that runs under A2osX.  The source for all of these external commands is readily available, so you can make your own as your needs dictate.  Note, that there are some **internal** commands that are build into the shell (the interactive prompt) such CD (change directory) or PWD (print working directory).  Those commands are discussed in-depth in the **[Shell Developers Guide](.Docs/Shell%20Developers%20Guide.md).**  
+A2osX comes with a nice variety of system, file, network and data utilities or what we refer to as external commands.  This just means that each of the following commands or utilities is built as a separate BIN or executable file that runs under A2osX.  The source for all of these external commands is readily available, so you can make your own as your needs dictate.
+
+>Note, that there are some **internal** commands that are build into the shell (the interactive prompt) such CD (change directory) or PWD (print working directory).  Those commands are discussed in-depth in the **[Shell Developers Guide](.Docs/Shell%20Developers%20Guide.md).**  
 
 ## System Commands
 
@@ -21,6 +23,14 @@ GETTY handles 3 types of connections:
 - for serial terminals (or emulated terminals i.e. a PC running a VT-100 emulator) connected to your Apple via a Super Serial Card.  One GETTY process serves one terminal.  See the User Guide for setup and configuration information on connecting Physical Terminals. 
 - for internet terminals connected to your Apple via via the internet using A2osX TCP networking suite.  This suite includes a TELNETD server process that listens for requests from the internet and when such a request is initiated, TELNETD will launch a GETTY process to support that user.  One GETTY process will launch for each TELNET user and will exit when then user disconnects (the TELNETD process calls GETTY with the -E option). 
 
+### INITD
+
+| Command |
+| ---- |
+| INITD RunLevel |
+
+This is a stub, or a placeholder, for a new routine being added to A2osX.  It will replace part of the startup process and allow for different run levels to be initiated included RunLevel 0 or shutdown.  Full implementation is targeted for 0.94.
+
 ### INSDRV
 
 | Command |
@@ -50,19 +60,11 @@ In KCONFIG you can set:
 
 | Command |
 | ---- |
-| INSDRV Driver |
+| LOGIN |
 
-### SH
+LOGIN is a system process for A2osX that authenticates users against the A2osX User Database stored in ./ETC/PASSWD.  Once a user is authenicated, LOGIN then loads the SH (./BIN/SH) process passing it the PROFILE script found in the users ${HOME} directory.
 
-| Command |
-| ---- |
-| SH Script |
-
-### INITD
-
-| Command |
-| ---- |
-| INITD InitLevel |
+>Note at this time that the User Database system is not complete so login temporarily defaults to logging in as user ROOT.  
 
 ## BIN,External Shell commands:
 
@@ -72,7 +74,37 @@ In KCONFIG you can set:
 | --- | --- |
 | CAT | -A : Show All non printable caracters <br> -N : Number all output lines <br> -S : Suppress repeated empty output lines |
 
-The CAT command is used to display the contents of files stored on any ProDOS volume.  While the primary use of this tool is to display the contents of TEXT or TXT files, it can be used to display the contents of other files by using the -A option, which will substitute non-printable characters with readable and displayable values such as [EOF] for End of File (Hex x04) or [LF] for Line Feed (Hex x0A).
+The CAT command is used to display the contents of files stored on any ProDOS volume.  While the primary use of this tool is to display the contents of TEXT or TXT files, it can be used to display the contents of other files by using the -A option, which will substitute non-printable characters with readable and displayable values such as [EOF] for End of File (Hex x04) or [LF] for Line Feed (Hex x0A).  In addition you can use the -N option to display the listing of a file with line numbers.
+
+As an example, if you had a text file called CATTEXT with the following lines:
+
+    Start of Cattext
+	
+	
+	End of Cattext
+
+Then if you executed at the A2osX prompt:
+
+    /A2OSX/ROOT/$ CAT -N CATTEXT
+
+You would get:
+
+----------
+>      1: Start of Cattext
+> 	   2:
+> 	   3:
+> 	   4: End of Cattext
+----------
+
+If you did CAT -N -S CATTEXT to suppress the extra blank lines you would see:
+
+----------
+>      1: Start of Cattext
+> 	   2:
+> 	   4: End of Cattext
+----------
+
+Note that the numbering of the lines didn't change, because that is their true number in f the file, but CAT removed the redundant blank lines.  Whether there are 2 or 200 blank lines in a row, they will be reduced to just 1.
 
 ### CUT
 
@@ -80,12 +112,74 @@ The CAT command is used to display the contents of files stored on any ProDOS vo
 | --- | --- |
 | CUT | CUT \<opt\> "line" or CMD\|CUT \<opt\> <br> -H : This help screen <br> -F nn : Output field nn <br> -M nn : Output starting at nn <br> -N nn : Output Ending at nn <br> -S ch : Change default SPACE separator to 'ch' |
 
+The CUT command is used to extract a sub part or portion of a string.  While one use of this command can be used to simply extract substrings much like Basic's MID, LEFT, or RIGHT might be used, it can also be used within the powerful FOR NEXT construct to process fields of columns from files or the output of processes.
+
+As an example, normally when you execute the **LS -L /** command you get output similar to:
+
+----------
+>/A2OSX.BUILD/ROOT/$ LS -L /
+>/RAM3            S3D2 Blocks Used:8 Total:16000
+>/A2OSX.BUILD     S7D1 Blocks Used: 3230 Total:65535
+>/MAKE            S7D2 Blocks Used:48946 Total:65535
+----------
+
+Now, if instead we execute the follow command at the shell prompt:
+
+    /A2OSX/ROOT/$ CAT -N CATTEXT
+
+----------
+>/A2OSX.BUILD/ROOT/$ FOR F IN `LS -L /`;ECHO $F;NEXT 
+>/RAM3            S3D2 Blocks Used:8 Total:16000 
+>/A2OSX.BUILD     S7D1 Blocks Used: 3230 Total:65535 
+>/MAKE            S7D2 Blocks Used:48946 Total:65535 
+----------
+
+----------
+>/A2OSX.BUILD/ROOT/$ FOR F IN `LS -L /`;CUT -M 00 -N 15 $F;NEXT                  
+>/RAM3                                                                           
+>/A2OSX.BUILD                                                                    
+>/MAKE                                                                           
+----------
+
+----------
+>/A2OSX.BUILD/ROOT/$ FOR F IN `LS -L /`;CUT -M 17 -N 21 $F;NEXT                  
+>S3D2                                                                            
+>S7D1                                                                            
+>S7D2                                                                            
+----------
+
+
+Another use of CUT.  Given a Text File like ./ETC/PASSWORD with the following contents:
+
+----------
+>root:1cedeaefaffab15fd23d7a282c6610b1:0:0:A2osX Root:/root:/bin/sh
+>guest:084e0343a0486ff05530df6c705c8bb4:1000:1000:Guest Account:/home/guest:/bin/sh
+----------
+
+Note the results of various CUT commands that use the -S option to denote : (colon) as the field separator.  This makes CUT a great tool for processing delimited text files.
+
+----------
+> /A2OSX.BUILD/ROOT/$ FOR F IN `CAT ../ETC/PASSWD`;CUT -S : -F 1 ${F};NEXT
+> root
+> guest
+> /A2OSX.BUILD/ROOT/$ FOR F IN `CAT ../ETC/PASSWD`;CUT -S : -F 2 ${F};NEXT
+> 1cedeaefaffab15fd23d7a282c6610b1
+> 084e0343a0486ff05530df6c705c8bb4
+> /A2OSX.BUILD/ROOT/$ FOR F IN `CAT ../ETC/PASSWD`;CUT -S : -F 3 ${F};NEXT
+> 0
+> 1000
+> /A2OSX.BUILD/ROOT/$ FOR F IN `CAT ../ETC/PASSWD`;CUT -S : -F 5 ${F};NEXT
+> A2osX Root
+> Guest Account
+----------
+
 ### CHGRP
 
 | Command | Options |
 | --- | --- |
 | CHGRP | In Progress | -C : Continue On Error <br> -R : Recurse subdirectories | - |
 
+This command is not currently implemented.
 
 ### CHMOD
 
@@ -93,6 +187,7 @@ The CAT command is used to display the contents of files stored on any ProDOS vo
 | --- | --- |
 | CHMOD | In Progress | -C : Continue On Error <br> -R : Recurse subdirectories | - |
 
+This command is not currently implemented.
 
 ### CHOWN
 
@@ -100,6 +195,7 @@ The CAT command is used to display the contents of files stored on any ProDOS vo
 | --- | --- |
 | CHOWN | In Progress | -C : Continue On Error <br> -R : Recurse subdirectories | - |
 
+This command is not currently implemented.
 
 ### CHTYP
 
@@ -114,6 +210,7 @@ The CAT command is used to display the contents of files stored on any ProDOS vo
 | --- | --- |
 | CP | Working | -C : Continue On Error <br> -Q : Quiet <br> -R : Recurse subdirectories <br> -Y : Dont't Prompt For Override | 0.93 |
 
+CP, which stands for Copy, is one of the most powerful commands in A2osX.  Not only can it copy files from one ProDOS volume to another, it can copy entire directories or even directory trees from volume to volume, or to another location on the same volume.  This recursive nature allows you to use a single command to copy the contents of an entire ProDOS volume with a single command.  CP also supports wild cards so that you can copy just those files matching a pattern.
 
 ### EDIT
 
@@ -121,6 +218,12 @@ The CAT command is used to display the contents of files stored on any ProDOS vo
 | --- | --- |
 | EDIT | Working | still missing : find/replace | 0.93 |
 
+![](../.screen-shots/ScreenShot.EDIT.png)
+
+There is a help screen
+
+![](../.screen-shots/ScreenShot.EDIT%20Help.png)
+
 
 ### FORMAT
 
@@ -128,6 +231,7 @@ The CAT command is used to display the contents of files stored on any ProDOS vo
 | --- | --- |
 | FORMAT | In Progress | FORMAT \<BLOCKDEV\> [VOLUME.NAME] <br> -L : Low-Level Format *not currently supported <br> -1..9 : Catalog Size (block count) | 0.92 |
 
+The FORMAT command will erase an existing volume and update its name to the VOLUME.NAME supplied.  FORMAT does not currently support low level formatting.  The Volume/Device to be formatted must already be formatted.
 
 ### GREP
 
@@ -135,20 +239,41 @@ The CAT command is used to display the contents of files stored on any ProDOS vo
 | --- | --- |
 | GREP | Working | GREP \<opt\> PATTERN FILE or CMD\|GREP \<opt\> PATTERN <br> -H : This help screen <br> -I : Ignore Case <br> -N : Print line Number | 0.93 |
 
+The GREP command parses multiple lines of input (either from a file or from the redirected output of another command) and only outputs those lines that contain the PATTERN.  In this way, you can thing of the GREP command as a filter.  You can use the -I option to force GREP to ignore case in the PATTERN and the INPUT lines (i.e. it capitalizes both the source and the PATTERN before doing the compare) though it still outputs the actual lines of content that match (their original capitalization is preserved.
+
+Here are 4 examples of GREP:
+
+----------
+> /A2OSX.BUILD/ROOT/$ LS -L / | GREP S7                                           
+> /A2OSX.BUILD     S7D1 Blocks Used: 3230 Total:65535                             
+> /MAKE            S7D2 Blocks Used:48946 Total:65535                             
+>
+> /A2OSX.BUILD/ROOT/$ GREP :1000: ../ETC/PASSWD
+> guest:084e0343a0486ff05530df6c705c8bb4:1000:1000:Guest Account:/home/guest:/bin/sh
+>
+> /A2OSX.BUILD/ROOT/$ GREP ROOT ../ETC/PASSWD                                     
+>
+> /A2OSX.BUILD/ROOT/$ GREP -I ROOT ../ETC/PASSWD                                  
+> root:1cedeaefaffab15fd23d7a282c6610b1:0:0:A2osX Root:/root:/bin/sh              
+----------
+
+In the first example, only those volumes that are attached to Slot 7 are listed.  In the second, you can see that the user account for user 1000 is displayed from the PASSWD file.  In the third, you can see nothing is listed, but once we add the case insensitive option (-I) the root account is listed.
 
 ### KILL
 
 | Command | Options |
 | --- | --- |
-| KILL | Working | KILL \<signal\> PID <br> -0 : No Signal <br> -1 : SIGQUIT | 0.93 |
+| KILL | KILL \<signal\> PID <br> -0 : No Signal <br> -1 : SIGQUIT | 0.93 |
 
+The KILL command kills or terminates a running process.  This can be most useful when you have a running process that is stuck (perhaps you are debugging a program or script); you can switch to another virtual terminal (by pressing Open Apple-1) and executing the PS command to list currently running processes and then executing the KILL command on the errand process (i.e. KILL 27 to terminate process 27).
 
 ### LS
 
 | Command | Options |
 | --- | --- |
-| LS -A : Print . & .. <br> -C : Single column listing <br> -F : Single column, includes full path <br> -L : long listing with size/date... <br> -R : Recurse subdirectories |
+| LS | -A : Print . & .. <br> -C : Single column listing <br> -F : Single column, includes full path <br> -L : long listing with size/date... <br> -R : Recurse subdirectories |
 
+![](../.screen-shots/ScreenShot.LS.png)
 
 ### LSDEV
 
@@ -156,6 +281,7 @@ The CAT command is used to display the contents of files stored on any ProDOS vo
 | --- | --- |
 | LSDEV | Working | Dump device Drivers
 
+![](../.screen-shots/ScreenShot.LSDEV.png)
 
 ### LSOF
 
@@ -219,6 +345,12 @@ The CAT command is used to display the contents of files stored on any ProDOS vo
 | --- | --- |
 | RM | Working | RM \[File/Dir, *,? wildcards allowed\] <br> -C : Continue On Error <br> -Q : Quiet <br> -R : Recurse subdirectories 
 
+### SH
+
+| Command |
+| ---- |
+| SH Script |
+
 ## Network Tools
 
 ###ARP
@@ -294,7 +426,7 @@ ARP,IP,ICMP,UDP & TCP ok
 
 | Command |
 | ----- |
-| TELNETD -d [port]??? |
+| TELNETD -d [port] |
 
 
 ## Developer Tools
@@ -307,7 +439,7 @@ While almost every command and program that comes with A2osX can be considered a
 | ----- |
 | ASM |
 
-S-C MASM based multi CPU assembler
+ASM is A2osX's table driven multi-pass macro assembler.  This assembler is still in development and will be released shortly.  Technical documentation for the assembler and its language can be found in **[ASM](./ASM.md)**.  A Guide to using ASM will be forthcoming.
 
 ### MEMDUMP
 
@@ -315,12 +447,18 @@ S-C MASM based multi CPU assembler
 | ----- |
 | MEMDUMP |
 
-Tool to track memory leak
+![](../.screen-shots/ScreenShot.MEMDUMP.png)
+
+MEMDUMP is a program that allows the developer to display the contents of all of the memory that A2osX is currently using to aide with the debugging of your programs.
+
+RGXX you need to support more info on MEMDUMP and what the columns mean and how to look for mem that your particular program is using.
 
 ### RPCDUMP
 
 | Command |
 | ----- |
 | RPCDUMP |
+
 Tool based on UDP socket API, renamed from RPCINFO <br> RPCDUMP <ip\|host>
 
+RGXX we need more info on this command.