Sorting issues for consideration for siunitx v2.2

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!

Installing achemso and siunitx

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

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!

siunitx: testing for v2.1 release

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!

Testing versions of siunitx v2.1 on TLcontrib

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!

Time to take a look at the issues for siunitx v2.1

The list of issues for siunitx has been growing for a while. I’ve been holding off work on the bigger issues while bugs in v2.0 have come up, as I’d prefer to have something that works for most people now rather than try to add more new features too soon. At the same time, I’m also busy working on other things. However, I’ve been prodded by a few users to make a start on some of the feature requests. I do aim to please, so I’m going to make a start on the list.

Of course, just because I look at something does not mean I’ll do it. I decided to start simple, and took a look at issue 71. The question here was about automatically adding kerning for things like \femto\farad, as the kerning in Computer Modern is not good here. I did write some code, but looking at it decided that this is too close to the font choice for me. So I’ve closed the issue as ‘WONTFIX’. I’ll see whether this sticks or whether there is a lot of demand for such a feature.

The plan is to get on with adding features and fixing more complex issues over the next few weeks. I never leave the code unusable (I use the development version as my day-to-day workhorse), so you can grab the .dtx file and try things out if you like. I’ll post again if there are any particular new features or changes that need a try out.

The trouble with getting things right

I work hard on my LaTeX packages, and try to get things to work well for the user with clear interfaces. However, there is a down side to this: I get asked to do more things! For example, I’ve recently released version 2 of siunitx. This builds on the work from version 1, which itself was designed as an improvement to various earlier unit packages for LaTeX. I did remove a few features when I moved from version 1 to version 2, but in the main each new version of siunitx has added ‘more stuff’ to the package. However, I’ve also got organised with tracking bugs and feature requests using BitBucket. The resulting list of open issues is already quite frightening (at least for me). I’ve been keeping up with the bugs in the new release (I try to deal with them within a few days of being reported), so the list is all made up of feature requests, and almost all of those are new things. So the package being successful results in more work for me, not less. I’m not complaining: I want things to work. It’s just worth bearing in mind!

siunitx updates

Following the release of version 2 of siunitx, you might have noticed that there have been rapid minor updates (v2.0a, v2.0b and v2.0c). I thought I’d just say that most of this is to make sure that the version that ends up in TeX Live 2010 is as good as possible. There are the inevitable bugs to sort, especially with compatibility with version 1, and I want to get things working as well as possible. I suspect there will be a few more releases in quick succession!

siunitx version 2 released

After many months of work, I’m pleased to announce that I’ve just sent version 2 of siunitx to CTAN. Many readers will be familiar with the package and some of the development process. Here, I’ve put together a summary as ‘release notes’ for the new version.

A comprehensive (SI) units package

Typesetting values with units requires care to ensure that the combined mathematical meaning of the value plus unit combination is clear. In particular, the SI units system lays down a consistent set of units with rules on how these are to be used. However, different countries and publishers have differing
conventions on the exact appearance of numbers (and units).

The siunitx package provides a set of tools for authors to typeset numbers and units in a consistent way. The package has an extended set of configuration options which make it possible to follow varying typographic conventions with the same input syntax. The package includes automated processing of numbers and
units, and the ability to control tabular alignment of numbers.

Version 2

Over the past two years siunitx has developed to include many features not originally foreseen when development began. While it has been possible to add a range of new features, some of the underlying limitation of the version 1 code have made this difficult. At the same time, renewed effort by the LaTeX Team on the development of LaTeX3, and in particular the expl3 programming system, has offered a more robust method to create the internal structure of siunitx. As a result, version 2 of siunitx has been almost completely re-written internally.

As well as fixing a number of bugs and limitations in the original release, version 2 is also much better written to work quickly. As a result, most users should see performance enhancements with this new release of siunitx.

As part of the revision of siunitx, the option system and user macros have been completely re-thought. The options now have longer, descriptive names and also a much clearer range of input values. The options which in version 1 took either a key word or a literal value have been replaced by ones which take literals only: in some cases this means that advice has been added to the documentation on how to get particular output effects.

Moving from version 1 to version 2

Depending on how you use siunitx, there may be very little to do to move to version 2. The new version includes a compatibility support file, meaning that loading siunitx using:

\usepackage[load-configurations = version-1]{siunitx}

should mean that existing documents compile with very few changes.

There are some changes to standard settings between version 1 and version 2, which may lead to some alterations in documents. At the same time, a small number of the features of siunitx version 1 which I feel did not work cleanly have been dropped. At present, some of these are scheduled to be re-examined for
inclusion in later releases of siunitx.

While there is a back-compatibility layer for users upgrading, it is strongly recommended that documents are updated to use the new option names and functions. The new approach has been chosen as it is an improvement on the previous version, and in the longer term this layer may be removed.

Installation

Most users will obtain siunitx as part of their TeX distribution. MiKTeX 2.8 should include siunitx version 2 after a short delay (a few days after CTAN upload). For TeX Live users, there will be a slight delay as the package will appear in updated form in TeX Live 2010 but not TeX Live 2009 (which is frozen).

For users who wish to install siunitx themselves, the package is available as a pre-extracted zip file, siunitx.tds.zip. Simply unzip this in your local texmf directory and run ‘texhash’ to update the database of file locations. Version 2 of siunitx requires up to date versions of the LaTeX3 packages expl3 and xpackages. These are also available from CTAN in ready to install format (as expl3.tds.zip and xpackages.tds.zip), and can be installed in the same way if necessary.

