Merge pull request #445 from TG9541/docs

Just docs

CORE/README.md

@@ -1,18 +1,18 @@
 ## STM8 eForth "CORE" configuration
 
-`CORE` is a configuration for a minimal Forth system for STM8S Low Density devices (e.g. STM8S003F3P6 or STM8S103K3T6C). It's close to the original eForth feature set but it still contains the most important STM8 eForth features like `NVM`, `CONSTANT`, `'IDLE`.  and `SAVEC .. IRET` for interrupt handlers, and `WIPE` for removing temporary words.
+`CORE` is a minimal STM8 eForth configuration for [STM8S "Low Density" devices](https://github.com/TG9541/stm8ef/wiki/STM8-Low-Density-Devices#stm8s-low-density-devices) (e.g., STM8S003F3P6, STM8S103K3T6C or STM8S903K3T6C). It's close to the original eForth feature set but many words were unlinked from the dictionary (using the `BAREBONES` configuration). It still contains the most important STM8 eForth additions like `CONSTANT` (true literals), `NVM` (compile to Flash memory), `'IDLE` (console idle tasks), `SAVEC .. IRET` (for interrupt handlers)and `WIPE` (for removing temporary words).
 
-Compared to full-featured STM8 eForth binaries the following limitations apply to `CORE`:
+Compared to a full STM8 eForth configuration `CORE` it contains the following feature/memory trade-off:
 
-* case sensitive command line (the original eForth behavior)
+* case sensitive (the original eForth behavior)
 * no Background Task (`BG` and `TIM`)
 * no I/O words (`ADC!`, `ADC@`, `OUT` and `OUT!`)
