Quick and dirty guide to generating our documentation
=====================================================

1. Preparations
---------------

To transform the Readme/FAQ/Exult Studio documentation you need xsltproc.
This is usually either bundled with libxslt, or a standalone package
dependent on it. Here is how you can install it on a few common platforms
(probably needing to add `sudo`):

- MSYS2 on Windows:
    pacman -S --noconfirm libxslt
- Chocolatey on Windows:
    choco install xsltproc
- vcpkg:
    vcpkg install libxslt
- ArchLinux:
    pacman -S --noconfirm libxslt
- Debian/Ubuntu:
    apt install xsltproc
- Fedora/CentOS:
    dnf install libxslt
- FreeBSD:
    pkg install -y libxslt
- Homebrew on macOS:
    brew install libxslt
- MacPorts on macOS:
    port install libxslt

2. Generating the docs
----------------------

- Use the Makefile provided in the docs/xml directory by running "make".

- If you also want to update the files in exult-web, you can pass its
  directory to make as the variable WEB_DIR like this:

    make WEB_DIR=/path/to/exult-web

3. What the Makefile does
-------------------------

By running make you get docs.txt/html/dat, exult_studio.txt/html/dat,
and faq.txt/html/dat in the docs/xml directory. The *.dat files also
get further processing by "sed" to strip the root tag "<test>" which
gets generated by the xslt processing.

Additionally, make will perform the following updates:

- docs.txt will be copied as README in the root source directory

- faq.txt will be copied as FAQ in the root source directory

- docs.html will be copied as ReadMe.html in docs directory

- faq.html, exult_studio.html, and exult_studio.txt in docs will be
  updated with the newly generated files of the same names

- If you supplied WEB_DIR to make, then docs.txt/faq.txt/exult_studio.txt
  will be copied to "$WEB_DIR", and docs.dat/faq.dat/exult_studio.dat will
  be copied to "$WEB_DIR/content".
