siunitx version 2.0: alpha 1

I’ve been working on siunitx version 2, getting the code to the point where I’d hope it works for most things that the current release does. Over the last couple of weeks I hope I’ve sorted out the table issues which tend to be a problem in version 1, plus “mopped up” a few outstanding odds and ends. So it feels like an appropriate point for a public snap shot of the code. As progress has been good, I’m calling this one alpha 1.

At this stage, there are likely to be some bugs and other annoyances in the code. However, I hope that enough works for people to risk taking the plunge and trying it out. For those willing to try out siunitx v2.0, you can get:

You’ll need to have up to date installations of both expl3 and the xpackages to try out the code, as internally the new code uses the LaTeX3 internal syntax. The biggest change that users should see from version 1 is that I’ve re-thought the option names. They are mainly longer, but more informative, in the new code. Improvements to the names I’ve picked are of course welcome.

At this stage, I’m still working on adding more ideas to the code. So there are some omissions in the release that I know are there and am intending to sort out. Of course, different users have different priorities for improvement. That said, there are bound to be things which simply are broken, things I’ve forgotten and the odd item that I’m currently planning not to carry forward from version 1. Feedback by as comments here, by e-mail or at the BerliOS site is very welcome.

The current development plan is to see how much is wrong with the alpha code, and if necessary to have some more alpha-status snap shots. I’d then hope to have a beta some time in the spring (perhaps April or May), with a full release currently in my mind for June or July. Exactly how this will work out depends on other projects: I’d like, for example, to have some floating-point tools in siunitx, but for that I need to write them for LaTeX3. The feature list for the release certainly isn’t fixed, and I’d expect that once v2.0 is out there will continue to be more ideas to add on.

Real life pgfplots examples

I’ve just sent a draft to TUGBoat for an article about pgfplots. As many readers will know, pgfplots is built on pgf/Tikz, which means that it can be used for both DVI and PDF output, and with plain TeX, LaTeX and ConTeXt. In my draft, I’ve used some real life plots (from a couple of recent publications in the research group I work in). The draft will probably change a bit, but for a preview take a look a the the PDF.

LaTeX Books online

I was looking something up today, and quite by accident found that Safari Books Online has both the Guide to LaTeX and The LaTeX Companion available. Unfortunately, the subscription costs mean that for individuals the price is far too high, compared to buying the printed versions. However, I also found that my employers (UEA) have paid for access to a range of books via the service. So if you are in a university it might be worth seeing if you can get the books as part of your institution’s more general access policies.

Building biblatex-biber

The biblatex-biber project provides probably the best way for biblatex users to switch to pure UTF-8 bibliography information. However, getting it to build can cause problems: biblatex-biber is a Perl programme, and needs various downloads from CPAN. I thought it would therefore be useful to put some simple recipes here, explaining what I’ve done to get a working biblatex-biber on Windows, Ubuntu and Mac OS X. I’m assuming that the latest biblatex-biber release has been downloaded and unzipped somewhere, and that the Command Prompt/Terminal/Shell is open in that directory (folder).

Mac OS X 10.6 (Snow Leopard)

Mac OS X comes with Perl installed, so life is relatively easy. At the Terminal, you need to run the cpan script as root:

sudo cpan

The cpan script has its own prompt, but this is very similar to the Terminal one. First, I updated cpan itself and installed a helper module with

install CPAN
reload cpan
install YAML

That done, the various requirements for biblatex-biber can be installed, using the single call

install Data::Dump List::AllUtils Readonly Text::BibTeX Readonly::XS

For the more cautious person (such as me), each install instruction can be given on a separate line: this keeps things a bit more controlled. I accepted the standard settings, except when asked about installing items that were only needed for testing, where I said no.

Once cpan has done all of the installing, you can leave it by typing

exit

So now back at the Terminal prompt, a few simple instructions

perl Build.PL
./Build
sudo ./Build install

That put biblatex-biber onto the path for all users: everything then worked correctly.

Ubuntu 9.10

Once again, Perl is installed as standard in Linux distributions: I’m using Ubuntu as a representative system. Before starting cpan, there is an additional step, which is to install an extra Ubuntu package. So at the Terminal, you need to do

sudo apt-get install libxml2-dev

This is needed as otherwise you get some very odd errors in a bit. Now, essentially the same recipe works as for the Mac. First run cpan running and update and install YAML. Then there is a long list of items to install

install Data::Dump List::AllUtils Readonly Text::BibTeX Readonly::XS XML::Writer XML::LibXML File::Slurp