-* just eForth counted loops (no `DO .. LEAVE .. LOOP/+LOOP`)
+* no `DO .. LEAVE .. LOOP/+LOOP` (only eForth [`FOR ... NEXT`](https://github.com/TG9541/stm8ef/wiki/eForth-FOR-..-NEXT) counted loops)
 * no `CREATE .. DOES>`
 
-`CORE` requires about 4000 bytes Flash, about 800 bytes less than [MINDEV](https://github.com/TG9541/stm8ef/tree/master/MINDEV).
+`CORE` requires less than 3900 bytes Flash memory, that's about 730 bytes less than [MINDEV](https://github.com/TG9541/stm8ef/tree/master/MINDEV).
 
-`CORE` has the following vocabulary:
+The following is the visible vocabulary:
 
 ```Forth
 WORDS
@@ -23,11 +23,13 @@ UM/MOD WITHIN MIN MAX < U< = 2DUP ROT ?DUP BASE - 0< OR AND XOR + UM+ I OVER SWA
 R> C! C@ ! @ 2@ 2! EXIT EXECUTE EMIT ?KEY COLD 'BOOT ok
 ```
 
+Hidden Forth words, which can be made visible with [`ALIAS`](https://github.com/TG9541/stm8ef/wiki/STM8-eForth-Alias-Words), are listed in the `CORE/target` folder.
+
 ## Adding STM8 eForth Features to `CORE`
 
 Adding more STM8 eForth features is possible by copying the `CORE` folder to a new target folder, adding configuration items, e.g. from [MINDEV/globconf.inc](https://github.com/TG9541/stm8ef/blob/master/MINDEV/globconf.inc), and executing `make BOARD=<target folder>`.
 
-Adding the following lines to `globconf.inc` will result in a binary with about 4144 bytes size:
+Adding the following lines to `globconf.inc` will result in a binary with about 4040 bytes size:
 
 ```
         HAS_DOLOOP       = 1    ; DO .. LOOP extension: DO LEAVE LOOP +LOOP
@@ -45,4 +47,26 @@ SPACE KEY DECIMAL HEX FILL CMOVE HERE +! PICK 0= ABS NEGATE NOT 1+ 1- 2+ 2- 2* 2
 NIP >R R@ R> C! C@ ! @ 2@ 2! EXIT EXECUTE LEAVE EMIT ?KEY COLD 'BOOT ok
 ```
 
-`CORE` can also be used creating binaries for very space constraint systems (even for STM8S devices with 4K Flash like the STM8S103F2P6) by moving a part of the dictionary to the EEPROM.
+# Creating even leaner STM8 eForth binaries
+
+`CORE` can be used for creating binaries for very space constraint systems (even for STM8S devices with a nominal Flash size of 4K Flash like the STM8S103F2P6) by moving a part of the dictionary to the EEPROM:
+
+In order to achieve this, it's recommended to first "unlink" a group of dictionary entries, e.g.:
+
+```
+        UNLINK_DDUP      = 1    ; "2DUP"
+        UNLINK_DNEGA     = 1    ; "DNEGATE"
+        UNLINK_EQUAL     = 0    ; "="
+        UNLINK_ULESS     = 0    ; "U<"
+        UNLINK_LESS      = 0    ; "<"
+        UNLINK_MAX       = 1    ; "MAX"
+        UNLINK_MIN       = 1    ; "MIN"
+        UNLINK_WITHI     = 1    ; "WITHIN"
+        UNLINK_UMMOD     = 0    ; "UM/MOD"
+        UNLINK_MSMOD     = 0    ; "M/MOD"
+        UNLINK_SLMOD     = 0    ; "/MOD"
+        UNLINK_MMOD      = 1    ; "MOD"
+
+```
+
+After building the kernel, files with `ALIAS` statements for temporary dictionary entries are in `target`. The file `target/aliaslist.fs` contains a list of `#require` statements from which a selection for temporay dictionary entries in the EEPROM can be made.

DCDC/README.md

@@ -1,5 +1,21 @@
 ## STM8 eForth "DCDC" configuration
 
-This folder contains the STM8 eForth configuration files for a cheap DC/DC converter with voltmeter.
+This folder contains the STM8 eForth configuration files for the first mod of a "cheap DC/DC converter with voltmeter".
 
-Documenation for this board is in the [Wiki](https://github.com/TG9541/stm8ef/wiki/Board-CN2596).
+Documenation for this first board is in the [Wiki](https://github.com/TG9541/stm8ef/wiki/Board-CN2596).
+
+In the meantime [other boards](https://hackaday.io/project/19647-low-cost-programmable-power-supply/log/172244-the-dcdc-mh-works-a-hack-while-waiting-for-santa) became more readily [available](https://www.aliexpress.com/item/32900897070.html):
+
+![DCDC-MH](https://cdn.hackaday.io/images/931381577209891351.png)
+
+For the DCDC-MH board there is additional information on [Hack-a-Day](https://hackaday.io/project/19647-low-cost-programmable-power-supply/log/172404-dcdc-mh-circuit-diagram), and a GitHub Gist with an initial [DCDC-MH STM8 eForth configuration](https://gist.github.com/TG9541/666e421f80dfbc6cca5957238175bf08).
+
+The DCDC-MH board is powered by a pin-to-pin replacement Nuvoton chip, and converting the board for STM8 eForth requires some soldering skills. The conversion is still worth it since the design is well suited for implementing a serial console.
+
+![DCDC-MH STM8S103F3P6 Mod](https://cdn.hackaday.io/images/7220691577209814290.png)
+
+The schematics of the DCDC-MH board was "reverse-engineered" :
+
+![DCDC-MH Circuit Diagram](https://cdn.hackaday.io/images/4607931577535865964.c7bee2247edabff2e773cde3ee5bba23)
+
+An analysis of the [linear power supply](https://hackaday.io/project/19647-low-cost-programmable-power-supply/log/172270-this-linear-regulator-circuit-doesnt-look-quite-right) for the µC circuit shows that the board has a wider supply range than earlier DCDC-with-voltmeter modules.

DOUBLECOM/README.md

@@ -1,8 +1,10 @@
 ## STM8 eForth "DOUBLECOM" configuration
 
-This folder contains the STM8 eForth configuration files for a full-featured system that communicates through a half-duplex simulated serial interface but that also provides the words `?RX` and `TX!` for the STM8 UART.
+This folder contains a full-featured STM8 eForth configuration for an STM8S "Low density" device like the STM8S103F3P6 that communicates through a half-duplex simulated serial interface but that also provides the words `?RX` and `TX!` for the STM8 UART hardware that are independent of the Forth console. The binary release contains the image DOUBLECOM simulates a 2-wire half-duplex communications interface on PD1/SWIM.
 
-The binary release contains the image DOUBLECOM, which simulates a 2-wire half-duplex communications interface on PD1/SWIM.
+The condiguration is a good starting point for developing simple RS232 protocols in Forth, especially with boards like the [C0135](https://github.com/TG9541/stm8ef/tree/master/C0135), and it's an example for "advanced" serial interface configuration in STM8 eForth.
+
+Please refer to the local [globconf.inc]( https://github.com/TG9541/stm8ef/blob/master/DOUBLECOM/globconf.inc) for details.
 
 The recommended circuit for connection to a USB RS232 "TTL" adapter is this:
 
@@ -25,5 +27,3 @@ GND------------>>-----*----o ST-LINK GND
 ```
 
 [e4thcom](https://github.com/TG9541/stm8ef/wiki/STM8S-eForth-Programming#using-e4thcom) fully supports STM8EF 2 wire connections, and an example `picocom` configuration for half-duplex communication is described [here](https://github.com/TG9541/stm8ef/wiki/STM8S-eForth-Programming#using-file--hand).
-
-