LaTeX writer: a span with an id inside a header will have an extra right brace

[bpj]

When converting with pandoc to LaTeX a span with an id inside a header will have an extra right brace appear which causes a syntax error in latex. The brace marked with ^ in the LaTeX output is one too many, as can be readily seen in an editor which highlights matching braces. From these tests it appears to happen only when converting from Markdown, but I first noticed it when converting from HTML from various web pages. Apparently they put an empty span in the header instead of giving the header an id. They must be using (non-pandoc) Markdown! It doesn't happen when there is no id in the span.

Testing:

## <span id="a-header-with-a-span-in-it">A header with a span in it</span>

Paragraph

Converting markdown to html
Converting html to pdf
No errors
Converting markdown to pdf
Stderr:

! Argument of \@sect has an extra }.
<inserted text> 
                \par 
l.121 it}}{A header with a span in it}}

pandoc: Error producing PDF from TeX source

Latex output:

\subsection{\texorpdfstring{\hyperdef{}{a-header-with-a-span-in-it}{}{A
header with a span in
it}}{A header with a span in it}}\label{a-header-with-a-span-in-it}
   ^

Paragraph

[jgm]

+++ Benct Philip Jonsson [May 06 15 09:38 ]:

Latex output:
\subsection{\texorpdfstring{\hyperdef{}{a-header-with-a-span-in-it}{}{A
header with a span in
it}}{A header with a span in it}}\label{a-header-with-a-span-in-it}
   ^

This right bracket matches the left bracket after \texorpdfstring.
As far as I can see, the brackets here are balanced.

There is a problem here, but I don't think we yet understand what it is.

[lierdakil]

The problem is \hyperdef is used inside moving arguments. A simple workaround is to add \protect before \hyperdef. Now then, equivalent could be done with some TeX magic in template, e.g.

\let\oldhyperdef\hyperdef
\DeclareRobustCommand{\hyperdef}{\oldhyperdef}

But it could also be implemented in pandoc with \protect, e.g. this will work:

\subsection{\texorpdfstring{\protect\hyperdef{}{a-header-with-a-span-in-it}{}{A
header with a span in
it}}{A header with a span in it}}\label{a-header-with-a-span-in-it}

While first option is generally more robust, second would work for non-standalone LaTeX output. There are other environments in which \hyperdef can (and likely will) break though.

See TeX stackexchange for more info on this topic.

Also see http://www.giss.nasa.gov/tools/latex/fragile.html for other examples where \hyperdef would break (most notably, inside \caption arguments)

[lierdakil]

P.S. Now that I think about it, \oldsomething is really not the best name choice, since this could be redefined by user. Better option would be to use @ to avoid collisions, e.g.

\makeatletter
\let\hyperdef@original\hyperdef
\DeclareRobustCommand{\hyperdef}{\hyperdef@original}
\makeatother

[jgm]

I think just adding a \protect to the output before each \hyperdef might be the best approach.
(Or maybe just inside headers? Which pandoc contexts correspond to "moving arguments" in LaTeX?)

[lierdakil]

Moving arguments are literally arguments which can appear in document in
places other than exact place of definition. Examples include (and this is
not an exhaustive list, not by a long shot):

• Section operators (\part, \chapter, \section, etc) -- arguments can
  be "moved" to table of contents
• \caption commands -- arguments can be "moved" to \listoftables or
  \listoffigures
• \markboth and \markright commands -- arguments will be moved to top
  of each page
• @{} expressions in tabular and array arguments -- will be "moved"
  to every row
• letter environment
• etc

\protect in general context is equivalent to \relax, which essentially
does nothing (it's usually used to stop argument scanning or to terminate
expansion loops, since \relax itself is expanded into nothing), so I
would assume it's safe enough to use before any command in any context.
It's not encouraged though, at least not in (La)TeX guides I read. Bear in
mind, that last time I used LaTeX extensively was about 5 or 6 years ago,
when writing my master's degree thesis, so details can be a little fuzzy.