$ git diff --color-words

followed by -S in the subsequent less pager.

Advanced features of LaTeX are best learned on a need to know basis. The LaTeX Companion can be daunting in its length. If you thought you needed to master all of that material before writing a LaTeX document you would never do so. So start simple, and learn how to do more advanced things as and when you need to.

Learn on a need to know basis, and when you do learn, hack. Don’t feel like you need to know whether the code will work before running it. The worst thing that will happen is that LaTeX will throw an error. LaTeX errors are instructive. Learn to love them.

These reflections arose today when I needed to do something which should have been simple. It was simple—once I learned how to do it. I was preparing a handout for my seminar. On the handout is a summary of the material that I presented on Cook Wilson and the nature of representation and notes on the ensuing discussion. It would be useful if these were visually distinguished.

My first thought was to use the color package. It has a command \colorbox that specifies the background color of a box. However, the results were suboptimal—small strips of white separate the colored lines. Disappointed, I thought, well, perhaps I can just color the relevant text with \textcolor. The discussion however could run for several paragraphs and it turns out that \textcolor chokes when it wraps multiple paragraphs. It was obvious to me, then, that there was no straightforward, out of the box, solution.

I decided to define a new environment, discussion:

\begin{discussion}
    
\end{discussion}

It requires the color package, and you need to define a color that will be used for the background. I used \definecolor{myblue}{rgb}{0.8,0.8,1}. (Readers of the wonderful Tikz Pgf manual will recognize this as the background color of the code blocks.) The strategy was simple—wrap a minipage in a box. The minipage environment defines, well, a small page:

\begin{minipage}[position]{width}
  
\end{minipage}

The minipage is wrapped in a box. Boxes are usually created by commands, but there is a box environment lrbox:

\begin{lrbox}{}
    
\end{lrbox}

The text within this environment is saved in the box <cmd>. Here is the discussion environment with all the bells and whistles.

\makeatletter\newenvironment{discussion}{%
   \noindent\begin{lrbox}{\@tempboxa}\begin{minipage}{\columnwidth}\setlength{\parindent}{1em}}{\end{minipage}\end{lrbox}%
   \colorbox{myblue}{\usebox{\@tempboxa}}
}\makeatother

Here’s the gist:

(Sorry for the duplication, but embedded gists are not showing up in some news readers.)

Two comments. The initial \noindent is required otherwise the entire box will be indented—which would be awkward since the width of the minipage is set to the width of the column. Another issue is that there is no paragraph indentation within the minipage environment. In effect, within that environment, LaTeX sets \parindent to 0. This, however, can be overridden with the \setlength command:

\setlength{\parindent}{1em}

Here is the result:

There are two ways to call SyncTeX, from the command line and in source. From the command line simply use the argument -synctex=1, and from source include \synctex=1 in the preamble. The former may be preferable if you want to distribute your LaTeX source—that way it will run without errors even by those whose TeX distributions do not include SyncTeX support.

Here is how synchronization worked with pdfsync. A word in your source is associated with a file name and a line number where it occurs. The file name and line number together constituted the input record. That same word as it occurs in the pdf generated from the source is associated with a page number and a location on that page. Together these constituted the output record. Synchronization was achieved by linking the input record with the output record. Moreover this was done by assigning each of these records with a unique tag. This was necessary since while the TeX engine will place a word in the source on some page in the generated pdf and on some location on that page, by the time it has done this, it has “forgotten” the file name and line number. Unique tags were thus required to preserve this information for synchronization. These tags were stored in special data nodes in every pargraph, math display, etc.

There were three problems, however, with this synchronization solution:

1. The data nodes used by pdfsync could interfere with TeX’s line breaking mechanism and thus affect the layout of the page.
2. pdfsync was incompatible with certain LaTeX packages. While some could be rewritten to accommodate pdfsync, others could not.
3. The mapping from the input record to the output record was not one-one, but one-many. So developers of pdf viewers supporting pdfsync had to choose the right mapping from the input record to the output record, and this was not always easy to do.

Instead of using special data notes, SyncTeX exploits kern nodes and glue nodes that are determined early on in TeX’s processing of the source to track the location of a word in the pdf output.

Another advantage of SyncTeX over pdfsync is that SyncTeX also supports dvi and xdv outputs (not that useful for me, but your situation may differ).

