path: root/macros/latex/contrib/rpgicons/rpgicons-doc.tex

% File: rpgicons-doc.tex 
% Copyright 2024 Jasper Habicht (mail(at)jasperhabicht.de).
% 
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License version 1.3c,
% available at http://www.latex-project.org/lppl/.
% 
% This file is part of the `rpgicons'  package (The Work in LPPL)
% and all files in that bundle must be distributed together.
% 
% This work has the LPPL maintenance status `maintained'.
% 
\documentclass[a4paper]{article}
\def\rpgiconsfileversion{1.8.4}
\def\rpgiconsfiledate{8 August 2024}

\usepackage[T1]{fontenc}
\usepackage{Alegreya}
\usepackage{AlegreyaSans}
\usepackage{FiraMono}

\usepackage{geometry, longtable, booktabs, tcolorbox, hyperref}
\geometry{margin=25mm, left=45mm}

\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhf{}
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[R]{\thepage}

\linespread{1.1}\selectfont
\addtolength{\skip\footins}{1em plus 5pt}
\makeatletter
\renewcommand*{\thefootnote}{\fnsymbol{footnote}}
\renewcommand{\@makefntext}[1]{%
    \noindent\hbox to 0.75em{\normalfont\@thefnmark\hss}~#1%
}
\makeatother

\tcbuselibrary{listings}
\lstdefinestyle{rpgiconsdocmacro}{
    basicstyle=\small\ttfamily,
    literate=*{<}{{{\color{black!50}\guilsinglleft}}}1 
        {>}{{{\color{black!50}\guilsinglright}}}1,
    keywords={},
    moredelim=[is][\bfseries]{|}{|},
    moredelim=[is][\color{black!50}]{!}{!},
}
\lstdefinestyle{rpgiconsdoccodeexample}{
    basicstyle=\small\ttfamily,
    keywords={},
}

\hypersetup{colorlinks}

