diff options
Diffstat (limited to 'macros/latex/contrib/wargame/doc/README.md')
-rw-r--r-- | macros/latex/contrib/wargame/doc/README.md | 417 |
1 files changed, 206 insertions, 211 deletions
diff --git a/macros/latex/contrib/wargame/doc/README.md b/macros/latex/contrib/wargame/doc/README.md index e5fd92458c..a66da25247 100644 --- a/macros/latex/contrib/wargame/doc/README.md +++ b/macros/latex/contrib/wargame/doc/README.md @@ -1,42 +1,48 @@ # 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 +## Version 0.2.1 -- 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 +This package can help make classic [Hex'n'Counter +wargames](https://en.wikipedia.org/wiki/Wargame) using LaTeX. The +package provide tools for generating -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). +- 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 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 +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). -## Sources +- The package uses [NATO App6](#nato-app6 "Section below") symbology + for units. +- The package uses [TikZ](https://github.com/pgf-tikz/pgf) for most + things. +- The package support exporting the game to a + [VASSAL](#vassal-support%20'Section%20below') module -The sources of the package are kept at [GitLab][3] +## Sources -## CTAN +The sources of the package are kept at +[GitLab](https://gitlab.com/wargames_tex/wargame_tex) -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]). +## CTAN -If you get the sources (`wargame.ins`, all `.dtx` and `.py`) files, -then to install do +The package is available from +[CTAN](https://ctan.org/tex-archive/macros/latex/contrib/wargame) in the +directory `/macros/latex/contrib/wargame`. As of this writing, the +package has not hit any of the major distributions (e.g., +[TeXLive](https://tug.org/texlive/index.html)). - latex wargame.ins +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 light_woods pdflatex mountains pdflatex rough pdflatex swamp @@ -47,224 +53,213 @@ then to install do (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 +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 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 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 - + 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/`) +You can install these into your TeX tree with (e.g., `~/texmf/`) - mkdir -p ~/texmf/doc/latex/wargame/ + 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 - + 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) +`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](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/download?job=dist) +- [Browse content of + package](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/browse?job=dist) +- [Documentation](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/wargame.pdf?job=dist) +- [Tutorial](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/tutorial.pdf?job=dist) + (and associated VASSAL + [module](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/Game.vmod?job=dist)) +- [Table of + symbols](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/symbols.pdf?job=dist) +- [Compatibility](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/compat.pdf?job=dist) + +To install, get the ([zip +file](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/download?job=dist)) +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 "Link works on GitLab only") page +for more +([here](https://ctan.org/tex-archive/macros/latex/contrib/wargame/doc/tutorial/) +if you browse from CTAN). + +## 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](https://gitlab.com/wargames_tex/bfm_tex) + - [Hell's Gate](https://gitlab.com/wargames_tex/hellsgate_tex) + (private) + - [Unternehmung + 25](https://gitlab.com/wargames_tex/unternehmung_tex) + (private) + - Western Front + - [D-Day](https://gitlab.com/wargames_tex/dday_tex) (Avalon + Hill classic) + - [Paul Koenig's Market + Garden](https://gitlab.com/wargames_tex/pkmg_tex) + - [Paul Koenig's + D-Day](https://gitlab.com/wargames_tex/pkdday_tex) + - Pacific theatre + - [First + Blood](https://gitlab.com/wargames_tex/firstblood_tex) + (Avalon Hill International Kriegspiel Association classic) + - [Malaya](https://gitlab.com/wargames_tex/malaya_tex) + (private) + - Africa + - [Afrika + Korps](https://gitlab.com/wargames_tex/afrikakorps_tex) + (Avalon Hill classic) + - [Battles of El + Alamein](https://gitlab.com/wargames_tex/boel_tex) (private) +- Modern/Speculative + - [Strike Force One](https://gitlab.com/wargames_tex/sfo_tex) + - [Kriegspiel](https://gitlab.com/wargames_tex/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 packages has the script [`export.py`](utils/export.py) to generate a +draft [VASSAL](https://vassalengine.org) 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. +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] +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](https://gitlab.com/wargames_tex/bfm_tex) project, and of course +in the [tutorial](tutorial/ "Link works on GitLab only") + +## 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](https://en.wikipedia.org/wiki/NATO_Joint_Military_Symbology) + on NATO Joint Military Symbology +- The [NATO + page](https://nso.nato.int/nso/nsdd/main/standards/ap-details/1912/EN). + If this does not work for you, then try to go to the [standards + page](https://nso.nato.int/nso/nsdd/main/standards) 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](https://github.com/ralphieraccoon/MilSymb) ## Copyright and license -(c) 2022 Christian Holm Christensen +(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. +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](http://creativecommons.org/licenses/by-sa/4.0/) or +send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, +USA. -### Some comments on copyright +### Some comments on copyright -_Caveat_: I am not a lawyer. +*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_. +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). +However, that copyright rights on games is not as prohibitive as you may +think (see [this thread on +BGG](https://boardgamegeek.com/thread/493249/)). 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. +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_ +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 +- 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 - +previously published game to avoid +[SNAFU](https://en.wikipedia.org/wiki/SNAFU). If in doubt, seek +professional help. |