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

When you have Foo Sheets, you put

\begin{extractable}{Foo Sheets}
\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. The actual Foo Sheets you have in some directory, probably (game)/FooSheets; each is a complete .tex file itself that can print nicely. When you use the magic perl script packets on a character file, it will tickle some tex magic and end up getting a list of what Foo Sheets the character is supposed to have; it will look those up in the FooSheets directory and print one of each for the character, magically putting the character name in the corner. Because the extracting part produces a mere list of sheets, these are list-type extractables; they're not individualized per-character except for (usually) putting the name of the char they're printed for (to help packet-stuffing). When you have something like item cards, where the actual tex code in the charsheet is extracted and separately latex'd, you have tex-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 Pinksheets (some games have used these as "public greensheets of real-world knowledge," like the Magna Carta). List-type extractables don't have to be sheets, but almost always are. The base Template provides things like Bluesheets and Greensheets as list-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.

Create the new style for your thing in LaTeX/Styles. For Pinksheets, we'll make a pinksheet.sty very very similar to bluesheet.sty and greensheet.sty; we'll start with
```
\ProvidesPackage{pinksheet}  % let latex check that this is the desired package
\RequirePackage{sheets}      % base this on the "sheets" package (w no options)
\renewcommand\sheetname{Pinksheet}  % gets printed on sheet header
```
Because the sheets.sty package already sets up a nice format for sheets, we really don't have to do much more. The \sheetname macro is used by the header that sheets.sty defines to print the kind of sheet, so that it'll say things like "Happy Fun Game... Pinksheet". If you don't want character names appearing in the corner for pinksheets printed for character packets, do what whitesheet.sty does (blank out \docharnamehere). You could call \useicon to have Pinksheets use a non-default icon.

Do not \RequirePackage the "extractable" package; that is for tex-type extractables.

If you don't base it on sheets.sty, well, you can write whatever you want.... The funky header sheets.sty provides is from defining \sheetbanner and then having that called by \doname (which \name always calls after setting \me but which does nothing until you \renewcommand it). To have the character name automagically appear when you use the packets script, copy the definition of \docharnamehere from sheets.sty and insert \docharnamehere wherever the bottom right corner of the name should show up. (It'll be blank when there isn't a char name to put there.)

You can use \RequirePackage[inlineheaders]{sheets} to get "inline" (aka "run-in") headers for \section, \subsection, and \subsubsection. The default LaTeX/Central/rules.tex does this.
Create a directory where your things will live. If your new extractable is named "Foo Bar", the perl scripts will by default look for it in (game)/FooBar. You could use the optional .structure file to redirect that if you wish. We'll just use (game)/Pinksheets.

The perl scripts will also assume there's a DVI subdirectory to the new directory, in which the .dvi files for things ready to be printed for char packets go. You should create that subdir or have .structure redirect it (you can redirect FooBar/DVI to FooBar if you wish).
Create a template for GMs to use there. We'll make Pinksheets/template.tex and it will look a lot like Bluesheets/template.tex and Greensheets/template.tex:
```
\documentclass{game}
\usepackage{pinksheet}
\begin{document}
\name{ insert group macro identifier from Lists/pinksheets.tex here }
\end{document}
```
It's based on the game class as everything is, and it uses the pinksheet.sty package we just made.
What's this "Lists/pinksheets.tex" our template just mentioned? Well, you don't have to have a LaTeX/Lists/whatever.tex serving as a centralized list of whatevers, but for list-type extractables you almost certainly want to. (Tex-type extractables sometimes do.) There you will define a bunch of macros that will usually turn into the titles of the various pinksheets, so \name{\Pmagnacarta} will put "Magna Carta" in the header. You could just put \name{Magna Carta} directly if you don't want to use macros.

Let's assume you want the centralized list, so we create LaTeX/Lists/pinksheets.tex where we'll define \Pmagnacarta and \Pcommunistmanifesto and so on in terms of the Template-provided macro \listsheet. The \listsheet macro takes the sheet title and the name of the file where it is found, and usually just typesets the title---except that when the packets script is doing its thing, it tickles the magic in charextracts.sty so that \listsheet also writes out the filename to a list, which the script can then look at to tell which Pinksheets to print for the character. If we don't define pinksheet macros in terms of \listsheet, we'll have to either use \listsheet explicitly in character sheets (\extract{\listsheet... \Pmagna...}) or have the magic extraction fail.

