diff options
Diffstat (limited to 'macros/latex/contrib/wargame/source/wargame.dtx')
-rw-r--r-- | macros/latex/contrib/wargame/source/wargame.dtx | 265 |
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 + + |