Latex Macros
🛑 👉🏻👉🏻👉🏻 INFORMATION AVAILABLE CLICK HERE👈🏻👈🏻👈🏻
A six-part series: How do TeX macros actually work?
This article series has an ambitious goal: to explain, step-by-step, how TeX macros, such as LaTeX commands, actually work—by exploring processes which take place inside TeX engine software. It tries to tell the story of TeX’s processing behaviour:
However, because TeX engines are such complex software programs we cannot hope to cover everything but we have tried to address the most important, core, features of TeX’s macro-processing capabilities.
Each article has the following navigation bar before and after the text so that you can quickly jump to another article in the series:
This article examines the reasoning behind TeX’s concept of category codes: what they are and how TeX uses them to filter its input into content for typesetting and commands to be executed.
Through a series of graphics we use the time-tested analogy of TeX having “eyes” with which to read (scan) its input. We explore examples of TeX’s use of category codes to create character tokens and how TeX recognizes and processes commands by using category code 0 (“escape character”).
This article takes an in-depth look at how TeX recognizes and process commands detected in the input. We explore how TeX stores and retrieves information about commands: command codes, command modifiers and survey a few internal variables that TeX uses to store information about items read-in from the input. Some of the article is quite low-level material which can be skipped on a first reading.
We introduce and use the following “framework” for describing the structure of macros:
{}
We then explore a range of examples to demonstrate the role and purpose of a macro’s as a “token template” which can be constructed through the use of tokens acting as delimiters.
This article explores, in detail, how TeX uses token lists to store macro definitions. Using extensive diagrams generated with a specially modified version of TeX, we explore the specialized tokens that TeX uses to identify and process a user’s macro arguments.
In Part 6 we use some detailed graphics to explain and explore the exact meaning of macro expansion and the consequences of TeX’s tokenization of macro arguments prior to feeding them into a macro’s .
As discussed in the article What’s in a Name: A Guide to the Many Flavours of TeX a wide range of terms are used to reference/describe TeX, LaTeX and their derivatives. Consequently, it is worth, briefly, clarifying our use/meaning of “TeX” within the context of this series.
“TeX” is, somewhat confusingly, both the name of an executable program and the name of a typesetting language. To distinguish between the two, the term TeX engine is used to differentiate between an executable TeX program and the typesetting language. Some of the specific data, information and details used within this series are derived from a detailed examination of the source code to Knuth’s original TeX software but the principles described are common to all TeX engines. So, throughout our discussion, the use of “TeX” should be inferred to mean one of the executable TeX engines—such as Knuth’s original TeX, pdfTeX, XeTeX or LuaTeX.
Within the articles we use the TeX primitive command \def to define our macro examples: we don’t use LaTeX command \newcommand which is almost certainly more familiar to most Overleaf users. There’s a very good reason for this: our objective is to understand the fundamental principles underlying TeX’s macro behaviour but to do that we need to use the core commands (primitives) built into TeX software. LaTeX commands, such as \newcommand, are themselves macros: commands with specific programmed behaviour and which, ultimately, are constructed from layers of lower-level TeX primitive commands. To better understand the fundamental behaviour of TeX we have to use TeX primitives, not LaTeX macros.
Instead of relying solely on a suite of example macros designed to demonstrate various features, edge cases and behaviours of TeX, we also use an extensive array of graphics to look inside TeX itself to see how and why its macro processing works the way it does. Many of the graphics (token lists/node diagrams) have been prepared using a specially modified version of Knuth’s original TeX.
Overleaf adapted Knuth’s TeX with additional code (written in C) that “hooks into” TeX’s macro processing and explores data, and data structures, which are normally inaccessible to users. Each time a macro is called, the modified TeX engine generates additional output files containing data in a format which can be processed using Graphviz, an open-source graph-visualization program. The end-result is graphics (node-list diagrams) which show exactly how TeX stores a macro’s definition, together with a graphical representation of any arguments supplied by the user when the macro was called.
Out of necessity, this series’ objectives require discussion of a wide range topics, many of which are quite low-level, and, initially, might seem to be very distant from the task of typesetting your documents. Hopefully, after taking a deeper-dive, you’ll come through with a foundation for building a better understanding that will, in the end, save you a lot of time and, perhaps, minimize the frustration levels too. It is also our hope that the specially-generated graphics which accompany this series also offer a uniquely valuable insight to help and support any readers in their quest to better understand TeX macros.
The video gives a short demonstration of Overleaf’s modified version of TeX, adapted to generate Graphiviz node diagrams (.gv files)—no other aspect of TeX’s behaviour is affected by those changes. The .gv files contain representations of the TeX token lists used to store macro definitions and macro arguments. The Graphviz visualization is exported to SVG which is then imported into Inkscape for further annotation prior to incorporating the graphic into an article.
How TeX macros actually work: Part 4
In Parts 1–3 we took a deep-dive into some low-level backgound details in preparation for understanding how TeX macros work. In this article we are going to “come up for some air” to review some basic practical principles of TeX macros in readiness for another deep-dive in Parts 5 and 6. Throughout this article we are going to show example macros defined using the TeX primitive command \def: we won’t use the, perhaps more familiar, LaTeX command \newcommand. There’s a very good reason for this: our objective is to understand the fundamental principles underlying TeX’s macro behaviour but to do that we need to use core commands built into TeX software. LaTeX commands, such as \newcommand, are themselves macros: commands with specific programmed behaviour which are, ultimately, constructed from layers of lower-level TeX primitive commands. To better understand the fundamental behaviour of TeX we have to use TeX primitives, not LaTeX macros.
In essence, we are working towards an explanation of macros as a specialized form of token list: when you instruct TeX to define a macro it creates a sequence of tokens (a token list) and stores them in its memory linked to a name that you define. In Parts 5 and 6 we will look at macro token lists in some detail but if you’d prefer to jump off this article to read some background information you can find that in What is a TeX token list?
Token lists for macros, and their parameters, incorporate a few additional twists which we’ll work through in detail—and use plenty of examples. To better understand TeX’s macro processing behaviour(s) there’s really one key factor to remember: TeX only thinks about characters at the earliest stage of input processing: from that point on it’s tokens all the way! Over this, and the remaining articles in this series, we will explore the role that tokens play in TeX macros.
Before we start it’s worth reminding ourselves of the difference between a macro’s parameters and a macro’s arguments, because we’ll be using both terms throughout this article. Suppose you define a macro \foo
\def\foo#1#2{This is #1, this is #2}
The constructs (tokens) #1, #2 (up to #9) are called the macro’s parameters: think of them as “placeholders” for the actual data you will use when you call the macro:
Here, alpha and beta are the arguments used with this call of \foo: a macro’s arguments are the actual values fed into the parameter placeholders (#1, #2... #9) used when you defined the macro.
We’ll start with what, perhaps, looks like a slightly formal definition of a macro, but it does provide a useful framework for further discussions.
Any macro definition is comprised of 4 parts:
{}
NOTE: Throughout the discussion we are assuming that will be followed by a space character of category code 10 to act as a delimiter to terminate the . We have not explicity shown that space character in our text/discussion but we assume it is there. Strictly speaking, we should represent it something like this:
{}
However, we will omit explicit inclusion of a character and implicitly assume its presence.
We’ve shown the use of two braces: { and } which surround (delimit) the actual body of your macro’s . However, the use of { and } is just an adopted convention because what TeX actually expects is the text of your macro to open with a character of category code 1 (“Start a group”) and close with a character of category code 2 (“End a group”). By convention, these are the { and } characters respectively. However, you can, if you wish, assign any pair of characters to do that. For example
Now, you can define and use macros like this:
And you can still use { and } because we have not changed their category codes—multiple characters can, and do, have the same category code, so you could continue to define macros in the usual way:
The components of a macro’s definition most relevant to our discussion are and {}. When you define a macro the is, in effect, a strict token template which defines how the macro is to be used. As noted, can be empty e.g., \def\foo{Some text} where nothing appears between our command name (\foo) and the opening brace { which, here, signals the start of our macro’s .
Note: Some readers may know about TeX’s “hashquote” mechanism (#{) but we won’t touch on that here.
This particular article isn’t designed as a thoroughly comprehensive review of writing macros but it is worth having a short refresher, with some examples, showing that the can become complex because TeX allows to contain:
So what does this actually mean—let’s look at some examples. The sits between the between the name of the macro and the left-brace { of the macro’s definition.
Suppose we define a basic macro \foo as follows:
The three character tokens ABC are treated as delimiters: not something to be typeset but “punctuation” which is expected to be present when the macro is called—when you use the macro \foo you must supply the same delimiters that were present when it was defined.
If you type \foo ABC within your text this will typeset hello, there—the character tokens ABC are not typeset but TeX did, very carefully, check to make sure they were present in your invocation (call) of \foo. TeX looks for those delimiters (“punctuation”) and removes (absorbs) them as you can see in the following Overleaf screen image: ABC is not typeset:
If you try to use \foo without the ABC delimiters TeX will complain Use of \foo doesn’t match its definition.:
In the example above, after detecting \foo TeX expects to see the three character tokens ABC but it does not: it sees the character token for w and immediately detects something is wrong.
An interesting, and perhaps surprising, fact is that delimiters can be arbitrary command tokens—including commands that have not even been defined. For example, we could define \foo as:
\def\foo A\bob B\anne{Hello \TeX{}}
When you call a macro, TeX checks (scans) the that is is present in your macro call and compares it, token-by-token, with the “token template” version stored in memory—the one created at the time the macro was defined. TeX scans the used in your macro call and simply converts any commands it finds there into its numeric token value: it is not trying to execute those commands, hence it does not matter that \bob and \anne were never defined. TeX is simply using the token template stored in memory as a guide that enables it to work out which tokens in the of your macro call are the actual arguments to feed into the .
As you can see from the following Overleaf screen fragment, neither of the character tokens (A and B) within A\bob B\anne was typeset and our undefined commands \bob and \anne did not cause any problems. All of these tokens were absorbed by TeX as it matched your use of \foo with the definition (token template) of \foo (a token list) stored in memory.
You can intersperse various delimiters (character tokens, command tokens) with macro parameters, as in this example:
\def\foo A\bob#1B\anne#2\jane#3bye!{Hello from \TeX{} to \#1=#1, \#2=#2 and \#3=#3}
Here, you have, in effect, provided TeX with a template that it will very carefully try, and expect, to match when you call \foo: it will go through your macro call, token-by-token, and expect to match (find):
Remember: TeX thinks in tokens so bye! is four character tokens.
There are two ways we can use this macro—we could put any multi-token arguments in braces to provide a group:
\foo A\bob{This}B\anne{That}\jane{Other}bye!
However, that is not necessary because our macro definition has delimiters which provide a token template. TeX can use that template to pick out the tokens for each argument from among tokens that are purely delimiters. We can use our macro like this:
\foo A\bob ThisB\anne That\jane Otherbye!
and TeX can pick out the arguments to produce the same result as using groups {...}:
Note how TeX was able to detect, precisely, which tokens matched parameters #1 and #3:
Here is a short example to demonstrate that, when working with macros, it is important to remember that we really are in the world of tokens and not characters…
We’ll define the following short macro where A and B are characters acting as delimiters and both have category code 11. This works without problems:
\documentclass{article}
\begin{document}
\def\foo A#1B{Hello, #1}
\foo AGrahamB
\end{document}
However, if you change the category code of A or B to something other than 11, the macro call will fail. Suppose we change the category code of B to 12, using \catcode`B=12 and try to call the macro again, as before:
\documentclass{article}
\begin{document}
\def\foo A#1B{Hello, #1}
\foo AGrahamB % This works
\catcode`\B=12\relax
\foo AGrahamB
\end{document}
It fails with a somewhat puzzling error:
Runaway argument?
GrahamB \end {document}
! File ended while scanning use of \foo.
\par
<*> main.tex
I suspect you have forgotten a `}', causing me
to read past where you wanted me to stop.
I'll try to recover; but if the error is serious,
you'd better type `E' or `X' now and fix your file.
! Emergency stop.
<*> main.tex
*** (job aborted, no legal \end found)
Unfortunately, TeX’s default suggestion of I suspect you have forgotten a `}' is incorrect, it isn't caused by a missing brace (}).
TeX is trying to match the \foo macro call with the \foo macro definition it has stored in memory. When you call a macro that needs one or more arguments, TeX has to examine (scan) your use of the macro to work out the arguments you are supplying to that macro. Here, TeX is expecting the argument to be sandwiched between an A (category code 11) and a B (category code 11). Remember: TeX is thinking in tokens, not characters.
The token values for A and B, [Math Processing Error]
TA
and [Math Processing Error]
TB
respectively, are:
However, as TeX continues its search it sees the B but now it has category code 12 and that results in a different token value:
In the \foo macro definition, the token value for B (used as a delimiter) was 2882 but TeX now sees a token value of 3138: it thinks this is just another token destined for use in the argument supplied to \foo. As far as TeX is concerned, the final token of the argument has not yet been found so it goes to get another token in its search for a B with category code 11. That is when, and why, the macro fails: in its attempt to find the argument TeX “overshoots” and starts to read tokens that you did not intend to become part of the argument for the \foo macro call. What happens next depends on the tokens TeX discovers after the B—they will trigger various Runaway argument? errors.
In our example, TeX overshoots and consumes the stream of tokens \end {document} and quickly hits the end of the file, hence the error message:
! File ended while scanning use of \foo
As we saw above, the section of our macro’s definition can range from extremely simple through to a complex mix of macro parameters interspersed with character tokens and command tokens acting as delimiters. TeX is able to process the various combination of tokens present in to extract the arguments supplied to a macro—and detect when we try to use a macro incorrectly. How it does that is the subject of the next article in the series.
Porno Latex Black
Anal Ass Latex
Latex Boots Femdom
Latex Jacket
Latex Dick
LaTeX Macros - UH
LaTeX/Macros - Wikibooks, open books for an open world
How do TeX macros actually work? - Overleaf, Online LaTeX ...
Part 4 - Overleaf, Online LaTeX Editor
LaTeX - Macros
Springer LaTeX templates | Springer
The todonotes package - CTAN
What are (TeX) macros | The TeX FAQ
Latex Macros
