This document discusses LATEX hooks, which allow packages and classes to override and modify default LATEX behavior. It provides several lessons about hooks:
1. Hooks let packages override standard LATEX functions by redefining them, like redefining \l@part.
2. Hooks aren't documented, as any package can override existing functions. To see which functions a package overrides, you must examine its code.
3. When overriding existing code with hooks, you should change the minimum needed and avoid removing calls to other functions, as those may also be hooks.
This document discusses LATEX hooks, which allow packages and classes to override and modify default LATEX behavior. It provides several lessons about hooks:
1. Hooks let packages override standard LATEX functions by redefining them, like redefining \l@part.
2. Hooks aren't documented, as any package can override existing functions. To see which functions a package overrides, you must examine its code.
3. When overriding existing code with hooks, you should change the minimum needed and avoid removing calls to other functions, as those may also be hooks.
This document discusses LATEX hooks, which allow packages and classes to override and modify default LATEX behavior. It provides several lessons about hooks:
1. Hooks let packages override standard LATEX functions by redefining them, like redefining \l@part.
2. Hooks aren't documented, as any package can override existing functions. To see which functions a package overrides, you must examine its code.
3. When overriding existing code with hooks, you should change the minimum needed and avoid removing calls to other functions, as those may also be hooks.
your Parts are printed. The hook mechanism and the “over-riding functionality” technique above are more or less the same thing. Hooks are fundamental to how LATEX packages work: they let the package over-ride the standard operation with something different. As an example, consider the shorttoc.sty package, which is useful if you want a one-page summary table of contents before the main TOC, for example. The package contains only about 40 lines of code, and in essence, all it does is call the standard table of contents, having first redefined the variable \c@tocdepth to a Figure 2: How LATEX hooks work small value to show only the top levels of contents. In effect, shorttoc.sty is using all the standard table-of-contents macros as hooks, although it hasn’t is called — \l@part in our example — the new changed any of them. code is used instead of the old (Figure 2). Lesson D: you don’t have to understand ev- Lesson E: hooks aren’t documented (as far erything to make a change to something rela- as we’ve been able to see). In fact they can tively small. As long as you change as little as never be exhaustively documented, because possible, you probably won’t break anything any package author can just copy any function else. In our case, even though \l@part con- (as we did with \l@part earlier) and over- tains lots of complex stuff, we were confident ride it with their own code, thus using that that our minor format changes would work, function as a hook. In real life, the only way because we didn’t modify anything else. you can determine the important hooks is by looking at the important packages, to see By the way, many functions or macros in the which functions they over-ride. package and class files are defined using the TEX primitive \def, instead of LATEX’s \newcommand. If Lesson F: when you copy a chunk of stan- you redefine an existing command with \def, you dard code, change the absolute minimum you don’t get an error, unlike \newcommand’s behavior. can get away with. The reason is you don’t really know what parts of it might be used as 6 The hard bits 2 — LATEX hooks hooks, or what might happen if you remove The first clue we got about how LATEX2 packages a call from it to some other hook. Resist the work with class files, i.e. how they modify their be- temptation to tidy or “improve” the code. havior, was reading ltsect.dtx — the documented 7 The hard bits 3 — adding extra version of the sectioning code in core LATEX2. It has functionality a comment: “Why not combine \@sect and \@xsect and save doing the same test twice? It is not possible (This section describes a technique that you will often to change this now as these have become hooks!” come across, and which you might find useful.) What’s a hook? In the Emacs programmable Let’s say you want to change some function so editor, hooks are used to customize the editor’s be- that it continues to do exactly what it does at present, havior. For example, before-save-hook is a list but does something extra in addition, i.e. the new of Lisp functions that should be run just before a is a superset of the old. Here’s a real but slightly file is saved. By default the list is empty, but by weird example. The author of a book [4] was using adding your own functions to the list, you can have superscripts in his index for a special purpose. We Emacs perform any special actions you want, such as needed a list of the superscripts, and it was difficult checking the file into a version control system as well to get this from the source files. Using the TEX as saving it, etc. Emacs provides about 200 hooks, primitive \let, you can assign a whole function to letting you customize most aspects of its behavior. a new variable, and then call the same old function In LATEX a hook is slightly different. It’s a but with the new name. We used this as follows: named function or macro that some other part of the \let\origsuper=\textsuperscript system is going to call. For example, in Section 5 we \renewcommand{\textsuperscript}[1] used \l@part as a hook. As we saw, by redefining {\origsuper{XXX(#1)XXX}}
358 TUGboat, Volume 29 (2008), No. 3 — Proceedings of the 2008 Annual Meeting