Adding New TeX-Type Extractables for Character Sheets (Czar)

When you have Foo Cards, you put

\begin{extractable}{Foo Cards}
\extract{ \Fone }
\extract{ \Ftwo }
...
\end{extractable}

in a character sheet file. Then you expect that latex'ing the character sheet itself will typeset a list "Foo One, Foo Two, ..." so that the player knows what should be in their packet. When you use the magic perl script packets on the character file, it will cause the actual latex code in the extractable list into a new file and latex it such that it produces actual Foo Cards. Because the extracting part produces actual latex, these are tex-type extractables. (They might also be made in non-character-packet batches, as with LaTeX/Central/misc-items.tex and friends.) When you have something like bluesheets, whose latex is all pre-written somewhere, the perl just wants to look up where to find the bluesheet, based on what the charsheet says, and print a copy of it; those are list-type extractables.

The Production Czar should find creating new extractable types straightforward. However, do it well ahead of time, not the day before packet handout! For one thing, you'll want time to fiddle around with it. For another, if you do it early, you can put an appropriate section in your charsheet template; if you do it late, you'll have to add it to all those charsheets you wrote already. But mostly, you want to be sure it all works while there's still time to fix it and to get help.

Our example here will be a simple Seduction Card. The base Template provides items and abilities (and maybe other things) as tex-type extractables. As you read through here, use the relevant files for those as further examples.

You can name the extractable field with any not already taken string of letters (either case), numbers, and spaces; it's probably not a good idea to use anything else, in case it has special meaning to latex or perl.

Every tex-type extractable has its own core macro that "does" the extractable. Abilities have \ability, items have \specialitem, combat cards have \combatcard. There might be others built on it (\normalitem and \bulkyitem are built on \specialitem) but it's best to have a single base. This macro can be called whatever you want; we'll use \seduction.

