Schnee (schnee) wrote,

TeXstudio, nomencl and arara (and Perl)

Another thing that TeXstudio sadly lacks is built-in support for the nomencl package's workflow. This package requires an extra run of makeindex (with certain parameters) in between two LaTeX runs to generate the data file used for the nomenclature section; there was a feature request to integrate this eight years ago, which was curtly denied by a developer.

Failed attempts to integrate nomencl and TeXstudio

There is a suggestion to use user commands, of course. To do this, go to Options › Configure TeXstudio › Build; in the "User Commands" section, Click on the "Add" button to add a new command. In the left text input field, put "nomencl:Nomenclature" or so (left of the colon is the internal identifier of the command, to the right is the command's user-facing name); in the right input field put "makeindex.exe %.nlo -s -o %.nls". So far, so good; the command's now available as Tools › User › Nomenclature.

Of course you don't want to have to remember to run this whenever you add nomenclature to your document; it should be automatic, part of the compilation process. So you might add it to the "Build & View" command; under Options › Configure TeXstudio › Build again, you might update the "Build & View" command to execute the following "txs:///nomencl | txs:///compile | txs:///view".

But there's three problems.

First of all, you may not want to run makeindex to generate nomenclature data for every document; they don't all use the nomencl package, after all. What's more, you may not want to give nomencl special treatment that other tools like biblatex etc. don't get either.

Finally, and this is the biggest issue, it may simply not work. If your TeX document uses a magic comment to indicate which engine it should be processed with, e.g. "%!TEX TS-program = xelatex", TeXstudio will ignore the default Build & View command and use whatever you specify instead.

Now, you might think you could use this to your advantage: create another user command, e.g. "xelatexnomencl:XeLaTeX and Nomenclature", have it invoke "txs:///xelatex | txs:///nomencl", and then put an appropriate magic comment such as "%!TEX TS-program = xelatexnomencl". But this doesn't work; TeXstudio will complain, saying "%!TeX program not recognized! (xelatexnomencl). Using default." (if you use "Compile") or "Error: Could not start the command: xelatexnomencl" (if you use "Build & View").

Enter arara

The solution I've found is to use arara. It's not obvious from the name, but this is a tool that'll allow you to specify, in a document what commands need to be run and in which order to process it correctly. Having done this once, you then only need to process the document in question with arara, and you're set.

You'll want a user command again for this, so do as described above, create a command named "arara:Arara" or so, and have it run "arara %.tex". To make it more accessible, go to Options › Configure TeXstudio › Toolbars; select the "Tools" toolbar in the left dropdown and "All menus" in the right one, then expand "Tools" and "User" in the right pane and move over the "Arara" menu item to the left pane. Drag it to the preferred location (I like having it at the top, i.e. leftmost in the toolbar), and right-click and select "Load Other Icon" from the context menu to assign it a different icon. (TeXstudio does not seem to give you access to its internal icons, so maybe just find a nice picture of a macaw. Personally, I used pdfimages(1) to extract one from the arara documentation.)

Now all you still need to do is put arara's magic comments into your document, e.g.

% arara: xelatex
% arara: nomencl
% arara: xelatex

Compile the document by clicking on the arara toolbar button, and it should Just Work&tm;. You won't have to remember what tools to invoke for which document in which order; it's all in the document. And what's more, your regular build/... workflow isn't affected, so you can choose to use arara or not for each new document, or even choose to mix build tools (e.g. if you know you've not changed your nomenclature).

A note on Perl

You may or may not find that running makeindex and friends will throw this error:

The script engine could not be found. 
Data: scriptEngine="perl.exe"

When this first happened to me, I installed Strawberry Perl (the best Perl distribution for Windows). Yet the error persisted in TeXstudio, even though invoking makeindex manually on the command line worked just fine.

I managed to solve it by configuring an appropriate search path in TeXstudio. Go to Options › Configure TeXstudio › Build again. At the bottom of the window, you'll see two fields for entering "Additional Search Paths". See the tiny little scrollbar on the right? Scroll down, and you'll find a third field, previously hidden, labeled "Commands ($PATH)". Put "C:\Strawberry\perl\bin" here, assuming you installed Strawberry Perl to C:\Strawberry (adjust accordingly otherwise). Great UI design this ain't — but after making this change everything worked for me.

A closing thought

The arara manual, in its prologue, says "Writing software is easy. Writing good software is extremely difficult". That's very true, and TeXstudio is a good example of that, IMO.

Don't get me wrong, I like the program, and I think it's the best LaTeX IDE that there currently is. But it's got its warts – fair enough, all programs do –, and the developers' apparent aversion to integrating tools because a (complex, complicated, difficult-to-implement, unsatisfactory, or just-plain-not-working) solution exists is dismaying. As with much other free software, the developers don't seem to understand (or care) that software is primarily a tool allowing you to get work done. Making a tool configurable is good — but it's no excuse for not endowing the tool with good, built-in support for users' workflows. And understanding users' workflows and requirements is important. The more easily and quickly users can get their jobs done, the better.

Tags: latex, software

Recent Posts from This Journal

  • Icelandic is cool

    Just spotted this over on OCremix: I think that should be " veiðigyðja fjallanna" instead — Icelandic doesn't work like…

  • How democracy should work

    From Allan J. Lichtman, Predicting the Next President: The Keys to the White House (2020 Edition), p. viii–ix: A properly functioning…

  • Blade Runner: San Francisco

    It's exactly what it says on the tin: Impressive — just wish it was longer. (H/t to canisrufus_uk BTW.)

  • Post a new comment


    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded