Added a readme.

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!