LaTeX Alive

Use of § in refstyle

Sun, 05 May 2013 17:05:59 +0930

I’m a big fan of the refstyle package. (Before I knew it existed, I started writing something similar myself. I’m glad I found refstyle before it was too late!)

The refstyle package automates the use of cross references; while vanilla LaTeX would have us write Figure~\ref{xyz}, this is written in refstyle as \figref{xyz}. Far more flexible and this syntax lends itself to many clever extensions such as referring to ranges of figures with \figrangeref or multiple individual ones using comma-lists. (And sections, and chapters, and equations, etc.)

From memory, The LaTeX Companion does not mention refstyle; I don’t recommend the use of prettyref or fancyref these days, as they’re both very limited in comparison. There is a rival to refstyle named cleveref which I have not used; it has been actively developed for a number of years and is worth checking out.

I’ll talk about refstyle’s syntax vs cleveref another day, perhaps. If we were to chose one of them to emulate for a LaTeX3 package, which would we choose? I do not know. We’re not at that stage now, so I’ll put off thinking about it.

What I do want to discuss here is the use of the section sign, §. By default, writing

see \secref{foo} for foo and we know about bar already (\secref*{bar}).

results in the output

see section §1 for foo and we know about bar already (§2).

In this case, I’m (ab)using the default appearance of the section sign to use \secref* as a ‘short reference’ that’s nice and tidy within parentheses, while preferring to spell out ‘section’ explicitly in text within a sentence.

My PhD supervisor has pointed out to me, however, that writing ‘section §1’ is like writing ‘section section 1’ — not really the thing to do. Luckily refstyle provides hooks (namely, \ifRSstar) that allow us to define a reference that defaults to ‘section 1’ but shifts to ‘§1’ when the star form is used.

In the configuration file that defines the refcmd for sections, simply write

