Some TeX Developments

I’ve been leaving siunitx alone for a while, concentrating on bug fixes in the v2.1 branch. The  list of issues has continued to grow, and I’m now getting some organisation done before starting on items for v2.2. Some of these are more likely to get tackled, some rather less likely, but it’s best to get everything logged! If you look at the closed issues, you’ll see that part of getting organised is closing some bugs where I don’t feel that it is appropriate to take action. What I would say is that if you’ve got something you’d like considering, put it into the database. I do try to keep up with ideas by e-mail or from forums, but do forget some.

On particular thing I want to think about is the naming is some options and macros. I’ve had some discussion with Marcus Foster from CSIRO Information Management & Technology about siunitx, and he’s pointed out various errors on my part. Some of those, in the documentation, have been fixed. At the code level, he pointed out that what \SI prints are properly called quantities, and that units are separated by products. So I’m thinking of some reasonably radical renaming of macros and options (with the old ones retained, of course!). Feedback on these ideas would be welcome. At the same time, he’s not at all keen on the ‘qualifiers’ concept, but on that I think users would not be happy if I removed it!

As regular readers will know, I’m a big fan of the biblatex approach to producing bibliographies, particularly now that we have Biber ‘on tap’. There was a question on the {TeX} site a while ago about an IEEE style, and so I wrote the biblatex-ieee style as a partial answer. Doing that, I realised that my other biblatex styles need a bit of work. I’ve now revised both biblatex-nature and biblatex-science to make them more flexible, and also to improve their documentation. Next on the list is the biblatex-chem bundle: there are four styles in it, so it will take a little while. Once all of that is done, then I will take a look at the requirements for physics, which I’m going to call biblatex-phys.

Many readers will be familiar with the Biber program, a replacement for BibTeX which works with the biblatex package. Binaries for common platforms have been available from TLcontrib for a while, but have now been added to the main TeX Live 2010 system. So you can install Biber on the ‘common’ platforms using the TeX Live Manager (or tlmgr from the command line). Yet another reason to move on from BibTeX and switch to biblatex, if you’ve not already!

[latexpage]
Reading through the chat page for the {TeX} Q&A site today, I stumbled upon a reference to QuickLaTeX. This is a plugin for WordPress to allow you to show LaTeX code in your page or blog. That’s not unique, but what is interesting is that it runs the LaTeX on the QuickLaTeX server, meaning that you don’t need LaTeX on your web host’s system. For me, that was immediately interesting as I don’t have a TeX installation on the host for this site. (It looks like QuickLaTeX is built using TeX Live 2010, so most packages should be available unless you are on the bleeding-edge.)

The system seems pretty easy to use. The plugin follows the standard WordPress model: download, install and activate. The plugin page gives some details on how to use it, but a few examples here will show off the power of the system. It’s possible to put something simple into the blog, such as

!\[ y = mx + c \]

and get
\[ y = mx + c \]
or something much more complex, like

!\begin{tikzpicture}
[+preamble]
\usepackage{tikz}
\usepackage{pgfplots}
\pgfplotsset{compat=newest}
[/preamble]
\begin{axis}
\addplot3[surf,domain=0:360,samples=40] {cos(x)*cos(y)};
\end{axis}
\end{tikzpicture}

and get
\begin{tikzpicture}
[+preamble]
\usepackage{tikz}
\usepackage{pgfplots}
\pgfplotsset{compat=newest}
[/preamble]
\begin{axis}
\addplot3[surf,domain=0:360,samples=40] {cos(x)*cos(y)};
\end{axis}
\end{tikzpicture}
All that is needed, beyond the plugin, is to put ![latexpage] at the start of the page. You can then escape any ‘raw’ LaTeX by prefixing the beginning with !, for example

!!\[ y = mx + c \]

is what I used for the first of my demos.

I don’t often find the need to post actual LaTeX examples in my blog, but the facility is certainly one I’m happy to have access to. The license for QuickLaTeX asks for a public link to their site, which seems like a small pay-off for a very handy service.

Martin Scharrer has put together a hand reference list of macros for programming LaTeX2e. This covers stuff in the LaTeX kernel itself, rather than add-ons such as etoolbox. This should be a real benefit to newer LaTeX programmers, as finding all of this information has in the past been quite awkward.

