1 files changed, 115 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..abb8fce
--- /dev/null
+++ b/README.md
@@ -0,0 +1,115 @@
+# GWFetch
+
+GWFetch is a screenfetch/neofetch/etc. system information tool, but it
+is written in GW-BASIC for use on DOS-based systems.  The little tool
+should output some reasonably accurate information about your MS-DOS,
+FreeDOS, DR DOS, or PC-DOS computer with some caveats, of course.
+Because we're talking about MS-DOS and work-alikes, there are drastic
+variations in CPUs with only complicated ways of detecting them combined
+with the simplicity of older PCs (i.e. no "packages" per se).  
+
+## Requirements
+
+To run GWFetch, you'll need the following:
+
+ * GW-BASIC
+ 
+This script has been tested again GW-BASIC versions 2 and 3, nothing
+more.  It may run under QBASIC, but it hasn't been tested.
+
+The script will call common DOS commands, so please make sure your DOS
+directory is on the path.
+
+## Running
+
+To run GWFetch, simply enter:
+
+```
+gwbasic gwfetch.bas
+```
+
+or whatever your GW-BASIC executable is named (I simplified it to *gw*
+on my computer...).
+
+### Customization
+
+If you really want your machine to display a name, you can set an
+environment variable *HOSTNAME* to what you'd like to see displayed.
+
+The first few lines, specifically 10-100, have two other options:
+
+**SHOWUPTIME**
+
+The script uses GW-BASIC's TIMER command to calculate uptime for the
+current day.  MS-DOS and its cousins do not have a concept of uptime
+beyond one day natively.  Additionally, the output of TIMER becomes even
+more useless if the system has a working, battery-backed clock or the
+user has entered the time via the DOS *TIME* command, in which cases
+TIMER just reports the time since midnight.  Maybe you want to turn off
+displaying this potentially useless information by setting that variable
+to 0 (zero).
+
+**SYSTEMONEND**
+
+When set to 1 (one), the script will call *SYSTEM* just before *END* so
+that you're not dumped into the GW-BASIC interpreter.  Maybe you prefer
+that.
+
+## Limitations
+
+The CPU detection is pretty thorough except that it stops once it thinks
+a 386 is present.  It will report 386 if you're on a 486, Pentium, K5,
+etc.  Detecting a 486 might be possible, but that's how it works right
+now.  Because I was mostly interested on lower-than-386 computers, I
+wasn't particularly interested in continuing down that road.
+
+Furthermore, other than NEC CPUs, everything is reported as Intel.  This
+decision is, for the most part, accurate since 286 and earlier CPUs were
+effectively just second-sourced Intel designs as opposed to novel
+designs from other chip companies.  I believe detecting different
+manufacturers of 386s starts to become possible, but that seems a bit
+much.
+
+No memory will be reported under DR DOS.  Their *MEM* output is bananas.
+
+## How It Works
+
+Most attempts to classify the system are achieved through calling known
+DOS commands, such as *MEM*, *VER*, and *CHKDSK* (in the absence of
+*MEM*).  
+
+CPU detection follows a winding assembly path that detects 386 and
+earlier CPUs based on CPU characteristics, bugs, and other hacky means.
+GWFetch contains the machine code to execute these checks starting
+around line 12000.  The machine code is written to memory, modified
+slightly, and called.  Likewise, there is a DOS version and provider
+section around line 12500 that relies on a DOS interrupt along with some
+additional hacks.
+
+System hardware detection is pretty basic.  An initial check is made to
+detect Digital Rainbow 100 video memory.  If that fails, the BIOS system
+ID is read.  Unless you're on a true, early IBM system (yuck) or DOSBox,
+your machine will be reported as an AT or compatible.
+
+The assembly source code for the machine code routines is stored in the
+"asm" subdirectory.  The assembly is included to build the machine code,
+which requires the *INLINE* tool, a program used to convert assembly
+into Pascal inline machine code.  The "support" directory contains a
+Python script to subsequently convert the Pascal inline machine code
+into valid GW-BASIC *DATA* statements.
+
+## About
+
+GWFetch is Copyright 2024 Jeffrey Armstrong <jeff@rainbow-100.com>, and
+is licensed under a JSON-style license.  Please see LICENSE.txt for more
+information.
+
+If you like the software, have comment, suggestion, patch, complaint,
+etc., let me know by email or at:
+
+ * Fediverse: @jeff@toot.rainbow-100.com
+ * Ko-Fi:     https://ko-fi.com/fortranjeff
+ * Twitch:    https://twitch.tv/fortranjeff
+ * Itch:      https://printstar.itch.io/
+
+Thanks for looking!