a more detailed readme

README.md

@@ -5,3 +5,105 @@ minimalist constructed language *toki pona*.
 
 Included are all the files and scripts used to build it.
 
+# building
+
+You will need a Linux-based OS, or a UNIX-like environment, to build the
+website from this source package. If you already have one, you can skip until
+the horizontal line, otherwise here is how you can get things working if you
+have Windows or macOS.
+
+On Windows 10 and later, you can use
+[WSL](https://learn.microsoft.com/en-us/windows/wsl/) to install a Linux
+distribution inside your Windows system.
+
+On macOS, you can use [Homebrew](https://brew.sh/) to install the necessary
+tools into your macOS system.
+
+Alternatively, you can install an OS inside a virtual machine, like
+[VirtualBox](https://www.virtualbox.org/).
+
+If your choice is WSL or VirtualBox, you should also pick a Linux distribution
+("distro") to run inside of it. [Ubuntu
+Desktop](https://ubuntu.com/download/desktop) is a good choice.
+
+---
+
+After installing one of these, Here are the tools required:
+
+ * `discount`, the Markdown-to-HTML converter
+ * `cpp`, the C preprocessor that's part of the `gcc` compiler, here used to build stylesheets
+ * `make`, the build system used to track which files need to be updated.
+
+Optionally, you might want these tools:
+
+ * `git`, to get a copy of this repository's data into your computer and be able
+   to make and commit changes
+
+All of these should be available in any Linux distro's (or Homebrew's) package
+manager. Enter the command line provided by your Linux distro, WSL or macOS
+respectively, and use one of these commands:
+
+* Ubuntu / Debian (by themselves or inside WSL): `sudo apt install discount gcc
+make git`
+
+* Fedora: `sudo yum install discount gcc make git`
+
+* Homebrew: `brew install discount gcc make git`
+
+---
+
+After doing that, you need to get the repository's data onto your computer. You
+can either "clone" this repository using Git, or download it as an archive and
+unpack it somewhere.
+
+To clone the repository, use the following command inside the terminal:
+
+`git clone https://codeberg.org/lipu-sona-pona/lipu-sona-pona.git`
+
+This should copy the data to a new folder called `lipu-sona-pona`. Enter this
+directory:
+
+`cd lipu-sona-pona`
+
+Now try building the website using the following command:
+
+`make`
+
+(if you run macOS and Homebrew, you might want to use `gmake` instead.)
+
+If everything goes right, then there should appear a folder called `public`,
+containing all the files ready to be uploaded to a website hosting (such as
+[Neocities](https://neocities.org/)).
+
+---
+
+Depending on the environment you're running, this error might appear:
+
+```
+make: theme: No such file or directory
+```
+
+If that happens, then you need to check the name of the `theme` executable
+installed in the `discount` package.
+
+Try out the following commands:
+
+* `discount-theme -V`
+* `markdown-theme -V`
+
+If one of these outputs a version number instead of the `not found` error, then
+edit the `Makefile.cfg` file in a text editor to say the name of the correct
+executable:
+
+```
+THEME=discount-theme
+```
+
+or
+
+```
+THEME=markdown-theme
+```
+
+---
+