Welcome to the additional documentation for tt
Jump ahead to the following areas:
What is tt and why should I use it?
tt is a command line utility that is meant to aid in the process of working with a course's latex documents. It provides a means for a centralized include directory and support for modes or versions of a document. It also centralizes the process of building, viewing, and installing documents to allow for a greater flexibility and a way to save you the trouble of actually traversing the filesystem as long as you know where it is you want to go. More specifically, the following are some of the features of tt:
The main use case of tt is to deal with a course's documents,
whether they be lectures, homeworks, projects, labs, or
something else entirely. The general idea is to create a
centralized repository such as /course/cs169/latex
where you will store all of the headers and footers for
documents. Then at the beginning of each document you can simply
include it. The idea behind this is that way if you would like
to make a change to how you're documents are presented, or you
have a lot of common macros that you like to use, they can be
present in all documents from one centralized place. This could
be most likened to a common #include file that stores macros in
a C program.
The goal of this tool, and several of the other MTA provided pieces of software / scripts is to provide a universal set such that once a TA learns how to use this software it will serve them well throughout their entire time TAing, regardless of what class they are TAing for.
The other benefits of tt come from features such as enforcing a specified umask, that way you don't have to worry about TAs forgetting to change their umask to something else by default. Furthermore, the design of tt is such that a course can wrap the script, hardcoding the course that is used and place it in their course's tabin directory.
A brief interlude about the history of tt. tt came about based on work by Aleks Bromfield creating a similar build system that utilized first a preprocessor for scheme macros and a multi phase generation of documents. Several of the ideas for how this works have come from his work. By default we are not compatible with documents modified under his system. This is because one of the goals was to make sure that the system used as much plain tex and latex as possible. It was also to centralize and universalize the system so that it would work with any course with minimal initial set up.
To begin using tt, the first step is to fill out the
configuration file. You should copy the configuration file, by
copying the current prototype from
/pro/tasupport/share/tt/tt.conf to the
config directory in your course directory, for
example, /course/cs017/config/. Please read
through the file carefully, it tries to give decent
documentation before each entry. If you find something is
lacking, let me know so I can improve it for the future. Please,
note, this only needs to be done once per course!
After that, there is an optional user configuration file that is
looked for in ~/.tt.user.conf. The base file can be
found at /pro/tasupport/share/tt/tt.user.conf.
That is all that is necessary to really set up tt and be ready to go. Many courses may find that they want to write a wrapper around tt, so that the course to find can be hardcoded in so TAs don't always have to enter it, otherwise they may want to consider appending /pro/tasupport/bin to their path in their sourcehooks.
Tell me everything about modes!
The first question that might come to mind is, what are modes?
Modes are designed to allow you to put sections of a document into a file that you may not want generated every time. An example of this is when trying to get the solutions to problems. With modes, you can type up the question in your tex file and then surround the solution section with a tag that says it is the solution. When you build or view the file normally, you will not see anything that you specified was in the solution. When you build for a specific version, you get what was there previously and then get everything in that version. Plus, you can specify multiple versions!
So how do I use these modes?
To use modes, you have to do two things. First, add the
following latex command to the document:
\input{mta-tmp-version}. Then there is a latex
macro you can use that is called \version.
\version takes two arguments, the first is what
mode to use, the second is the data that should be inside that
mode. As an example:
\version{sol}{ All the answers to this problem...
}
Then, when you build, view, install, etc. you must include the
-m flag. You can specify as many different modes
when you build as you like. The following are all examples:
tt cs167 build -m sol hw01
tt cs018 view -m sol -m extras -m more-modes
Okay, so what can't I do?
There is really one main thing that isn't possible, you can nest
multiple \version commands inside of one another.
Multiple instances of tt can run at a time, that's just fine. What isn't fine is having multiple people try to build or install the same document! I can't support that situation. Things shouldn't break horribly if you enter it, but it's not very reasonable. If you want to be able to support that, I would suggest using advisory locks and wrapping tt in your own script that calls into it.
Something broke or why can't tt do X?
Now, there are two categories of issues that things fall into, bugs, and RFEs. Let's talk about bugs. Bugs exist, if they didn't I'd be entirely surprised and confused. If you find one, first off, Don't Panic. What you need to do is contact me, rm@cs and the current mta (as I won't be it forever) and have the following information:
This means, that you should have a very simple way to reproduce this bug. Not, I ran these five different things in parallel, but a simple stream of operations. Thanks for taking the time to tell us about bugs, we do appreciate it, even if we grumble when we fix it.
Now we get to the trickier issues, RFEs - Requests for Enhancement. Now, when you want tt to be able to do something new, remember something important, the unix philosophy. There should be lots of small tools that do one thing well. While, tt, doesn't quite honor that, that will be greatly enforced. Please check to make sure that what you are asking for isn't already solved, the last thing we want to do is spend time reinventing the wheel. Now when you are ready to contact us, contact either me, rm@cs or the current mta tech at mta@cs. You must include these pieces of information, or your request will not be dealt with:
Now, the first one of those is the most important. Do not phrase the problem you are trying to solve as I'm trying to solve the problem of tt recognizing my new cool thing. You should be able to phrase the problem that you are trying to solve without ever referring to tt. At this point, the mta tech will work with you to figure out if using tt is the right way. Then provide an idea for the second question. Don't worry if you don't have an idea, that's fine. We just ask for these questions because we all can fail to see that there is a simpler solution right around the corner.
Please don't be scared by this bit about RFEs, we do want to hear about them, we just want to ensure that they make sense and are worth solving before we put a lot of time into it. We're friendly people, we don't bite.
Can I get the source? Can I submit patches?
Of course you can get the source. tt is technically distributed under the GPL v2. If you're in the department, you can find it in /pro/tasupport/src/tt. If you're not, feel free to contact me with user name rm at the domain cs.brown.edu.