refcmd  = {\ifRSstar\S\fi\ref{#1}},

and we’re all set.

(At the same time, I switch all of the lowercase alternatives to uppercase so that cross-references are always ‘Section 1’ and so on — this is probably a regional preference.)

Removing subsection numbers in a ToC

Wed, 10 Apr 2013 16:57:37 +0930

Very behind on taking care of the Herries Press packages (PDF) which I’m maintaining. Apologies to all who have emailed with suggestions, comments, and questions, and to whom I’ve unfortunately not been able to respond.

Funny request today: how can I remove subsection numbers from the Table of Contents without removing their entries altogether? LaTeX’s tocdepth counter controls which entries will appear in the ToC, but has nothing to say about their formatting. Adjusting LaTeX’s ToC formatting yourself is of course possible, but the tocloft package makes things a bit easier.

Still, in this case it doesn’t provide an easy interface, since who in their right mind would want to number a subsection but not include that number in the ToC? (You can’t fight stylistic decisions like this sometimes—just go with the flow.) Even with tocloft, it’s still necessary to write some internal code — and caveat emptor as always in such a case because you never know when the package might change its internal commands behind your back!

In this case, the trick is to read the tocloft documentation and notice that it provides hooks for inserting material before and after the number of a section entry in the ToC. For subsections, these commands, respectively, are \cftsubsecpresnum and \cftsubsecaftersnum. E.g., write

\renewcommand\cftsubsecaftersnum{!}

to have a bang after every subsection number. (Presumably, a style or spacing change would be more common here.)

Aha! The intrepid LaTeX programmer at this point might suggest something like this:

\def\cftsubsecpresnum#1\cftsubsecaftersnum{}

That is, when the pre-hook before the number executes, read everything up to and including the after-hook, and do nothing with it. (If the definition was {#1} instead, then it would typeset as usual.)

Well, give it a try like I did, and you’ll discover it fails miserably. Back to the drawing board—time to read the package source. The issue stems from the fact that LaTeX uses one command only to typeset each line of a ToC, so this command must be completely general whether it’s a chapter or section or subsection that it’s dealing with.

Internally, the number in the ToC is typeset using something like

… \@cftbsnum « the number itself » \@cftasnum …

where \@cftnbsum and \@cftasnum are \let equal to their appropriate high level definitions \cft…presum and \cft…aftersnum as necessary for the context. Therefore, any look-ahead-and-gobble command must be defined specifically to look ahead for the internal version of the hook rather than the high-level name for it given in the documentation.

Et voila:

\usepackage{tocloft}
\makeatletter
\def\cftsubsecpresnum#1\@cftasnum{}
\makeatother

I still don’t think this is very useful, but it’s a nice trick.

Hooks are funny in this way. If you define them to be defined by commands with an argument, such as

… \cftsubsecsnumhook{ « the actual number here » } …

it’s hard to do parsing on it that involves scanning ahead for the contents of the number. On the other hand, in this case where the hook has the form where it’s surrounded by a pre-hook and a post-hook, it’s hard to grab the whole argument and do something with it since the internal post-hook might not be very user-accessible, as in the example above.

I don’t know if there’s a way to structure hooks in any better way, however. One possibility I can think of would be to have a generic ‘end hook’ token that could always be read until, such as

… \cftsubsecpresnum « the actual number here » \cftendhook \cftsubsecaftersnum …

where \cftendhook was simply a no-op. There would be some subtle issues with nesting that would be somewhat painful to work around.

Maybe it would be better to have the number braced as an argument and instead of having \cftsubsecpresnum be a no-op by default it could be an identity function: (\def\cftsubsecpresnum#1{#1})

… \cftsubsecpresnum { « the actual number here » } \cftsubsecaftersnum …

Does anyone know of any best practices here?

New babel release on CTAN

Mon, 01 Apr 2013 17:17:00 +1030

In May 2012, Javier Bezos wrote the following message to the LaTeX-L mailing list:

> Babel gets back on track and it is again actively maintained. The goals are mainly to fix bugs, to make it compatible with XeTeX and LuaTeX (as far as possible), and perhaps to add some minor new features (provided they are backward compatible).

> No attempt will be done to take full advantage of the features provided by XeTeX and LuaTeX, which would require a completely new core (as for example polyglossia or as part of LaTeX3).

In November of that year, a new alpha release was uploaded to CTAN, and in January 2013 a beta release was made. In the change notes to the beta, Javier wrote:

> I hope the final version will be available by March/April.

Well, as of a few days ago, version 3.9b of babel is now available on CTAN. Read more about the release at Javier’s website.

It’s been around five years since the last update by Johannes Braams, who was babel’s original developer and who maintained it for many years, pre-dating my involvement with the TeX world. (Indeed, Javier himself has been a contributor to the LaTeX community longer than I.)

Babel has had a bit of a funny role in LaTeX, as it is not strictly an integral part of LaTeX2e itself, but until recently was tightly knit into LaTeX2e’s development. With active development of babel required to fix bugs and provide (some) support for XeTeX and LuaTeX, it was no longer appropriate to keep babel as part of the LaTeX2e release cycle.

Congratulations to Javier for continuing babel and successfully releasing an important new version. It’s people like this that keep the LaTeX world relevant in what seems like a quickly changing world.

It’s difficult to give up code you’ve lived with for many years, and I know it must have been a hard decision for Johannes to pass on the reigns to another. I know this because I’m staring at the prospect myself, with hundreds of unread emails from the last eighteen months, many of which are questions and suggestions on many of the LaTeX packages I maintain.

I’m not ready to give them up myself, but I will need to work hard this year to get back on track. I use people like Javier as inspiration to keep on shipping.

New version of pstool

Thu, 07 Feb 2013 12:23:18 +1030

Somewhat to my surprise, I have a new version of pstool to release. This is a LaTeX package I maintain that provide an easy workflow (I hope) for including psfrag graphics into pdfLaTeX documents. This allows, say, graphs from Matlab or Mathematica to be presented with fonts matching your document and using macros defined in your main preamble.

For context below, here’s a brief run-down of how it works. As a graphic is requested in the main document (using \psfragfig or similar), a check is made whether it has been converted into PDF in a previous compilation (and the source graphic hasn’t been updated in the mean time). If so, it saves some time and simply loads that graphic. If not, an entirely new LaTeX document is created with the preamble of the main document, but which otherwise contains only the graphic that needs to be processed. This document is run through the regular (‘old-fashioned’) latex → dvips → ps2pdf compilation workflow, which performs the wanted psfrag substitutions (and any other PostScript-based processing) and the final figure is cropped to size. Execution returns back in the main document and the PDF graphic can be inserted directly, and the compilation of the main document continues as normal.

The pstool package been invaluable to me in preparation of my PhD thesis, but I haven’t had the opportunity to work on the code for a long time. In fact, I discovered some code I’d written for it from 2010 (see below) that I’d never released to CTAN. Why a new package now, then? Because I hate it when my code breaks and wastes people’s time.

Windows ps2pdf breaking

Some time back, the maintainers of ps2pdf changed the way that options were passed on the command line under Windows, so where previously pstool was writing something like

ps2pdf "-dPDFSETTINGS=/prepress" "foo.ps" "foo.pdf"

to generate the PDF file from the psfrag-generated PostScript file, the default settings were now terribly broken for recent users of MiKTeX, causing their documents to fail to compile. The syntax which now works correctly is

ps2pdf -dPDFSETTINGS#/prepress "foo.ps" "foo.pdf"

Note # instead of = to set the options. In order to fix the issue, I decided to separate the fix from the user-level interface to pstool, which can set ps2pdf options with syntax like

\usepackage[
    ps2pdf-options={-dPDFSETTINGS=/prepress}
]{pstool}

Rather than requiring users to know to replace the = with \# (remembering that # is a special character than needs to be escaped), pstool automatically replaces all equals signs in the ps2pdf options with hash characters. This provides some level of platform-independence so that documents will compile correctly whether on Windows, Linux, or Mac OS X. Of course, it will still work correctly for Windows users that write \# anyway.

More robust preamble scanning

The second feature (and this is the code that was written in 2010 but never released) is a more robust scanning method for copying the main document’s preamble into the preamble for each externally processed graphic. In prior versions of the package, this was achieved by redefining \begin{document} but this method broke whenever a class or package did their own redefinition. The command \EndPreamble was provided to manually indicate where the preamble should end, but users would usually run across the error and not know where to look to fix the problem.

The changes for this feature are all internal and shouldn’t be noticeable if the code is working correctly; \EndPreamble still works for the cases where you don’t need the entire document preamble to be replicated for each graphic.

Cross-references and citations supported

The third major change for the new version of pstool is to support cross-references and citations in externally-processed graphics. This has been on my wish-list for some time, as I know that some people have used references and citations in their figures and graphs, and have had to use Rolf Niepraschk’s pst-pdf (or my wrapper package auto-pst-pdf) in this case. That solution is fine and perhaps still preferable in many cases, but if it could be done in pstool then I wanted to try and support it if possible.

It wasn’t entirely straightforward, but I think it now works. The short of it is: the main file’s .aux and .bbl files are now copied over for each graphic’s external compilation; the current page number is passed into the external graphic; and anything written to the .aux file by the external graphic is copied back into the main document’s .aux file. Copying the .bbl file is only necessary to support biblatex use, for reasons I’m still not entirely clear on.

What does this allow us to do now? If you have a document that defines several different equations and plots the results of those equations, it is possible to annotate the figure with the actual equation numbers cross-referenced from the document. Or even include a citation in the graph for some method that was described in another paper.

However, there’s a downside to all of this, which is that pstool graphics require multiple passes to resolve any cross-referencing. And this is not possible to detect automatically (well, it may be theoretically possible but I don’t think it’s easy). So the old approach of pstool to check the PDF and update the graphic only if necessary fails for those which use cross-references; in these cases, it is necessary to force their generation manually until everything resolves. This can be done on a per-graphic level by using \psfragfig*, or on a document level by loading the package with the [process=all] option.

This new version is still being tested on GitHub (please check it out if you’d like to help!) and I hope to upload it to CTAN in the next few days. I hope this release marks the beginning of somewhat of a return to the LaTeX community for me — last year was tumultuous for many reasons and I hope I can now re-dedicate some time every week.

Famous last words.

Here’s a photo I took of Donald Knuth at the TUG 2010...

Thu, 03 Jan 2013 16:08:05 +1030

Here’s a photo I took of Donald Knuth at the TUG 2010 conference during his “Earthshaking Announcement”. I’m not sure exactly how it has been distributed (perhaps Facebook) but I see it’s now floating around the internet. I’m not a big stickler for attribution in this case—I’m quite happy the photo turned out this well at all, let alone good enough for others to use. In any event, I thought it would be a good idea to clear up who the original author of the photograph was.

For future reference, I’m happy for my photographs to be freely used with attribution. Should really start making more of them public…

TUG 2012 in Boston

Mon, 28 May 2012 00:42:55 +0930

This year’s been a bit of a rollercoaster for being busy and trying to make decisions. After flipping-flopping over the last six months, I’ve decided at the last minute to attend TUG 2012 in Boston in July. (Thanks to Steve Peter, president, for the gentle nudge that finally sorted me out.)

TUG is the annual conference of the TeX Users Group, and I attended it for the first time in San Francisco in 2010. It was the best conference I’ve been to, and I’m expecting to have a great time in Boston as well. I’ve barely been to the east coast of the US, so I’m excited to explore the city in the days around the conference.

For my presentation, I’ll talk about LaTeX3 from a fairly high level, why it exists, why I work on it, and other assorted aspects of my somewhat-dormant TeX work. (Spoiler: without LaTeX3 I wouldn’t have been able to develop unicode-math; it would simply have been too much work.) If there’s anything in particularly you think I should address, feel free to drop me a line beforehand.

If you yourself are attending the conference, please say hi. What do people like to drink in Boston? I’ll buy you one.

Lucida Math OpenType As part of the next incarnation of the...

Mon, 05 Sep 2011 01:36:15 +0930

Lucida Math OpenType

As part of the next incarnation of the Lucida typefaces, I’ve been testing out the OpenType versions of the maths fonts.

It’s fair to say that most people will have seen a Lucida font in one form or another. Lucida has been very popular in the past as one of the very few commercial and unique maths fonts for TeX. It is a super-family of fonts with more font faces than I’m aware of in any other such collection, including serif, sans serif, typewriter, script, blackletter, handwriting, casual, fax (a sturdier serif), and symbols or wingdings. It has been distributed very widely on various computer systems, with Lucida Grande used in Mac OS X itself (the menu font, among other uses), and Java and Windows shipping the standard serif/sans/mono trio for many years.

For more information about the Lucida fonts and their new release, Ulrik Vieth and Mojca Miklavec have just published a TUGboat paper with all the gossip. (Link accessible for TUG members only until it becomes open access in one year.) Further information can also be found on TUG’s own site for the font and an overview of the fonts written by the font designers, Charles Bigelow and Kris Holmes.

Due to my particular interest in Unicode maths, I’m especially excited to see a new OpenType maths font on the scene. I like to think that we’re entering into somewhat of a golden age of maths font design, as OpenType provides a mechanism by which both TeX users and GUI apps such as Microsoft Word can use them; in times past, it was simply rarely worth the expense of creating a new TeX maths font and this is evident by the relative paucity of them.

After the Lucida release later this year, available OpenType maths fonts will include:

Latin Modern Math (1347)
XITS Math (2428)
Cambria Math v1.0 (1592)
Lucida Math (1947)
Lucida Math Demibold (877)
Asana Math (2240)
Neo Euler (411)

shown with approximate symbol counts for each font (based on symbols defined in unicode-math, not by literal glyph count). The STIX fonts are the reference, here, and contain the largest number of symbols; I believe recent versions of Cambria Math have more than is listed above. But what is impressive to see is that not only does Lucida have a large glyph coverage already, but it will also be provided with a ‘bold’ version of the font as well and, as far as I know, will be the first OpenType maths font to offer this.

To facilitate the use of the bold font, unicode-math can now load multiple maths fonts simultaneously through LaTeX’s \mathversion command (although this new feature hasn’t been widely tested), which is shown in the image above. Note in the image above the integral sign for the bold example isn’t scaling yet; this will be rectified of course for the release version of the fonts.

I’m very pleased to be able to play whatever small role I can in bringing these fonts to new audiences. Many thanks to Charles Bigelow and Kris Holmes for working on the new fonts and everyone involved in the OpenType transition but particularly the seemingly tireless Khaled Hosny. Great work!

Non-textual tabular requirements I once wrote a procedure for...

Tue, 29 Mar 2011 19:36:56 +1030

Non-textual tabular requirements

I once wrote a procedure for drawing tabulars with square cells; it was one of my earliest experiences with LaTeX programming, actually. When I’d done so, I received a comment ‘why doesn’t LaTeX allow this easily’?

Well, I wondered, why not? My feelings at the time (echoed a little today) were that LaTeX is a tool for writing largely technical documents, and such specific requirements fall outside its regular bounds of ways to typeset tabular material. (Forget, for the minute, that LaTeX’s tables are pretty ugly by default; I’m assuming everybody uses the booktabs package.)

I still agree with the author of booktabs on this matter: ‘It is not going too far to say that if you cannot create a table using the commands in this package, you should redesign it.’ However, I do admit that things like tables with coloured rows and so on do have their uses.

Just recently Karl Berry mentioned he wanted to typeset a grid of images with a large image in the centre. (Not unlike what you see at the top of the page. Just replace the coloured boxes by real images.) This isn’t something that LaTeX does out of the box, and I’m not sure, actually, if any third package can do it either. (I tried but failed with multirow.)

Spurred on by the requisite ConTeXt example that ‘just works’, my own attempt to implement this arrangement turned out to be quite easy but not exactly straightforward. Let me know if there’s a better way.

First of all, the input syntax:

\begin{tighttabular}{@{}c@{}c@{}c@{}c@{}c@{}c@{}}
\1&\1&\1&\1&\1&\1\\
\1&\1&\1&\1&\1&\1\\
\1&\1&  &  &\1&\1\\
\1&\1&\9&  &\1&\1\\
\1&\1&\1&\1&\1&\1\\
\1&\1&\1&\1&\1&\1\\
\end{tighttabular}

Notice that my approach simply puts the material in the lower-left cell in order to fill in the space taken up by the others. This would not work if the cells were of unknown and uneven sizes.

The definition of tighttabular is easy; just define \arraystretch to zero, locally:

\newenvironment{tighttabular}{%
  \def\arraystretch{0}%
  \begin{tabular}%
}{%
  \end{tabular}%
}

How do we place material in that box \9 so it comes out with the correct alignment? Actually, it’s not that bad:

\def\9{%
  \rlap{\smash{\largebox}}%
}

The \rlap first removes the horizontal width, and the \smash removes the vertical height. This is done so that the cell that holds \9 takes up only the same amount of space as the other cells around it. (Otherwise, they would stretch to fit, distorting the size and alignment of the tabular.)

Finally, what is \1 and how do you get the colours to do that?

\def\1{\smallbox}
\def\smallbox{\color{blah!!+}\rule{2cm}{2cm}}
\def\largebox{\scalebox{2}{\smallbox}}

(\scalebox requires the graphicx package.) These boxes use the xcolor package’s very convenient ‘colour series’ feature:

\usepackage{xcolor}
\definecolorseries{blah}{hsb}{step}[hsb]{.5,1,1}{.1,-.05,0}
\resetcolorseries{blah}

And that’s it. Whether you think this whole approach is nice and straightforward or horribly arcane will be somewhat of a personal decision. We’re still awaiting the one tabular package to replace all others in the LaTeX world, although I’m pleased to see recent efforts moving towards providing a complete interface to the different methods supported by the various LaTeX third-party packages in this area.

(With my LaTeX3 hat on: no, as far as I know we’ve not even begun thinking about how this might be dealt with there. I’m not an expert in this area. Although I will say that I mildly dislike both LaTeX’s & and ConTeXt’s \bTR…\eTR syntax; for me, the former is too close to the metal and the latter too verbose.)

fontspec missing font error

Sun, 27 Feb 2011 18:24:24 +1030

The latest version of fontspec now returns proper error messages when a font cannot be found:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
./small.tex:6: 
! fontspec error: "font-not-found"
! 
! The font "Ggeorgia" cannot be found.
! 
! See the fontspec documentation for further information.
! For immediate help type H <return>.
!...............................................  

l.6 \fontspec{Ggeorgia}

? H
|'''''''''''''''''''''''''''''''''''''''''''''''
| A font might not be found for many reasons.
| Check the spelling, where the font is installed etc. etc.
| 
| When in doubt, ask someone for help!
|...............................................

The wording might not be optimal, but having something to explain what’s going on here has been missing for a long time!

The ASCII-art ‘design’ of these error messages comes from work we’ve been doing in expl3 trying to make the console output a little more attractive. It’s not an easy job working around TeX’s idiosyncrasies here, but I’m quite happy with the final result.

KenKen in LaTeX etc.

Wed, 23 Feb 2011 19:34:33 +1030

The latest issue of the PracTeX Journal (discl.: I used to be a production editor there some years back) contains a set of interesting challenges: typeset and solve a KenKen puzzle. I haven’t seen this puzzle before; it looks fun for those of you who like this sort of thing. I encourage all with the time to attempt at least some of the problem—it looks fun!

In 2008 TPJ issued a similar challenge for Sudoku. At the time I didn’t think anyone would implement a complete Sudoku solution in TeX but I was astonished and happily surprised when two solutions were forthcoming.

It’s good to remember that almost anything can be done in TeX macros if one tries hard enough. In this theme, my favourite example of ‘why not?’ when it comes to theoretically-possible but rather-quite-difficult problem solving in TeX is from the late Michael Downes’ series of ‘Around the Bend’ problems. (Peter Wilson created a wonderfully typeset version available, in a TeX Live distribution at least, via ‘texdoc AroundTheBend’.) See chapters 10 and 11:

Using as few lines of TeX code as possible, set up an Around the Bend post containing a typical exercise so that it can be processed by plain TeX to (a) skip over the exercise text and (b) decode an embedded encoded answer.

It’s a fascinating idea to encode and decode text in TeX itself (of course with LuaTeX around now such ‘problems’ are little more than academic); as far as I know, however, such tools were never exploited for robust text passing to/from other formats. (E.g., inside PDF metadata where data should be encoded correctly.)

And surely everyone reading this has seen David Carlisle’s xii.tex before, right?

Trends in recent years for texhax and the Mac OS X TeX mailing...

Tue, 15 Feb 2011 19:13:21 +1030

Trends in recent years for texhax and the Mac OS X TeX mailing lists. And a comparison with tex.stackexchange.com.

Manuel Pégourié-Gonnard asked whether I’d looked at the number of posts to the texhax mailing list when I posted last night about traffic to comp.text.tex. I had considered it, but I ran out of time, then, to scrape the data from the online archives. See above for the newly-gleaned information.

Interesting enough (and perhaps gratifying) to see that texhax traffic has remained constant over the last eight years; the mailing list itself dates back to 1986 but only recent years were available for my primitive data-analysis skills.

I’ve also included the data for the TeX on Mac OS X mailing list, and there the results are a little more noisy. (Note even three months with greater than 1000 posts per month!) The drop-off in 2007 is interesting, because it correlates with the switch from Gerben Wierda’s ‘gwTeX’ distribution to TeX Live as the basis for MacTeX. Gerben’s work in the 2000s was fantastic, and TeX on the Mac would not have thrived as it did without him—but the move to a centralised TeX Live seems to have been the right choice at that time. (Gerben provided the initial support for TeX Live on the Mac, so his work lives on.)

Since 2007 the data for the Mac OS X TeX mailing list is pretty much constant, tracking slightly above texhax in terms of number of posts per month.

I also mentioned yesterday that I think a fair chunk of the traffic to comp.text.tex may have moved to tex.stackexchange.com. The ‘tex.se’ Q&A site officially launched three months ago after a three month beta period. At that time, the site had on average 12.7 questions per day with 2.4 answers being given per question (numbers from area51).

Three months later, being now, the site receives 24 questions per day, and the answer ratio is slightly lower at 2.1 answers per question.

In total, the site currently contains some 3400 questions and 7200 answers: the equivalent of around 1700 ‘posts’ per month (I don’t have exactly numbers to the day for how long it’s been operating). And this rate seems to be increasing, although two data-points is hardly a trend.

Compared to the traffic for comp.text.tex and the mailing lists I’ve shown above, I don’t think you can argue that tex.se is now playing a very important role for TeX support.

With new LaTeX sites around nowadays such as...

Tue, 15 Feb 2011 04:53:58 +1030

With new LaTeX sites around nowadays such as tex.stackexchange.com and latex-community.org, it seems that the comp.text.tex newsgroup, the mainstay of the TeX support world, is in decline.

Newsgroups in 2011 are an anachronism from the younger days of the internet, and access to them is rather more limited than it used to be. Google provides a web interface to them through Google Groups but in recent years it’s slowly been more and more spam-afflicted.

Is this a indication, perhaps, that TeX use itself is diminishing? I don’t think you can really argue this, as posts on c.t.t. hardly reflect consistent usage numbers over time—if newcomers to TeX and friends find Q&A sites like Stack Exchange I think they’ll be far less likely to want to use Google Groups, which is far more clunky with a poorer signal-to-noise ratio.

But it’s still a shame (or perhaps just a nostalgic twinge) to see a community in decline, even while new ones are coming into being. Despite this, the c.t.t. archives are full of valuable information, and even if new postings diminish the group will live on as a historical record of helpful answers. When in doubt, search!

Delayed active characters

Sat, 12 Feb 2011 17:51:00 +1030

Funny problem in mathtools vs. francais babel. (Only a coincidence that I’m debugging two babel problems back-to-back.)

Morten Høgholm’s mathtools package has an option to turn the colon into an active character so that writing := produces a colon-equals sign with a correctly centred colon. (Unicode mathematics provides a specific character for this symbol but the input shorthand is still a convenience.)

But babel’s French module also has a feature with an active colon, and although both mathtools and babel can be otherwise used together without problem, these two features cannot both be active simultaneously. This is a documented problem, and a workaround requires changes to babel to allow hooks into its active characters. (Not going to happen any time soon, in other words.)

Despite the documented incompatibility, there was still something breaking when both packages were loaded, and even when the centred-colon feature was never activated. Turns out we were lazy in mathtools. (To be fair, this portion of the code originated in the depths of time on comp.text.tex.)

Active characters are interesting because they can be switched on and off by changing their catcode, and they remember their meaning the whole time. In mathtools, we were taking advantage of this by writing something like

\begingroup
  \catcode`\:=\active
  \gdef:\fancycolon % not the actual defn.
\endgroup

and in the mathtools option processing, all we had to do to activate the centred-colon feature was to execute

\catcode`\:=\active

and our previously saved definition automatically takes into effect.

Unfortunately, this is a rather inconsiderate way to do things, because it doesn’t take into account the fact that other people (in this case babel) might also want to assign the colon an active meaning. If mathtools is loaded after babel, then the colon is overwritten even though the centred-colon feature is never activated!

There are a few ways that both mathtools and babel could behaviour more sensibly here. But when dealing with catcodes, such clashes are inevitable since there are so few ASCII characters and we always want to simplify the way we write our documents.

TeX’s font-loading optimisation

Fri, 11 Feb 2011 15:18:00 +1030

A user of Peter Wilson’s fonttable package reported an interesting bug in the interaction between it and the Spanish module (if not others) of babel.

Here’s the problem in a nutshell:

\documentclass{article}
\usepackage[spanish]{babel}
\begin{document}
$\lim x_n$
{\font\x=cmr10\x hello}
$\lim x_n$
\end{document}

Can you see the problem? It certainly wasn’t immediately obvious to me.

I probably wouldn’t have had time to work through the problem (after all, it’s clearly babel’s problem, not fonttable’s) but the user that reported the problem had also tracked down the root of it already (thanks!). In Spanish, the maths operator \lim is written as ‘lím’, which requires the use (in 8-bit LaTeX) of an acute accent combined with a dotless ‘i’. And inside the definition for \dotlessi in babel’s Spanish module, you’ll find

\expandafter\expandafter\expandafter
\split@name\expandafter\string\the\textfont\mathgroup\@nil

Note the \split@name command, which takes an NFSS font name such as OT1/cmr10/m/n/10 and split it into its components (resp.: encoding, family, series, shape, size). It’s operating on \the\textfont\mathgroup there, and this is where the problem comes from.

By default in a 10pt LaTeX document, \textfont is defined as OT1/cmr10/m/n/10. In pseudocode, LaTeX originally calls something like this:

\font \OT1/cmr10/m/n/10 = cmr10 at 10pt
\textfont\fam=\OT1/cmr10/m/n/10

(This would not execute without ‘/’ having \catcode ‘letter’.) The problem comes in when someone comes along and writes something like

\font\x=cmr10 at 10pt

Because TeX does not want to load the same font more than once, it optimises its references to font names to point to the last name a specific font was requested with (here ‘font’ means ‘font face + size’).

At this point, the \textfont now points to \x instead of \OT1/cmr10/m/n/10, which causes \split@name to break pretty spectacularly. And this even happens if the font loading happens inside a group:

\font\1=cmr10 at 9pt
{\font\2=cmr10 at 9pt}
\textfont\fam=\1
\showthe\textfont\fam

The above code returns ‘\2’, quite unintuitively. So what can be done about this problem? Let’s assume for now that we can’t change how babel does things (I don’t know the practicality of that in any event).

One way to avoid this problem occurring might be to dynamically check the current ‘values’ of \textfont, \scriptfont, etc., and then not reload the same font under a different name if it’s the same as the font you would like to load. This could be implemented in a wrapper around \font like \newcommand is around \def, and this might be something we look into for expl3.

A less general solution is to simply load the new font like this:

\font\x=cmr10 at 9.9999pt

Because the font is technically at a different size (although the difference is imperceptible), TeX considers it a separate font and will no longer replace its old pointer to \OT1/cmr10/m/n/10 with \x. (I also perform this trick in unicode-math to load the same font with different \fontdimens for assigning to different math groups.)

This is certainly less robust than an explicit check, and will not always be an acceptable solution, but it’s simple to implement in fonttable and serves its purpose there quite well.

In conclusion, due to this fragility in babel (I don’t know if it’s the Spanish module only but it seems likely the problem could occur elsewhere), be careful loading certain fonts with \font unless you are confident it won’t also be used as a maths font. If possible, use the LaTeX font loading interface instead.

Callbacks in LuaTeX

Sat, 23 Oct 2010 19:33:55 +1030

You often hear the term “callbacks” bandied about when reading about new functionality offered by LuaTeX. Callbacks offer powerful functionality, but they don’t have pithy explanation that can easily explain why they’re so useful.

Paul Isambert has written a great example of using callbacks on comp.text.tex, his post prompted by Dan Luecking’s plea:

What is a callback? And don’t tell me to read the manual: it has over 100 instances of the word callback and I gave up trying to find out what they are after examining the first 50 or so instances.

Paul’s reply is here; he hints at an upcoming TUGboat article going into more detail (don’t have a TUG subscription? You should: it’s cheap and furthers the development of TeX and friends), but here’s his opening explanation:

[A] callback is a point where you can interrupt TeX’s normal operations, and throw in some (Lua) code of your own. There are many such points, for many different operations: managing the input buffer, reading a file, loading a font, building a paragraph, etc.

His example then shows a short way to do in LuaTeX what requires rather more fragile and tricky code in regular TeX. Good stuff.

The asymptote LaTeX package

Mon, 18 Oct 2010 21:28:36 +1030

John Bowman has just announced version 2.05 of Asymptote, a 3D programmatic drawing package that uses TeX for typesetting its labels. Asymptote is unique in its ability to generate 3D graphics that can be rotated and zoomed within Adobe Reader, allowing far more interactive graphics for scientific documents.

John has written several TUG papers on Asymptote over the last few years; the latest was for the TUG 2010 conference held earlier this year in San Francisco (the video of John’s presentation is available on River Valley TV). I had the great pleasure of meeting John at the conference; amongst other things we discussed some improvements I had in mind for the LaTeX package for including Asymptote graphics within a document.

After the conference I foolishly went over the package and re-wrote much of it in the DocStrip format to better document the internal behaviour of the code. Unfortunately—hence the ‘foolishly’—many bugs were introduced in the process when my new code smoothed over edge cases that it shouldn’t have—but it’s now finally working and included in the main Asymptote distribution. The package source is now more modern and better documented (available in the file doc/asy-latex.dtx in the Asymptote distribution), which should help with maintenance in the long run.

The main reason for the re-write was to add the feature to be able to include graphics defined in external files; before, graphics had to be included inline in the form

\begin{asy}
asy graphics code
\end{asy}

The new version of asymptote.sty allows you to write

\asyinclude{myfig.asy}

where the asy graphics code is now placed in the file myfig.asy. This can be useful when you wish to re-use an Asymptote graphic between multiple files or if you just like to keep your document source as minimal as possible.

Thanks to John for his patience in testing the packages as bugs were fixed and yet more bugs were discovered. It’s been great to work together.

A little bit of TLContrib

Wed, 13 Oct 2010 13:52:19 +1030

The indefatigable Taco Hoekwater has released a new project called “TLContrib”, which is an orthogonal package hosting site for TeX Live installations. It does not mirror TeX Live, but consists of a place to distribute material that is otherwise unsuitable for the main TeX Live tree: namely, non-free material, binary updates, and pre-release updates. For example:

Non-free material: cowfont (pdf link)
Binary updates: LuaTeX, MetaPost
Pre-releases: siunitx, fontspec

TLContrib is ready to be used by any users of TeX Live 2010; no extra software needs to be installed nor extra configuration performed.

Joseph Wright has already commented on this new repository and has taken advantage of TLContrib for providing testing releases for siunitx. I’m currently experimenting with the same idea for fontspec.

While users until now have been able to grab pre-release versions of siunitx and fontspec from Bitbucket and Github, the nice thing about using TLContrib is that you can use standard TeX Live tools to do the updates.

TLContrib as a user

Here’s how it’s all done as a user. First define an alias to make things easier to remember; put this into your .bash_profile or equivalent:

alias tlc="tlmgr --repository http://tlcontrib.metatex.org/2010"

You can now view what is available in the TLContrib repository with standard tlmgr commands such as

tlc list

to see what is currently available for installation. Packages can be updated to their pre-release versions by typing, say,

tlc update siunitx

and if an update performed in this way ‘goes bad’ and you’d like to revert to the official release, execute

tlmgr install fontspec --reinstall

and things will be back to normal.

TLContrib as a package author

As a package author, what I really like about TLContrib is the automated upload process—it’s a very friction-free way to push out quick updates to users. It works by only accepting the very rigid directory structure via which the package is installed into a texmf directory on installation. No human verification of the package contents is performed, so updates are very fast (a delay of at most one hour).

(Updates can even be slurped in from an online SVN repository, but I’m not sure how that would typically work for a LaTeX package that would typically not be kept in a texmf directory structure for development.)

In contrast, material submitted to CTAN must be manually processed for addition to TeX Live so that real humans can check to verify correctness and consistency of installation, and to ensure that the material is legally allowed to be included in the distribution, which is free in a very strict sense. It will be great to be able to iterate package development quickly, when necessary, through TLContrib while sending stable releases to CTAN and TeX Live.

Improving documentation through the community

Mon, 04 Oct 2010 11:57:42 +1030

While I’m technically spending as little time as possible on TeX development at the moment, I’m still keeping an eye on things around the place. (In some cases, having to fix bugs comes as a rather time-critical priority now that users are updating very frequently with tools such as tlmgr or MacTeX’s ‘TeX Live Utility’.)

Over on the TeX branch of Stack Exchange (still yet to be named, although I favour ‘overfull-hbox.com’), I’m currently experimenting with a way to replace my current lack of attention on my documentation with community-contributed material.

The background to this is that LuaTeX’s font loading through luaotfload allows OpenType fonts to be augmented at load time with new features and updated information such as kerning. I’d love to be able to document this feature properly in fontspec, but the problem is that I don’t have time to learn about it and write it up in the detail that it deserves. So I’ve opened up a question on StackExchange asking how to do this (‘changing kerning of a font in LuaLaTeX’) with the request that the answer come in the form of a patch to the fontspec manual.

I don’t know if anyone’s going to reply, but there’s a bounty of 400 reputation points going for it if anyone does. (You get 10 reputation points for each upvote on a question or answer you post on the site). The reputation system is an indicator of your participation on the site, so the reward is essentially just good karma — but I hope this can perhaps be a useful way to muster the community so that users who otherwise might not be able to contribute with the code can still help out with the non-technical aspects of putting together a package. You’d be surprised how long it takes to write good documentation!

Hiatus

Wed, 04 Aug 2010 14:40:00 +0930

Those of you who have been following my activity for the last few years will recall my frequent comments “the thesis is almost done” — for the last several years. Well, has it been? All that time?

The past year has been a combination of too many mini-projects for me: code and papers for my PhD; fontspec and unicode-math in XeLaTeX and LuaLaTeX; the Herries Press collection of packages; the continued development of LaTeX3; teaching and lecturing; and more besides. My responsibilities seem to be compounding rather than settling down. My actual thesis has seen far less attention than it should have.

“Why, I feel all thin, sort of stretched, if you know what I mean: like butter that has been scraped over too much bread. That can’t be right. I need a change, or something.”

I wish it didn’t have to come to this, but as of today I’m not going to be able to devote any significant time to the LaTeX world until my thesis is complete. I’ll still be answering support emails when I can, and I’ll release bug fixes for urgent problems, but don’t expect to hear too much from me for the next six months.

I’m sorry to let down those with whom I’m working fairly closely on a couple of different things. Rest assured I’ll be back and able to spend some real time on everything once I’ve got the monkey off my back.

Correct punctuation spaces

Sun, 18 Jul 2010 18:23:00 +0930

Who can remember when to use \@ in a (La)TeX document? I thought I knew, but an exception caught me by surprise today.

In approximate detail, the idea of \@ is to indicate when punctuation is or isn’t ending a sentence. Why would you want to do that? By default, Plain TeX and LaTeX both have a feature whereby a little extra space is allowed after a sentence (whether a period or other punctuation mark) to help break the paragraph into lines. If you need a little extra space in this line, better to lump it after the period than add extra space between all the words.

This typesetting approach was very common (often to an exaggerated extent) in the 1800s and early 1900s but nowadays I think is less common. If you don’t like it, write \frenchspacing in your preamble and you can forget about whether \@ is ever required. However, when writing a LaTeX document for another source, such as a journal, it’s polite to follow their style and include such niceties.

The canonical example for using \@ is after abbreviations such as ‘Prof.\@ Crumb’. Without the \@, the space after ‘Prof.’ will be mistakenly enlarged—this is a common typographical mistake in (La)TeX documents.

Conversely, \@ can also be used to indicate when a punctuation mark should end a sentence. By default, punctuation after a capital letter is assumed not to end a sentence (so you can write ‘M. C. Escher’ without the \@). But if you happened to refer to someone by their initial at the end of a sentence you’d need to write, say,

… `So he did', said M\@.  (New sentence) …

to ensure that the extra spacing was included after that final period.

I should also mention that I often don’t use \@ after punctuation in favour of typing an explicit space control sequence; that is, I prefer to write Prof.\ Crumb. This is shorter to type and perhaps more memorable.

Well, that’s where the limits of my understanding finished until today. And then I wrote something like

depending on the context of `a' and `b' (etc.) where …

Much to my surprise, the space after the ‘(etc.)’ was too large! Turns out that the space factor (which is the parameter governing when and where this extra space should appear) isn’t ‘reset’ by the parenthesis and you need to write (etc.\@) instead.

Update: Karl Berry gives another example:

… `Et cetera et cetera etc.' said the King …

Here, there will be extra space after the closing quotes ' (or '') that is incorrectly added due to the presence of the period; the closing bracket ] is also ‘invisible’ to the space factor. His take on the matter:

Fixing end-of-sentence spacing (in one direction or the other) is one of the most common things we have to with TUGboat submissions.

End update

The best idea in a case like this is to define a macro for inserting it all without your having to remember it; for example,

\makeatletter
\newcommand\etc{etc\@ifnextchar.{}{.\@}}
\makeatother

where you would write ‘(\etc)’ or ‘…, \etc, …’ but if you wanted to finish a sentence with it, you would explicitly include the period:

… \etc. (New sentence) …

I’m continually learning about small details like this even though I’ve been using TeX and friends quite closely for a number of years. It’s important to keep one’s eyes open.