summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/wargame/doc/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/wargame/doc/README.md')
-rw-r--r--macros/latex/contrib/wargame/doc/README.md270
1 files changed, 270 insertions, 0 deletions
diff --git a/macros/latex/contrib/wargame/doc/README.md b/macros/latex/contrib/wargame/doc/README.md
new file mode 100644
index 0000000000..e5fd92458c
--- /dev/null
+++ b/macros/latex/contrib/wargame/doc/README.md
@@ -0,0 +1,270 @@
+# A package to make Hex'n'Counter wargames in LaTeX
+## Version 0.2
+
+This package can help make classic [Hex'n'Counter wargames][1] using
+LaTeX. The package provide tools for generating
+
+- Hex maps and boards
+- Counters (called _chits_ since TeX have already taken _counters_)
+ for units, markers, and so on
+- Counter sheets
+- Order of Battle charts
+- Illustrations in the rules using the defined maps and counters
+
+The result will often be a PDF (or set of PDFs) that contain
+everything one will need for a game (rules, charts, boards, counter
+sheets).
+
+- The package uses [NATO App6](#NATO-App6) symbology for units.
+- The package uses [TikZ][2] for most things.
+- The package support exporting the game to a
+ [VASSAL](#VASSAL-support) module
+
+## Sources
+
+The sources of the package are kept at [GitLab][3]
+
+## CTAN
+
+The package is available from [CTAN][4] in the directory
+`/macros/latex/contrib/wargame`. As of this writing, the package has
+not hit any of the major distributions (e.g., [TeXLive][5]).
+
+If you get the sources (`wargame.ins`, all `.dtx` and `.py`) files,
+then to install do
+
+ latex wargame.ins
+ pdflatex beach
+ pdflatex city
+ pdflatex light_woods
+ pdflatex mountains
+ pdflatex rough
+ pdflatex swamp
+ pdflatex town
+ pdflatex village
+ pdflatex woods
+
+(You need to use `pdflatex`, `xelatex`, or `lualatex` - plain `latex`
+with DVI output will not work)
+
+Then copy the relevant files to your TeX tree (e.g., `~/texmf/`)
+as
+
+ mkdir ~/texmf/tex/latex/wargame
+ cp tikzlibrary*.tex ~/texmf/tex/latex/wargame/
+ cp wargame.sty ~/texmf/tex/latex/wargame/
+ cp wgexpor.sty ~/texmf/tex/latex/wargame/
+ cp city.pdf ~/texmf/tex/latex/wargame/
+ cp light_woods.pdf ~/texmf/tex/latex/wargame/
+ cp mountains.pdf ~/texmf/tex/latex/wargame/
+ cp rough.pdf ~/texmf/tex/latex/wargame/
+ cp swamp.pdf ~/texmf/tex/latex/wargame/
+ cp town.pdf ~/texmf/tex/latex/wargame/
+ cp village.pdf ~/texmf/tex/latex/wargame/
+ cp woods.pdf ~/texmf/tex/latex/wargame/
+ cp export.py ~/texmf/tex/latex/wargame/
+ cp svg2tikz.py ~/texmf/tex/latex/wargame/
+
+To generate the documentation, after having done the above, do
+
+ pdflatex wargame.dtx
+ makeindex -s gind -o wargame.ind wargame.idx
+ pdflatex wargame.dtx
+ pdflatex wargame.dtx
+ pdflatex symbols.tex
+ pdflatex compat.tex
+ pdflatex compat.tex
+
+(You need to use `pdflatex`, `xelatex`, or `lualatex` - plain `latex`
+with DVI output will not work)
+
+You can install these into your TeX tree with (e.g., `~/texmf/`)
+
+ mkdir -p ~/texmf/doc/latex/wargame/
+ cp wargame.pdf ~/texmf/doc/latex/wargame/
+ cp symbols.py ~/texmf/doc/latex/wargame/
+ cp compat.py ~/texmf/doc/latex/wargame/
+
+If you want to generate the tutorial document, do
+
+ cd tutorial
+ pdflatex game
+ pdflatex game
+
+If you also want to make the tutorial VASSAL module, do (also in
+`tutorial`), do
+
+ pdflatex export.tex
+ ../export.py export.pdf export.json -o Game.vmod \
+ -d "Example module from LaTeX PnP game" \
+ -t "LaTeX wargame tutorial" -v 0.1 \
+ -p patch.py
+
+
+
+
+## Download from GitLab
+
+- [Zip file of package and support files][artifacts.zip]
+- [Browse content of package][browse]
+- [Documentation][wargame.pdf]
+- [Tutorial][tutorial.pdf] (and associated VASSAL [module][Game.vmod])
+- [Table of symbols][symbols.pdf]
+- [Compatibility][compat.pdf]
+
+To install, get the ([zip file][artifacts.zip]) and unzip into your
+TeX tree, for example
+
+ mkdir -p ~/texmf
+ (cd ~/texmf && unzip ../artifacts.zip)
+
+on Un*x like systems.
+
+## Tutorial
+
+See the [tutorial](tutorial/README.md) page for more.
+
+## Examples
+
+Below are some print'n'play board wargames made with this package.
+These are not original games but rather revamps of existing games.
+All credits goes to the original authors of these games.
+
+- WWII
+ - Eastern Front
+ - [Battle for Moscow][bfm_tex]
+ - [Hell's Gate][hellsgate_tex] (private)
+ - [Unternehmung 25][unternehmung_tex] (private)
+ - Western Front
+ - [D-Day][dday_tex] (Avalon Hill classic)
+ - [Paul Koenig's Market Garden][pkmg_tex]
+ - [Paul Koenig's D-Day][pkdday_tex]
+ - Pacific theatre
+ - [First Blood][firstblood_tex] (Avalon Hill International
+ Kriegspiel Association classic)
+ - [Malaya][malaya_tex] (private)
+ - Africa
+ - [Afrika Korps][afrikakorps_tex] (Avalon Hill classic)
+ - [Battles of El Alamein][boel_tex] (private)
+- Modern/Speculative
+ - [Strike Force One][sfo_tex]
+ - [Kriegspiel][kriegspiel_tex] (Avalon Hill classic)
+
+## VASSAL support
+
+The packages has the script [`export.py`](utils/export.py) to
+generate a draft [VASSAL][5] module from the defined charts, boards,
+counters, OOBs, and so on. More about this is given in the
+documentation.
+
+The script will generate a first draft of a module, which then can be
+edited in the VASSAL editor for the final thing.
+
+Alternatively, one can provide a Python script to do more on the
+generated module, such as defining starting positions, fixing grid
+layouts, and so on. Using such a patch script, one can get an
+(almost) final module. This means, that even if one makes changes to
+the original content, it is easy to remake the module without much
+need for the VASSAL editor.
+
+An example of this is given in the [Battle for Moscow][bfm_tex]
+project, and of course in the [tutorial](tutorial/)
+
+## NATO App6
+
+The package supports
+
+- All air, equipment, installation, land, sea surface, sub surface,
+ and space command symbols, including amplifiers and modifiers
+- All friendly, hostile, neutral, and unknown faction frame.
+ Undecided faction frames can be made by specifying `dashed` line
+ styles.
+- Some, but very few, other kinds of symbology.
+
+Here are some references for more information on the NATO App6
+symbology standard.
+
+- The [Wikipedia page][6] on NATO Joint Military Symbology
+- The [NATO page][7]. If this does not work for you, then try to go
+ to the [standards page][8] and put in and write in `SYMBOLOGY` in
+ the _Document Title Contains Words_ field and press _Start_.
+- Other LaTeX package for making NATO symbology [XMilSymb][9]
+
+## Copyright and license
+
+(c) 2022 Christian Holm Christensen
+
+This work is licensed under the Creative Commons
+Attribution-ShareAlike 4.0 International License (CC-BY-SA-4.0). To
+view a copy of this license, visit [CC][10] or send a letter to
+Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+
+### Some comments on copyright
+
+_Caveat_: I am not a lawyer.
+
+Note that this license applies to the `wargame` package as such. What
+you generate using the package is _not_ required to be licensed
+according to the _ShareAlike_ clause of CC-BY-SA-4.0. That is, you
+can license your materials _any way you want_.
+
+However, that copyright rights on games is not as prohibitive as you
+may think (see [this thread on BGG][11]). What you _can_ copyright is
+original, artistic expression. That is, the copyrighted work must not
+be a copy of something else (originality) and must be some form of
+expression. One _cannot_ copyright ideas, only their expression in so
+far as it is _artistic_ (i.e., not a trivial expression that anyone
+knowledgeable within the field can do with rudimentary effort).
+
+So you _can not_ copyright your game mechanics, for example, only how
+you described them. You _can not_ copyright a title (but you may be
+able to claim trademark on it). You _can_ copyright the wording of
+the rules, the graphics that you use, and so on.
+
+This also means, that you are essentially free to make your own
+version of previously published game, _as long as_
+
+- you do not copy existing text
+- you do not copy existing graphics
+- you respect any kind of trademark claims
+
+However, it is advisable to contact the copyright holders of the
+previously published game to avoid [SNAFU][12]. If in doubt, seek
+professional help.
+
+[1]: https://en.wikipedia.org/wiki/Wargame
+[2]: https://github.com/pgf-tikz/pgf
+[3]: https://gitlab.com/wargames_tex/wargame_tex
+[4]: https://ctan.org/tex-archive/macros/latex/contrib/wargame
+[5]: https://tug.org/texlive/index.html
+[6]: https://vassalengine.org
+[7]: https://en.wikipedia.org/wiki/NATO_Joint_Military_Symbology
+[8]: https://nso.nato.int/nso/nsdd/main/standards/ap-details/1912/EN
+[9]: https://nso.nato.int/nso/nsdd/main/standards
+[10]: https://github.com/ralphieraccoon/MilSymb
+[11]: http://creativecommons.org/licenses/by-sa/4.0/
+[12]: https://boardgamegeek.com/thread/493249/
+[13]: https://en.wikipedia.org/wiki/SNAFU
+
+
+[artifacts.zip]: https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/download?job=dist
+[browse]: https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/browse?job=dist
+[wargame.pdf]: https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/wargame.pdf?job=dist
+[tutorial.pdf]: https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/tutorial.pdf?job=dist
+[Game.vmod]: https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/Game.vmod?job=dist
+[symbols.pdf]: https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/symbols.pdf?job=dist
+[compat.pdf]: https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/compat.pdf?job=dist
+
+[bfm_tex]: https://gitlab.com/wargames_tex/bfm_tex
+[hellsgate_tex]: https://gitlab.com/wargames_tex/hellsgate_tex
+[unternehmung_tex]: https://gitlab.com/wargames_tex/unternehmung_tex
+[dday_tex]: https://gitlab.com/wargames_tex/dday_tex
+[pkmg_tex]: https://gitlab.com/wargames_tex/pkmg_tex
+[pkdday_tex]: https://gitlab.com/wargames_tex/pkdday_tex
+[firstblood_tex]: https://gitlab.com/wargames_tex/firstblood_tex
+[malaya_tex]: https://gitlab.com/wargames_tex/malaya_tex
+[afrikakorps_tex]: https://gitlab.com/wargames_tex/afrikakorps_tex
+[boel_tex]: https://gitlab.com/wargames_tex/boel_tex
+[sfo_tex]: https://gitlab.com/wargames_tex/sfo_tex
+[kriegspiel_tex]: https://gitlab.com/wargames_tex/kriegspiel_tex
+