The TDS and TDS zip files

In my post about working with dtx files, I made the somewhat throw-away statement

The idea of a TDS-ready zip is also popular …

I’ve been pulled up on that by e-mail, so I thought I’d consider this a bit more before looking at automating working with dtx sources.

First, what does ‘TDS’ mean? The short answer is TeX Directory Structure, but that does not really help. The idea of the TDS is to have a standard layout for the location of TeX files, so for example LaTeX .sty files go inside tex/latex/ (or more likely tex/latex/<package>/), while BibTeX style files (.bst) go inside bibtex/bst.

That’s important as both TeX Live and MiKTeX use a database to locate files, and only scan the ‘correct’ parts of the TeX installation when building the database. So if you do a local file installation and put the file in the wrong place TeX won’t find it. The result is that you need to lay things out properly if you’re installing TeX files, which can be confusing if you’re not familiar with the idea.

The TDS zip idea is very simple: rather than having just the source files in a zip, set up the documentation, extracted package, source and so on in the correct layout. The end user can then just unzip the TDS zip inside their local TeX directory to install a package (of course, they’ll still need to run texhash). As a package author, sending a user a file they can just unzip and use is much faster in the long run than sending them a bunch of files with a list of installation instructions on where everything needs to go.

The downside of the system is that the TDS zip has to be built in the first place, by the package author. With a batch script or Makefile for doing releases, that’s not an issue, but it is if everything is being done by hand. Mistakes can be a problem (even with a script, if you get it wrong!).

One argument against needing TDS zips is that both TeX Live and MiKTeX update very regularly, and so it’s easy to install a package from CTAN using the package manager of your TeX system. However, not everyone is using a burning edge system. Many Linux systems are still on TeX Live 2007, and on multi-user systems the TeX system is probably fixed by the administrator. So doing local installations is still a reality for a lot of people.

Over all, I think the idea has merit, but as a package author you do need to put in some effort to get things ‘right’. I’ll be talking about some scripting in my next post, and hopefully the ideas there will show how things can be done reliably. The overall aim is to make life easier for non-experts, and if that means a bit more effort for the more experienced TeX users then I think the trade-off is not too bad. I don’t expect everyone to agree with me!

Cross-platform working

As many people will know, the CTAN team have come up with the idea of having TDS-ready zip files for packages. The idea is that you can just download the zip into your local TeX directory, unzip it and run texhash, with no TeX-based unpacking or document compilation.

That’s all fine when it works, but I’ve recently had a bit of trouble making zips at my end. My favoured tool for doing that has tended to be 7-Zip. However, it was pointed out to me last week that the resulting zip files are not quite right. On Unix systems, the command unzip -xa will convert line endings to the system convention (LF only), even if they come from Windows (LF-CR endings). However, this requires that the zip identifies text files, and 7-Zip marks everything as binary!

I did a bit of hunting around, and found Info-ZIP, where after a bit of hunting about you can find zip and unzip binaries for Windows. These give me Unix-like capabilities on Windows, so I can make the appropriate files, alter line endings on zipping/unzipping and check the results.

That led me to take another look at the batch file I use each time I release something to CTAN: doing it by hand is an unreliable business! I’ve reworked it quite a bit, to generalise everything and also add a few tweaks. For anyone interested, the file is available here. It’s called make, so that you get Unix-like abilities on Windows. The file has to be customised for each package I write, but most of this version is generalised, and can be altered using a few settings.

set AUXFILES=aux cmds dvi glo gls hd idx ilg ind ist log los out tmp toc
set CLEAN=bib bst cls eps gz ins cfg pdf sty tex txt zip
set DOCEXTRA=\AtBeginDocument{\OnlyDescription}
set INDEXFILE=gglo
set PACKAGE=achemso
set PDF=%PACKAGE%
set TDSROOT=latex\%PACKAGE%
set TEX=achemso-demo
set TXT=README
set UNPACK=%PACKAGE%.dtx

Anyone at all familiar with batch files will see that this is a block of environmental variables: in this case, these are the settings for my achemso package. Most are pretty obvious settings, but in case anyone wants to use the file for their own purposes:

  • AUXFILES File types to delete after every run: throw away files.
  • CLEAN File types deleted only if make clean is run: useful stuff.
  • DOCEXTRA Inserted when creating documentation, can be anything. I don’t typeset the code for my packages in the release documents, hence the \OnlyDescription setting.
  • INDEXFILE This is always gglo for documents using the ltxdoc class, but is l3doc if using the LaTeX3 class l3doc.
  • PACKAGE Pretty obvious, the bundle name!
  • PDF The names of PDF files to add to the documentation part of a TDS zip. By having this as a setting, special effects (demo documents, for example) are possible.
  • TDSROOT. Almost always as given for a LaTeX package.
  • TEX A list of .tex files to copy into the TDS archive: to avoid any testing files, not all .tex files are copied.
  • TXT The names of text files to copy to the documentation directory
  • UNPACK The file(s) to run to unpack the package. I use .dtx files that are self-extracting, but the traditional method is to have a separate .ins file.

If the batch file proves useful to enough people, I might write some proper documentation and do a bit more generalisation.

With all of that in place, I can hopefully keep Unix-based LaTeX users happy without too much work!