\listsheet{magna-carta}{Magna Carta} says "Magna Carta" is the title of the sheet (to be typeset) and that it can be found in Pinksheets/magna-carta.tex (or actually, that .dvi for it will be found in Pinksheets/DVI/magna-carta.dvi). Usually those two things are all we want to set about a sheet, so we could define our pinksheet macros
```
\newdef\Pmagnacarta{\listsheet{magna-carta}{Magna Carta}}
\newdef\Pcommie{\listsheet{commie}{Communist Manifesto}}
```
in Lists/pinksheets.tex, but we can make that less ugly and more legible by first defining
```
\newdef\listpink[3]{\newdef#1{\listsheet{#2}{#3}}}
```
and then doing
```
\listpink{\Pmagnacarta}{magna-carta}{Magna Carta}
\listpink{\Pcommie}{commie}{Communist Manifesto}
```
much as Lists/bluesheets.tex and Lists/greensheets.tex do. Note that we'd define that \listpink right in Lists/pinksheets.tex, at the top; it's the same for anything that \input's pinksheets.tex, so as far as they're all concerned, all that matters is that \Pmagnacarta ends up being defined in terms of \listsheet.

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

You could potentially have a list-type extractable macro that takes an argument, though this is very rarely appropriate. Say we have a bunch of countries (France, Spain, England) and for each one we have a pinksheet on their history in Pinksheets/history-France.tex, history-Spain.tex, history-England.tex, and we want to name them all "History of France" etc. Instead of defining N macros for N countries, we could do
```
\newdef\Phistory[1]{\listsheet{history-#1}{History of #1}}
```
and then \Phistory{France} typesets "History of France" and looks for the file Pinksheets/history-France.tex. Note that since we wanted uppercase "France" in the title, we had to put it in the filename; you cannot use \lowercase{history-#1} to get around that, because whatever \listsheet sees as its first argument is used as the literal filename, so that would try to find the literal file Pinksheets/\lowercase{history-France}.tex and of course fail.

Put enough documentation and examples in your Lists/pinksheets.tex that your GMs can easily add more pinksheet macros; see Lists/bluesheets.tex and greensheets.tex.
The LaTeX/Styles/character.sty file has to know about the field, since it's responsible for the actual extraction step where the list gets made. The field definitions already there should make the format clear.
- \list@extract{Pinksheets}
  defines a new list-type extract field whose name is "Pinksheets".
- \input Lists/pinksheets.tex
  sucks up those macros we just talked about so that, for instance, each sheet can understand its own \name{\Pmagnacarta} and so that they can refer to each other.
If you want the macros available in other game documents, that don't use pinksheets.sty, just add the "\input Lists/pinksheets.tex" to their style file or to their .tex (e.g. you might want to refer to pinksheets in the rules). If you want them available in all game documents, put that in LaTeX/Styles/custom.sty in the trailing section meant for such general customizations. If you do that, take it out of character.sty, or else charsheets will try to define the pinksheet macros twice (once from custom.sty, once from character.sty) and break.

Add the extractable field to the Charsheets/template.tex file, with some dummy values from Lists/pinksheets.tex so the template will latex:

\begin{extractable}{Pinksheets}
\extract{ \Pmagnacarta }
\secret{ \Pcommie } % though why a by-defn-public Pinksheet is secret...
\end{extractable}

Add a line describing the new field type to the file bin/packets.config so that the perl scripts will know about it. Since this is a list-type extractable, the line will look like
```
 Pinksheets: list fillme -Zinlower 
```
which specifies
- Pinksheets -- the name of the field as give in \begin{extractable}{Pinksheets}, which is how it appears in the character sheet; any unique abbreviation of this ("pinks", "pin") will be understood by the perl scripts
- list -- this is a list-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

All done! But before you move on, put in some samples and test that they latex right by themselves, that they look right in charsheets, and that they work right with the packets script. Find troubles now, not when printing for packet handout. If you're not using sheets.sty as the base, this goes double.