%% %% magicthegathering-doc.tex -- Documentation for the magicthegathering LaTeX package %% %% This file is both the user manual and a compilable working example. %% Compile with two passes for the table of contents: %% %% lualatex --shell-escape magicthegathering-doc.tex %% lualatex --shell-escape magicthegathering-doc.tex %% %% Or, if SVGs have been pre-converted to PDF: %% %% pdflatex magicthegathering-doc.tex %% pdflatex magicthegathering-doc.tex %% \documentclass[a4paper,11pt]{article} %% --- Layout --------------------------------------------------------------- \usepackage[T1]{fontenc} \usepackage{lmodern} \usepackage[top=2.5cm, bottom=2.8cm, left=2.8cm, right=2.8cm, headheight=15pt]{geometry} %% --- Load the package we are documenting ---------------------------------- %% (hyperref=false because we configure hyperref ourselves below) \usepackage[hyperref=false]{magicthegathering} %% --- Hyperref ------------------------------------------------------------- \usepackage[ colorlinks = true, linkcolor = black, urlcolor = blue, citecolor = black, pdftitle = {The magicthegathering package -- User Manual}, pdfauthor = {Hypergeomancer}, ]{hyperref} %% --- Code listings -------------------------------------------------------- \usepackage{listings} \lstdefinestyle{mtgcode}{ language = [LaTeX]TeX, basicstyle = \ttfamily\small, keywordstyle = \bfseries, commentstyle = \color{gray}\itshape, backgroundcolor = \color{black!3}, frame = single, framerule = 0.4pt, rulecolor = \color{black!25}, xleftmargin = 4pt, xrightmargin = 4pt, aboveskip = 8pt, belowskip = 4pt, breaklines = true, columns = flexible, keepspaces = true, showstringspaces= false, morekeywords = { mana,manacost,manaW,manaU,manaB,manaR,manaG,manaC, setmanasymbolsize,setsetsymbolsize, setsymbol,card,cardlink, initem,outitem,matchup, insertdeck, matchresult,matchresults, }, } \lstset{style=mtgcode} %% --- Result boxes --------------------------------------------------------- \usepackage{tcolorbox} \tcbuselibrary{skins,breakable} \newtcolorbox{result}{ enhanced, colback = white, colframe = black!25, boxrule = 0.4pt, left = 6pt, right = 6pt, top = 5pt, bottom = 5pt, fonttitle = \bfseries\small, title = Output, } %% --- Section formatting --------------------------------------------------- \usepackage{titlesec} \titleformat{\section} {\large\bfseries}{\thesection}{0.7em}{} [\vspace{2pt}{\color{black!40}\hrule height 0.8pt}] \titleformat{\subsection} {\normalsize\bfseries}{\thesubsection}{0.6em}{} %% --- Header / footer ------------------------------------------------------ \usepackage{fancyhdr} \pagestyle{fancy} \fancyhf{} \fancyhead[L]{\small\textsf{The \texttt{magicthegathering} package}} \fancyhead[R]{\small\textsf{v1.1 \,--\, \today}} \fancyfoot[C]{\small\thepage} \renewcommand{\headrulewidth}{0.4pt} %% --- Misc ----------------------------------------------------------------- \usepackage{booktabs,array,enumitem,parskip,longtable,multicol} %% --- Doc shorthand -------------------------------------------------------- \newcommand{\pkg}[1]{\textsf{#1}} \newcommand{\opt}[1]{\texttt{#1}} \newcommand{\env}[1]{\texttt{#1}} \newcommand{\file}[1]{\texttt{#1}} \newcommand{\cmd}[1]{\texttt{\textbackslash#1}} \newcommand{\meta}[1]{\textnormal{\textit{$\langle$#1$\rangle$}}} \newcommand{\carg}[1]{\texttt{\{}\meta{#1}\texttt{\}}} %% ========================================================================== %% Title %% ========================================================================== \title{% {\LARGE\bfseries The \texttt{magicthegathering} package}\\[6pt] {\large Magic: The Gathering typesetting for \LaTeX}\\[6pt] {\normalsize v1.1 \quad\textbullet\quad 2026-03-21}% } \author{Hypergeomancer} \date{} %% ========================================================================== \begin{document} %% ========================================================================== \maketitle \thispagestyle{empty} \begin{abstract}\noindent The \pkg{magicthegathering} package provides \LaTeX{} commands for typesetting \emph{Magic:~The~Gathering} content: inline mana symbols, expansion-set icons, Scryfall-linked card names, sideboard-guide tables, plain-text deck-list import, and tournament match-result tracking. Every code listing in this document is a live, compilable example. \end{abstract} \tableofcontents \newpage %% ========================================================================== \section{Feature overview} \label{sec:features} %% ========================================================================== \begin{center} \begin{tabular}{@{} c l l @{}} \toprule \textbf{\#} & \textbf{Feature} & \textbf{Primary command(s)} \\ \midrule 1 & Mana symbols & \cmd{mana}\carg{id} \\ 2 & Full mana costs & \cmd{manacost}\carg{id id \ldots} \\ 3 & Colour shortcuts & \cmd{manaW} \ldots\ \cmd{manaC} \\ 4 & Set symbols & \cmd{setsymbol}\carg{code} \\ 5 & Card hyperlinks & \cmd{card}\carg{name} \\ 6 & Custom-text card links & \cmd{cardlink}\carg{name}\carg{text} \\ 7 & Sideboard guide & \env{matchup} environment \\ 8 & Deck-list import & \cmd{insertdeck}\carg{file} \\ 9 & Match results & \env{matchresults} environment \\ \bottomrule \end{tabular} \end{center} %% ========================================================================== \section{Requirements} %% ========================================================================== \paragraph{TeX distribution.} TeX~Live~2020+ or MiK\TeX~21+. Dependencies: \pkg{pgfopts}, \pkg{svg}, \pkg{booktabs}, \pkg{array}, \pkg{multicol}, \pkg{enumitem}, \pkg{xcolor}, \pkg{xparse}, \pkg{expl3}, \pkg{hyperref}. All of these ship with standard distributions. \paragraph{SVG rendering.} The package uses \pkg{svg}, which delegates SVG-to-PDF conversion to Inkscape. Two workflows: \begin{enumerate}[itemsep=2pt] \item \textbf{Live SVG} (Inkscape required): compile with \texttt{lualatex -{}-shell-escape}. \item \textbf{Pre-converted PDF} (no Inkscape): convert all SVGs to PDF beforehand; the package auto-detects \file{.pdf} files. \end{enumerate} %% ========================================================================== \section{Installation} %% ========================================================================== Copy the following tree into any texmf directory: \begin{lstlisting}[language={},basicstyle=\ttfamily\small] /tex/latex/magicthegathering/ magicthegathering.sty symbols/ <-- mtg-sym-*.pdf / mtg-sym-*.svg sets/ <-- mtg-set-*.pdf / mtg-set-*.svg \end{lstlisting} Then run \texttt{texhash} (TeX~Live) or \texttt{initexmf -{}-update-fndb} (MiK\TeX). %% ========================================================================== \section{Package options} \label{sec:options} %% ========================================================================== \begin{lstlisting} \usepackage[]{magicthegathering} \end{lstlisting} \medskip \begin{center} \begin{tabular}{@{} l l p{6.8cm} @{}} \toprule \textbf{Option} & \textbf{Default} & \textbf{Description} \\ \midrule \opt{hyperref} & \opt{true} & Load \pkg{hyperref}. Set \opt{false} if your document loads it first. \\[3pt] \opt{colorlinks} & \opt{true} & Colour hyperlinks. \\[3pt] \opt{activelinks} & \opt{true} & Enable Scryfall links in \cmd{card} and \cmd{cardlink}. When \opt{false}, these commands produce plain italic text with no hyperlink. \\[3pt] \opt{symbolpath} & \opt{symbols} & Directory for mana-symbol files. \\[3pt] \opt{setpath} & \opt{sets} & Directory for set-symbol files. \\[3pt] \opt{symbolprefix} & \opt{mtg-sym-} & Filename prefix for mana-symbol files. \\[3pt] \opt{setprefix} & \opt{mtg-set-} & Filename prefix for set-symbol files. \\ \bottomrule \end{tabular} \end{center} \medskip\noindent Example: \begin{lstlisting} \usepackage[hyperref=false, symbolpath=img/symbols]{magicthegathering} \end{lstlisting} %% ========================================================================== \section{Feature 1 -- Mana symbols} %% ========================================================================== \subsection{Syntax} \begin{lstlisting} \mana{} % single symbol \setmanasymbolsize{} % default: 0.8em \end{lstlisting} The command \cmd{mana} inserts the symbol whose filename (without extension) matches \meta{id} from the \opt{symbolpath} directory. \subsection{Example} \begin{lstlisting} \mana{W} \mana{U} \mana{B} \mana{R} \mana{G} \mana{C} \mana{3} \mana{X} \mana{S} \mana{BG} \mana{UR} \mana{WU} \mana{2W} \mana{BP} \mana{WUP} \end{lstlisting} \begin{result} \mana{W}~\mana{U}~\mana{B}~\mana{R}~\mana{G}~\mana{C}~% \mana{3}~\mana{X}~\mana{S}~% \mana{BG}~\mana{UR}~\mana{WU}~% \mana{2W}~\mana{BP}~\mana{WUP} \end{result} \subsection{Available identifiers} \begin{center} \begin{tabular}{@{} l p{8.5cm} @{}} \toprule \textbf{Category} & \textbf{IDs} \\ \midrule Generic / colourless & \texttt{0}--\texttt{20}, \texttt{X}, \texttt{C}, \texttt{S} \\ Colours & \texttt{W}, \texttt{U}, \texttt{B}, \texttt{R}, \texttt{G} \\ Phyrexian & \texttt{WP}, \texttt{UP}, \texttt{BP}, \texttt{RP}, \texttt{GP} \\ Two-colour hybrid & \texttt{WU}, \texttt{WB}, \texttt{UB}, \texttt{UR}, \texttt{BR}, \texttt{BG}, \texttt{RG}, \texttt{RW}, \texttt{GW}, \texttt{GU} \\ Hybrid Phyrexian & \texttt{WUP}, \texttt{WBP}, \texttt{UBP}, \texttt{URP}, \texttt{BRP}, \texttt{BGP}, \texttt{RGP}, \texttt{RWP}, \texttt{GWP}, \texttt{GUP} \\ Hybrid generic & \texttt{2W}, \texttt{2U}, \texttt{2B}, \texttt{2R}, \texttt{2G} \\ Colourless hybrid & \texttt{CW}, \texttt{CU}, \texttt{CB}, \texttt{CR}, \texttt{CG} \\ \bottomrule \end{tabular} \end{center} \medskip\noindent \textbf{Note on symbol updates.} The mana and set symbol artwork bundled with this package was last updated in December~2025. Symbols for sets released after that date may not be included. Updated artwork will be provided in future package releases. %% ========================================================================== \section{Feature 2 -- Full mana costs} %% ========================================================================== \subsection{Syntax} \begin{lstlisting} \manacost{ ...} \end{lstlisting} A space-separated list of symbol IDs. Each token is passed to \cmd{mana} internally. \subsection{Example} \begin{lstlisting} Lightning Bolt: \manacost{R} Counterspell: \manacost{U U} Cryptic Command:\manacost{1 U U U} \end{lstlisting} \begin{result} Lightning Bolt: \manacost{R}\quad Counterspell: \manacost{U U}\quad Cryptic Command: \manacost{1 U U U} \end{result} %% ========================================================================== \section{Feature 3 -- Colour shortcuts} %% ========================================================================== Six convenience commands for the most common single-colour symbols. \medskip \begin{center} \begin{tabular}{@{} l l l @{}} \toprule \textbf{Command} & \textbf{Output} & \textbf{Equivalent} \\ \midrule \cmd{manaW} & \manaW & \lstinline|\mana{W}| \\ \cmd{manaU} & \manaU & \lstinline|\mana{U}| \\ \cmd{manaB} & \manaB & \lstinline|\mana{B}| \\ \cmd{manaR} & \manaR & \lstinline|\mana{R}| \\ \cmd{manaG} & \manaG & \lstinline|\mana{G}| \\ \cmd{manaC} & \manaC & \lstinline|\mana{C}| \\ \bottomrule \end{tabular} \end{center} %% ========================================================================== \section{Feature 4 -- Set symbols} %% ========================================================================== \subsection{Syntax} \begin{lstlisting} \setsymbol{} \setsetsymbolsize{} % default: 1em \end{lstlisting} The \meta{set-code} is the lowercase Scryfall / MTGJSON set identifier (e.g.\ \texttt{mh3}, \texttt{fdn}, \texttt{lea}). \subsection{Example} \begin{lstlisting} Modern Horizons 3: \setsymbol{mh3} Foundations: \setsymbol{fdn} Alpha: \setsymbol{lea} \end{lstlisting} \begin{result} Modern Horizons~3: \setsymbol{mh3}\quad Foundations: \setsymbol{fdn}\quad Alpha: \setsymbol{lea} \end{result} %% ========================================================================== \section{Feature 5 -- Card hyperlinks} %% ========================================================================== \subsection{Syntax} \begin{lstlisting} \card{} \end{lstlisting} Typesets \meta{card name} in \textit{italics} and makes it a clickable link to the Scryfall search page for that card. Requires \pkg{hyperref} (loaded by default). \subsection{Example} \begin{lstlisting} \card{Lightning Bolt} has been a staple since Alpha. \card{Tarmogoyf} defined Modern for years. \end{lstlisting} \begin{result} \card{Lightning Bolt} has been a staple since Alpha.\\ \card{Tarmogoyf} defined Modern for years. \end{result} %% ========================================================================== \section{Feature 6 -- Card links with custom text} %% ========================================================================== \subsection{Syntax} \begin{lstlisting} \cardlink{}{} \end{lstlisting} Like \cmd{card}, but shows \meta{display text} instead of the card name. \subsection{Example} \begin{lstlisting} \cardlink{Lightning Bolt}{This iconic spell} costs \manacost{R}. \end{lstlisting} \begin{result} \cardlink{Lightning Bolt}{This iconic spell} costs \manacost{R}. \end{result} %% ========================================================================== \section{Feature 7 -- Sideboard guide} %% ========================================================================== \subsection{Syntax} \begin{lstlisting} \begin{matchup} \initem{} % IN column \outitem{} % OUT column \end{matchup} \end{lstlisting} Produces a centred IN\,/\,OUT table. Entries are sorted alphabetically within each column. The shorter column is padded automatically. Any content is accepted as \meta{entry}\,---\,plain text, \cmd{card} links, etc. \subsection{Example} \begin{lstlisting} \begin{matchup} \initem{\card{Leyline of Sanctity}} \initem{\card{Roiling Vortex}} \initem{\card{Skullcrack}} \outitem{\card{Eidolon of the Great Revel}} \outitem{\card{Searing Blaze}} \end{matchup} \end{lstlisting} \begin{result} \begin{matchup} \initem{\card{Leyline of Sanctity}} \initem{\card{Roiling Vortex}} \initem{\card{Skullcrack}} \outitem{\card{Eidolon of the Great Revel}} \outitem{\card{Searing Blaze}} \end{matchup} \end{result} %% ========================================================================== \section{Feature 8 -- Deck-list import} %% ========================================================================== \subsection{Syntax} \begin{lstlisting} \insertdeck{} \end{lstlisting} Reads a plain-text file and renders a two-column deck list with Scryfall-linked card names and automatic totals. \subsection{File format} \begin{lstlisting}[language={},basicstyle=\ttfamily\small] 4 Lightning Bolt 4 Goblin Guide 4 Monastery Swiftspear ... SIDEBOARD 3 Leyline of Sanctity 2 Skullcrack \end{lstlisting} One card per line: \texttt{\meta{qty}~\meta{card name}}. The literal line \texttt{SIDEBOARD} (uppercase, no leading whitespace) separates main deck from sideboard. Blank lines are ignored. The sideboard separator is optional; omitting it treats all entries as main-deck cards. \subsection{Example} \begin{lstlisting} \insertdeck{deck-sample.txt} \end{lstlisting} \insertdeck{deck-sample.txt} %% ========================================================================== \section{Feature 9 -- Match results} %% ========================================================================== \subsection{Syntax} \begin{lstlisting} \begin{matchresults} \matchresult{}{}{}{}{} ... \end{matchresults} \end{lstlisting} The \meta{result} argument must be exactly \texttt{Win}, \texttt{Loss}, or \texttt{Draw} (case-sensitive). The win--loss--draw record is computed automatically. \subsection{Example} \begin{lstlisting} \begin{matchresults} \matchresult{1}{Alice}{Amulet Titan}{2--1}{Win} \matchresult{2}{Bob}{Living End}{0--2}{Loss} \matchresult{3}{Carol}{Yawgmoth}{2--1}{Win} \matchresult{4}{Dave}{Burn}{2--0}{Win} \matchresult{5}{Eve}{Cascade Crash}{1--1}{Draw} \end{matchresults} \end{lstlisting} \begin{result} \begin{matchresults} \matchresult{1}{Alice}{Amulet Titan}{2--1}{Win} \matchresult{2}{Bob}{Living End}{0--2}{Loss} \matchresult{3}{Carol}{Yawgmoth}{2--1}{Win} \matchresult{4}{Dave}{Burn}{2--0}{Win} \matchresult{5}{Eve}{Cascade Crash}{1--1}{Draw} \end{matchresults} \end{result} %% ========================================================================== \section{Quick-reference table} %% ========================================================================== \begin{longtable}{@{} p{5.8cm} p{7.5cm} @{}} \toprule \textbf{Command / environment} & \textbf{Description} \\ \midrule\endhead \bottomrule\endfoot \cmd{setmanasymbolsize}\carg{dim} & Set mana-symbol height (default 0.8em). \\ \cmd{mana}\carg{id} & Single mana symbol. \\ \cmd{manacost}\carg{id id \ldots} & Full mana cost (space-separated). \\ \cmd{manaW}\,\ldots\,\cmd{manaC} & Colour shortcuts. \\[3pt] \cmd{setsetsymbolsize}\carg{dim} & Set-symbol height (default 1em). \\ \cmd{setsymbol}\carg{code} & Expansion symbol. \\[3pt] \cmd{card}\carg{name} & Italic card name with Scryfall link. \\ \cmd{cardlink}\carg{name}\carg{text} & Custom text with Scryfall link. \\[3pt] \env{matchup} & IN\,/\,OUT sideboard table. \\ \quad\cmd{initem}\carg{entry} & Add to IN column. \\ \quad\cmd{outitem}\carg{entry} & Add to OUT column. \\[3pt] \cmd{insertdeck}\carg{file} & Import deck list from text file. \\[3pt] \env{matchresults} & Tournament results table. \\ \cmd{matchresult}\carg{rd}\carg{opp}\\% \carg{deck}\carg{score}\carg{result} & Add one match row. \\ \end{longtable} %% ========================================================================== \section{Licence} %% ========================================================================== This work is released under the \href{https://www.latex-project.org/lppl/lppl-1-3c/}% {LaTeX Project Public Licence v1.3c} or later. The SVG artwork in \file{symbols/} and \file{sets/} is from the \href{https://mana.andrewgioia.com}{Mana} and \href{https://keyrune.andrewgioia.com}{Keyrune} projects by Andrew~Gioia, released under the SIL Open Font Licence~1.1. Magic:~The~Gathering, the mana symbols, the tap symbol, the set symbols, and all associated card names and game elements are trademarks and/or copyrighted materials of Wizards of the Coast~LLC and/or its affiliates. All rights in such materials are reserved by Wizards of the~Coast. This package is an unofficial fan project and is not produced, endorsed, supported, or affiliated with Wizards of the~Coast. %% ========================================================================== \section{Version history} %% ========================================================================== \begin{description}[font=\normalfont\ttfamily\bfseries, itemsep=4pt] \item[v1.1 (2026-03-21)] Renamed all symbol and set files with unique prefixes (\file{mtg-sym-*}, \file{mtg-set-*}) for TeX~Live compatibility. Added \opt{symbolprefix} and \opt{setprefix} package options. No changes to user-facing commands. \item[v1.0 (2026-03-15)] First public release. Nine features: mana symbols, full mana costs, colour shortcuts, set symbols, card hyperlinks, custom-text card links, sideboard guide, deck-list import, match results. \end{description} \end{document}