What do \@mkboth and \markboth do?

Question

What do the toc related commands \@mkboth and \markboth do?

It is mostly the same as \markboth, the kernel docs suggest class and package writers sometimes use \@mkboth instead as then certain packages can redefine it to do nothing. See texdoc source2e — daleif, Aug 30 '14 at 15:26
Fair enough. I now edited the question to ask for \markboth as well. — Matti, Aug 30 '14 at 15:36

score 17 · Accepted Answer · answered Aug 30 '14 at 17:03

17

Here is the definition of \markboth from the LaTeX kernel:

\def\markboth#1#2{%
  \begingroup
    \let\label\relax \let\index\relax \let\glossary\relax
    \unrestored@protected@xdef\@themark {{#1}{#2}}%
    \@temptokena \expandafter{\@themark}%
    \mark{\the\@temptokena}%
  \endgroup
  \if@nobreak\ifvmode\nobreak\fi\fi}

It takes two arguments, designed to aid in the setting of the headers in twoside mode - the first is set as the left page header, while the second ends up in the right page header.

In contrast, \@mkboth is used as an internal kernel tool and may take on multiple functions. From source2e (section 65.3 marking conventions, p 310):

Commands like \tableofcontents that should set the marks in some page styles use a \@mkboth command, which is \let by the pagestyle command (\ps@...) to \markboth for setting the heading or to \@gobbletwo to do nothing.

For example, the empty page style (in latex.ltx) sets

\def\ps@empty{%
  \let\@mkboth\@gobbletwo\let\@oddhead\@empty\let\@oddfoot\@empty
  \let\@evenhead\@empty\let\@evenfoot\@empty}

while the headings page style (in article.cls) sets

\if@twoside
  \def\ps@headings{%
      \let\@oddfoot\@empty\let\@evenfoot\@empty
      \def\@evenhead{\thepage\hfil\slshape\leftmark}%
      \def\@oddhead{{\slshape\rightmark}\hfil\thepage}%
      \let\@mkboth\markboth
      ...

answered Aug 30 '14 at 17:03

Werner

603,163

Are \markboth and \@mkboth thus only intended to be used with twoside option? – Matti Aug 30 '14 at 17:41
1

@Mappi: No. Their effect will depend on the twoside option, but you can use them in both. – Werner Aug 30 '14 at 17:47
2

For anybody else who's also wondering what \unrestored@protected@xdef does, I asked this question (which was before I got enough reputation to comment everywhere, thus explaining why I didn't just ask in a comment on this answer.) – RandomDSdevel Dec 31 '17 at 02:32
@Werner: OK, but what does the \temptokena macro do? – RandomDSdevel Dec 31 '17 at 02:38
@Werner: Never mind, found this. – RandomDSdevel Dec 31 '17 at 02:47
@Werner: Now that I think about it, I'm not sure if I completely understand a couple of things. First, why does \markboth's implementation invoke \expandafter with only one argument (\@themark, on the line where the result of doing that gets assigned to \@temptokena?) Does @themark get expanded once before \expandafter sees it? … – RandomDSdevel Jan 01 '18 at 00:40
@Werner: …Second, I'm a bit perplexed as to how the invocation reading '\mark{\the\@temptokena}' would play out. I understand that \the\@temptokena should come out as something like either '{#1}\number2expanded' or '{#1}{#2}' depending on what the earlier \expandafter sees and outputs, but, as far as I understand from this link, doesn't \mark only take one argument? I suppose one could expand both into the same argument slot right after one another, but I'm not sure why one would want to do that, as a user of this command… – RandomDSdevel Jan 01 '18 at 00:46
…presumably wants to set more than just one of \topmark, \firstmark, and \botmark when invoking it. Doing so additionally makes even less sense in the context of why I asked this other question, where the source I was looking at that initially led me down this rabbit hole passed the exact same thing for both #1 and #2; one would then get the text resulting from the expansion of those identical token streams' contained macros seen twice, right next to each other. Could you or someone else walk me through what's going on here? – RandomDSdevel Jan 01 '18 at 00:54
@RandomDSdevel I am not sure what you mean by '{#1}\number2expanded' but the result is always two brace groups. The point is to edef expand everything except page number related commands such as \label at the point of the \markboth while allowing the other commands to be expanded later when/if the mark is used. – David Carlisle Jan 02 '18 at 00:03
@DavidCarlisle: By '\number2expanded', I meant a placeholder for the result of expanding the '{#2}' in the '{{#1}{#2}}' assigned to '\@themark' by \unrestored@protected@xdef' in the implementation of '\markboth.' Other than that, what you say makes sense…except I'm still a bit confused by the apparent macro parameter/argument arity mismatches that pop out at me in the invocations of '\expandafter' and '\mark' in that same code. – RandomDSdevel Jan 02 '18 at 00:16
@RandomDSdevel you seem to be asking questions about how \markboth works internally as comments on an existing question about what it does as a user command, which isn't really the way the site is supposed to work, but what you seem to be missing is that in latex \mark is always used as \mark{{a}{b}} with two brace groups – David Carlisle Jan 02 '18 at 00:18
@DavidCarlisle: Oh. That wasn't exactly clear from this other documentation I found. Am I to take it that the first argument is for setting \firsmark and the second is for setting \botmark, then? – RandomDSdevel Jan 02 '18 at 00:20
1

no \firatmark and \botmark are primitives so they will get the contents of \mark (both groups) but the latex macros \@leftmark and \@rightmark extract the first or second group respectively – David Carlisle Jan 02 '18 at 00:22
@RandomDSdevel that page is documenting plain tex so it is not that it isn't clear about latex, it doesn't attempt to document latex at all. – David Carlisle Jan 02 '18 at 00:23
@Symbol1: I evidently made a mistake, as an frequent reader but only rarely a poster on this site, in not entering what I wrote under the category that you prefer. But it ought to be said that I wrote, with the help of Werner, would indeed answer the question, as it suggests a functional interaction of @mkboth and \markboth, and its consequence, without subjecting the hypothesized interaction to Werner's superior scrutinyt. I now see that what I wrote is too long for a comment. I request that you allow Werner to respond for benefit of the original writer and others. – Louis Apr 21 '21 at 09:02
@Louis: I did read your post, but it doesn't make sense to me. Perhaps because I didn't read as much into "should" as you did... – Werner Apr 21 '21 at 15:48
@Werner: I could try to clarify first by saying that I don't know what they meant by "should." That aside, there are three problems posed for understanding what goes on between @mxboth and \markboth. (1) Does “Contents” gets stored in @mkboth? (2) By virtue of \let@mkboth\markboth, is "Contents" passed to \rightmark or \leftmark in the definitions of \oddhead and \evenhead, thence to become a header? – Louis Apr 21 '21 at 17:00
@Werner: (3) The answer to (2) seems to turn on whether \let establishes a symmetric relations between its arguments. Knuth suggests it is when defining \let with `=' (TeXbook, 206), but his prose and commentary seem to suggest that it is asymmetric: it assigns the current value of the second argument to the first, but does not assign the first to the second. I thought from your quotation of the same code lines that I've been studying that you might know. – Louis Apr 21 '21 at 17:01
@Louis: \let\cmdA\cmdB copies the current version of \cmdB to \cmdA, overwriting whatever \cmdA used to contain. The use of = is optional. – Werner Apr 21 '21 at 17:48
@Werner: That's exactly how I've seen it described (Kopka and Daly, 440), which is to say that the relation is asymmetric, hence =' is not used in its mathematical sense. (The equality relation is reflexive, symmetrical, and transitive.) If so, how could@mkbothat beginning of a document, before any marks are set by section commands, acquire 'Contents,' or any token list, from\markboth,which would seem to be empty there? Perhaps there's some other that way that\tableofcontents' populates \markboth? But then what's `\let@mkboth\markboth' doing in your quote from article.cls? – Louis Apr 21 '21 at 21:37
@Louis: Note that adding \let\@mkboth\markboth as part of \tableofcontents doesn't mean the assignment to \@mkboth happens when \tableofcontents is defined (as part of the document class, or possible in the preamble with other package loading, like tocloft). Instead, that assignment only occurs when \tableofcontents is invoked/called/executed. This is referred to as expansion. This is unlike other programming languages where variable definitions are set at the time of definition. – Werner Apr 21 '21 at 21:55
@Werner: I understand. I was referring to LaTeX processing when it comes to table of contents on the first or other early page, at which point nothing has been written to \markboth' because no sectioning command has been issued. How then does anything get copied to@mkboth`? – Louis Apr 21 '21 at 23:14
@Louis: The ToC is set as a \section* or \chapter*, depending on the document class. – Werner Apr 21 '21 at 23:47
@Werner: Thanks. This is revelatory! I see it in classes.dtx and article.cls, with \section* sending 'Contents' formatted to @mkboth, which could begin a path to a header: to \markboth by operation of \let, in oneside thence to \firstmark, by expansion to \rightmark, by expansion to \oddhead. But that path is open only if \let is symmetric. Only then does \markboth get 'Contents.' The authors of classes.dtx suggest this path by 'we `let @mkboth' to \markboth, 'to' suggesting 'equate to.' Yet commentary contradicts this interpretation of symmetry. I'm stumped. – Louis Apr 22 '21 at 18:03
@Louis: I suggest you create a small example, something with just one section and a ToC inside an article, and add \tracingmacros1 just before \tableofcontents. Then you can look in the resulting .log how the macro execution works, step-by-step, and figure out where assignments are made and what values they contain. That would be a starting point for a in-depth view on the macro process. Latex \tracing commands list? – Werner Apr 22 '21 at 18:21
@Werner: I followed those steps, generating the large .log file, and searched for all the code I've mentioned, but did not find anything seeming to be directly on point. I don't know to which macro's execution you refer. I'm trying to imagine an explanation from the logic of the code. – Louis Apr 22 '21 at 23:21

What do \@mkboth and \markboth do?

1 Answers1

Linked