which can again be done one at a time, for the more cautious.

After exiting cpan, the same three lines at the Terminal should work as in the Mac section.

perl Build.PL
./Build
sudo ./Build install

Windows (XP, Vista and 7)

To date, my attempts to build biblatex-biber on Windows (using Strawberry Perl) have failed as I can’t get the Perl module Text::BibTeX to install. This is supposed to be optional, but without it biblatex-biber does not seem to work, although I do get it to build. Luckily, there is a self-contained binary for Windows available from the project site. This includes its own Perl system, so there is no need to get Perl set up before trying it. Everything seems to work for me with this version. Any ideas on what is necessary would be helpful!

Asking for help

I get quite a few e-mails asking for help with my packages, and also spot a few questions in various public places (comp.text.tex and The LaTeX Community, mainly). I’m always happy to help where I can, and it always makes my life a bit easier if the question arrives with all the information to start with.

One of the things that get repeated by almost everyone trying to help out users is the need for a minimal example. For LaTeX, that typically looks something like:

\documentclass{article} % Or perhaps memoir, beamer, ...
\usepackage{...}
\begin{document}
Example here
\end{document}

ConTeXt examples are not dissimilar, while plain TeX ones need very little at all (but I get very few of these). It’s much faster to supply everything to start with than to send a snippet with key details left out. It’s surprising how many things people simply assume are obvious, when they are not (“Surely everyone uses package wibble”).

Another useful thing to do in advance of sending a query is to send a log file. Again, LaTeX users are normally best advised to include \listfiles in their input, so the kernel makes a neat listing of everything in use (hopefully including the versions).

Often, I get description of either how things should look or why they are wrong, rather than an actual example. If at all possible, a “reference rendering” is much easier to follow. That can be something done in a drawing programme, using some alternative (but awkward) TeX code, or a screenshot of something. Describing things in words (especially if the questioner is not a native English speaker) can be a recipe for a long and painful process.

For questions posted in public, it’s always best to drop me a line so I spot it: I do my best but sometimes I miss things. For places such as comp.text.tex, that can simply be a CC on the posting, or for forums a quick note that says

Hello,

I posted a question about your <whatever> package:

http://some-url-here/

Please take a look.

will make sure that the issue gets me interest.

On the other hand, questions direct to me obviously get straight to the point but miss out on the public record part of a posting to Usenet. The same issues do tend to pop up more than once! Sometimes there is good reason for avoiding public postings: I get questions including unpublished material about achemso, for example. So I’d encourage anyone with an issue they think is general (such as a bug in one of my releases) to post something in public if possible. I always try to follow up postings as well as e-mailing people directly as well.

As I say, I’m always happy to try to help. I hope that most of the time I succeed.

achemso: Cross-referencing to floats

I’ve had a a few questions about the achemso bundle concerning creating references such as “Figures 1 to 3” automatically. The problem has been that I’ve been using the varioref package to turn \ref{some-fig} in “Figure 1” automatically, rather than having to put Figure~\ref{some-fig}. Unfortunately, varioref does not handle multiple references in an automated fashion.

For version 3.4 of achemso (which I’ve just sent to CTAN), I’ve switched to the cleveref package. This means that you can now write something like \ref{fig-1,fig-2,fig-3} and get “Figures 1 to 3” without further effort. I hope that this makes life much easier for users, although it does mean that there is another package required to use achemso. I think that this is the right balance: I’m sure users will let me know if I’ve got it wrong.

PDF Version and file size

The PDF format has evolved over the years as Adobe have released new versions of their Acrobat and Reader software. New ideas have been added to the file format, and as a result there are different versions of the PDF format. If you take a look at a PDF in Adobe Reader, you can see which version the file is using in the Document Properties information. Of course, files using the newer versions of the PDF format need a suitable viewer, be that Reader or something else.

This is relevant to TeX users as PDF tends to be the target format, either directly or via DVI files, for many users. Tools such as pdfTeX are not tied to one version of the PDF specification. For example, when creating a PDF directly with pdfTeX the \pdfminorversion primitive can be used to set the PDF version to 1.3, 1.4 or 1.5.

Why would you want to do this? Well, obviously the newer versions bring new features. A particularly significant one is the compression of non-stream objects. The detail of these objects is not really important, but they relate to items such as links within documents. Version 1.5 of the PDF specification allows these to be compressed, which can make quite a difference to the resulting file size. For example, I did a trial run with the siunitx manual, and by adding the lines

