How can I balance uniformity of style files against modularity?

Question

I'm using Windows/TeXworks/MiKTeX, and I would like to have one style file I can use anywhere in any document in my top-level folder. If I want to add a new command or renew an old one, I'd like that to be available in all documents recursively contained in my top-level folder. I have a very hierarchical structure to my top-level folder. So this would seem to point to having a single file that TeXworks knows about. Could I add a path in Preferences -> Typesetting -> Paths for TeX and related programs? I've tried that, possibly superficially, without any success. Adding the correct folder to the Windows PATH variable doesn't seem to do the trick, either.

On the other hand, suppose I want to send someone a TeX file? It would be nice in such circumstances to be able to have the style file in the same folder as the TeX file. If I do that, how could I ensure that it's always up-to-date? Is there a script available somewhere that could take my master style file and push it down to all pre-existing lower-level locations?

Just to reiterate: I want uniformity of my style files in my very hierarchical folder structure. However, I would also like modularity, in that each folder is self-contained. How can I achieve that?

Also, out of curiosity, since I may acquire a Linux computer soon, how would I do this in, say, *ubuntu with TeXlive?

Answer 1

If either of these two cases (or both) apply:---

1. [portability problems] examplestyle.sty = a file as described in the original question: namely, a personal .sty file generally available and used by several on-going projects (e.g., in TEXMFHOME or the less convenient place MikTeX likes to put it);
2. [long-term stability problems] use of packages that are under active development, and, more worrying, may not be backwards-compatible in the future (e.g., tabu).

---the helper programs bundledoc and arlatex solve your problems. arlatex is the easiest to use, and best for solving the modularity problems. bundledoc can also be used as a solution, and is better for long-term stability. Better yet, the two can be combined into a one-stop solution that solves all portability issues over the short- and long-term. I am, in fact, currently archiving my old projects now that I see its power in action. (+1 and then some for this question making me look into these programs more carefully!!)

Bundledoc

One solution is to use bundledoc when the project is complete and you don't want to worry about losing the 'current' defintions of examplestyle.sty

Here's how:

% Example projectfile.tex
\RequirePackage{snapshot}% <-- this *must* be used!
\documentclass{article}
\usepackage{examplestyle,lipsum}
\begin{document}
\lipsum
\end{document}

Run latex projectfile.tex (or lualatex, etc.). This creates in addition to your usual many files, a file called projectfile.dep, which will be then used to take a snapshot of (up to!) all the files used to create your .dvi or .pdf.

(The following are more GNU/Linux specific, but similar [though not identical] principles apply for a Windows/MikTeX setup. See the manpage: man bundledoc.)

To create a bundled archive, you can do something like:

bundledoc --config=texlive-unix.cfg --verbose projectfile.dep

(Compare the other config file, miktex.cfg.)

This should create a file called projectfile.tar.gz, which will contain everything from article.cls to your personal examplestyle.sty.

Note the useful options for including or excluding material:

--localonly # only includes files in the current .tex directory
--include=  # e.g., --include="*.bib" includes all .bib files, even if not used in the actual .tex file
--exclude=  # e.g., --exclude=.cfg excludes all .cfg files

Arlatex

Another (related) solution is to use arlatex. The purpose of this script is to archive ancillary files into a master .tex file. In other words, it allows you to embed a personal sty file into your project file, which allows for total modularity (e.g., the file can be sent to someone else with no worries that they might have an outdated version of your personal .sty) and the regular 'global' nature of having a .sty file installed system- or user-wide.

arlatex is simple to use (the following assumes bash, but the man page provides some hints for Windows too). Assuming examplestyle.sty is still installed at ~/texmf/tex/latex, and is needed for projectfile.tex, when you want to embed the .sty in projectfile.tex you can do (use better filenames, though):

arlatex --outfile=projectfile-with-examplestyle.tex --document=projectfile.tex $(kpsewhich examplefile.sty) projectfile.tex

This will create a new file with the (ridiculous) name projectfile-with-examplestyle.sty, which includes via the filecontents in the original projectfile.tex a filecontents environment that contains an exact copy of examplestyle.sty. This new file is otherwise identical to the original.

Arlatex + Bundledoc

Finally, arlatex and bundledoc were designed to be used together, so it is possible to combine the two and create an archived file make up of the arlatex superfile. Such a file should be compressed via gzip or better, however, because even a tiny .tex file that uses a package like fontspec will grow to be over 2 MB.

Here's one possible .cfg for using arlatex and bundledoc together. It assumes you've followed the earlier steps that got you to create a projectfile.dep. Call this file something like arlatex+bundledoc.cfg

# basic config file for use of arlatex + bundledoc
bundle: (arlatex --document=$BDBASE.tex $BDINPUTS | tar -cvf - $BDINPUTS | gzip --best > $BDBASE-all.tar.gz )
sink:   > /dev/null 2>&1
find:   kpsewhich -progname=latex $BDINPUTS

Then you use this config file in the same way as described above, but with arlatex+bundledoc.cfg as the .cfg file. This creates a file, in our case projectfile-all.tar.gz that uses filecontents to write all the used packages and the class itself(!) to a single archived folder. (It reduces the size from about 2 MB to 389 kB.) And you are now good to go, today or several years hence.