Merge thyself! - a wize man said

This book is written in asciidoc. You need access to MOO2150 repository to edit it. The documentation is in .adoc files with the root being doc/index.adoc. Use s/doc-build.pl script to build it. The output goes to output/doc, when doc/path/to/X.adoc is processed the corresponding output/doc/path/to/X.html is created.

The lastest released version of this book is available here.

Structure

Source files are under doc/ subdirectory:

  • .adoc files are organized in a hierarchical manner:

    • doc/index.adoc — book root, you can add new .adoc files too any subdirectory but not in doc/ itself,

    • doc/dist/ — technical information installing the game, patches and mods,

    • doc/history/ — historical information on various releases of the game, fan tools, patches, and mods,

    • doc/game/ — descriptions of game mechanics and interfaces,

    • doc/150/ — info specific to 1.50 patch. This is for something that only exists in 1.50 like scripting or modding, place bug fixes into appropriate game/ article when possible.

    • doc/other/ — instructions on tools outside MOO2 universe, like Git, ssh, Asciidoctor and such.

  • All images are placed under doc/img/, don’t place elsewhere. Any format supported by asciidoctor will do.

  • doc/cache.txt — the cache used by the doc builder script, changes when modified project is rebuilt, always commit it with your changes.

Feel free to move files around or invent new subdirectories if needed. Just remember that the goal is to maintain the semblance of order rather than a perfect classification.

Syntax

Apart from usual asciidoctor syntax the following macros are supported:

  • conf:some_parameter — links to the section of this parameter in 150/parameters.html. Build fails if there’s no such parameter. Works off config.json, see below. Link text is parameter name.

    • conf:some_parameter[link-text] — the same, but with custom link-text instead,

  • cvalue:some_parameter — links to the section of this parameter in 150/parameters.html. Build fails if there’s no such parameter. Works off config.json, see below. Link text is parameter_name = value, where value is the classic game default.

  • book:some/section — resolves into the link to the doc/some/section.html, sets capitalized section name as a text. This will automatically make relative path, e.g. in doc/index.adoc it will become link:some/section.html but in doc/game/combat.adoc it will become link:../some/section.html. This is needed to avoid using absolute paths which break local browsing.

    • book:some/section[The Section] — supports custom link text.

  • img:pic.png — inserts doc/img/pic.png image.

  • TODO…​; — is not a macro per se, but the builder script will list them so you always know where to find more work.

Build

Note here and below use a Terminal to run commands.

  1. Run normal build, you need the latest output/test/config.json to be up to date with the current branch. Otherwise config parameters may be out of date. See Build The Patch .

  2. Run $ perl s/doc-build.pl, the output appears in output/doc and can be reviewed by opening output/doc/index.html in your browser.

The build will fail if there are dangling local links or unreferenced .adoc files. It doesn’t check external links obviously. It also reports TODOs as warnings.

Built documentation can be browsed locally or packaged.

Package

Run $ s/doc-pack, it creates output/doc.tgz.

Contribute

To contribute to the documentation on topic X you must:

  1. Ensure the Asciidoctor is installed.

  2. Edit an X.adoc file, e.g. doc/some/X.adoc with any plain text editor.

  3. Run $ perl s/doc-build.pl, and make sure it says all good in its last line. If it reports errors repeat from step 2.

  4. Take a look in a browser, if not satisfied repeat from step 2.

  5. Commit all X.adoc and cache.txt, e.g.:

    $ git add doc/cache.txt doc/some/X.adoc && git commit -m'Some Changes in X'

You can now push your changes.