\pdfminorversion=5
\pdfobjcompresslevel=2

resulted in reducing the file size from around 700 KiB to around 550 KiB, a saving of roughly 20 %.

There is some discussion ongoing at the moment on the TeX Live mailing list about possibly changing the default PDF version produced by tools such as pdfLaTeX, XeLaTeX, etc. The current standard setting is version 1.4, which makes larger files but does have the advantage of being readable by a wider range of viewers. On the other hand, PDF version 1.5 was first released in 2003, and there is pretty good support for it in most of the well-known readers. As long as switching to version 1.5 also enables the compression, this looks like a good idea: just moving to version 1.5 without using the features available seems a bit odd to me.

There are times where you need to use PDF version 1.4 (for example for archive-type PDFs), but for those you also need to check other features of the PDF. So I feel that the change looks like a good idea, provided there is a good way to set the version to something else.

Chemistry journals: publishers support of LaTeX

As the author of the achemso bundle (for supporting submissions to the American Chemical Society), I get a few queries about the support various publishers provide for LaTeX. Unlike more physics-focussed journals, the chemistry journals never typeset directly from authors LaTeX sources. As a result, the acceptance of LaTeX material from authors is rather less popular, and tends to be patchy. So I thought I’d summarise things as I currently understand them.

American Chemical Society (ACS)

As I said above, I’ve written the achemso bundle specifically for submissions to the ACS. However, while the central office are happy to host a copy on their website and so on, the ACS don’t officially support the bundle. That means, in practice, that some journals are happier with LaTeX submissions than others. Each journal has its own office, and so I hear different things from people submitting to different journals. It also means that I have to pick up the requirements of each office based on feedback via authors, rather than getting any formalised instructions. There are mistakes in the achemso bundle, and there are also requirements that I don’t know about. So feedback is always useful (good or bad).

Royal Society of Chemistry (RSC)

The RSC have rather less information about LaTeX on their website than the ACS. They do mention TeX, but only very briefly. I’ve written some BibTeX styles, and a very basic article template, which are available in the rsc bundle. I’ve had a bit of feedback on these, and I hope that they at least provide a starting point for writing a submission to the RSC in LaTeX. More generally, I think the best advice is to check with the editorial office for the relevant journal before writing anything, and to stick to the basic LaTeX article class when you do.

Wiley

As with the RSC, Wiley don’t have a lot of LaTeX information. What they do say is that they only accept PDF submissions: you can’t send your source. They also say to stick to the plain article class, and basically to keep things simple.

Elsevier

Elsevier have recently had a new class written for journal submissions, elsarticle. From what I can make out on their site, you can use this for most of their journals, which should include the chemistry ones. As this has actually been written for them to order, I imagine that Elsevier is the best place to be sending LaTeX submissions to. Hopefully other publishers will see that they have made life easier for their authors and will take note.

pgfplots v1.3

A new version of the very useful pgfplots package has been released. pgfplots provides a very handy interface on top of pgf/TikZ to generate print-quality plots without too much effort. As many readers will know, pgf works with both DVI and PDF output methods, making pgfplots very handy for generating plots without worrying about other content.

For me, the stand-out new feature in v1.3 of pgfplots is the ability to automatically reverse the axes. As a chemist, I need to do this as convention dictates that some types of data are displayed with the x axis running from high values to low ones. So for me not having to do this by hand is a really significant reason to upgrade. There are lots of other new features as well: I see that the manual now includes a number of 3D surface style graphs, which many people like.

If you are plotting data in TeX, the pgfplots should be very high on your list of packages to consider.

siunitx performance (again)

My previous post mentioned some efforts to improve the performance of the siunitx parser. I’ve now committed an entirely new version of the parsing code to the repository. I’ve also done my best to speed up the rest of the package. The speed you see very much depends on the type of input involved. With my test file, I got a time of roughly 3 minutes using version 1 of siunitx, about 2 minutes before improving version 2, and about 1.5 minutes after. For comparison, doing no processing at all take the time down below 10 seconds for the same file (roughly 700 pages of repeated input). For the interested reader, an siunitx snapshot TDS-style zip is available.

One thing that I find interesting in all of this is that even before optimising the code, version 2 still worked faster than version 1, even though it does more things. A lot of that is because the pre-built looping material in expl3 does a much better job than my own attempts in version 1 of siunitx. Of course, good programmers will always use fast loops, but for the rest of us I think this shows how a sensible tool-kit can bring benefits “behind the scenes”.