Update Documentation

[BenjamenMeyer]

There is currently user documentation in the documentation folder; however, there are several issues:

1. There's two DOC file (Word 2000 and earlier) for 0.4.3 and 0.5.0 releases.
2. There's a TEX file of the actual documentation.

Tasks:

• Archive the DOC files as release assets.
• Update the TEX file to use a variable for the game version OR move away from using TEX to using RST.

TEX is a great format for generating multiple document types - HTML, PDF, DOC, etc. However, it also requires great care to work with. It is probably wise to convert to using RST and Sphinx instead as a more modern solution.

[ministerofinformation]

The DOC files should definitely be retired, when possible.

My two cents Re: LaTeX vs RST - I think moving to something that is easiest for the largest number of people to edit and maintain should probably be the goal for documentation related to things that are themselves expected to be continuously changing or being actively added to (e.g. user-documentation, engine-specific documentation, etc.). It looks like Sphinx can generate LaTeX as an output format, but I have no experience with what that generated content looks like.

I suspect that, for things that are, whatever their file format, isomorphic to a set of webpages, something RST-like would work very well. If it's intended to be more "book-like" and there's a desire to exert fine-grained control over layout, LaTeX may remain appropriate. Of the documents that fall in that latter category, I'd say the lore doc and game design doc may qualify, but I don't see any particular need for that level of control for other documentation and any barrier to documentation being kept up to date outweighs how prettily it handles text layout.

[pyramid3d]

There is also the Markdown (md) format which is extremely easy to learn, does not require specialized editors, and can be easily converted (pandoc) to other target formats: epub, pdf, html, wiki, rst, ... Further, there is this great md editor with WYSIWYG formatting and chapter outline (Typo) which I use for my quite extensive docu. Find a sample here: libre-gaming-manifest.md

[BenjamenMeyer]

I like RST a little better than MD, both are in the same field and basically equivalents.

• RST works a little better with Vim than MD

You can do chapters, etc in RST directly (no extra tools required). I'm sure you can in MD too, I just haven't done it.

We can use either one.