summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/rpgicons/rpgicons-doc.tex
blob: 72aad456a78615f07ba33541238737f3ce91ce9c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
% 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.2}
\def\rpgiconsfiledate{28 April 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}]
    {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.}

\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 veriant 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 installted, 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 veriant, 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 defintions 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 instace 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. 

\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`.