There was a question on the {TeX} Q&A site recently about compiling a document reading

\documentclass{minimal}
\document
a
\enddocument

This doesn’t work: I’ve explained why as my answer to the question. I also mentioned that in LaTeX3 I’d expect this won’t work. Here, I want to look at that in a bit more detail.

First, the background. When LaTeX2e creates an environment foo, what actually happens is two macros called \foo and \endfoo are defined (hence the original question). When you do

\begin{foo}
...
\end{foo}

LaTeX looks for the \foo macro, and if it finds it starts a group and inserts \foo. At the end of the environment, LaTeX will use \endfoo if it exists, but this is not required.

There are some problems with this scheme. First, it’s possible to abuse the system, as something like

\begin{emph}
...
\end{emph}

will not raise an error even though \emph was never intended to be used as the start of an environment. (LaTeX2e does not require that \endemph exists here: it’s only the start of an environment which must be defined.) Secondly, due to this mixing it’s not possible to have a foo environment and independent \foo macro: the two are tied together. Finally, as \endfoo is ‘special’ \newcommand won’t let you create macros which start \end....

For LaTeX3, we want the approach to be different. Document commands and document environments should be independent of one another, and so xparse defines a pair of special internal macros when you use

\NewDocumentEnvironment{foo}...

This is totally independent of a macro called \foo, so the plan is that you’ll be able to have an environment called foo and a separate \foo command, or indeed one called \endfoo.

At present, most people will be using xparse with LaTeX2e. That means we still need to follow what LaTeX2e does. So at the moment you’re not going to see the change: messing with the LaTeX2e mechanism looks like a very bad idea. However, for a native LaTeX3 format the clash will disappear.

The latest version of biblatex, v1.1, appeared on CTAN yesterday. This is a feature release, not just bug fixes, and so there are lots of new things there. At the same time, Biber has been updated to v0.7. If you use TeX Live 2010, you’ll be able to get the new biblatex using tlmgr in a day or so, and can get the Biber update via TLcontrib already.

Many of the new features rely on Biber, and will not work with BibTeX. As Biber has lots of advantages anyway, including UTF-8 support and active development, this is no real hindrance.

I want to focus here on one new feature, as it’s one I requested. In chemistry and physics we tend numerical reference styles and to have lots of references. Often, several of these will be related, and so can be ‘compacted’ into a single number. With traditional BibTeX styles, this can be done using the mciteplus package and a suitable .bst file. biblatex has supported this using ‘reference sets’ for some time, but up to now this has required modification of the database entries. In v1.1, you can define a reference set in the preamble:

\defbibentryset{set1}{key1,key2,key3}

and then cite the set in the document. There is also support for mciteplus-like syntax, but I think it’s probably best to use the native biblatex approach here.

Compressing multiple citations in a dynamic way was really the only problem I had with using biblatex for all of my citations. Now that this is sorted, I’ll be sticking to biblatex all of the time, and I’d urge other physical scientists to do the same: biblatex is a much more flexible approach than the traditional BibTeX citation system.

A question that comes up from time to time is how to install one or other of my packages, usually either achemso or siunitx. While both are essentially standard LaTeX packages (no weird files or binaries needed), there are still soem stumbling blocks that cause issues. So I thought a few notes by be useful here.

Installing as part of an up to date TeX system

By far the easiest way to install my LaTeX packages is to get them as part an up to date TeX system. Both MikTeX 2.9 and TeX Live 2010 include all of my general packages. MiKTeX is of course Windows-only, but TeX Live can be installed on Windows, Mac OS X and Linux. After installation, doing an on-line update should grab all of the latest packages from CTAN. Both MiKTeX and TeX Live include graphical update programs, so this is not such a difficult process nowadays.

Mac users may well prefer MacTeX over plain TeX Live, but MacTeX is built on top of TeX Live and so the same ideas apply. You can install either TeX Live or MacTeX and get the same basic functionality.

For Linux users, it’s worth noting that popular Linux distributions tend to include old versions of TeX Live (or even teTeX), rather than TeX Live 2010. So if you want an up-to-date TeX system you’ll be better off ignoring your Linux package manager and grabbing TeX Live directly.

