summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/wargame/source/wargame.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/wargame/source/wargame.dtx')
-rw-r--r--macros/latex/contrib/wargame/source/wargame.dtx265
1 files changed, 256 insertions, 9 deletions
diff --git a/macros/latex/contrib/wargame/source/wargame.dtx b/macros/latex/contrib/wargame/source/wargame.dtx
index d721befdb6..e8a3b9b1e1 100644
--- a/macros/latex/contrib/wargame/source/wargame.dtx
+++ b/macros/latex/contrib/wargame/source/wargame.dtx
@@ -44,6 +44,11 @@
\date{\today}
\begin{document}
\maketitle
+\begin{center}
+ \begin{tikzpicture}
+ \wargamelogo
+ \end{tikzpicture}
+\end{center}
\begin{abstract}
This package provides tools to typesetting manuals, board, and
counters for wargames using \LaTeX{}.
@@ -92,6 +97,10 @@
% typeset using a similar interface. Unit types are identified using
% the NATO Joint Military Symbology \cite{app6c} standard.
%
+% This document is meant as a reference manual (although far from
+% complete). A separate tutorial is available, and may be the best
+% starting point.
+%
% \iffalse
% --------------------------------------------------------------------
%
@@ -127,17 +136,26 @@
% \item[\keyval{town}{\meta{town-keys}}] specifies that a town (or
% similar) is present in the hex. The various keys are described in
% \sectionname~\ref{sec:hex:town}.
+% \item[\keyval{bevel}{\meta{bevel-keys}}] specifies that a bevel
+% should be added to the hex. The various keys are described in
+% \sectionname~\ref{sec:hex:bevel}.
% \item[\keyval{extra}{\meta{extra-keyx}} \textrm{and} \keyval{extra
% clipped}{\meta{extra-keyx}}] allows the user to put custom
% graphics in the hexes. See also \sectionname~\ref{sec:hex:extra}
% for more.
+% \item[\keyval{row}{\meta{row}} \textrm{and}
+% \keyval{column}{\meta{column}}] Keys to set hex coordinates.
+% Mainly used when using \cs{node} rather than \cs{hex}. These
+% coordinates should be specified in the \spec{hex cs} coordinate
+% system (\sectionname~\ref{sec:hex:cs}).
% \item any style key defined for \TikZ{} pictures.
% \end{description}
%
% The \meta{location} argument specifies the coordinates, in the hex
% coordinate system where to put the hex. More about the coordinate
% system is given in \sectionname~\ref{sec:hex:cs}. Note, the numbers
-% starts from the lower--left corner.
+% by default starts from the lower--left corner, but can be changed
+% via options.
%
% The elements are rendered in the following order
% \begin{enumerate}
@@ -146,6 +164,7 @@
% \item The ridges, if any
% \item The label, if any
% \item Extra graphics clipped to the hex
+% \item Bevel if selected
% \item Town, if any
% \item Extra graphics which may extend beyond the confines of the
% hex.
@@ -180,7 +199,46 @@
% indicate two units of length.}
% \label{fig:hex:parts}
% \end{figure}
+%
+% Note that the macro \cs{hex} is really a short hand for \TikZ{}'s
+% \cs{node} macro, but with preset options. An alternative to using
+% the \cs{hex} macro is to do
%
+% \begin{MacroSyntax}{\hex}
+% \cs{node}[hex=\marg{key-value-pairs}] \parg{name} at \parg{location};
+% \end{MacroSyntax}
+%
+% This can be useful when placing explanatory graphics or the like.
+% The main difference between using \cs{hex} and the raw
+% \cs{node}\texttt{[hex=\textellipsis]} is that the former can
+% automatically generate labels and set shape coordinates in the
+% picture. If you want that for your board, it is recommended to use
+% \cs{hex}. For example, if one does
+%
+% \begin{verbatim}
+% \begin{tikzpicture}[
+% every hex={label={auto=alpha column}},
+% hex/labels is name=true]
+% \hex(c=1,r=1);
+% \end{tikzpicture}
+% \end{verbatim}
+%
+% then one can refer to the location of the hex by its label i.e.,
+% \texttt{(A1)}. Since the hex is really a \TikZ{} \texttt{node}, we
+% can also use anchors defined for \texttt{hex} node shape, such as
+% \texttt{(A1.west)}, \texttt{(A1.north edge)}, and so on. This is
+% not possible if one uses the \cs{node} macro.
+%
+% \subsection{Hex bevels}
+% \label{sec:hex:bevel}
+%
+% A bevel (or ``shadow-effect'') can be added to hexes using the key
+% \spec{bevel}, with a value that specifies where the light comes from
+% (e.g., north west or NW). The percentage of the half width of a
+% chit of the bevel can be specified by the key \spec{bevel fraction}
+% (default 10\%).
+%
+%
% \subsection{Styling hexes}
%
% Typical \TikZ{} options can be passed to the \cs{hex} macro. For
@@ -200,6 +258,18 @@
% \end{scope}
% \end{tikzpicture}
% \end{verbatim}
+%
+% For example, to render only the corners of the hexes, as popular
+% among some designers, one can do
+%
+% \begin{verbatim}
+% every hex/.style={
+% dash pattern=on .2cm off .6cm on .2cm off 0cm
+% },
+% \end{verbatim}
+% Note that the dash pattern should be 1cm long and the last element
+% should be \spec{off 0cm} so the dash pattern is started afresh on
+% each hex edge.
%
% \subsection{Hex coordinate system}
% \label{sec:hex:cs}
@@ -216,7 +286,7 @@
% where \meta{vertex} and \meta{edge} are optional. The hex row and
% column defaults both to 0 and can be decimal numbers. The
% \spec{row}, \spec{column}, \spec{vertex}, and \spec{edge} keywords
-% may be shorted to \spec{r}, \spec{c}, \spec{v}, and \spec{e},
+% may be shortened to \spec{r}, \spec{c}, \spec{v}, and \spec{e},
% respectively. Possible vertexes and edges are listed in
% \tablename~\ref{tab:hex:ve}.
%
@@ -320,9 +390,15 @@
% coordinates are shifted upward or downward for smaller or larger
% numbers. Figure~\ref{fig:hex:coord:nb} illustrates. this. This can
% make it a little hard to specify coordinates relative to a hex
-% centre. Alternatively one may use vertex or edge specifciations
-% together with a relative offset in those directions.
-% \
+% centre. Alternatively one may use vertex or edge specifications
+% together with a relative offset in those directions. If one
+% require even more flexibility, one can use the \TikZ{} library
+% \spec{calc} to add arbitrary offsets, e.g.,
+%
+% \begin{verbatim}
+% \coordinate at ($(hex cs:c=1,r=10)+(.2,.2)$);
+% \end{verbatim}
+%
% \begin{figure}
% \centering
% \begin{tikzpicture}
@@ -1014,6 +1090,15 @@
% \caption{Adding rivers, boarders, and roads}
% \end{figure}
%
+% \subsubsection{Styling paths}
+%
+% Rivers, roads, railroads, and borders are styled by
+% \spec{hex/river}, \spec{hex/road}, \spec{hex/railroad}, and
+% \spec{border}, respectively, and the keys \spec{every hex river},
+% \spec{every hex road}, \spec{every hex railroad}, and \spec{every
+% hex border} will also be applied. The latter can be defined by the
+% user.
+%
% \subsection{Board clipping and frame}
%
% In the river, border, and road example above, the roads extend beyond
@@ -1117,6 +1202,134 @@
% The \cs{boardframe} macro prints the position of the rectangle to
% the log output, if one needs to do some more stuff around the board.
%
+% \subsection{Constructing the physical board}
+%
+% If the board is not too large, so that it may fit on a paper format
+% that can easily be printed (say A4, A3, Letter, or Tabloid), one can
+% simply print the board and glue it onto a sturdy surface (say
+% 1\textonehalf\,mm poster carton). However, if the board is large,
+% meaning it does not fit on a piece of printable paper, then one has
+% two options.
+% \begin{description}
+% \item[\textit{Either}] scale the board down so that it fits. Use
+% the \TikZ{} key \spec{scale=}\meta{factor} as an argument to the
+% \spec{tikzpicture} environment in which you create the board. In
+% this case, you should make sure you also scale the chits by the
+% same \meta{factor}, again via the \spec{scale} key.
+% \item[\textit{Or}] you can split the board over several pages. The
+% package provides a number of tools to help with this.
+% \end{description}
+%
+% \subsubsection{Split the board over multiple sheets}
+%
+% First, make sure you produce a standalone PDF of the board only.
+%
+% \begin{verbatim}
+% \documentclass{standalone}
+% \usepackage{wargame}
+% \begin{tikzpicture}[scale=SCALE]
+% % Define the board here.
+% \end{tikzpicture}
+% \end{verbatim}
+%
+% and that you have created this PDF --- say \texttt{board.pdf}.
+%
+% Next, prepare another document in which we will do the calculations.
+% For example
+%
+% \begin{verbatim}
+% \documentclass[11pt]{standalone}
+% \usepackage{wargame}
+% \begin{document}
+% \splitboard{paper=letter,margin=.7,ncol=2,nrow=2,overlap=1}
+% \end{document}
+% \end{verbatim}
+%
+% to calculate the split of \spec{board.pdf} over $2\times2$ letter
+% paper sheets, with a non-printable margin of 7mm, and an overlap
+% between the segments of 1cm.
+%
+% The possible keys for the \cs{splitboard} macro are
+%
+% \begin{itemize}
+% \item \spec{paper}=\meta{format}: Specifies the paper format. One
+% of \spec{a4}, \spec{a3}, \spec{letter}, \spec{tabloid}. Default
+% is \spec{a4}.
+% \item \spec{landscape}: Sets the paper format to be in landscape
+% mode (default is portrait).
+% \item \spec{margin}=\meta{size in centimetres}: Size of margins on
+% each sheet in centimetres \emph{without} unit. That is put
+% \spec{0.6} for 6mm, \emph{not} \spec{6mm}. Default is \spec{0.6}.
+% This should be \emph{slightly} larger (by roughly 5\%) than the
+% \emph{least} margin required by the printer used. \emph{Must} be
+% given \emph{before} \spec{paper} to have any effect.
+% \item \spec{ncol}=\meta{number of columns}: Sets the number of
+% columns of sheets.
+% \item \spec{nrow}=\meta{number of rows}: Set the number of rows of
+% sheets.
+% \item \spec{overlap}=\meta{size in centimetres}: Sets the size of
+% the overlap between sheets in centimetres \emph{without} unit.
+% That is put \spec{2} for 2cm, \emph{not} \spec{2cm}. Default is
+% \spec{2}.
+% \item \spec{image}=\meta{image file name}: File name of the board
+% image (a PDF). Default is \spec{board}
+% \item \spec{output}=\meta{output file name}: File name (without
+% \spec{.tex} ending) to write calculated split to.
+% \item \spec{standalone}: Boolean flag. If true, then output file
+% will be a standalone document (i.e., has a \cs{documentclass}).
+% \item \spec{scale}=\meta{scale}: Set scale of board.
+% \end{itemize}
+%
+% The macro will produce a file named \meta{output file
+% name}\spec{.tex} which can be included in another document to
+% generate the split board PDF. Crop marks will be added to the
+% board segments to make it easier to align the parts.
+%
+% \subsubsection{Foldable board}
+%
+% To make a fold-able board use for example the below template to
+% create grooves and cuts.
+%
+% \begin{tikzpicture}[
+% cut/.style={red!50!black,thick},
+% front groove/.style={green!50!black,dashed,thick},
+% back groove/.style={blue!50!black,dash dot,thick},
+% ]
+% \node[minimum width=8.4cm,
+% minimum height=5.9cm,
+% inner sep=0pt,
+% draw,
+% thick] (a) {};
+% \coordinate (middle) at (a);
+% \coordinate (top) at (a.north);
+% \coordinate (top left) at ($(a.north west)!.5!(a.north)$);
+% \coordinate (middle left) at ($(a.west)!.5!(a)$);
+% \coordinate (bottom left) at ($(a.south west)!.5!(a.south)$);
+% \coordinate (top right) at ($(a.north)!.5!(a.north east)$);
+% \coordinate (middle right) at ($(a)!.5!(a.east)$);
+% \coordinate (bottom right) at ($(a.south)!.5!(a.south east)$);
+% \coordinate (bottom) at (a.south);
+% \draw[cut] (middle)--(bottom);
+% \draw[cut] (top left)--(middle left);
+% \draw[cut] (top right)--(middle right);
+% \draw[back groove] (middle)--(top);
+% \draw[back groove] (bottom left)--(middle left);
+% \draw[back groove] (bottom right)--(middle right);
+% \draw[front groove] (a.west)--(a.east);
+%
+% \draw[cut] ($(a.south west)+(0,-1)$)--++(2,0) node[anchor=west]{%
+% Cut through carton};
+% \draw[back groove] ($(a.south west)+(0,-1.5)$)--++(2,0) node[anchor=west]{%
+% Cut groove (\textonehalf{} through) in carton on \emph{back} side};
+% \draw[front groove] ($(a.south west)+(0,-2)$)--++(2,0) node[anchor=west]{%
+% Cut groove (\textonehalf{} through) in carton on \emph{front} side};
+% \end{tikzpicture}
+%
+% This will fold the board down to a fourth of the size of the full
+% map. For example, if the board is A1
+% ($84\,\mathrm{cm}\times59.4\,\mathrm{cm}$) it will fold down to A4
+% ($21\,\mathrm{cm}\times29.7\,\mathrm{cm}$) for easier storage.
+%
% \iffalse
% --------------------------------------------------------------------
%
@@ -1228,7 +1441,22 @@
% \caption{Example of chits fit within hexes. }
% \label{fig:chit:hex}
% \end{figure}
+%
+% Just as \cs{hex} is really a wrapper around \TikZ{}'s \cs{node}
+% macro, so it is with \cs{chit}. This means that an alternative way
+% of making a chit is to do
+%
+% \begin{MacroSyntax}{\chit}
+% \cs{node}[chit=\marg{key-value-pairs}] \parg{name} at \parg{location};
+% \end{MacroSyntax}
+%
+% Since chits are really \TikZ{} \texttt{node}s we can use anchors
+% on the chit. Unlike for \cs{hex} where there are additional
+% features available when using the dedicated macro, there really
+% isn't much difference between \cs{chit} and
+% \cs{node}\texttt{[chit=\textellipsis]}.
%
+%
% \subsection{Styling chits}
%
% Typical \TikZ{} options can be passed to the \cs{chit} macro. For
@@ -1269,9 +1497,21 @@
% similar keys. For example, the picture \spec{chit/identifier} is
% styled by \spec{tikz/chit/identifier}.
%
+%
+% A bevel (or ``shadow-effect'') can be added to chits using the key
+% \spec{bevel}, with a value that specifies where the light comes from
+% (e.g., north west or NW). The percentage of the half width of a
+% chit of the bevel can be specified by the key \spec{bevel fraction}
+% (default 10\%). This can be used for both symbol or full chits.
+%
% In addition, one can define the key \spec{tikz/every chit} to be the
% default options for all chits.
%
+% By default, the outer ``frame'' of a chit is drawn with the same
+% graphics options as the chit it self (i.e., same fill and stroke
+% colour). To change that, one can pass \spec{frame}=\marg{options}
+% as part of the chit options.
+%
% \subsection{Defining preset chit types}
%
% One can conveniently pre-define some chit styles. For example,
@@ -1314,7 +1554,7 @@
% The NATO markers are designed to fit within the template shown in
% \figurename~\ref{fig:natoapp:template}. The template is serves as a
% placement guide of the the various parts of the NATO marker as
-% illustrated in \figurename{fig:natoapp:usage}.
+% illustrated in \figurename~\ref{fig:natoapp:usage}.
%
% \begin{figure}[htbp]
% \centering
@@ -1688,6 +1928,9 @@
%
% \subsection{Unit type identification}
%
+%
+% See \tablename~\ref{tab:natoapp6c:abbr}.
+%
% \begin{table}
% \centering%
% \def\typemark#1{%
@@ -1737,7 +1980,7 @@
% & FA\\
% \typemark{main=infantry}
% & Infantry
-% & IN\\
+% & IN\footnote{Sometimes just `I'}\\
% \rowcolor{altcol}
% \typemark{main={infantry,armoured}}
% & Mechanised infantry
@@ -1775,7 +2018,7 @@
% \rowcolor{altcol}
% \sizemark{division}
% & Division
-% & D\\
+% & D\footnote{Sometimes `DIV'}\\
% \sizemark{brigade}
% & Brigade
% & BD\\
@@ -1828,7 +2071,9 @@
%
% \begin{thebibliography}{99}
% \bibitem{fb} Hanover,C., Hendrix,C.E., \& Llewelyn,S.,
-% \textit{First Blood}, 1997, \url{https://grognard.com/fb/}
+% \textit{First Blood}, 1997, \url{https://grognard.com/fb/}. See
+% also implementation using this package at
+% \url{https://gitlab.com/wargames_tex/firstblood_tex}.
% \bibitem{app6c} \textit{NATO Joint Military Symbology}, APP-6(C),
% May 2011,
% \url{https://en.wikipedia.org/wiki/NATO_Joint_Military_Symbology}.
@@ -2453,3 +2698,5 @@
% TeX-command-extra-options: "-shell-escape"
% End:
% \fi
+
+