From efb5d2d650a0622f1fd2c67a598734b1fb2e66ef Mon Sep 17 00:00:00 2001 From: Patrick Kloepfer Date: Tue, 17 Sep 2019 22:50:11 -0400 Subject: [PATCH] Updates to documentation to get ready for release. --- .Docs/Shell Developers Guide.md | 3 +- .Docs/User Guide.md | 166 +++++++++++++++----------------- .Floppies/A2OSX.MAKE.po | Bin 33553920 -> 33553920 bytes TESTS/ARGTEST.txt | 5 - TESTS/ARGTEST2.txt | 11 --- TESTS/BUILDTEST.txt | 32 ++---- 6 files changed, 86 insertions(+), 131 deletions(-) diff --git a/.Docs/Shell Developers Guide.md b/.Docs/Shell Developers Guide.md index 6a1288e0..169ce057 100644 --- a/.Docs/Shell Developers Guide.md +++ b/.Docs/Shell Developers Guide.md @@ -124,7 +124,8 @@ Notice that the DO X and DO Y logic is swapped between the two cases. | END | Working | End of SWITCH Statement | | EXIT | Working | exit function, script or shell | | FI | Working | Terminator for IF block | -| FUNCTION | Working | FUNCTION fonction_name {
\
} | +| FUNCTION | Working | FUNCTION fu +nction_name {
\
} | | IF | Working | [ \ ]
![ \ ]| | LOOP | Working | Terminator for WHILE block | | MD | Working | MD path or relative path
Create a directory | diff --git a/.Docs/User Guide.md b/.Docs/User Guide.md index 3481a58e..0c1dec76 100644 --- a/.Docs/User Guide.md +++ b/.Docs/User Guide.md @@ -9,7 +9,7 @@ A2osX is already much more then a "primitive" command line operating system. Wh A core element at the foundation of A2osX that enables its multiuser multitasking capabilities is its reusable set of APIs and Libraries (written in Assembly) that all programs can and do use that make them very lean and fast. For instance, there is one network API that any program can call which in turn handles the I/O to different LAN cards via drivers. A significant feature is that multiple programs can be using the network at the same time such as the TELNETD server, the HTTPD server and/or the TELNET client. A key benefit is that the code for doing each program is smaller because the network API is doing a lot of the work. And since CORE APIs like printf and libraries such as Network loaded only once, much like a DLL in Windows, significant memory is conserved providing the resources needed to support multitasking and multiple users. -The core of A2osX is written entirely in 65C02 Assemnbly and built using the S-C Macro Assembler. Assembly was chosen because at end of day it provides for the most strict and stringent memory management as well as the fastest performance of any language on the Apple II. Work is underway to provide ASM running under A2osX (see Current and Future Development Process sections below). There is also an entire shell scripting language (see below) and in the future we plan a CSH (C-Shell) which is the first step to an Interactive C interpreter and then a Compilter that will make C feed to built-in assembler. Yes, that is a lot on our development plan, but the only way to make it feasible is by building the core using assembly to provide enough memory and processing sources to enable such features. +The core of A2osX is written entirely in 65C02 Assembly and built using the S-C Macro Assembler. Assembly was chosen because at end of day it provides for the most strict and stringent memory management as well as the fastest performance of any language on the Apple II. Work is underway to provide ASM running under A2osX (see Current and Future Development Process sections below). There is also an entire shell scripting language (see below) and in the future we plan a CSH (C-Shell) which is the first step to an Interactive C interpreter and then a Compilter that will make C feed to built-in assembler. Yes, that is a lot on our development plan, but the only way to make it feasible is by building the core using assembly to provide enough memory and processing sources to enable such features. ## Developing for A2osX @@ -21,19 +21,27 @@ The Developers Guide is all about developing the core of A2osX, its drivers, uti One of the most significant parts of A2osX is its shell which can perform both interactive and scripted tasks. With the interactive part of the shell you can perform many common and complex tasks using both built-in (native or internal to shell) and external (BINs or executables) commands. Internal commands include CD (change directory), MD (make directory), DATE, TIME, etc. External commands include CP (copy), RM (remove), CAT (display file contents), TELNET, etc. -It should be noted, that it is possible to create and execute short scripts right on the interactive command line (these are run once and not saved like true scripts). An example +It should be noted, that it is possible to create and execute short scripts right on the interactive command line (these are run once and not saved like true scripts). An example + +``` +FOR FILE IN `LS -C CT*`; CAT ${FILE}; NEXT +``` + +In this example, the system will generate a list of files found in the current directory that match the CT* wildcard and perform the CAT operation on each. The semicolons act as a line separator allowing you to type in multiple commands, or short scripts, to execute as an inline script. An entire Shell Developers Guide is being written to help you with both using and writing scripts for the A2osX Shell. It can be found **[Here](.Docs/Shell%20Developers%20Guide.md).** ### File System Layout of A2osX -To use files and directories well, you need to understand the concept of a hierarchical file system. This section introduces the A2osX file system and shows you how to work with files and directories using several A2osX commands. -A2osX organizes information in files and directories. A directory is a special file that can contain other files and directories. Because a directory can contain other directories, this method of organizing diles gives rise to a hierarchical structure. This organization of files is the file system. -Folks who use and are accustomed to working with Linux or Unix will find familiarity with A2osX. Many of the commands and much of the Shell interface follows the User Interface (UI) presented by Linux. There is however one key difference, that makes A2osX adhere more to the ProDOS model and that is the concept of the ROOT directory or volume. +To get the most out of the use of files and directories you need to understand the concept of a hierarchical file system. This section introduces the A2osX file system and shows you how to work with files and directories using several A2osX commands. + +A2osX organizes information in files and directories. A directory is a special file that can contain other files and directories. Because a directory can contain other directories, this method of organizing files gives rise to a hierarchical structure. This organization of files is the file system. + +Folks who use and are accustomed to working with Linux or Unix will find familiarity with A2osX. Many of the commands and much of the Shell interface follows the User Interface (UI) presented by Linux. There is however, one key difference, that makes A2osX adhere more to the ProDOS model which is the support for multiple distinct volumes. In Linux there is only one root represented by / (typically the boot volume) with all other drives appearing as sub directories of this volume. A2osX instead continues to present each volume separately by their name as does ProDOS. A2osX does present a BOOT/SYSTEM directory (where A2OSX.SYSTEM was loaded from) and uses this for finding critical system directories and files such as BIN and ETC. + You move around the file sytesm with CD and pwd will tell you were you are. Your default prompt includes your current path. - -The following are the primary sub-directories used by A2osX. While A2osX supports all standard ProDOS media/volumes and you can use its commands and utilities (like cp [copy] ls [catalog] rm [delete]) on these volumes, A2osX and its modules, commands, scripts, etc. must be installed under one directory that has these directories (at their related files) stored under it. Below where you see a ./ (dot slash) in front of each path, think of that as the volume name or directory name where you have installed A2osX. For example, on the media we supplied called BOOT, which has a volume name of /A2OSX.BOOT/, you will find directories named BIN and ETC. The full path name for those dirs would be /A2OSX.BOOT/BIN/ and /A2OSX.BOOT/ETC/. If you installed A2OSX on your own harddrive called /MYVOL1 in a directory called A2OSX, then your ./ would refer to /MYVOL1/A2OSX/ and your BIN would be /MYVOL1/A2OSX/BIN/. See the installation section for more information on using A2osX with your own volumes. +The following are the primary sub-directories used by A2osX. While A2osX supports all standard ProDOS media/volumes and you can use its commands and utilities (like cp [copy] ls [catalog] rm [delete]) on these volumes, A2osX and its modules, commands, scripts, etc. must be installed under one directory that has these directories (and their related files) stored under it. Below where you see a ./ (dot slash) in front of each path, think of that as the volume name or directory name where you have installed A2osX. For example, on the media we supplied called BOOT, which has a volume name of /A2OSX.BOOT/, you will find directories named BIN and ETC. The full path name for those dirs would be /A2OSX.BOOT/BIN/ and /A2OSX.BOOT/ETC/. If you installed A2OSX on your own hard drive called /MYVOL1 in a directory called A2OSX, then your ./ would refer to /MYVOL1/A2OSX/ and your BIN would be /MYVOL1/A2OSX/BIN/. See the installation section for more information on using A2osX with your own volumes. | Path | Use | | ---- | --- | @@ -180,29 +188,11 @@ Network Card (Uthernet I or II, LanCes) ## Getting Started -A2osX Distribution Media -Several media image files are being made available. -BUILD -BOOT -MAKE -AW -INSTALL -APPWIN - - Several images are available including: - BUILD a 32-megabyte bootable hardrive image containing all of A2osX. - BOOT a 140K bootable floppy image containing the minimum files needed to boot the A2osx Kernel and core functions. - INST100- A series of 140K floppy images that can be used to install - INST10x A2osx onto your own ProDOS volume. Disk 100 is bootable and - automatically runs an appopriate instalation script. - INST800- A series of 800K floppy images that can be used to install - INST80x A2osx onto your own ProDOS volume. Disk 100 is bootable and - automatically runs an appopriate instalation script. - +To get started with A2osX, the very first thing you need to do is download a disk image from GitHub. Images are available in multiple versions from cutting edge developer seeds to release candidates as well as in multiple sizes suitable for placing on Disk II drives, 3.5 drives or hard drives of for use with emulators. Please consult the **[A2osX Media Guide](.Docs/Media%20Guide.md).** for detailed information on the available images. ### Using AppleWin -Running from supplied media +Download one of the available 32MB images from GitHub. Open AppleWin and then click on the configuration icon. When the configuration screen appears, select the Disk tab. Next, make sure the **Enable Hard disk controller in slot 7** box is checked and set the **HDD 1** to the image you downloaded. Click OK to save your changes and finally boot the emulated Apple by clicking on the colored Apple icon. Suggestion: on the configuration screen, for Video Mode, select Color (RGB Monitor). You may also want to setup AppleWin for Ethernet as A2osX has many features that make use of the emulated Uthernet I card supplied by AppleWin (consult AppleWin documentation for more information on enabling this feature). ### Installing on Your Apple @@ -214,8 +204,7 @@ Find out more MAN Additional resources -##Networking - +## Networking install the drivers for the hardware (uther, lances, ssc, etc.) then NETWORKD lib lib (and the libs are tcpip or etalk maybe) libs are protocalls here @@ -224,10 +213,6 @@ NETWORKD will read ETC/NETWORK will load network programs right now it contains IPCONFIG, you can also add to it HTTPD TELNETD etc, they are loaded in order and each needs to complete its full load before next one happens (assuring IPCONFIG happends before TELNETD tries to load) IPCONFIG will then look for ETC/TCPIP.CONF, if found uses those settings, if not does dhcp. in addition ipconfig uses ETC/HOSTNAME and ETC/HOSTS for setting hostname and doing DNSloopups - - - - Hardware Drivers MAC Address TCPIPD @@ -252,12 +237,12 @@ Telnetd httpd -##Utilities +## Utilities -###Using Text Editors +### Using Text Editors EDIT -###Commands for navigating the file system +### Commands for navigating the file system CD CD .. PWD @@ -266,68 +251,27 @@ PUSHD POPD LS LS -L or L -###Commands for working with files + +### Commands for working with files + MV CP RM -###Commands for working with directories + +### Commands for working with directories + MD RD -## License +## Error Messages -A2osX is made available under the GNU License 2.0. Our Full License can he found **[Here](../License).** +* ProDOS Error Codes : $00->$5F +* Kernel Error Codes : $60->$7F +* Lib Error Codes : $80->$BF +* Shell Error Codes : $C0->$CF +* Application Error Codes : $ D0->$FF -##Error Messages - -The Error section is out of date. Refresh from INC/A2osX.I -Error nums have been realigned and move around. - - - -Shell Errors - -| Hex | Error Code | Error Message | -| --- | --- | --- | -|||User Interrupt| -|||Command Syntax Error| -|||Script Syntax Error| -|||Expression Syntax Error| -|||Stack Overflow| -|||LOOP Without WHILE| -|||NEXT Without FOR| -|||FI/ELSE Without IF| -|||Bad Expression| -|||Bad File Type| -|||Unknown Error| - -* ProDOS ERROR CODES : $00->$5F -* Lib ERROR CODES : $80->$BF -* Kernel ERROR CODES : $F0->$FF - -| Hex | Error Code | Error Message | -| --- | --- | --- | -| $FF | 0 | Out Of Memory Error| -| $FE | 0 | Out Of Handle Error| -| $FD | 0 | Invalid Handle| -| $FC | 0 | Buffer Overflow| -| $FB | 0 | Bad Path| -| $FA | 0 | Bad Argument| -| $F9 | 0 | No Such Process Error| -| $F8 | 0 | Syntax Error| -| $F7 | 0 | Env is Full| -| $F6 | 0 | Invalid BIN format| -| $F5 | 0 | File Too Big Error| -| $F4 | 0 | Out Of Bound| -| $F3 | 0 | Invalid Numerical| -| $F2 | 0 | Invalid User| -| $EF | 0 | Undefined Key| -| $EE | 0 | Duplicate Key| -| $ED | 0 | No Data| -| $EC | 0 | Data Length Mismatch| - - -ProDOS or MLI Errors +### ProDOS or MLI Errors | Hex | Error Code | Error Message | | --- | --- | --- | @@ -364,6 +308,48 @@ ProDOS or MLI Errors | $57 | 87 | Duplicate Volume| | $5A | 90 | File Structure Damaged| +### Kernel Errors + +| Hex | Error Code | Error Message | +| --- | --- | --- | +| $7F | 0 | Out Of Memory Error| +| $7E | 0 | Out Of Handle Error| +| $7D | 0 | Invalid Handle| +| $7C | 0 | Buffer Overflow| +| $7B | 0 | Bad Path| +| $7A | 0 | Bad Argument| +| $79 | 0 | No Such Process Error| +| $78 | 0 | Syntax Error| +| $77 | 0 | Environment is Full| +| $76 | 0 | Invalid BIN format| +| $75 | 0 | File Too Big Error| +| $74 | 0 | Out Of Bound| +| $73 | 0 | Invalid Numerical| +| $72 | 0 | Stack Error| +| $6F | 0 | Undefined Key| +| $6E | 0 | Duplicate Key| +| $6D | 0 | No Data| +| $6C | 0 | Data Length Mismatch| +| $68 | 0 | Invalid PWD database | +| $67 | 0 | Invalid User | + +### Shell Errors + +| Hex | Error Code | Error Message | +| --- | --- | --- | +| $BF | 0 |User Interrupt| +| $C0 | 0 |Command Syntax Error| +| $-- | 0 |Script Syntax Error| +| $C1 | 0 |Expression Syntax Error| +| $C2 | 0 |Stack Error| +| $C3 | 0 |Stack Overflow| +| $C4 | 0 |LOOP Without WHILE| +| $C5 | 0 |NEXT Without FOR| +| $C6 | 0 |FI/ELSE Without IF| +| $C7 | 0 |Bad File Type| +| $C8 | 0 |Undefined Function| +| $C9 | 0 |Unexpected EOF| + ## License A2osX is licensed under the GNU General Pulic License. diff --git a/.Floppies/A2OSX.MAKE.po b/.Floppies/A2OSX.MAKE.po index 0e320d34d55cdaad78da2c602481ba979649065f..a1cba664ec9c86b20fd53596d47e315e0b8ee479 100644 GIT binary patch delta 2365 zcmYMzdw30G9Ki9tvoT9^=xEAqHI0y>S&T5YSC(w!QqW6_rchUr#;#@%cXQ^LzhzpXYs^-;5*28_&S%oaCgA?K-8@ zXC~}QNa)xuDJdaUoQ!ld$0;}!EzlCJ&>C%!fzxn0GSL=iAPeo#9%rHhI-(QKLT8+f zbI=7{aW1ma4LLXu-O&TN=!sr9AHC5BeUXQL=#P99z+(U|z(5q@LJY!17>ptmV+e*~ z7=~j6Mq(63V+=0FCAbuq;c{Gou^5N(xDr?4YFvW}xE9ypdfb2;aT6wD5+>tj+=5$i z8*axGgm4F@;?CHr9@F~oPwSkKH*~=8f?>nEX5?jbiDs2-aNz?TO8m0+C5hoRolA1! zMZqmDsbOqVcFDZtnn0s&PI5~m_b$o3JDNM)rN&*_7I)lJKa|ES$PC;+jlx$4Zlm z=VL)EsknSjWq9(~qJELXH6b@9yf43QeK=NIz9>?=JL+15BL#Ki!i5EOBO=M`LT>Rt z)8?Y(qK}9!6b*}3h%OR+RCKZEW1^3XR*FVMmxwMEeM0m}(JIlWM3;#!7kyfEh3HDr zXGEVBeNMDmbd~68(KVvai`Iy)6(eFin5dBf~C(-?)Ka2h%dO);R^x!hp zp{WxmWDN9!3Pu(TicDS_a)aY5`O1+lJa&9hgGlk7s0&2WD?_fQ_&V{wivLag@8S=M zKP>(a@qdc{OZ*Y>N5vl#e|)xgW!@nX^^k;Q)JFrPpdnIm0vh2&q@ghaXo99V2|+Z& z$w)_YoPtx)0xi)Bt3kc0Ek z9X*hXp6G@1(Hnix7kTK1{>VoG>|X}p0t`eUF2o>Qguy66F@|6$hG95HU?fIiG{)d! zT!Kq+87{{a7>jWjk1KH%uEsT(fNOCbuE!0y5jSBXCSfve#x1xNx8Zh7an(NLMlVd; zloT${uNxL$u_WY1)r;?lg$M85R5y28H#S?fERd@=^upCcg z1yJ61Ti+dCjuX^15Y{5th1&ZYcBD@SG;fkb*h^DrZk+zs+3z?Xt_M^;j>E**L zpBC9-sig5tOG+!-ELyE>GtCwk@JD5qOW$kDsXsp7x#u@CXYRRY%8#FFTaNYV;bAGs zG4UI`;n`iCP=9g5oX&Hr5-X|_9W+BI!Vr$;Xn~f9KqOkBHKNc4Z4r$a#G+lWDlu+j z^y#kz3)13_JAW_J;~JglJH@tjjngUg!sNA7>qg+ov*VEtiq`ICo*E7KNq`RKg zJ<6K39q4*8Tu-L!Npw9aQHg=6n@gRJftppNPEw!`>y?3>G4)QW|4?#SySff>^^P|p z=uItK94_86@y-(OoweTCPGlgKXA}Nbl^hwdDM4uL2Bl?W!v!ZK7*NLtdtr2}r zbc5(d(dR{LMT4T7L|+iyEV@PXMbVc;w~E$@zAXBR=r+;qqOXd+Ci=SQ4$(J6-xPgI z^lj01M0bk5EBc;jz3BU*ABcV^`jP0zqMwNF68%*4GttjQcZ+@@`laYsqF;-CBf3ZQ zThYCu`$WGJ-7osR=ntYlivA>eK=h#KA<@I44Wf;rM^>vAF6}ijGH_sJsngnj`t(K~ z@on(;Xz*?E`x|}5Vw%MKEan$6zlu33<~K3N#QZMi4>8BZoDg$T%&GatsWc9nArxT< zM{~45OGF?NtD!}XYo z8!!zw;wDVT&A0`(;x=ckDRsv4leF;Xrs*#^YFxC-5Ym!qZrTXYef6Vjb3_2G3ywHsX0_ zZFQ|PBv3Q2>b}nA4OJ49#g;;{^Kcs&&!=gHF^skqfi-*E%F3Zy&1*KV+w8D;!{$w!w`|_FdBHA diff --git a/TESTS/ARGTEST.txt b/TESTS/ARGTEST.txt index e61432a9..b40c0cf6 100644 --- a/TESTS/ARGTEST.txt +++ b/TESTS/ARGTEST.txt @@ -19,11 +19,6 @@ AUTO 4,1 # # Now call Argtest Sub Script # -echo "Here are the variables that are SET" >> ${Log} -echo "----------------------------------------" >> ${Log} -echo >> ${Log} -SET >> ${Log} -echo "----------------------------------------" >> ${Log} . ARGTEST2 A 1 B 2 C 3 Hello $$ 82 Tenth MAN TEXT /MAKE/USR/SHARE/TESTS/ARGTEST diff --git a/TESTS/ARGTEST2.txt b/TESTS/ARGTEST2.txt index 8986d105..547c3fbf 100644 --- a/TESTS/ARGTEST2.txt +++ b/TESTS/ARGTEST2.txt @@ -18,17 +18,6 @@ AUTO 4,1 # # $0 should be name of script # -ECHO ARRIVED AT ARGTEST2 -PAUSE -echo >> ${Log} -ECHO $1 $2 $3 $4 $5 $6 $7 $8 $9 $# $* -# >> ${Log} -echo >> ${Log} -echo "Here are the variables that are SET" >> ${Log} -echo "----------------------------------------" >> ${Log} -echo >> ${Log} -SET >> ${Log} -echo "----------------------------------------" >> ${Log} IF [ -Z $T ] SET T = 0 FI diff --git a/TESTS/BUILDTEST.txt b/TESTS/BUILDTEST.txt index 45e7a5d0..e71e0013 100644 --- a/TESTS/BUILDTEST.txt +++ b/TESTS/BUILDTEST.txt @@ -57,43 +57,27 @@ ECHO "\n----------------------------------------\n" >> ${Log} SET T = 1 SET P = 0 SET F = 0 - -echo "Here are the variables that are SET" >> ${Log} -echo "----------------------------------------" >> ${Log} -echo >> ${Log} -SET >> ${Log} -echo "----------------------------------------" >> ${Log} # # Run The Tests using the current shell (. test) # . BADSHTEST ECHO "\n----------------------------------------\n" >> ${Log} -echo "Here are the variables that are SET" >> ${Log} -echo "----------------------------------------" >> ${Log} -echo >> ${Log} -SET >> ${Log} -echo "----------------------------------------" >> ${Log} -ECHO "\n Calling VTTEST\n" >> ${Log} -ECHO "\n----------------------------------------\n" >> ${Log} -. VTTEST -ECHO "\n----------------------------------------\n" >> ${Log} -echo "Here are the variables that are SET" >> ${Log} -echo "----------------------------------------" >> ${Log} -echo >> ${Log} -SET >> ${Log} -echo "----------------------------------------" >> ${Log} -ECHO "\n Calling ARGTEST\n" >> ${Log} -ECHO "\n----------------------------------------\n" >> ${Log} -. ARGTEST -ECHO "\n----------------------------------------\n" >> ${Log} ECHO "\n Calling ECHOTEST\n" >> ${Log} ECHO "\n----------------------------------------\n" >> ${Log} . ECHOTEST ECHO "\n----------------------------------------\n" >> ${Log} +ECHO "\n Calling VTTEST\n" >> ${Log} +ECHO "\n----------------------------------------\n" >> ${Log} +. VTTEST +ECHO "\n----------------------------------------\n" >> ${Log} ECHO "\n Calling CATTEST\n" >> ${Log} ECHO "\n----------------------------------------\n" >> ${Log} . CATTEST ECHO "\n----------------------------------------\n" >> ${Log} +ECHO "\n Calling ARGTEST\n" >> ${Log} +ECHO "\n----------------------------------------\n" >> ${Log} +. ARGTEST +ECHO "\n----------------------------------------\n" >> ${Log} ECHO "\n Calling IFLEVEL\n" >> ${Log} ECHO "\n----------------------------------------\n" >> ${Log} . IFLEVEL