One thing to do if you update your TeX system is to check any locally-installed files you might have (see the next section for more about local installation). These will be in ~/texmf on Linux, ~/Library/texmf on a Mac and (probably) %USERPROFILE%\texmf on Windows. One problem I see from time to time is that users of achemso have installed some of the BibTeX styles locally, then update the main package and all sorts of things go wrong. So do check carefully on any local files: they might be outdated by a new TeX system.

Installing using the TDS zip files

The method above is fine if you are happy installing an entirely new TeX system, but if all you need is access to one of my packages then it is probably over-kill. For these users, I provide ready-to-install zip files on CTAN. For achemso, you need achemso.tds.zip, while for siunitx users you probably need

• siunitx.tds.zip
• expl3.tds.zip
• xpackages.tds.zip

The idea with these files is that I have set them up with documentation, ready to use LaTeX styles and all of the support files. All that needs to happen with them is to unzip them inside your local TeX directory and tell TeX about them.

Where the files should go depends a little on your operating system. The local directory (folder) is usually ~/texmf on Linux, ~/Library/texmf on a Mac and (probably) %USERPROFILE%\texmf on Windows. Here, ~ and %USERPROFILE% represent your home directory (folder). So on my Windows 7 PC, I have a folder

C:\Users\joseph\texmf

while on my Mac there is one at

/Users/joseph/Library/texmf

Whichever system you use, copy the appropriate zip files there and unzip. The result should be a structure which looks like

texmf/tex/latex/achemso/achemso.sty
...
texmf/tex/latex/siunitx/siunitx.sty

and so on. Of course, the exact structure will depend on which packages you install! What is important for installing siunitx is to also install expl3 and xpackages. If the versions do not match then trouble will not be far away.

To tell TeX about the new files, you need to run the program texhash. There is a graphical interface for this in both MiKTeX (Update File Name Database) and TeX Live. I find it easiest just to start a Command Prompt/Terminal and type

texhash

[For users with recent versions of TeX Live (2009 and 2010, I think), running texhash is actually not needed. However, it will not do any harm so you may as well run it.)

Installing from the dtx file

The traditional method to install a package is to unpack it from the dtx source. I’ve got to say that I only recommend this for experienced LaTeX users. While both achemso and siunitx are designed to be easy to unpack, life is more complex for expl3 and xpackages. So I’d strongly recommed using the TDS zip files unless you know a bit more about LaTeX!

Reading through some TeX-related material today, I spotted that the very popular biblatex package has finally reached version 1. Accompanying this release is a version step for the biber BibTeX-replacement program, which reaches version 0.6. Both are now considered non-beta, and the biblatex release in particular is a big story to me. I’ll be checking on my own biblatex-related packages over the weekend and making sure that they are working with the new release, and if all goes well will move them to v1.0 as well.

A quick look through the documentation for both biblatex and biber shows that the new versions are mainly about stability. There are not a lot of changes listed from the previous testing releases: they’ve proved to be pretty stable and so the time for an official move to release status has obviously arrived.

I’ve written in the past about the biber program, a replacement for BibTeX when using the biblatex system for citations in LaTeX. The biggest stumbling block to using biber to date has been the need to build it from the source. On Windows, that also means getting a working Perl installation, which is a non-standard item on that operating system. However, there is now an alternative approach, at least for people using TeX Live 2010. The new TLContrib system for additions to TeX Live now includes a biber package for Windows, Mac OS X (64 bit) and Linux.

To get biber installed, you’ll need to use the Command Prompt or Terminal. On Windows, you probably need to run the Command Prompt as the Administrator, while on the Mac or Linux you will  probably want to sudo the following. To get biber installed, all you need to type is

tlmgr --repository http://tlcontrib.metatex.org/2010 install biber

The system will then get on with installing biber, which you can then use as a replacement for BibTeX. I’d then add biber to my graphical editor’s list of programs to make it easy to use: the detail of course depends on which editor you use.

What is particularly interesting here is that it has been possible to build a stand-alone biber. This should mean that at some stage both TeX Live and MiKTeX can integer ate it directly. This will really make biber a viable choice for most people using biblatex: building from the source is not most people’s idea of ‘easy to use’!