If you want to unpack the dtx yourself, running ‘tex siunitx.dtx’ will extract the package whereas ‘latex siunitx.dtx’ will extract it and also typeset the documentation. Typesetting the documentation requires a number of packages in addition to those needed to use siunitx. These should all be available in a complete TeX Live 2010 or MiKTeX 2.8 installation.

Development code and bug database

In order to help users see what is happening, and also to allow me to work efficiently, the development code for siunitx is available on the code hosting site BitBucket.

You can download the very latest code from there: of course, this may or may not work properly depending on exactly what I have added to the code.

The BitBucket site includes an issue tracker, where you can report bugs or make feature requests. I also add bugs to the database from e-mails I get from users. Filling in the bug database helps to make sure that I do not forget things, and also helps other users see what issues are known.

If you want to contribute code to siunitx, you can of course send patches directly to me. Alternatively, the code is hosted using the revision control system Mercurial, which was chosen as it is decentralised and is easy to install on a range of operating systems (I use MacOS X, Windows XP, Windows 7 and Ubuntu!). I’m happy to explain to potential contributors how Mercurial works for developing siunitx.

Roadmap for future releases

The bug database already includes a number of feature requests which are marked to be looked at for version 2.1. The current intention is that the next few months will be devoted to bug fixes in this release (v2.0), with moves to add features for v2.1 beginning in the late summer. I anticipate that v2.1 will be released toward the end of 2010.

It is likely that not all of the features currently marked as to be looked at for v2.1 will be fully working by the time it is released. At the same time, there are some longer term areas which may also need attention. Version 2.2 of siunitx is therefore planned, but with no current list of features marked for inclusion. This version is likely to appear in Spring 2011.

One longer term aim is to include LuaTeX support in siunitx, so that the entire package can work much more rapidly with LuaTeX than when using TeX macros alone. This is not likely to happen until next year (2011), but is in the bug database and is part of the longer term development plan for siunitx.

The internals of siunitx

Currently, the only documented interface to any of the functionality of siunitx is via the key-value control system and functions described in the manual. The internal code of the package is not documented, and there is therefore no guarantee of stability of internal functions. While it is common for users to have to modify the internals of LaTeX2e packages as part of their documents, this is not good programming practice and is not encouraged for siunitx, or indeed in general.

If there is a user function that you require that is not available using the documented tools, please either e-mail or report a bug in the database. One of the general aims of siunitx is to provide a proper documented interface for all of the
functions of the package. I am therefore very happy to add interfaces to internal processes as necessary.

Programmers should note that siunitx is coded using the LaTeX3 ‘expl3’ programming system. This looks somewhat different to traditional TeX or LaTeX programming. Details of the programming environment are documented as part of the expl3 bundle. Currently, none of the internal functions or interfaces are documented, and so are not meant for use outside of siunitx. Other programmers wanting to make use of internal siunitx functions are encouraged to get in contact with me. This will enable me to ensure that the parts of siunitx which are needed by others are documented and are not changed without consultation.

siunitx version 2: beta release

Over the past few months I’ve been working a new version of siunitx with completely re-written internals. This is now at the point where I hope that it is usable for most people, but before replaced version 1 some testing is needed. This is what this beta (testing) release is for. There are some important notes for people testing, which I’ll run through below. For the impatient, you can get:

Release notes

The code used in siunitx relies on the LaTeX3 Project packages expl3 and xpackages. You will need the latest versions of both of these to test siunitx 2: they can both be downloaded from CTAN or installed using the update facilities in TeX Live or MiKTeX.

Version 2 of siunitx renames most of the package options to make them more informative. The old names are available by using:

\usepackage[load-configurations = version-1]{siunitx}

The new option names are intended to make it easier to continue to expand siunitx without having completely opaque option names. At the same time, the nature of some of the options has been changed. This means that there are no longer any ‘magic’ keywords, which have caused confusion in the past.

There will be no significant features added to siunitx version 2 between the beta version and the production release (probably in June). The aim is to get the inevitable bugs in the current code found and fixed, which is best done while not making other changes.

A small number of features from version 1 of siunitx are not present in version 2. The features removed have never worked as well as I would like, and so I felt it was better to remove them and rework them later if needed. If this causes severe problems for users then some of these decisions may of course be reversed.

I have had a large number of feature requests for siunitx, and only some of these have been added to version 2 at present. This is partly as I have a limited amount of time, and need to get siunitx 2 to release within a reasonable time. At the same time, some of the feature requests are very specialist and I need to consider which of these fall within the scope of the package. That said, I intend to work on adding more features to siunitx after the full release of version 2.0. More details on this will be posted here in the future.

Feedback on any aspect of siunitx version 2 is very welcome: joseph.wright@morningstar2.co.uk.

siunitx 2: release timetable

As many readers will know I’ve been working on version 2 of siunitx for some time. There are always more feature requests, but at some stage I have to actually release something. I’ve now got some code that fixes a lot of bugs and annoyances in the current release and provides a better platform for new features, and so I want to move to releasing it.

The plan is to fix the known bugs in the development code and add as many new features as possible by the 25th of the month, and then to freeze development for a beta (testing) release. Depending on feedback, I’ll then aim to fix the bugs in the beta and go for a first production edition of version 2 in June. I’m not going to add any new features between the beta and production releases, but will start on them again once the production version is out. There is a feature tracker on the BerliOS site, which is a good place to put things so I don’t forget about them.