Decide what information this macro will need; what differentiates seductions? Ours will have an attack type, an attack rating, and a gratuituous picture, so it will be called like
```
\seduction{Romatic}{7}{rose.eps}
```
The LaTeX/Styles/character.sty file has to know about the field, since it's responsible for the actual tex extraction. The field definitions already there should make the format clear.
- \tex@extract{Seduction Cards}{\usepackage{seduction}}
  defines a new tex-type extract field whose name is "Seduction Cards" and whose extracted tex needs to do \usepackage{seduction} (which we'll get to in a moment) to process the cards correctly.
- \newdef\seduction[3]{Type #1 Rated #2}
  causes \seduction to, in charsheets, just typeset a description of the attack -- we don't want the pictures here.
- Later we'll get to the \input we may add to that section.
\newdef is a Template-provided safer version of \newcommand; they use the same syntax:
```
\newdef\newmacroname[numberofarguments]{text where #1 will be replaced 
by first arg, #2 by second, etc.}
```
where [number of arguments] can be omitted if it's zero. (If you \newdef it with no [number of arguments], it's just like \newcommand'ing it; if you \newdef with an explicit [0], the new macro will insist on being followed by braces, so that you'll never lose spaces using it.) See the macro glossary for \newdef's behavior.
The extracted material has to latex differently, since we want it to make actual cards. We make a new style package for this; just as items have LaTeX/Styles/items.sty and abilitities have abilities.sty, we'll make a seduction.sty, probably based on those. This is what the \usepackage{seduction} we used above calls. This will also define \seduction, with the same arguments, but it will expand it differently. A simplistic seduction.sty might look like
```
\ProvidesPackage{seduction}   % let latex to check that this is desired package
\RequirePackage{extractable}  % early line in any tex-type style package
\RequirePackage[single]{cards} % single-sided flavor of base cards package
\newdef\seduction[3]{\makecard{%   % make the card
  #1 #2                         % attack type and rating
  \includegraphics[width=1cm]{#3} % gratuitous picture
}}
```
\RequirePackage{extractable} should always be present early in a tex-type extractable's style file; you'll also want to have a \ProvidesPackage{mypackagename} first thing so that latex can check that it's getting the packages you want.

The character sheet has \usepackage{character}, so it gets the character.sty definition, so it typesets "Type Romantic Rated 7" from an \extract{ \seduction{Romantic}{7}{rose.eps} }. The packets script tickles the magic in charextracts.sty (used by character.sty) to have it create a separate file of seductions for the character, with the \usepackage{seduction} header that \tex@extract was told to use, and to put the contents of the \extract in that file, \seduction{Romantic}{7}{rose.eps}. The \usepackage{seduction} will there turn that into an actual Seduction Card (albeit an ugly one, since we defined \seduction hastily) with a rose on it.

See cards.html for details on how to create new cards. See mechanics-packet.sty for a base for some typical non-card setups; this is how memory packets and ingestibles work. Or you could do something more creative.

LaTeX/Central/misc-items.tex makes a batch of item cards that aren't in any character packet. You can do the same thing to make random seduction cards, with
```
\documentclass{game}
\usepackage{seduction}
```
so that it knows to make \seduction into cards.
This part is optional. While we can call \seduction directly in the character sheet and have everything work, we'll probably want to have some "standardized" seductions that more than one character has. For these we'll make a seductions.tex file in LaTeX/Lists/ in parallel to the items.tex and abilities.tex there. It will have lines like
```
\newdef\SEDromeo{\seduction{Romantic}{7}{rose.eps}}
\newdef\SEDflirt{\seduction{Suave}{6}{tuxedo.eps}}
```
to define standard seductions. The items.tex file actually starts by defining macros like \normalitem for convenience; it does them in terms of the core macro \specialitem, which character.sty and items.sty define as they wish. \seduction will be enough for seduction.

We have to tell character.sty and seduction.sty about this new file, or else they won't know about \SEDflirt etc. Adding
```
\input Lists/seductions.tex
```
to each of them (in seduction.sty, probably at the end; in character.sty, just after we define \seduction) accomplishes this.

Now when
```
\extract{ \SEDflirt }
```
appears in a charsheet, it expands to the definition Lists/seductions.tex gives it,
```
\extract{ \seduction{Suave}{6}{tuxedo.eps} }
```
which character.sty turns into "\extract{ Type Suave Rated 6" } for the character sheet and which seduction.sty turns into the appropriate card when extracted. (That's a bit misleading; actually the \extract macro expands before its contents do.)

If you wanted a range of flirts without having to define them separately, you can arrange for \SEDflirt to take an argument:
```
\newdef\SEDflirt[1]{\seduction{Suave}{#1}{tuxedo.eps}}
```
You now call it as \SEDflirt{5} to get "Type Suave Rated 5" in the character sheet. The [1] in the declaration said it would take one argument; the #1 then refers to that argument.

Put enough comments and examples in your centralized Lists/seductions.tex file for your team to know how to add entries.
add the extractable field to the Charsheets/template.tex file with some dummy values (perhaps macros defined in your centralized LaTeX/Lists/ file) and documentation:
```
% generic seductions defined in LaTeX/Lists/seductions.tex; make
% unique ones here with \seduction{type}{rating}{picture}
%
\begin{extractable}{Seduction Cards}
\extract{ \SEDflirt }
\extract{ \SEDjump }
\extract{ \seduction{Hypnotic}{4}{metronome.eps} }
\end{extractable}
```
In some cases, you'll want the template.tex Seduction Cards section to be entirely commented out, but it's still good to have it there so that the GMs can see it in every charfile.
Add a line describing this new field type to the file bin/packets.config so that the perl scripts will know about it. Since this is a tex-type extractable, the line will look like
```
 Seduction Cards: tex fillme -Zinlower 
```
which specifies
- Seduction Cards -- the name of the field as give in \begin{extractable}{Seduction Cards}, which is how it appears in the character sheet; any unique abbreviation of this ("seductioncards", "seduc", "sed") will be understood by the perl scripts
- tex -- this is a tex-type extractable
- fillme -- the printer to send to; obviously you will often change this when you're actually printing things
- -Zinlower -- options to print with, in this case "print from lower tray"; you will often change this for actual printing
Document your new macro in macro-glossary.html for your team.

All done! But before you move on, put in some samples and test that they look right in charsheets and that they work right with the packets script. Find troubles now, not when printing for packet handout.