The TeXLive distribution, which MacTeX is built upon, is the first implementation of SyncTeX, and both PdfTeX and XeTeX in TeXLive now have SyncTeX support embedded deep within these TeX engines.

• Packages in TeX Live 2008 can be updated over the internet. This is a major advance in the distribution. See documentation about the TeX Live Manager for details, and read the tlmgr man page. Additional documentation for the Mac is forthcoming; see the final paragraph of the previous section.
• Donald Knuth updates the TeX once every five or six years, fixing bugs that have accumulated over that time. This is an update year; TeX now has version number 3.1415926.
• pdfTeX has been updated to version 3.1415926-1.40.9.
• XeTeX has been updated to version 3.1415926-2.2-0.999.6; by default the program now uses the xdvipdfmx driver.
• luaTeX is in TeX Live 2008; this is a beta release of a program intended to eventually replace pdftex. To use the program, call it using one of the following commands: luatex, pdfluatex, lualatex, pdflualatex.
• Jerome Laurens’ new SyncTeX is included. This software causes pdfTeX, pdfeTeX, and XeTeX to output a “synctex” file during typesetting containing information to synchronize the source input and pdf output of a TeX run. In modern TeX distributions, pdfeTeX is used for almost all typesetting, since LaTeX and other engines are symbolically linked to that program, so SyncTeX is available for most typesetting jobs.

