Producing Character Packets

# Producing Character Packets (All GMs)

This is the magic that lets you print out an entire character packet from the character sheet, using what you wrote there in the `\begin{extractable} ... \end{extractable}` lists. To print out a single specific sheet or card see printing-misc.html instead. During runtime, you may wish to do that even when replacing items from character packets.

Note that statcards and badges are not printed as part of character packets, because there's usually one one of each per packet and that'd be a lot of cardstock (and printing time) wasted with one-card-per-page. Those are printed from centralized files.

If you haven't already, set up your dotfiles properly. Each GM needs to do so, but only once.

## Preliminaries (preferably by Czar)

The Czar should have kept the `bin/packets.config` file up-to-date in terms of extractable fields if you've added or punted any. Check this before production starts.

The Czar should run the `preliminary` script:
`gmX preliminary [options] [fields]`
which will look in packets.config to see what the list-type extractables are, go into the DVI subdir for each (subject to .structure). For each foo.tex it sees above it, it will latex it and/or xdvi DVI/foo.dvi. (Skipping dotfiles (which aren't latex-able and are probably emacs lockfiles or something) and "template.tex".) This lets you ensure that you have up-to-date DVI/foo.dvi for each list-type foo. Those are where packets' bluesheets etc will be printed from.

(Q: Why the Czar?
A: Not because `preliminary` is complex, but because if multiple GMs run it, or someone runs it while someone else is still editing sheets, you could screw yourselves up. Singling out the Czar just makes someone responsible for checking safety first. Have other GMs run it if you're sure you're ok.)

(Q: Why don't we only latex the foo.tex that have changed more recently than DVI/foo.dvi?
A: Because that isn't enough to know it's up-to-date. If anything has changed in Lists/characters.tex, or Lists/players.tex, or Styles/custom.sty, or LaTeX/Numbers/*-assigned.tex, or any of lots of other places, any .dvi could be stale without seeming so. Since you can't trace the input path without running latex anyway, there's no Makefile-like way of doing this.)

Here are `preliminary`'s options. Order of options (and list-type fields, for that matter) is completely irrelevant, which can be handy for doing "... -l" (return)(up arrow) "... -x" (return). Single-character options may be bundled (`-abc` is the same as `-a -b -c`). Unique option abbreviations are understood.

`--help, -h`
  Print usage message and exit.
`--config=configfile`
  Use configfile instead of bin/packets.config, e.g. `--config=bin/joe.config` (this is rarely needful).
`--latex, -l`
  Latex each .tex found (into the DVI subdir) for each field to be done.
`--xdvi, -x`
  For each .tex found in the source dir, xdvi the associated .dvi in the DVI subdir. (Random .dvi there are ignored.) If both this and `--latex` are specified, this one always happens second, to preview what you just did.
`--only`
  Do only the list-type extractable fields specified on the command line, instead of all of them. This is the default if you specify any command-line fields.
`--except`
  Do all the list-type extractable fields except those specified on the command line. This is the default if you don't specify any, i.e. by default it does all of them.

Typical usages (remembering that gmX groks script abbreviations):
`gmX pre -lx`
`gmX pre bl gr -l`
`gmX pre -x --except bl gr`

## Packets

This part is per-GM instructions.

If you're actually printing things (not just previewing), check the printers and printer options (mostly for tray selection) in `bin/packets.config`. If you don't like the settings (e.g. if things point to nonexistent printers), either change them (best for the Czar to do this if they're around) or copy the file to one of your own to edit:
`cp packets.config joe.config`
so that GM Joe can print in one cluster while everyone else uses another.

Now run the `packets` script:
`gmX packets [options] [charfiles] [--only|--except fields]`

charfiles is a list of one or more Charsheets files, with or without their .tex suffixes, for whom to do packets. Note the `--all-characters, -a` option below to easily say "all".

By default all extractable fields, including the pseudo-extractable "Charsheets", are dealt with; `--only (field list)` restricts to those, while `--except (field list)` does all but those. As always, unique abbrevs are ok, e.g. `--except blue char` to punt bluesheets and charsheets.

Before we list the options, some typical usages (using gmX's willingness to take abbreviated script names):

    gmX pac fred --except mem -e (return, up arrow, edit:)
    gmX pac fred --except mem -lx (return, up arrow, edit:)
    gmX pac fred --except mem -dg (return, up arrow, edit:)
    gmX pac fred --except mem -p

    gmX pac alice bob --only item money --print

    gmX pac --all-characters --extract --latex --xdvi --dvips --gv --print
    gmX pac -aelxdgp

In the first example, we do fred's packet (based on Charsheets/fred.tex), except for memory packets, one stage at a time (extract; latex & xdvi preview; dvips & gv preview; print). In the second, we print both alice's and bob's items and money, assuming we've already taken actions to generate the ps. In the last, which we do with both the long and short option forms, we do everything at once: for all characters (-a), extract their stuff (-e), latex it (-l), preview that (-x), dvips everything including their list-type stuff (-d), preview that (-g), and print (-p). (We'll damn well look at those previews carefully before going on to print since we're not that overconfident, right? Though with the -g there we could skip the -x part.)

`--except, --only` mark the change from non-options being charfiles to non-options being extract fields. Other than that, options can be specified at any point on the command line. Again, their single-character versions can be bundled; `-abc` is equivalent to `-a -b -c` (be careful doing that with those that take an argument, though, or -a will eat "b") and unique option abbreviations are understood.

Actions always occur in their natural order (extract, latex, xdvi, dvips, gv, print) regardless of order specified, though only those specified will occur at all.

By default actions take place in a temp directory as provided by gmX so as not to cause quota problems, so you won't see anything appear in $GAME/Charsheets/{Extracts, DVI, PS}. See `--ingame` below to change that. (You can look at the temp-dir results; a Charsheets/ tree is created there mirroring $GAME/Charsheets.)

`--help, -h`
  Print usage message and exit.
`--config=configfile`
  Use configfile instead of bin/packets.config, e.g. `--config=bin/joe.config` so you can (for instance) use a different set of printers than everyone else.
`--all-characters, -a`
  Instead of specifying the charfiles list, do all the .tex files in Charsheets/, punting "template.tex" (Template sample file) and dotfiles (can't be latex'd anyway; likely emacs lockfiles or something).
`--extract, -e`
  Extract from the charsheets all information about their tex-type and list-type extractables, plus their names. Because this involves latex'ing the charsheet while tickling charextracts.sty magic, `--only` and `--except` are irrelevant to this stage.
`--latex, -l`
  Latex the tex-type extracts made by `--extract`. (The `preliminary` script is used to pre-latex the list-type material, and `--extract` already had to latex the charsheet.)
`--xdvi, -x`
  Preview with xdvi the .dvi results of `--extract` and `--latex`, i.e. the charsheet and tex-type extracts. Note that things like cards often don't show up properly in xdvi. If `--dvips` was also specified, you will be asked after the xdvis whether to abort, in case the preview showed problems you need to fix.
`--dvips, -d`
  Dvips (dvi-to-postscript) the charsheet, tex-type extracts, and list-type extracts, arranging for the latter to be labelled with the character name (and possibly "SECRET") as appropriate.
`--gv, -g`
  Preview with gv (sipb locker) the .ps results of `--dvips`; unlike xdvi, this ought to show you exactly what will be printed. If `--print` was also specified, you will be asked after the gvs whether to abort, in case the preview showed problems you need to fix.
`--print, -p`
  - Prints the .ps results of `--dvips` as per the printing specifications in the config file (bin/packets.config if you didn't specify an alternate with `--config`). Please preview with `--gv` first, and make sure you've put colored paper, cardstock, etc where it belongs and white paper in all the printers' other trays (so other people don't print on your cardstock).
  - Caveat: The new HP5 printers have a bug such that they do not always obey tray instructions. Until Athena puts in a workaround (which may have happened when you read this) you may or may not get the tray you ask for, regardless of the method you use to select it (passing -Zinlower or -Zinupper to lpr from the config file, dvips -h bottomtray manually, etc). Double-sided vs single-sided printing should be reliable.
  - Your material will be parcelled out to the printers such that you get a fair share of printer priority but don't flood the printer queues, because we don't want to violate the Athena Rules of Use, abuse the printers, and get Athena Ops pissed at the Guild. However, it will happily flood for printers it thinks are the Guild's.
  - Packet contents should print in perfect order, but may not; as of this version I don't know why and suspect a possible lprng issue---see the external issues documentation for current status.
  - The postscript files are called things like `mageking^Abilities.ps, mageking^Greensheets:destroyworld.ps` based on your .tex filenames. Since it would be Bad for those names to show up in the world-viewable printer queues ("look! one of the kings is secretly a mage! and he knows how to destroy the world!") the jobs are printed with names like `54321-7.ps` where "54321" is unique to this run of `packets` (it's the pid) and that's the 7th thing lpr'd. But since you want to look at `lpq` and know what the hell that is so you can `lprm` it 'cause you didn't mean to print it, the file `Q-yourusername-54321` is created in Charsheets with the queue mapping. If `packets` exits normally (after all printing is done) this file is removed; meanwhile, you can look at it.
`--ingame[=mode], -i[mode]`
  Highly optional.
  - `--ingame, -i` by itself causes all actions to both read from and write to the $GAME/Charsheets/* subdirs (where other GMs can look at them and where they won't vanish at logout) instead of the gmX-provided temp dir.
  - `--ingame=w, -iw` will read from the temp dir for its first action (unless that's `--extract`, which has to read from $GAME/Charsheets), but will write from that to the ingame dirs, from which subsquent actions will read. That is, if you previously ran, say, `-el` but not `--ingame`, you have extracted and latex'd stuff in the temp dirs; `-iw -xdg` would read the temp .dvi, show it to you (-x), dvips it (-d) to the ingame Charsheets/PS, and gv that (-g) from there.
  - `--ingame=r, -ir` is the inverse of "w"; it will read from the ingame dirs for its first action (which only makes a difference if that's not `--extract`), write the results to the temp dir, then stay entirely in the temp for subsequent actions. That is, if you did `-eli`, you can `-d -ir` to get from the ingame dvi to temp-dir ps.
  Since `-i` can take an argument, we recommend not bundling it; "`-alxi`" works, as does "`-alxiw`", but "`-ialx`" is "`-ia -l -x`" which is wrong.
`--only`
  As explained previously; do only the extractable fields given, except at `--extract` time.
`--except`
  As explained previously; do all extractable fields except those given, except at `--extract` time.

### Email Parts

For these you probably want to do everything except `--print`, and then take the postscript to mail (or to turn to pdf and mail, or put on the Web, or whatever). You may well want to deposit the postscript ingame, e.g.
`gmX pac emailone emailtwo emailthree -el`
`gmX pac emailone emailtwo emailthree -iw -dg`

Postscript from dvips gets comments put in it about the filenames involved. Since those can give away game information, this is a Bad Thing, so you wouldn't normally want to send game postscript to your players. The packets script pulls some tricks to avoid meaningful comments showing up, so it should be safe. If you dvips things by hand, you may want to edit out indiscreet comments by hand (open in emacs, search for %, zot things that look bad. Don't tamper with the leading %!PS or it'll cease to be a postscript file).