Some TeX Developments

I try to keep my siunitx package ticking over, even though it’s now pretty feature-rich. There are a couple of issues currently on the list for v2.6, and I’m planning to tackle those over the Christmas holidays. So now is a good time to log any feature requests you have for siunitx.

Anyone who watches the BitBucket site for siunitx development will have noticed that I’ve been adding a few new features. As I’ve done for every release in the 2.x series, new options means a new minor revision, and so these will all be in v2.5. I’ve also revised some of the behaviour concerning math mode, so there are now very few options which automatically assume math mode.

Looking beyond v2.5, I have some bigger changes I’d like to make to siunitx. When I initially developed the package, it was very much a mixture of things that seemed like a good idea. The work for version 2 meant a lot of changes, and a lot more order. However, I’ve learnt more about units, LaTeX and programming since then, and that means that there are more changes to think about.

The internal structure is quite good, but I need to work on some parts of the code again. For users, of course, that won’t show up, but it is important to me. It’s also not so straight-forward: the .dtx is about 17 000 lines long! However, there are also some issues at the user level. In particular, I think I’ve offered too many options in some areas, for example font selection. Revising those will alter behaviour, but it will also improve performance and the clarity of some edge cases. However, that is not such easy work and will take a while. I’ve got lots of other TeX commitments (plus of course a life beyond LaTeX), so these changes will wait a while yet. So once v2.5 is finalised I’d expect to have little change in siunitx for some time: probably until at least the autumn, and quite possibly the end of the year.

Development of the next release of siunitx has gone quite smoothly: I’ve added a few new features, and there is now nothing outstanding for v2.4. So it is time to ask for some volunteers to test the code.

In terms of new features, I have added the a choice of rounding modes modes the ability to compress down exponents in ranges and lists, both long-standing feature requests. In response to a recent TeX.sx question, siunitx can now also turn exponents into unit prefixes. At a lower level, I’ve also altered some of the options internally so fewer of the assume math mode.

To test, please download the ready to install TDS-style .zip file and install it locally. You should then be good to go. Feedback as a bug report or by e-mail welcome, as always. Assuming there are no problems, I’d expect to upload to CTAN by the end of the month.

On the TeX.SX site recently, there was some discussion about locally over-riding the round-mode = places setting in my siunitx package. One thing this highlights for me is the need to think about which settings to apply globally.

Some siunitx settings are about consistency of appearance, and seem to apply naturally to entire documents. A classic example would be output-decimal-marker: if you are using , as a decimal marker, it should apply everywhere!

However, this is not so clear-cut for many of the options related to number-manipulation. The rounding options in particular are really intended for the case where you have some auto-generated data (say a long list from an instrument), and the real accuracy is not as great as the apparent precision. Instruments are great at providing lots of numbers, but it takes a bit of human thought to decide how many of these are really relevant. So for these cases, setting an appropriate rounding scheme is perfectly sensible.

On the other hand, for a number you’ve typed in yourself I’d hope that you’ve done the thinking part when the number is typed, so rounding by the computer is not needed. That suggests to me that most of the time rounding should not be set as a global option.

Of course, it will depend on the exact nature of the document in question. If all of the data in a document is in tables, all of which need rounding, then there is a performance gain from setting the rounding once globally. So the best I can say, guidance-wise, is ‘think about your document’!

I’m making a start on the next release of siunitx: v2.3. There are a number of issues in the database targeting this release, and these are mainly about dealing with things behind the scenes. Some options need revision, and I need to improve the table code somewhat. However, I doubt that there will be much to excite users. That’s not necessarily a bad thing: there seem to be a lot of siunitx users, and I don’t want to break the code! Of course, if there is a particular issue that needs addressing then the usual rule applies: make a case to me and I’ll see what I can do.

As I detailed a little while ago, I’ve been working on v2.2 of siunitx. I’ve now released the latest version, v2.2, to CTAN. There are a number of small changes, introducing new features, but I thought I would highlight a few.

A long-standing feature request has been to be able to use the cancel package to show how units cancel out. This is useful for teaching, although it’s not of course part of the usual typesetting of units for publication. It turns out not to be too hard to allow this, so that you can now use input such as

\si[per-mode = fraction]{\cancel\kg\m\per\s\cancel\kg}

and have it come out properly. At the same time, I’ve made it possible to highlight particular units

\si{\highlight{green}\square\metre\candela\second}

again for teaching-related purposes.

A second long-standing request is to be able to parse uncertainties given in the form

\num{1.23 +- 0.15}

which was something more of challenge, but again is now working properly. So you can get the same output from the above and from

\num{1.23(15)}.

A final highlight is the new \tablenum macro. This is needed for aligning numbers inside \multicolumn and \multirow, which otherwise does not work. (At a technical level, both \multicolumn and \mutirow use the \omit primitive, and so the code inserted by the S column is not used. The \tablenum macro effectively makes the same approach available as a stand-alone function.)

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!

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!

Anyone who follows the BitBucket repository for siunitx will have seen that I’ve made a lot of commits over recent days. If you look at the list of open issues, you’ll also see that it’s got smaller and that some have been moved from targeting v2.1 to targeting v2.2. I’ve been aiming to get v2.1 finished this month, and I’ve been working out what I can and can’t do in that time frame.

The result is that the code on BitBucket now is what I’ll release as v2.1, baring any remaining bug fixes. The idea is to have some new features, but not so many that I’ll have introduced lots of new bugs. I hope that I’ve got the balance about right, and that there has been enough time for testing the new additions to the package. If all looks okay by the weekend I will be updating CTAN at the weekend. If you’d like to test it before then, either grab the code from BitBucket or, if you use TeX Live, try the TLcontrib installation method.

I’m hoping to work on v2.2 for a release early in the new year, probably late January. There are already a few issues on the list for v2.2, but that may alter if there is a good case made for something else. Of course, I’ll also have to avoid breaking anything!

I’m working on the list of issues for siunitx v2.1. As I do, I hope that the code is staying usable at all times! The list is getting shorter (finally), so I’m hoping to get something released around the end of the month.  One thing that I need for that is testing. My recent post about TLcontrib mentioned this as a route for testing packages prior to release. So I’m taking advantage, and sending snapshots of siunitx to TLcontrib each time I add a new feature. So if you want to help to test things out, then you can run

tlmgr --repository http://tlcontrib.metatex.org/2010 update siunitx

from your command prompt/terminal. Let me know about any new issues!