Setting up your dotfiles to use the Template

# Setting up your dotfiles to use the Template (All GMs)

These aren't the only possible ways you can do this setup; however, they'll work, and Template development is focused on doing it this way. If you have an Athena clue and grok what's going on here, you may want to vary things. There are explanations at the bottom for each non-self-explanatory part.

It's a very good idea to make sure your setup is working well ahead of time -- if you run into trouble, get your Production Czar to help you iron it out now, not an hour before packet handout!

## Lockers

You should not have

    add -f newtex

in your ~/.environment nor any of your other dotfiles. If you do, get rid of it!

## The gm script

Put a fresh, virgin copy of the `bin/gm` script from the published Template in your homedir:

    cp ~jemorris/Template/Template/bin/gm ~/gm

## Aliases

These go wherever you put your aliases; if you don't know otherwise, that'll be `~/.cshrc.mine` (if you don't have one, create it). (Each alias should be on a single line; to have it on multiple lines in your dotfile, you could backslash each internal newline.)

    alias dogame 'setenv TEXINPUTS .:$GAME/LaTeX//: ;
                  setenv DVIPSHEADERS $GAME/LaTeX/Postscript: ;
                  cd $GAME'

(The trailing colons are important.) Then for each game you start working on, add aliases like these:

    alias terror 'setenv GAME /mit/assassin/games/Terror; dogame'
    alias gmter '~/gm --game=/mit/assassin/games/Terror'

    alias buffy 'setenv GAME /mit/assassin/games/Buffy/Template; dogame'
    alias gmbuf '~/gm --game=/mit/assassin/games/Buffy/Template'

If you have customizations from versions of the Template older than 1.5, you probably have `shell_escape` set either in your dogame alias (if you have one) or directly in your dotfiles. This is not necessary for Template v1.5 and later, and we strongly recommend you get rid of it, as it can defeat some of the safety measures the Template otherwise now provides.

## Other TeX Environment Variables

If you have other TeX environment variables set from previous customizations, you may will to un-set them, as having them set to strange things may screw up the Template latex. In particular, TEXFONTS and TEXCONFIG have been known to do this. To see if you have any set,

    printenv | grep TEX

at the athena prompt. If you see any `TEXfoo=...` other than TEXINPUTS, consider getting rid of it. It's probably being set by a line in your dotfiles, most likely ~/.environment, where you can comment it out by putting a # in front of it.

Environment variables that change various memory limits on latex, like `pool_size.latex` or `hash_extra.latex`, are probably safe to leave in, although they're probably not necessary, the default limits having gotten larger.

## Activating Customizations

The most straightforward way to have your new dotfiles take effect is to log out and log back in; why don't you do that now, unless you know enough to do faster ways.

## Explanations

The newtex locker used to have spiffier latex packages than the Athena defaults, and earlier versions of the Template relied on it for this. Since then Athena's latex has advanced considerably while newtex has stood still. It is now far behind, and SIPB may do away with it altogether at some point. As of v1.6 the Template relies on the tetex distribution, which Athena now has built in, and which you won't get if you `add -f newtex` because the -f gives newtex priority.

The sample aliases have a GM working on both Buffy (which put its Template tree in a "Template" dir on its top level) and Terror (which put the Template's top level directly on its own top level). To do some work on Terror, you type "terror" at the athena prompt; this sets your GAME environment variable to the Terror Template area and executes dogame. That in turn sets TEXINPUTS to look for latex stuff in the game's LaTeX subdirectory (recursively, because of the trailing double slash) after looking wherever you happen to be at the time (the preceding . entry) but before looking at the default places (the trailing blank entry). Similarly, DVIPSHEADERS is set to read header files for dvips from the game's LaTeX/Postscript directory before the default locations (dvips looks in . whether it's in the env var or not). So you're set up to use Terror's styles and customizations instead of Buffy's.

To remind yourself what game any given xterm is in, type "printenv GAME" there. It'll be blank if you're not in any. Different xterms can be doing different games (there's no way to reset them all at once).

That's not all that $GAME does; the Perl scripts can look at it to know where to find the game material they're looking on, and in particular `gm` does this. The `--game` option tells `gm` what $GAME it ought to be working in; if it's wrong, it'll stop. That means that when you're working on Terror, you use your `gmter` alias to run things, and if you go and do this in an xterm where you're actually working on Buffy ($GAME set to the Buffy dirs) it'll tell you and punt instead of screwing up the Buffy stuff with Terror stuff or vice versa. When you mean to be working on Buffy, you use your `gmbuf` alias.

You should read at least the first part of gm.html about how to use these aliases, and check that you can successfully run something (doc, say) with it.