Directory Structure Rearrangement

# Directory Structure Rearrangement (Czar)

This is one of the most incredibly optional options in the Template.

The Template's perl scripts look in various directories to read and write things. In older versions of the Template you had to have a config file in bin/ to define the important paths. Since that was almost never used, we've now given all the paths consistent defaults, but to preserve the power to reconfigure if you want, we've added support for a $GAME/.structure file. You'll probably be happy just letting everything default, in which case you can forget all this.

To redirect where the perl scripts look, create a file called ".structure" at the top level of your directory tree (i.e. $GAME/.structure). The Template ships without such a file. It should look like

    % Everything from a % to end-of-line is a comment.

    % Our Foo Bar Sheets.
    FooBarSheets            foobar

    % Charsheets and its subdirs
    Charsheets              Char
    Charsheets/Extracts     Extr  % except this one

    % ooo, our Czar writes docs in *lots* of formats.
    html      doc/html

Ignoring the comments, each line has exactly two strings on it. The first is the default directory name; the second is where to map that. (Trailing slashes on either are optional.)

Here, anything that would normally be sought/written in $GAME/FooBarSheets/ will be in $GAME/foobar/ instead---$GAME/FooBarSheets/ is the default location for an extractable listed in bin/packets.config as "`Foo Bar Sheets: ...`" and put in sheets with "`\begin{extractable}{Foo Bar Sheets}`".

$GAME/Charsheets/ (which is where charsheets are expected, if you name the "char"-type extractable that in bin/packets.config as usual) is redirected to $GAME/Char/. This by itself also means that $GAME/Charsheets/DVI/ is redirected to $GAME/Char/DVI/, $GAME/Charsheets/Extracts/ to $GAME/Char/Extracts/, etc. However, since we also gave an explicit redirect for $GAME/Charsheets/Extracts/ to $GAME/Extr, that takes precedence for that subdir. The order redirects are given does not matter; the most specific one that matches is used. So $GAME/Charsheets/Extracts/Foo/ would be found in $GAME/Extr/Foo/.

You should only redirect directories; having entries for plain files will have undefined results. Redirection cannot take paths out of the $GAME directory tree.

The $GAME/.structure file, if it exists, is read by gmX, which does path interpretation with it for everything it wraps. (Meaning any script that runs under gmX doesn't have to worry about path redirection; the gmX functions it calls will handle that automatically.) Since gmX should be an alias to ~/gm with args, running it does not depend on any game directories; this means that nothing of the directory structure is nailed down as far as the perl scripts are concerned---you could redirect bin/ if you want, and gmX will look for things to run from the new location.

## Restructuring and Latex

The .structure file only affects the perl scripts. Your TEXINPUTS and DVIPSHEADERS environment variables control where latex looks for things (usually LaTeX/ and all its subdirs recursively) and where dvips looks for header files (usually LaTeX/Postscript/).

Files in LaTeX/Lists are usually \input as "Lists/foo.tex" so as not to slurp the wrong file if you have a foo.tex elsewhere. The Template's other \input's are just by base filename. So if you feel the urge to rearrange subdirs within LaTeX/, your only latex worry would be if you moved LaTeX/Lists/ to LaTeX/Bar/, in which case you'd have to find the "\input Lists/foo.tex" lines and change them to "\input Bar/foo.tex".

Dvips header searching isn't recursive, so if you want headers somewhere other than LaTeX/Postscript/, you'll have to have everyone change their dotfiles to fix DVIPSHEADERS, probably with

    alias spygame 'setenv GAME /mit/assassin/games/SpyGame; dogame;
                   setenv DVIPSHEADERS $GAME/psstuff'

assuming they have the dogame alias and things based on it as recommended in dotfiles.html.

Similarly, if you want latex to read things from somewhere in $GAME that's not in the $GAME/LaTeX/ subtree, you'll have to have everyone alter their TEXINPUTS.

You are strongly encouraged to stick to directory structures that don't require screwing with the environment variables. It's almost certainly gratuituous and is extra annoyance for everyone. If you do it and screw it up, we reserve the right to just laugh at you.