doc: start writing documentation for z8tool.

doc/porting.md

@@ -0,0 +1,46 @@
+# Porting zepto8 to other platforms
+
+## OpenDingux, GCW0, RG350, …
+
+### Build toolchain
+
+First you need to get a recent enough toolchain (GCC 8.x or clang) and its dependencies. I have had
+success with [rg350-buildroot](https://github.com/tonyjih/RG350_buildroot):
+
+```sh
+sudo apt install gcc-multilib mercurial rsync
+```
+
+```sh
+git clone https://github.com/tonyjih/RG350_buildroot
+cd RG350_buildroot
+make rg350_defconfig BR2_EXTERNAL=board/opendingux
+```
+
+Make sure a recent version of GCC is selected: `make menuconfig` → _Toolchain_ → _GCC Compiler Version_ → _gcc 9.x_
+
+```sh
+export BR2_JLEVEL=0
+make toolchain
+make toolchain sdl sdl_image sdl_mixer
+```
+
+### Configure zepto8
+
+Assuming `RG350_buildroot` is located in `${HOME}`:
+
+```sh
+./bootstrap
+
+HOST="mipsel-gcw0-linux-uclibc"
+XCHAIN="${HOME}/RG350_buildroot/output/host/usr/bin"
+SYSROOT="${HOME}/RG350_buildroot/output/host/usr/${HOST}/sysroot"
+PKG_CONFIG_LIBDIR="${SYSROOT}/usr/lib/pkgconfig:${SYSROOT}/usr/share/pkgconfig" \
+    PKG_CONFIG_SYSROOT_DIR="$SYSROOT" \
+    ./configure --host="${HOST}" --with-sysroot="${SYSROOT}" \
+        CC="${XCHAIN}/${HOST}-cc" CXX="${XCHAIN}/${HOST}-c++" \
+        CPPFLAGS="-I${SYSROOT}/usr/include"
+
+make -j
+```
+

doc/z8tool.md

@@ -0,0 +1,79 @@
+# z8tool
+
+**z8tool** is a multi-purpose tool for working with PICO-8 cartridges.
+
+Usage: `z8tool <command> <arguments>`
+
+## `z8tool stats`
+
+Outputs statistics about a cart.
+
+Usage:
+
+    z8tool stats <cart>
+
+Where `<cart>` is any cartridge in P8 (`.p8`), PNG (`.p8.png`), JavaScript (`.js`) or binary format (`.bin`).
+
+Example:
+
+```
+% z8tool stats celeste.p8
+file_name: celeste.p8
+token_count: 5921 [8192]
+code_size: 27484 [65535]
+compressed_code_size: 7903 [15616]
+
+%
+```
+
+## `z8tool listlua`
+
+Extract code from a cart, in text format.
+
+Usage:
+
+    z8tool listlua <cart>
+
+Where `<cart>` is any cartridge in P8 (`.p8`), PNG (`.p8.png`), JavaScript (`.js`) or binary format (`.bin`).
+
+## `z8tool printast`
+
+Not fully implemented yet.
+
+## `z8tool convert`
+
+Convert carts beetween formats: P8 (`.p8`), PNG (`.p8.png`), JavaScript (`.js`) or binary format (`.bin`).
+
+Usage:
+
+    z8tool convert <input> <output>
+
+Examples:
+
+    % z8tool convert celeste.p8.png celeste.p8
+    % z8tool convert celeste.p8 other_celeste.p8.png
+    %
+
+## `z8tool run`
+
+Run a cart in the terminal.
+
+Usage:
+
+    z8tool run [--telnet] [--headless] <cart>
+
+  - `--telnet` emit telnet server commands, for use with socat
+  - `--headless` run without displaying anything
+
+## `z8tool dither`
+
+Not fully implemented yet.
+
+## `z8tool compress`
+
+Not fully implemented yet.
+
+## `z8tool test`
+
+Run the internal test suite.  Not fully implemented yet.
+