\ExplSyntaxOn
\int_new:N \l_rpgicons_doc_change_int
\NewDocumentCommand{\changes}{ m m m }{
    \int_incr:N \l_rpgicons_doc_change_int
    \prop_new:c { l_rpgicons_doc_change_ 
        \int_to_roman:n { \l_rpgicons_doc_change_int } _prop }
    \prop_put:cnn { l_rpgicons_doc_change_ 
        \int_to_roman:n { \l_rpgicons_doc_change_int } _prop } { version } {#1}
    \prop_put:cnn { l_rpgicons_doc_change_ 
        \int_to_roman:n { \l_rpgicons_doc_change_int } _prop } { date } {#2}
    \prop_put:cnn { l_rpgicons_doc_change_ 
        \int_to_roman:n { \l_rpgicons_doc_change_int } _prop } { changes } {#3}
}
\NewDocumentCommand{\printchanges}{ }{
    \section{Changes}
    \begin{description}
    \int_step_inline:nn { \l_rpgicons_doc_change_int } {
        \item[ 
            \prop_item:cn { l_rpgicons_doc_change_ 
            \int_to_roman:n { ##1 } _prop } { version } ] 
            ( \prop_item:cn { l_rpgicons_doc_change_ 
            \int_to_roman:n { ##1 } _prop } { date } ) \\
            \prop_item:cn { l_rpgicons_doc_change_ 
            \int_to_roman:n { ##1 } _prop } { changes }
    }
    \end{description}
}

\tl_new:N \l_rpgicons_doc_doctitle_tl
\NewExpandableDocumentCommand{\makedoctitle}{ o m o m m o m }{
    \hypersetup{
        pdfauthor={#5},
        pdftitle={\IfValueTF{#1}{#1}{#2}},
        pdfsubject={\IfValueTF{#3}{#3}{#4}}
    }
    \tl_set:Nn \l_rpgicons_doc_doctitle_tl {
        \group_begin:
            \tcbset{
                title ~ style ~ hook/.style={
                    boxrule=2pt,
                    fontupper=\huge\ttfamily
                }
            }
            \setlength{\parindent}{0pt}\sffamily
            \Huge{\bfseries #2}\par\bigskip
            \Large #4\par\bigskip
            \large #5
            \IfValueT{#6}{
                \,\footnote{#6}\par\bigskip
            }
            #7\par\bigskip
            \rule{\textwidth}{.08em}
        \group_end:
    }
}

\NewExpandableDocumentCommand{\printdoctitle}{ }{
    \tl_use:N \l_rpgicons_doc_doctitle_tl
}
\ExplSyntaxOff

\tcbset{
    size=small,
    arc=2.5pt,
    outer arc=2.5pt,
    colframe=black!10,
    colback=black!10,
    title style hook/.style={}
}

\NewTCBListing{macrodef}{ }{ 
    listing only,
    listing style={rpgiconsdocmacro},
    grow to left by=2cm,
    boxrule=0pt,
    after={\par\smallskip\noindent}
}

\NewTCBListing{codeexample}{ }{
    text side listing,
    lefthand width=4.5cm,
    listing style={rpgiconsdoccodeexample},
    after={\par\smallskip\noindent}
}

\NewTotalTCBox{\macro}{ O{} v }{
    verbatim,
    size=tight,
    arc=1pt,
    outer arc=1pt,
    top=0.5pt, 
    bottom=0.5pt,
    left=2pt, 
    right=2pt,
    boxrule=0pt,
    colframe=black!10,
    colback=black!10,
    fontupper=\small\ttfamily,
    #1
}{\vphantom{/g}\lstinline^#2^}

\NewTotalTCBox{\titlemacro}{ s O{} m }{
    verbatim,
    size=tight,
    arc=1pt,
    outer arc=1pt,
    top=0.5pt, 
    bottom=0.5pt,
    left=2pt, 
    right=2pt,
    boxrule=0pt,
    colframe=black!10,
    colback=black!10,
    fontupper=\small\ttfamily,
    title style hook,
    #2
}{\vphantom{/g}\IfBooleanT{#1}{\textbackslash}#3}

\usepackage{rpgicons-l3}
\usepackage[pics]{rpgicons-pgf}

\ExplSyntaxOn
\clist_new:N \l_rpgicons_doc_logo_icons_clist
\clist_new:N \l_rpgicons_doc_logo_colors_clist
\cs_generate_variant:Nn { \color_set:nnn } { nne }

\clist_set:Nn \l_rpgicons_doc_logo_colors_clist { 
    264653 , 287271 , 2a9d8f , e9c46a , f4a261 , e76f51 
}
\int_step_inline:nn { \clist_count:N \l_rpgicons_doc_logo_colors_clist } {
    \color_set:nne { rpgiconslogo \int_to_roman:n { #1 } } { HTML } {
        \clist_item:Nn \l_rpgicons_doc_logo_colors_clist { #1 }
    }
}
\clist_set:Nn \l_rpgicons_doc_logo_icons_clist { 
    twentyside , charisma , armor , buff , ranged , proficiency 
}

\NewDocumentCommand{\rpgiconslogo}{ O{1} }{
    \draw_begin:
        \draw_transform_scale:n { #1 }
        \int_step_inline:nn { \clist_count:N \l_rpgicons_doc_logo_icons_clist } {
            \hcoffin_set:Nn \l_tmpa_coffin { 
                \draw_suspend_begin: 
                    \RPGIconsAbility[negative]{ 
                        \clist_item:Nn \l_rpgicons_doc_logo_icons_clist { ##1 } 
                    }[color=rpgiconslogo \int_to_roman:n { ##1 } ] 
                \draw_suspend_end: 
            }
            \draw_scope_begin:
                \draw_transform_shift:n { 
                    % fix bug in older l3draw version
                    \cs_if_exist:NTF \__draw_transform_shift:nnnn { 
                        \draw_point_polar:nn { 0.33cm } { 60 * ##1 + 10 }
                    } {
                        \draw_point_transform:n { \draw_point_polar:nn { 0.33cm } { 60 * ##1 + 10 } }
                    }
                }
                \draw_coffin_use:Nnn \l_tmpa_coffin { hc } { vc } 
            \draw_scope_end:
        }
    \draw_end:
}
\ExplSyntaxOff

\NewDocumentEnvironment{rpgiconsiconlist}{ }{
    \begin{longtable}{ @{} p{20em} p{5em} p{\dimexpr\linewidth-25em-4\tabcolsep} @{} }
    \toprule
    \textbf{Command} & \textbf{Icon} & \textbf{Shape} \\ 
    \midrule\endhead
}{
    \bottomrule
    \end{longtable}
}

\makedoctitle
    [The rpgicons package]
    {The \titlemacro{rpgicons} package}
    {A set of high-quality icons for use in notes for tabletop role-playing games}
    {Jasper Habicht}[E-mail: \href{mailto:mail@jasperhabicht.de}{mail@jasperhabicht.de}. I am grateful to Joseph Wright who fixes bugs at an astonishing speed and to all other contributors to this package.]
    {Version \rpgiconsfileversion, released on \rpgiconsfiledate}

\changes{v1.1.0}{2023/08/15}{First public release.}
\changes{v1.1.1}{2023/11/15}{Fudge dice icon added.}
\changes{v1.1.2}{2023/11/16}{Bug fixed that caused wrong spacing when using dice icons without quantifier.}
\changes{v1.2.0}{2023/11/20}{Corrections in the manual. Icons for six-sided dice with one to nine pips, plus sign and minus sign added.}
%\changes{v1.2.1}{2023/11/20}{Documentation of lengths for spacing added.}
%\changes{v1.2.2}{2023/11/21}{Corrections in the manual.}
\changes{v1.3.0}{2023/11/21}{Option to set background color added. Renamed global option.}
\changes{v1.3.1}{2024/02/18}{Correction of initializing code. Correction of default value of after sep. Addition of pics.}
%\changes{v1.3.2}{2024/02/19}{Reformatting of the manual.}
%\changes{v1.3.4}{2024/02/20}{Minor corrections of some shapes.}
\changes{v1.4.0}{2024/02/21}{L3 variant added.}
\changes{v1.4.1}{2024/02/21}{Corrections in L3 variant.}
\changes{v1.4.2}{2024/02/21}{Alternative set of commands in L3 variant defined.}
\changes{v1.4.3}{2024/02/22}{Added option to L3 variant to enable upward compatibility.}
\changes{v1.4.4}{2024/02/24}{Added styles for every instance of command or shape, correction of recent \titlemacro{l3draw} code.}
\changes{v1.5.0}{2024/02/25}{Alternative set of commands defined, added support of styles in pics.}
\changes{v1.5.1}{2024/02/28}{Addition of opacity to L3 variant.}
\changes{v1.5.2}{2024/02/29}{Unification of scaling, minor corrections.}
\changes{v1.5.3}{2024/03/03}{Optimisation of code in L3 variant.}
\changes{v1.5.4}{2024/03/06}{Correction of baseline settings in L3 variant, added accessibililty support for L3 variant.}
%\changes{v1.5.5}{2024/03/07}{Optimsation of accessibililty support for L3 variant.}
\changes{v1.6.0}{2024/03/15}{Four attribute icons added, minor correction of styles.}
\changes{v1.6.1}{2024/03/16}{Unified size of negative attribute icon.}
\changes{v1.7.0}{2024/03/16}{Macro for easy typesetting using roll dice syntax added in L3 variant, compatibility mode updated.}
\changes{v1.8.0}{2024/03/24}{Unified wrapper to load either package variant.}
\changes{v1.8.2}{2024/04/28}{Roll dice syntax for PGF variant.}
\changes{v1.8.3}{2024/05/15}{Minor compatibility fix. Example of how to use pics added to ducumentation.}
\changes{v1.8.3}{2024/05/15}{Bug fix in evocation spellschool shape. Unification of frames in PGF and L3 variants.}

\begin{document}

\vspace*{-1cm}
\noindent\rpgiconslogo[4]

\bigskip

\printdoctitle

\bigskip

\section{Introduction}

The \macro{rpgicons} package provides a set of high-quality icons for use in notes for tabletop role-playing games. The icons are meant to be used in the body text, but they can also be used in other contexts such as graphics or diagrams.

The package comes in two variants, a L3 variant based on the \macro{l3draw} package which is loaded per default and a PGF variant based on PGF/Ti\emph{k}Z.

\section{Loading the package}

To install the package, copy the relevant package files \macro{rpgicons.sty}, \macro{rpgicons-l3.sty} and \macro{rpgicons-pgf.sty} into the working directory or into the \macro{texmf} directory. After the package has been installed, the \macro{rpgicons} package is loaded by calling \macro{\usepackage{rpgicons}} in the preamble of the document. 

\begin{macrodef}l3\end{macrodef}
The L3 variant of the package is loaded by default. To load it explicitly, the package can be loaded using the option \macro{l3}. Alternatively, \macro{\usepackage{rpgicons-l3}} can be called instead.

\begin{macrodef}pgf\end{macrodef}
To load the PGF variant of the package the package needs to be loaded with the option \macro{pgf}. Alternatively, \macro{\usepackage{rpgicons-pgf}} can be called instead.

\subsection{Dependencies}

The L3 variant of the package loads the \macro{l3draw} package. If the package is loaded with the \macro{opacity} option to enable transparency, the \macro{l3opacity} package is also loaded.

The PGF variant of the package loads the \macro{tikz} package which in turn loads the \macro{xcolor} package. To make use of specific options these packages provide, you need to load the packages with the relevant options beforehand or use, such as \macro{\PassOptionsToPackage{svgnames}{xcolor}}.

\section{Main user commands}

Regardless of the variant of the package, a set of user commands is always available. These are described in the following. Depending on the use of the L3 or the PGF variant, certain specific commands or options are available that are explained in the following sections in further detail.

Because of the way the package defines the icons, every of the below described user commands can actually be used together with every shape. However, the combinations of shapes and commands as described in the following subsections are preferable.

\subsection[Command \textbackslash die]{Command \titlemacro*{die}}

\begin{macrodef}
|\die|[<style>]{<shape>}[<options>]{<integer>}
\end{macrodef}
The command \macro{\die} prints an icon to depict a die with a certain number of sides. Two special icons exist for a two-sided die (which would be equivalent to a coin) and for a hundred-sided die (which typically comes in the shape of a sphere). There is also a special icon for a fudge die. 

For the six-sided die, nine additional shapes exists representing the values one to nine as pips. Also, additional shapes exist representing the plus or minus side of a fudge die.

The command takes two mandatory commands, the first of which describes the shape (see the lists below) and the second can take an integer that is placed in front of the shape. For example, \macro{\die{eightside}{2}} results in \die{eightside}{2} (meaning two eight-sided dice are rolled).

The command also takes two optional arguments, the second of which can take additional options to style the icon. The options affect the shape, not the integer when it is printed before the icon. These options differ depending on the package variant. See the relevant sections below.

The first optional argument can take the value \macro{normal} or \macro{large}, \macro{normal} being the default value. With \macro{large} given as argument, the icon is drawn larger and the additional integer is printed inside of the shape instead of before it. As an example, \macro{\die[large]{eightside}{2}} results in \die[large]{eightside}{2}. Note that the integer will always be printed on top of the shape, even if the shape does not have an open center as in the case of the \macro{fudge} shapes or the shapes featuring pips. 

\begin{rpgiconsiconlist}
\macro{\die} 
    & \die{twoside}{} & \macro{twoside} \\
    & \die{fourside}{} & \macro{fourside} \\
    & \die{sixside}{} & \macro{sixside} \\
    & \die{eightside}{} & \macro{eightside} \\
    & \die{tenside}{} & \macro{tenside} \\
    & \die{twelveside}{} & \macro{twelveside} \\
    & \die{twentyside}{} & \macro{twentyside} \\
    & \die{hundredside}{} & \macro{hundredside} \\
    & \die{fudge}{} & \macro{fudge} \\
    & \die{sixside one}{} & \macro{sixside one} \\
    & \die{sixside two}{} & \macro{sixside two} \\
    & \die{sixside three}{} & \macro{sixside three} \\
    & \die{sixside four}{} & \macro{sixside four} \\
    & \die{sixside five}{} & \macro{sixside five} \\
    & \die{sixside six}{} & \macro{sixside six} \\
    & \die{sixside seven}{} & \macro{sixside seven} \\
    & \die{sixside eight}{} & \macro{sixside eight} \\
    & \die{sixside nine}{} & \macro{sixside nine} \\
    & \die{fudge plus}{} & \macro{fudge plus} \\
    & \die{fudge minus}{} & \macro{fudge minus} \\
\end{rpgiconsiconlist}

\subsection[Commands \textbackslash ability and \textbackslash saving]{Commands \titlemacro*{ability} and \titlemacro*{saving}}

\begin{macrodef}
|\ability|[<style>]{<shape>}[<options>]
\end{macrodef}
The command \macro{\ability} prints icons depicting an ability of a character. The abilities are represented by animal-like shapes. The relevant shape should be given as mandatory argument to the command. The second optional argument can take additional options to style the icon.

The first optional argument can take the value \macro{positive} or \macro{negative}, \macro{positive} being the default value. With \macro{negative} given as argument, the icon is drawn negative inside a circle. As an example, \macro{\ability[negative]{charisma}} results in \ability[negative]{charisma}.

\begin{macrodef}
|\saving|[<style>]{<shape>}[<options>]
\end{macrodef}
The command \macro{\saving} prints the icons that can be typeset using the \macro{\ability} command inside a small shield. It can take the same values for the mandatory argument as the \macro{\ability} command. The optional argument can take additional options to style the icon.

The first optional argument can take the value \macro{normal} or \macro{empty}, \macro{normal} being the default value. With \macro{empty} given as argument, the icon inside the shield is not printed. In this case, the mandatory argument can be left empty. As an example, \macro{\saving[empty]{}} results in \saving[empty]{}. 

\begin{rpgiconsiconlist}
\macro{\ability} 
    & \ability{strength} & \macro{strength} \\
    & \ability{dexterity} & \macro{dexterity} \\
    & \ability{dexterity alt} & \macro{dexterity alt} \\
    & \ability{constitution} & \macro{constitution} \\
    & \ability{intelligence} & \macro{intelligence} \\
    & \ability{wisdom} & \macro{wisdom} \\
    & \ability{charisma} & \macro{charisma} \\
    & \ability{resilience} & \macro{resilience} \\
    & \ability{sanity} & \macro{sanity} \\
    & \ability{perception} & \macro{perception} \\
    & \ability{luck} & \macro{luck} \\
    & \ability{armor} & \macro{armor} \\
    & \ability{proficiency} & \macro{proficiency} \\
\midrule
\macro{\saving} 
    & \saving{strength} & \macro{strength} \\
    & \saving{dexterity} & \macro{dexterity} \\
    & \saving{dexterity alt} & \macro{dexterity alt} \\
    & \saving{constitution} & \macro{constitution} \\
    & \saving{intelligence} & \macro{intelligence} \\
    & \saving{wisdom} & \macro{wisdom} \\
    & \saving{charisma} & \macro{charisma} \\
    & \saving{resilience} & \macro{resilience} \\
    & \saving{sanity} & \macro{sanity} \\
    & \saving{perception} & \macro{perception} \\
    & \saving{luck} & \macro{luck} \\
    & \saving{armor} & \macro{armor} \\
    & \saving{proficiency} & \macro{proficiency} \\
\end{rpgiconsiconlist}

\subsection[Command \textbackslash spell]{Command \titlemacro*{spell}}

\begin{macrodef}
|\spell|{<shape>}[<options>]
\end{macrodef}
The command \macro{\spell} prints icons depicting the effect of a spell or how it is to be effected. The optional argument can take additional options to style the icon.

\begin{rpgiconsiconlist}
\macro{\spell} 
    & \spell{linear} & \macro{linear} \\
    & \spell{conic} & \macro{conic} \\
    & \spell{quadratic} & \macro{quadratic} \\
    & \spell{cubic} & \macro{cubic} \\
    & \spell{spheric} & \macro{spheric} \\
    & \spell{cylindric} & \macro{cylindric} \\
    & \spell{verbal} & \macro{verbal} \\
    & \spell{somatic} & \macro{somatic} \\
    & \spell{material} & \macro{material} \\
    & \spell{focus} & \macro{focus} \\
\end{rpgiconsiconlist}

\subsection[Command \textbackslash spellschool]{Command \titlemacro*{spellschool}}

\begin{macrodef}
|\spellschool|[<style>]{<shape>}[<options>]
\end{macrodef}
The command \macro{\spellschool} prints icons that represent the school a spell belongs to. The second optional argument can take additional options to style the icon.

The first optional argument can take the value \macro{negative} or \macro{positive}, \macro{negative} being the default value. Per default the icon is drawn in white inside a filled escutcheon. With \macro{positive} given as argument, the icon as well as the escutcheon are drawn in the currently selected color. As an example, \macro{\spellschool[positive]{evocation}} results in \spellschool[positive]{evocation}.

\begin{rpgiconsiconlist}
\macro{\spellschool} 
    & \spellschool{abjuration} & \macro{abjuration} \\
    & \spellschool{conjuration} & \macro{conjuration} \\
    & \spellschool{divination} & \macro{divination} \\
    & \spellschool{enchantment} & \macro{enchantment} \\
    & \spellschool{evocation} & \macro{evocation} \\
    & \spellschool{illusion} & \macro{illusion} \\
    & \spellschool{necromancy} & \macro{necromancy} \\
    & \spellschool{transmutation} & \macro{transmutation} \\
\end{rpgiconsiconlist}

\subsection[Commands \textbackslash damage, \textbackslash attack, and \textbackslash condition]{Commands \titlemacro*{damage}, \titlemacro*{attack}, and \titlemacro*{condition}}

\begin{macrodef}
|\damage|{<shape>}[<options>]
\end{macrodef}
The command \macro{\damage} prints icons depicting the damage of an attack. The icon is printed inside a circle. The optional argument can take additional options to style the icon.

\begin{macrodef}
|\attack|{<shape>}[<options>]
\end{macrodef}
The command \macro{\attack} prints icons depicting the kind of an attack. The optional argument can take additional options to style the icon.

\begin{macrodef}
|\condition|{<shape>}[<options>]
\end{macrodef}
The command \macro{\condition} prints icons depicting a condition of a character. The optional argument can take additional options to style the icon.

\begin{rpgiconsiconlist}
\macro{\damage} 
    & \damage{acid} & \macro{acid} \\
    & \damage{bludgeoning} & \macro{bludgeoning} \\
    & \damage{cold} & \macro{cold} \\
    & \damage{fire} & \macro{fire} \\
    & \damage{force} & \macro{force} \\
    & \damage{lightning} & \macro{lightning} \\
    & \damage{necrotic} & \macro{necrotic} \\
    & \damage{piercing} & \macro{piercing} \\
    & \damage{poison} & \macro{poison} \\
    & \damage{psychic} & \macro{psychic} \\
    & \damage{radiant} & \macro{radiant} \\
    & \damage{slashing} & \macro{slashing} \\
    & \damage{thunder} & \macro{thunder} \\
    & \damage{healing} & \macro{healing} \\
\midrule
\macro{\attack} 
    & \attack{melee} & \macro{melee} \\
    & \attack{ranged} & \macro{ranged} \\
    & \attack{magic} & \macro{magic} \\
    & \attack{singlehanded} & \macro{singlehanded} \\
    & \attack{doublehanded} & \macro{doublehanded} \\
\midrule
\macro{\condition} 
    & \condition{buff} & \macro{buff} \\
    & \condition{blinded} & \macro{blinded} \\
    & \condition{charmed} & \macro{charmed} \\
    & \condition{deafened} & \macro{deafened} \\
    & \condition{exhausted} & \macro{exhausted} \\
    & \condition{frightened} & \macro{frightened} \\
    & \condition{grappled} & \macro{grappled} \\
    & \condition{incapacitated} & \macro{incapacitated} \\
    & \condition{invisible} & \macro{invisible} \\
    & \condition{paralyzed} & \macro{paralyzed} \\
    & \condition{petrified} & \macro{petrified} \\
    & \condition{poisoned} & \macro{poisoned} \\
    & \condition{prone} & \macro{prone} \\
    & \condition{restrained} & \macro{restrained} \\
    & \condition{stunned} & \macro{stunned} \\
    & \condition{unconscious} & \macro{unconscious} \\
    & \condition{hearing} & \macro{hearing} \\
    & \condition{seeing} & \macro{seeing} \\
\end{rpgiconsiconlist}

% l3 variant

\section{Specifics of the L3 package variant}

The L3 variant of the package that uses the \macro{l3draw} package is loaded by default or explicitly by either calling \macro{\usepackage[l3]{rpgicons}} or \macro{\usepackage{rpgicons-l3}} in the preamble of the document after having installed the files \macro{rpgicons.sty} and \macro{rpgicons-l3.sty}. The \macro{l3draw} package is an experimental package that provides only basic drawing functionality. The L3 variant thus only supports a certain set of option for styling the icons. 

The L3 variant of the package does not load the \macro{xcolor} package, but makes use of the \macro{l3color} module which uses a similar syntax like the \macro{xcolor} package, but color definitions made using the \macro{l3color} module are not directly usable via commands provided by the \macro{xcolor} package. Therefore, setting a color using the \macro{\color} macro provided by the \macro{xcolor} package won't affect the color of the icons.

\begin{macrodef}compat\end{macrodef}
The \macro{l3draw} package is experimental and subject to ongoing updates. Loading the L3 variant of the package with the option \macro{compat} will use macro definitions that have been available since the last major TeX Live release as replacement for certain functions that only became available in the most recent versions of the \macro{l3draw} and related packages.

\label{macro:opacity}
\begin{macrodef}opacity\end{macrodef}
With the \macro{opacity} option, the L3 variant of the package supports transparency using the functionality of the \macro{l3opacity} package. Since transparency requires the management of certain PDF settings, it is necessary to call \macro{\DocumentMetadata{}} before loading a \macro{\documentclass}. The \macro{l3opacity} package is experimental.

\subsection{Icon commands}

\begin{macrodef}
|\RPGIconsUseIcon|[<options>][<integer>]{<shape>}
|\RPGIconsUseIcon*|[<options>][<integer>]{<shape>}
\end{macrodef}
\macro{\RPGIconsUseIcon} is the primary command to typeset icons using the L3 variant of the package. The commands \macro{\die}, \macro{\ability}, \macro{\saving}, \macro{\spell}, \macro{\spellschool}, \macro{\damage}, \macro{\attack} and \macro{\condition} are based on this command. 

The \macro{\RPGIconsUseIcon} command has a starred version and two optional arguments as well as one mandatory argument. The mandatory argument holds the shape of the icon. The second optional argument can be used to add an integer when used with shapes for dice.

The starred version of the command is used to fill a frame with color instead of drawing its outline. Frames can be put around the shape via the relevant \macro{frame} option. 

\begin{macrodef}
|\RPGIconsDie|[<style>]{<shape>}[<options>]{<integer>}
|\RPGIconsAbiliy|[<style>]{<shape>}[<options>]
|\RPGIconsSaving|[<style>]{<shape>}[<options>]
|\RPGIconsSpell|{<shape>}[<options>]
|\RPGIconsSpellschool|[<style>]{<shape>}[<options>]
|\RPGIconsDamage|{<shape>}[<options>]
|\RPGIconsAttack|{<shape>}[<options>]
|\RPGIconsCondition|{<shape>}[<options>]
\end{macrodef}
The L3 variant of the package defines a set of commands on which the user commands \macro{\die}, \macro{\ability}, \macro{\saving}, \macro{\spell}, \macro{\spellschool}, \macro{\damage}, \macro{\attack} and \macro{\condition} are based. This set of commands can be used in cases where another package defines one of these user commands. These user commands are exact copies of this set of commands.

\subsection{Icon options}

\begin{macrodef}
frame
stroke
fill
text
color
background
stroke opacity 
fill opacity
text opacity
opacity 
background opacity
line width
scale
scale inner
rotate
\end{macrodef}
The \macro{\RPGIconsUseIcon} command and the commands \macro{\die}, \macro{\ability}, \macro{\saving}, \macro{\spell}, \macro{\spellschool}, \macro{\damage}, \macro{\attack} and \macro{\condition} can be used with certain options that each consist of a key-value pair and can be combined. When used with the \macro{\RPGIconsUseIcon} command or the other commands based on this command, these options should be used directly without wrapping them inside the \macro{style} option. 

For example, \macro{\die{eightside}[color=blue, line width=0.8pt]{2}} would result in \die{eightside}[color=blue, line width=0.8pt]{2}.

With the \macro{frame} option, one of four different frames can be selected that are drawn around the shape of the icon. The values \macro{ability} and \macro{damage} draw a circle around the shape. The value \macro{saving} draws a rounded shield and the value \macro{spellschool} draws an angular shield around the shape. The commands \macro{\ability}, \macro{\saving}, \macro{\spellschool} and \macro{\damage} make use of the relevant frame.

Some icons can be used with a negative color scheme where the icon is drawn negatively inside a filled shape. Per default, the icons are drawn in white in such cases, but it might be desirable that the icons are in the same color as the background. To this end, the \macro{background} option sets the color of the shape when it is printed over a filled frame which can be achieved by setting the \macro{negative} option for the \macro{\ability} or the \macro{\spellschool} command or using the starred version of the \macro{\RPGIconsUseIcon} command.

The \macro{color} option sets the color of strokes, fills and text in general while the \macro{stroke} option, the \macro{fill} option and the \macro{text} option set the color only for strokes, fills or text respectively. Similarly, the \macro{opacity} macro sets the opacity generally, while the options \macro{stroke opacity}, \macro{fill opacity} and \macro{text opacity} allow for setting the opacity of strokes, fill and text separately. The opacity styles are only available when loading the package with the \macro{opacity} option (see the \hyperref{macro:opacity}{description above}). The \macro{line width} sets the line width for strokes. Using the \macro{scale} and \macro{rotate} options, the shape can be scaled and rotated.

The \macro{scale inner} option can be used to change the scaling of the icon when placed inside a frame when using the \macro{\ability}, \macro{\saving}, \macro{\spellschool} and \macro{\damage} macros. The default value is 0.675.

\begin{macrodef}
accessible
accessible = basic
accessible = full
accessible = false
\end{macrodef}
Using the \macro{accessible} option with no value or the value \macro{basic}, a replacement text to the relevant icon can be added which can be copied to the clipboard. The value \macro{full} additionally places an \macro{\Alt} mark in the PDF which means that the shape of the relevant icon is read by screen readers. For this to work, is necessary to call \macro{\DocumentMetadata{}} before loading a \macro{\documentclass}, preferably with tagging enabled to make use of the \macro{accessible} option. The value \macro{full} can be used to disable the function explicitly. Note that depending on the compiler and PDF viewer, there might be line breaks or no spaces before and after the replacement text. 

\begin{macrodef}
every die
every ability
every saving
every spell
every spellschool
every damage
every attack
every condition
every <shape>
\end{macrodef}
Styles following the pattern \macro{rpg icons/every} followed by a space and the name of the command or the shape can be used to apply styles to every instance of this command or shape. For example, \macro{\rpgiconsset{every die={color={red}}}} can be used to draw in red all icons created using the \macro{\die} command. Calling \macro{\rpgiconsset{every charisma={color={red}}}} will draw every instance of the \macro{charisma} shape in red.

\subsection{Setting options globally}

\begin{macrodef}
|\rpgiconsset|
\end{macrodef}
Apart from setting the options to the commands directly, it is also possible to set them globally using the \macro{\rpgiconsset} command. Globally set options are overridden by options that are selected directly.

\begin{codeexample}
\rpgiconsset{
    color=blue
}

\ability{charisma}
\ability{charisma}[color=red]
\ability{charisma}
\end{codeexample}

\begin{macrodef}
before sep
after sep
baseline
\end{macrodef}
The spacing before and after the icons can be set using the options \macro{before sep} and \macro{after sep}. The option \macro{baseline} can be used to adjust the baseline of the icons. These options can also be applied to the icon commands directly.

\begin{codeexample}
Roll\die{eightside}{}a die!

\rpgiconsset{
    before sep={1cm}
}
Roll\die{eightside}{}a die!
\end{codeexample}

\subsection{Roll dice syntax}\label{sec:roll-dice-syntax}

\begin{macrodef}
|\roll|{<roll syntax>}
|\RPGIconsRoll|{<roll syntax>}
\end{macrodef}
The \macro{\roll} macro can be used to quickly typeset dice rolls with the relevant icons using the established dice rolling syntax. This syntax consists of a sequence of dice and numbers concatenated by mathematical operators (plus, minus or times). Typically, the letter \macro{d} is used to denote a die with a certain number of sides. For example \macro{d6} denotes a six-sided die. A number can be added to specify the number of such dice that are rolled together. The letter to denote the die can be changed using the option \macro{roll syntax}. 

For example, \macro{2d6 + 3d4 - 1} means ``roll two six-sided dice and three four-sided dice and subtract one from the result''. The command \macro{\roll{2d6 + 3d4 - 1}} results in \roll{2d6 + 3d4 - 1}.

The die notations \macro{d2}, \macro{d4}, \macro{d6}, \macro{d8}, \macro{d10}, \macro{d12}, \macro{d20} and \macro{d100} are defined. To denote a fudge die, \macro{dF} can be used. To denote that the lowest or highest die should be removed from the result, the letters \macro{L} and \macro{H} can be used. The syntax \macro{2d6 x 2} or \macro{2d6 * 2} can be used to denote several rolls with the same set of dice.

If the \macro{rpgicons} package is to be loaded together with some other package that defines the command \macro{\roll}, the command \macro{\RPGIconsRoll} can be used. This alternative command is an exact copy of the \macro{\roll} command. 

\begin{macrodef}
roll syntax
\end{macrodef}
The option \macro{roll syntax} can be used to change the character that denotes a die in the dice rolling syntax. Multiple characters can be given using a comma separated list. The default setting is \macro{d,D} which allows notations such as \macro{2d6} or \macro{2D6}. 

With \macro{\rpgiconsset{roll syntax={w,W}}}, for example, notations such as \macro{2w6} or \macro{2W6} could be used. 

% PGF variant

\RenewCommandCopy\die\rpgiconsdie
\RenewCommandCopy\ability\rpgiconsability

\section{Specifics of the PGF package variant}

The PGF variant of the package is loaded by either calling \macro{\usepackage[pgf]{rpgicons}} or \macro{\usepackage{rpgicons-pgf}} in the preamble of the document after having installed the files \macro{rpgicons.sty} and \macro{rpgicons-pgf.sty}. 

Since the commands to typeset the icons with the PGF variant of the package use \macro{tikzpicture} environments, these commands should not be used inside another \macro{tikzpicture}. However, because the package defines the icons as Ti\emph{k}Z shapes, it is possible to use the icons in \macro{tikzpicture} environments directly. 

Apart from that, the PGF variant of the package provides a way to define custom commands to typeset the icons as boxed material which is safe to use in a \macro{tikzpicture} context. Furthermore, the icons can be used as Ti\emph{k}Z pics. 

Once loaded, the PGF variant of the package defines a set of node shapes that can be used inside a \macro{tikzpicture} environment. 

\begin{macrodef}pics\end{macrodef}
The PGF variant of the package provides the option \macro{pics}. If the package is loaded with this option, every icon is also available as Ti\emph{k}Z pic. On the use of pics, see section \ref{sec:pics} below.

\subsection{Icon commands}

\begin{macrodef}
|\rpgiconsdie|[<style>]{<shape>}[<options>]{<integer>}
|\rpgiconsability|[<style>]{<shape>}[<options>]
|\rpgiconssaving|[<style>]{<shape>}[<options>]
|\rpgiconsspell|{<shape>}[<options>]
|\rpgiconsspellschool|[<style>]{<shape>}[<options>]
|\rpgiconsdamage|{<shape>}[<options>]
|\rpgiconsattack|{<shape>}[<options>]
|\rpgiconscondition|{<shape>}[<options>]
\end{macrodef}
The PGF variant of the package defines a set of commands on which the user commands \macro{\die}, \macro{\ability}, \macro{\saving}, \macro{\spell}, \macro{\spellschool}, \macro{\damage}, \macro{\attack} and \macro{\condition} are based. This set of commands can be used in cases where another package defines one of these user commands. These user commands are exact copies of this set of commands.

\subsection{Icon styles}

Using the PGF variant of the package, all icons can by styled using arbitrary Ti\emph{k}Z styles in general. As an example, \macro{\die{eightside}[blue, thick]{2}} results in \die{eightside}[blue, thick]{2}.

\begin{macrodef}
!rpg icons/!every die
!rpg icons/!every ability
!rpg icons/!every saving
!rpg icons/!every spell
!rpg icons/!every spellschool
!rpg icons/!every damage
!rpg icons/!every attack
!rpg icons/!every condition
!rpg icons/!every <shape>
\end{macrodef}
Using Ti\emph{k}Z styles, all instances of a certain command or a certain shape can be styled at once. These styles all follow the pattern \macro{rpg icons/every} followed by a space and the name of the command or the shape. For example, \macro{\tikzset{rpg icons/every die/.append style={red}}} can be used to draw in red all icons created using the \macro{\die} command. To draw every instace of the \macro{charisma} shape in red, \macro{\tikzset{rpg icons/every charisma/.append style={red}}} can be used.

\subsection{Setting styles lobally}

\begin{macrodef}rpg icons\end{macrodef}
All icons share the Ti\emph{k}Z style \macro{rpg icons} that has no options per default but can be used to style all icons at once. For example, if \macro{\tikzset{rpg icons/.append style={draw=red}}} is placed at the beginning of the document, all icons will be drawn in red. Per default, the icons are drawn in the color of the surrounding text. 

Note that it may be necessary to add the Ti\emph{k}Z option \macro{transform shape} when applying transformations to the icons, because the icons are realised as Ti\emph{k}Z nodes which are not affected by some transformations per default.

\begin{macrodef}!rpg icons/!background color\end{macrodef}
Some icons can be used with a negative color scheme where the icon is drawn negatively inside a filled shape. Per default, the icons are drawn in white in such cases, but it might be desirable that the icons are in the same color as the background. To this end, the color can be changed using the Ti\emph{k}Z option \macro{rpg icons/background color} in the following way:

\begin{codeexample}
\colorbox{blue!50}{%
    \ability[negative]{charisma}
        [scale=2, transform shape]%
}

\tikzset{
    rpg icons/background color={blue!50}
}
\colorbox{blue!50}{%
    \ability[negative]{charisma}
        [scale=2, transform shape]%
}
\end{codeexample}
This feature can, of course, also be used to change the color of the icon independently from the color of the background.

\begin{macrodef}
!rpg icons/!before sep
!rpg icons/!after sep
!rpg icons/!baseline
\end{macrodef}
The Ti\emph{k}Z options \macro{rpg icons/before sep} and \macro{rpg icons/after sep} are used to define the width of the space that is added before and after the icons respectively. The default value of both lengths is 0.05\,em. For example, setting the space before icons to 1\,cm can be achieved as follows:

\begin{codeexample}
Roll\die{eightside}{}a die!

\tikzset{
    rpg icons/before sep={1cm}
}
Roll\die{eightside}{}a die!
\end{codeexample}

The option \macro{baseline} can be used to adjust the baseline of the icons. A larger value for the baseline will shift the icon downwards relative to the baseline of the surrounding text. The default value of the baseline is \textminus 3.5\,pt.

\subsection{Direct use of shapes}

Because the icons are defined as Ti\emph{k}Z shapes, they can directly be applied to Ti\emph{k}Z nodes. However, the shapes don't have a shape border and no anchors except for the \macro{center} anchor that sits exactly in the center of the shape. Therefore, if nodes with these shapes are connected using edges, the \macro{center} anchor will be used to connect the nodes. If nodes with these shapes are being positioned, only the \macro{center} anchor is available. Text content of these nodes is simply printed on top of the center of the node. Compare the following example.

\begin{codeexample}
\begin{tikzpicture}
    \node[eightside, blue, thick] 
        at (0,0) (A) {A};
    \node[charisma] at (2,0) (B) {B};
    \draw[red] (A) -- (B);
\end{tikzpicture}
\end{codeexample}

\subsection{Boxing of icons}

Because the icons cannot simply be used inside \macro{tikzpicture} environments, the PGF variant of the package provides a workaround to place icons inside of boxes for later use. Icons that are boxed this way can safely used inside \macro{tikzpicture} environments. This might be necessary, if an icon should be used in inline text that sits inside a node.

\begin{macrodef}|\provideprotectedrpgicon|{<command>}[<style>]{<shape>}[<options>]{<box name>}\end{macrodef}
The command \macro{\provideprotectedrpgicon} creates a box containing the icon that would be created using one of the regular commands this package provides. 

\macro{\provideprotectedrpgicon{die}[large]{eightside}[blue, thick]{mybox}}, for example, stores the icon of an eight-sided die with the relevant style and Ti\emph{k}Z options in a new box named \macro{mybox}. Note that no integer can be added to the \macro{die} command in this context.

\provideprotectedrpgicon{die}[large]{eightside}[blue, thick]{mybox}

\begin{macrodef}|\useprotectedrpgicon|{<box name>}\end{macrodef}
Using the command \macro{\useprotectedrpgicon}, the previously defined box can be used to place the relevant icon. With the above definition, \macro{\useprotectedrpgicon{mybox}} would result in \useprotectedrpgicon{mybox}.

Having created a boxed icon, it is safe to use it, for example, inside a Ti\emph{k}Z node:

\begin{codeexample}
\begin{tikzpicture}
    \node[circle, draw, align=center] {
        \useprotectedrpgicon{mybox} \\ 
        Roll a die!
    };
\end{tikzpicture}
\end{codeexample}


\subsection{Icons as pics}\label{sec:pics}

If the PGF variant of the package is loaded with the option \macro{pics}, every icon is also available as Ti\emph{k}Z pic. The names of the pic always start with \macro{rpg icons} followed by a space and the name of the relevant icon (see the lists above). For abilities, savings, spellschools and damages, additional pics exists where the name has the suffixes \macro{ability}, \macro{saving}, \macro{spellschool}, and \macro{damage} respectively.

The icon is embedded as a node in the pic which has the name \macro{-node}. Thus, it is possible to name the pic and refer to the node inside. Due to the fact that the icon is a node, the option `transform shape` has to be used if transformations on the pic are to affect the node as well. It is easily possible to apply styles to the node using the Ti\emph{k}Z option \macro{every node} as shown in the following example.

\begin{codeexample}
\begin{tikzpicture}
    \pic[
        transform shape,
        scale=2, 
        fill=blue, 
        draw=red, 
        every node/.append style={
            white,
            thick
        }
    ] (p) {rpg icons charisma ability};
    \draw[red] (p-node) -- +(2,0);
\end{tikzpicture}
\end{codeexample}

\begin{macrodef}
!rpg icons/!create pic from shape
!rpg icons/!create pic from ability shape
!rpg icons/!create pic from saving shape 
!rpg icons/!create pic from spellschool shape
!rpg icons/!create pic from damage shape
!rpg icons/!create every style
\end{macrodef}
The PGF variant of the package defines five Ti\emph{k}Z keys that are used to create pics using the relevant node shapes. Another key is defined to create keys that can be used to style all instances of a command or shape. In normal circumstances, it is not necessary to use these keys. They are mentioned here only for reference. 

The following example shows how to create the drawing on the first page of this documentation using Ti\emph{k}Z pics. We need to call \macro{rpg icons/create pic from ability shape} for the shapes \macro{twentyside}, \macro{buff} and \macro{ranged}, because per default no pics are defined for these shapes in combination with ability. Note the use of \macro{\space} to ensure correct use of spaces in the pic name as spaces are gobbled after commands in TeX.

\begin{codeexample}
\tikzset{
    rpg icons/%
    create pic from ability shape/%
    .list={
        twentyside, 
        buff, 
        ranged
    },
    rpg icons/every ability/.style={
        ultra thick,
        draw=white,
        line join=round,
        line cap=round
    }
}

\begin{tikzpicture}[scale=4]
    \foreach \x/\c [count=\i] in {
        twentyside/264653, 
        charisma/287271, 
        armor/2a9d8f, 
        buff/e9c46a, 
        ranged/f4a261, 
        proficiency/e76f51
    } {
        \definecolor{color}{HTML}{\c}
        \pic[fill=color, transform shape] 
            at ({60*\i+10}:{0.33cm}) 
            {rpg icons \x\space ability};
    }
\end{tikzpicture}
\end{codeexample}

\subsection{Roll dice syntax}

\begin{macrodef}
|\roll|{<roll syntax>}
|\rpgiconsroll|{<roll syntax>}
\end{macrodef}
The \macro{\roll} macro can be used to quickly typeset dice rolls with the relevant icons using the established dice rolling syntax. This syntax consists of a sequence of dice and numbers concatenated by mathematical operators (plus, minus or times). Typically, the letter \macro{d} is used to denote a die with a certain number of sides. For example \macro{d6} denotes a six-sided die. A number can be added to specify the number of such dice that are rolled together. The letter to denote the die can be changed using the Ti\emph{k}Z style \macro{rpg icons/roll syntax}. 

For example, \macro{2d6 + 3d4 - 1} means ``roll two six-sided dice and three four-sided dice and subtract one from the result''. The command \macro{\roll{2d6 + 3d4 - 1}} results in \roll{2d6 + 3d4 - 1}.

The die notations \macro{d2}, \macro{d4}, \macro{d6}, \macro{d8}, \macro{d10}, \macro{d12}, \macro{d20} and \macro{d100} are defined. To denote a fudge die, \macro{dF} can be used. To denote that the lowest or highest die should be removed from the result, the letters \macro{L} and \macro{H} can be used. The syntax \macro{2d6 x 2} or \macro{2d6 * 2} can be used to denote several rolls with the same set of dice.

If the \macro{rpgicons} package is to be loaded together with some other package that defines the command \macro{\roll}, the command \macro{\rpgiconsroll} can be used. This alternative command is an exact copy of the \macro{\roll} command. 

\begin{macrodef}
!rpg icons/!roll syntax
\end{macrodef}
The Ti\emph{k}Z style \macro{rpg icons/roll syntax} can be used to change the character that denotes a die in the dice rolling syntax. Multiple characters can be given using a comma separated list. The default setting is \macro{d,D} which allows notations such as \macro{2d6} or \macro{2D6}. 

With \macro{\tikzset{rpg icons/roll syntax={w,W}}}, for example, notations such as \macro{2w6} or \macro{2W6} could be used. 

% =====

\printchanges

\end{document}

%% End of file `rpgicons-doc.tex`.