I have been waiting for this, not least because I want to dump pdfsync in favor of SyncTeX. However, the link to the zip file gives the following error “unknown error” (NSURLErrorDomain:-1). :( Hopefully this will be fixed soon.

Update: The MacTeX link is now live. I am downloading it now. \o/

\section{A Section} 

\subsection{A Subsection}

\section{Another Section}

A lack of closing tags, however, is far from being structurally innocent. Suppose, instead, we had sections and subsections represented like LaTeX environments:

\begin{section}{A Section}
    \begin{subsection}{A Subsection}
        
    \end{subsection}
\end{section}

With closing tags, we could have text at the beginning of the parent section and at the close of the section that was not part of any subsection. Why would you want to do that? I am currently writing a paper and I decided to break a long section into two subsections—both for ease of reading and to reflect the emerging structure of the text. It made sense to have some introductory remarks and some closing remarks that were part of the section but not part of either subsections. With closing tags, this would have been simple and transparent:

\begin{section}{A Section}
    
    Some introductory remarks.
    
    \begin{subsection}{A Subsection}
        
        Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
        
    \end{subsection}
    
    \begin{subsection}{Another Subsection}
        
        Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
        
    \end{subsection}
    
    Some closing remarks.
    
\end{section}

However, without closing tags, there is no way to represent this logical structure. The introductory remarks at the beginning of the parent section were no problem. It was the closing remarks following the final subsection that posed the problem:

\section{A Section} 

Some introductory remarks

\subsection{A Subsection}

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

\subsection{Another Subsection}

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Some closing remarks.

Notice, the closing remarks are part of the second subsection. To deal with this I had to resort ot a visual hack:

\section{A Section} 

Some introductory remarks

\subsection{A Subsection}

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

\subsection{Another Subsection}

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\\

\noindent Some closing remarks.

\\ in effect introduces a blank line, and \noindent forces the paragraph to begin without indentation. In this way, I signalled that the closing remarks were part of the section and not the final subsection. It is a visual hack since I signalled the status of the closing remarks by the visual layout of the text. As far as LaTeX is concerned, however, the closing remarks are still part of the final subsection. Disheartening for someone enamoured of structural markup.

LaTeX3 is vaporware, and I have no evidence that this issue will even be addressed. I am unfamiliar with ConTeXt—an alternative macro language for TeX that is meant to be based on more uptodate ideas about structural markup. I would be curious to see if this issue arises in ConTeXt as well.

As I explained in an earlier post, it is useful to independently maintain any LaTeX preambles you may have in version control. Independently, that is, of your present LaTeX project. The rationale is simple. If you discover some heretofore overlooked need requiring a change to the preamble, it would be useful if this change were made available to any other LaTeX document that uses that preamble.

Here is how to do this with Git and Git submodules. (Something similar could be achieved with Subversion and Subversion externals.)

First, let’s create a Git repository for our LaTeX project:

~ $ mkdir myproject
~ $ cd !$
~/myproject $ touch mytex.tex
~/myproject $ git init
Initialized empty Git repository in /Users/markelikalderon/myproject/.git/
~/myproject $ git add .
~/myproject $ git commit -m "Initial commit"

mytex.tex is just an empty file so far. Here is the template LaTeX file that I am currently using:

%!TEX TS-program = xelatex 
%!TEX TS-options = -output-driver="xdvipdfmx -q -E"
%!TEX encoding = UTF-8 Unicode
%
%  my_title
%
%  Created by my_name on date.
%  Copyright (c) year. All rights reserved.
%

\documentclass[12pt]{article} 

% Definitions
\newcommand\mykeywords{} 
\newcommand\myauthor{} 
\newcommand\mytitle{}
\newcommand\mybib{}

\input{preamble/preamble}

%%% BEGIN DOCUMENT
\begin{document}

% Title Page
\maketitle
% \begin{abstract} % optional
% \end{abstract} 
\vskip 2em \hrule height 0.4pt \vskip 2em
% \epigraph{text of epigraph}{\textsc{author of epigraph}} % optional; make sure to uncomment \usepackage{epigraph}

% Layout Settings
\setlength{\parindent}{1em}

% Main Content



% Bibligography
\bibliographystyle{plainnat} 
\bibliography{\mybib} 

\end{document}

A couple of observations about this. First, I am assuming that the included preamble is called preamble.tex and is in a subdirectory called preamble. This is required since we will be keeping our preamble in a Git submodule, and submodules are always subdirectories of the superproject. Second, I have defined some commands, \mytitle, \myauthor, etc. Basically these are all the elements of the preamble that could change from one LaTeX project to another. (So, in the preamble, we have \title{\mytitle}.) This was done to generalize the preamble so it can remain constant from project to project. Also, with a template, it is useful to pull, in this way, all the bits you would need to fill in to the top of the document so that you don’t need to hunt through the code. Once you have added content to mytex.tex, you will, of course, need to commit these changes.

Next we want to push to a remote repository. I will assume that your remote repository is hosted by GitHub (they provide free accounts for publically availbale repositories). So create a repository, “myproject”, on GitHub and then:

~/myproject $ git remote add origin git@github.com:myname/myproject.com
~/myproject $ git push origin master

(where “myname” is your GitHub username).

Now for something mysterious, but it’s required for Git submodules to work. We are going to delete our local Git repository and clone the remote repository:

~/myproject $ cd ..
~ $ rm -rf myproject/
~ $ git clone git@github.com:myname/myproject.com

Now we are going to create a Git submodule. Your preamble, call it preamble.tex, needs to be in a git repository. For the sake of illustration, we will use the preamble I am hosting on GitHub:

% Packages
\usepackage{geometry} \geometry{a4paper} 
\usepackage{url}
\usepackage{pdfsync} 
\usepackage{txfonts}
\usepackage{color}
\definecolor{gray}{rgb}{0.459,0.438,0.471}
% \usepackage{setspace}
% \doublespace % Uncomment for doublespacing if necessary
% \usepackage{epigraph} % optional
 
% XeTeX
\usepackage[cm-default]{fontspec}
\usepackage{xltxtra,xunicode}
\defaultfontfeatures{Scale=MatchLowercase,Mapping=tex-text}
\setmainfont{Hoefler Text}
\setsansfont{Gill Sans}
\setmonofont{Inconsolata}
 
% Section Formatting
\usepackage[]{titlesec}
\titleformat{\section}[hang]{\fontsize{14}{14}\scshape}{\S{\thesection}}{.5em}{}{}
\titleformat{\subsection}[hang]{\fontsize{12}{12}\scshape}{\S{\thesubsection}}{.5em}{}{}
\titleformat{\subsubsection}[hang]{\fontsize{12}{12}\scshape}{\S{\thesubsubsection}}{.5em}{}{}
 
% Headers and Footers
\usepackage{fancyhdr}
\pagestyle{fancy}
\pagenumbering{arabic}
\lhead{\thepage}
\chead{}
\rhead{\itshape{\nouppercase{\leftmark}}}
 
% Bibliography
\usepackage[round]{natbib} 
 
% Title Information
\title{\mytitle} % For thanks comment this line and uncomment the line below
%\title{\mytitle\thanks{}}% 
\author{\myauthor} 
% \date{} % Leave blank for no date, comment out for most recent date
 
% PDF Stuff
\usepackage[plainpages=false, pdfpagelabels, bookmarksnumbered, backref, pdftitle={\mytitle}, pagebackref, pdfauthor={\myauthor}, pdfkeywords={\mykeywords}, xetex, dvipdfmx, colorlinks=true, citecolor=gray, linkcolor=gray, urlcolor=gray]{hyperref} 

Here is what we need to do to create the submodule:

~ $ cd myproject/
~/myproject $ git submodule add git://gist.github.com/835.git preamble
~/myproject $ git submodule init
~/myproject $ git submodule update

Now, if we want to make a change to our preamble and make it available to all our LaTeX projects that use that particular preamble, you need only commit these changes to the Git repository where your preamble lives.

For more information about git submodules, see this tutorial.

My reaction.

BryanL demos Gist: A Super Hot Pastebin from Bryan Liles on Vimeo.

In the spirit of sharing, I have posted my LaTeX preamble and associated files. Feel free to download or clone these files, or better yet, post your own!

It is useful to independently maintain any LaTeX preambles you may use. Suppose, for example, you discover some need and make a corresponding change to your preamble. You might want that change available to some of your other LaTeX documents. Next time I will explain how to do this with include statements and git submodules.

There’s syntax highlighting, a preview window, and it can export to html. The best feature is the document outline, which is a joy for editing large documents. Plus you can use TODO tags and these get picked up as tasks, and an emacs-style text formatting tool.

If IDEs are your thing and you are using Eclipse, you might want to check it out.

1. I use a text editor for a number of other tasks (including but not limited to keeping my calendar with Remind, keeping notes in Markdown, constructing to do lists…) and felt it would be counterproductive to proliferate editors when all of these tasks are text based.
2. Relatedly, as I was worked increasingly with text files, I found the need for advanced text editing features not found in TeXShop.

Still, I would unhesitantly recommend TeXShop to any one new to TeX on OS X, and many much more proficient TeXnicians than I use TeXShop on a daily basis.

There are dedicated LaTeX editors on other platforms, but none are configured the way TeXShop is. (The LaTeX editors available for Windows that I have seen makes me weep.) Jonathan Kew, the developer of XeTeX, hopes to correct this situation with TeXWorks:

The TeXworks project is an effort to build a simple TeX front-end program (working environment) that will be available for all today’s major desktop operating systems—in particular, MS Windows (XP and Vista), typical GNU/Linux distros and other X11-based systems, and Mac OS X. It is deliberately modeled on Dick Koch’s award-winning TeXShop for Mac OS X, which is credited with a resurgence of TeX usage on the Mac platform.

• New multi-tabbed interface similar to Safari. This makes switching between open files faster and more intuitive.
• Full screen editing now available. This allows you to focus just on editing your files without distraction from other applications.
• Aquamacs no longer creates backup files by default: less clutter in your files.
• Now uses standard “unified” toolbar, with improved icons, for greater ease-of-use.
• Improved LaTeX support.
• Numerous improvements in text search.
• Can check for program updates from the application menu.

The LaTeX improvements include the inclusion of AUCTeX 11.85, better error reporting and improved syntax highlighting, and improved icons. Aquamacs 1.4 can be downloaded here.

One useful thing that academics share, though less often than their research, is their bibliographies. LaTeX is predominant in academia, though not universally so. So many of these online bibliographies are BibTeX files. See Benj Hellie’s BibTeX file as an example.

Sometimes, these have been converted to HTML. Sometimes, as in Benj’s case, the author simply posts the text file (BibTeX is a flat file database kept in plain text). This has some limitations. One problem is that the author has to periodically export to HTML, and even if he is posting the text file, it still needs to be uploaded to the server. Unlikely that this is done after each change to the bibliography.

From the users side, there are problems too. Suppose I have downloaded Benj’s BibTeX file. Some time passes, and I want to take advantage of Benj’s hard work. Some of the entries I already have, some are new. Some of the new entries may overlap with entries that I have made independently. Manually merging this material can be a pain, even with diff tools.

All of this would be a lot easier if academics used distributed version control to share their bibliographies. Suppose the distributed version control system in question is Git. When an author makes a change to his bibliography, then all he need do is to commit the change and push to the remote repository:

$ git commit mybibtexfile.bib
$ git push

From the users side, to download the bibliography all he need do is clone the git repository:

$ git clone git@github.com:PhilGeek/bib.git

After that, fetching and merging new changes is easy as:

$ git pull

Well, I am putting my money where my mouth is and publishing my BibTeX file in an open Git repository hosted at GitHub—http://github.com/PhilGeek/bib/tree/master. To clone this repository:

$ git clone git@github.com:PhilGeek/bib.git

Even if you are not a Git user and are shy about adopting new technology, the file can be viewed and downloaded here.

There is not as much in it as there should be. Before becoming a plain text Geek, I kept my bibliography in EndNote. Unfortunately, my EndNote file, a proprietary binary format, became corrupted before I could convert it to BibTeX. Yet another cautionary tale speaking in favor of the Power of Plain Text.

Donald Knuth, creator of TeX, describes his workflow for writing in an interview:

My general working style is to write everything first with pencil and paper, sitting beside a big wastebasket. Then I use Emacs to enter the text into my machine, using the conventions of TeX. I use tex, dvips, and gv to see the results, which appear on my screen almost instantaneously these days. I check my math with Mathematica.

I program every algorithm that’s discussed (so that I can thoroughly understand it) using CWEB, which works splendidly with the GDB debugger. I make the illustrations with MetaPost (or, in rare cases, on a Mac with Adobe Photoshop or Illustrator). I have some homemade tools, like my own spell-checker for TeX and CWEB within Emacs. I designed my own bitmap font for use with Emacs, because I hate the way the ASCII apostrophe and the left open quote have morphed into independent symbols that no longer match each other visually. I have special Emacs modes to help me classify all the tens of thousands of papers and notes in my files, and special Emacs keyboard shortcuts that make bookwriting a little bit like playing an organ. I prefer rxvt to xterm for terminal input. Since last December, I’ve been using a file backup system called backupfs, which meets my need beautifully to archive the daily state of every file.

…

I currently use Ubuntu Linux, on a standalone laptop—it has no Internet connection. I occasionally carry flash memory drives between this machine and the Macs that I use for network surfing and graphics; but I trust my family jewels only to Linux. Incidentally, with Linux I much prefer the keyboard focus that I can get with classic FVWM to the GNOME and KDE environments that other people seem to like better. To each his own.

What’s the best archival format for your important documents? In a previous post I suggested parchment might be—but that’s impractical. All joking aside, the issue is a serious for anyone who is going to spend the better part of their life writing and needs reliable access to this material.

James King of Adobe has a blog, Inside PDF, that’s well worth checking out. Besides covering ISO 32000—the ISO standard based on PDF 1.7, James has made an interesting case for PDF/A as an archival format.

Part of the case is a case against XML based alternatives such as ODF and OOXML. One problem is false advertising: While they do contain XML subfiles, they are, in fact ZIP archives that contain, besides binary files. Not only false advertising, but false promises as well:

There is what I think is a rather technically shallow belief that XML files are easier to work with and will survive the passing of time, even great periods of time, better than other formats. The text held within XML files can usually be viewed with any generic text editor and I guess that gives people a warm feeling that it will therefore also be easier to retrieve with a program. Fair enough. But what is glossed over way too much is that that text is enveloped within XML for [something]. (See my earlier blog entry.) The envelopes (schemas) offered by ODF and OOXML are different. Different enough that a simple program cannot extract just the raw text from either. And is that all I really want from a document in the future, the raw text. Because when you get to the layout and the images and the color space definitions and the fonts, these things do not lend themselves well to XML and are often stored within the ZIP archives as binary data. So tell me again where the advantage to XML is for this purpose?

To these two criticisms, let me add a third. The structure encoded in the XML subfiles of ODF and OOXML is not the logical structure of the document but the functions of the word processor. But that’s not what needs preserving.

Rob Weir at an Antic Disposition, not surprisingly, had an alternative view. Rob observes that not all goals that one might have in archiving is well served by PDF. Reflection on these raise a number of questions, none of which are are answered by PDF:

1. What was the nature of collaboration that lead to this document? How many people worked on it? Who contributed what?
2. How did the document evolve from revision to revision?
3. In the case of a spreadsheet, what was the underlying model and assumptions? In other words, what are the formulas behind the cells?
4. In the case of a presentation, how did the document interact with embedded media such as audio, animation, video?
5. How was technology used to create this document? In what way did the technology help or impede the author’s expression? (Note that researchers in the future may be as interested in the technology behind the document as the contents of the document itself.)

Nevertheless, Rob is not blind to the attractions of PDF only sensitive to the way it offers a partial solution to the problem of archiving. In the end he entertains a hybrid approach:

An intriguing idea is whether we can have it both ways. Suppose you are in an ODF editor and you have a “Save for archiving…” option that would save your ODF document as normal, but also generate a PDF version of it and store it in the zip archive along with ODF’s XML streams. Then digitally sign the archive along with a time stamp to make it tamper-proof. You would need to define some additional access conventions, but you could end up with a single document that could be loaded in an ODF editor (in read-only mode) to allow examination of the details of spreadsheet formulas, etc., as well as loaded in a PDF reader to show exactly how it was formated.

There is a third way.

It may not be the Final Solution (especially given its current incarnation). But it has the advantages of both approaches and the deficits of neither: Structural markup of plain text files kept under version control. Plain text is the lingua franca of computers and will remain that way in the foreseeable future. Any given file will remain editable, but any given commit will be preserved. Moreover, the version control system will preserve a wealth of metadata about the development of the document, the contribution of collaborators, etc. There are choices in implementation concerning both the markup—be it LaTeX, ConTeXt, or XML variants such as DocBook—and the version control system—be it Subversion, Git, Mercurial. None are perfect. But for now, my bet is on the third way.

The version control bundle requires GNU awk. If gawk is not installed on your *nix system, this script will do it for you:

#!/bin/sh
#
# installgawk.sh
#
# A bash script to install the latest version of GNU awk. Be sure to set the variables to the desired values. 
#
# http://www.gnu.org/software/gawk/
#
# Mark Eli Kalderon 2008-03-22

# Gawk. Change to the desired version if necessary
VER="3.1.6"
GAWK="gawk-${VER}"

# Build directories. Change to the desired directories if necessary.
GBLDDIR=/var/tmp/${GAWK}-build

# Create gawk build directory, but save source files if they exist.
test -d ${GBLDDIR} || mkdir ${GBLDDIR}
test -d ${GBLDDIR}/${GAWK} && /bin/rm -rf ${GBLDDIR}/${GAWK}
cd $GBLDDIR

# Download and unpack gawk source.
curl http://ftp.gnu.org/gnu/gawk/${GAWK}.tar.gz -O
tar -xvzf ${GAWK}.tar.gz
cd ${GAWK}

# Configure and build gawk.
./configure
make
make check

# Install gawk (in /usr/local/bin/). Will prompt for password.
sudo make install

As of version 0.3, the vc bundle supports bazaar, git, and subversion and runs on Windows and unices. Within the vc directory there are subdirectories for each of these cases:

• bzr-unix/
• bzr-windows/
• git-unix/
• git-windows/
• svn-unix/
• svn-windows/

Each of these subdirectories contains a pair of scripts. As I am on OS X and wanted to see how well this would work with git, I used the scripts in git-unix/:

• vc
• vc-git.awk

Copy these to the root directory of your repository. vc is a shell script that extracts version control information and writes it to a new file, vc.tex. vc does this by calling vc-git.awk to process the output of git status and git log. To use these scripts, put the following in the preamble of your LaTeX document:

\immediate\write18{sh ./vc}
\input{vc}

\write18 allows you to call shell scripts when running LaTeX. Most TeX installations has \write18 disabled by default for security reasons. That’s a good thing. Rather than enabling this globally, you can enable this on an as needed basis, by running pdflatex or xelatex with the -shell-escape argument.

vc.tex defines the following macros which can now be used in your LaTeX document:

• \VCRevision current (maximum) working copy revision number
• \VCRevisionMod as \VCRevision, but with an additional note if the working copy contains modified files
• \VCAuthor author of the last check-in operation
• \VCDateRAW date of last check-in in native format of the VCS software
• \VCDateISO date of last check-in in ISO format YYYY-MM-DD
• \VCDateTEX date of last check-in in TeX format YYYY/MM/DD
• \VCTime time of last check-in
• \VCModifiedText contains the note shown in macro \VCRevisionMod if there were modified files. This macro can be redefined by the user.
• \VCModified 0 if there are no modified files in the working copy directory; 1 or 2 if there are modified files. In general you don’t need this macro.

These macros can be called wherever appropriate. I wanted my version control information discretely tucked away in a footer:

\usepackage{fancyhdr}
\lfoot{\tiny{Revision: \VCRevision ; Author: \VCAuthor ; Date: \VCDateISO}}
\cfoot{}
\rfoot{}

The result:

If you want the version control information in draft mode only, Stephan Hennig, vc bundle’s maintainer, suggests using the ifdraft package.

Continuing our ongoing text editor roundup for OS X, I am pleased to report that SubEthaEdit 3.1 has just been released. The world’s best collaboration text engine just got better. SubEthaEdit now supports:

• Automatic port mapping making communication over the internet easier—no manual configuration required
• Inviting your iChat buddies
• Friendcasting—the ability to connect to a friend’s friend.

To get a better sense of this see, the Coding Monkeys screencast. It is a pretty major feature upgrade for a point one release. SubEthaEdit 3.1 also includes an improved LaTeX mode.

1. the message URI
2. the message id wrapped in angle brackets

Message URLs can take any of the following syntactic forms:

message:%3cmessage_id%3e 
message://%3cmessage_id%3e 
message:<message_id> 
message://<message_id>

Both Liyanage and Gruber provide applescripts for retrieving the message id of a given email saving the message URL to the pasteboard. Gruber’s applescript is as follows:

tell application "Mail"
    set _sel to get selection
    set _links to {}
    repeat with _msg in _sel
        set _messageURL to "message://%3c" & _msg's message id & "%3e"
        set end of _links to _messageURL
    end repeat
    set AppleScript's text item delimiters to return
    set the clipboard to (_links as string)
end tell

When saved in

~/Library/Scripts/Applications/Mail/

it will appear in the script menu when Mail.app is in focus. Just select the target mail and run the script and the mail URL will be in your pasteboard ready to paste into your textfile. And if you are a keyboard fanatic who eschews the mouse wherever possible, you can use Quicksilver to run the applescript. If your text file is in markdown format, simply enclose the message URL in angle brackets.

Having the ability to link to pertinent emails really increases the usefulness of plain text notes. More so if your text editor will launch the URL for you. In TextMate, simply move the cursor over the URL and hit ⌅. Another small step in harnessing the power of plain text.

wc -w

gives an inflated estimate since it will include LaTeX commands. One alternative is to use detex:

detex mydocument.tex | wc -w

This will strip the LaTeX commands first before counting words but this assumes that you are not running commands that insert text. Consider a document with the following command:

\newcommand{\yo}{To Whom It May Concern}
\yo

The detex method would not count these four words. For these reasons, I proposed an alternative method—typesetting the LaTeX document and the converting the resulting PDF to text with ps2ascii and then using wc:

ps2ascii mydocument.pdf | wc -w

There are two problems with this approach. First ps2ascii is sloooow. Second, it gives an inflated estimate since ps2ascii:

• substitutes spaces for ligatures it cannot handle
• preserves hypenation with the result that hyphenated words count as two words not one
• includes page numbers and headers and footers

A different conversion utility, pdftotext, fares better:

pdftotext -enc UTF-8 -nopgbrk mydocument.pdf | wc -w

It is much faster. And does not preserve hyphenation. Ligatures, page numbers, and headers and footers still present a problem, but a much better estimate.

A better approach would be to use TeX to generate the word count. There is a shell script available on CTAN that does just this—wordcount. Unfortunately, it is no longer actively maintained (someone reported to me that its author had died), and it failed on several of my LaTeX documents.

Googling has revealed a couple of perl scripts for determining the word count of LaTeX documents: TeXcount.pl and texWordCount.pl. These provide reasonable though different word count estimates.

Testing these methods on a longish document yielded the following results:

As far as I can determine, texWordCount gave the best estimate. Here is a command that uses it (be sure to correct the path):

perl -T /path/to/texWordCount.pl "$TM_FILEPATH"

In TextMate’s Bundle Editor the setting should be:

• Save: Nothing
• Input: None
• Output: Show as Tool Tip
• Activation: Key Equivalent ⌃ ⇧ N
• Scope Selector: text.tex.latex