Support short + long headers in sections and chapters (such as \chapter[short]{long long long} in LaTeX)

[maxheld83]

I have run into some downstream (bookdown) uses of pandoc, where it'd be really nice if pandoc supported short and long headers in sections and chapters (here and here).

If the origin and target formats support it, it would be nice to be able to pass on both the short and long version of headers, so that they can be layouted accordingly.
(This is often an issue in navbars, page headers and tables of content, where you'd usually only want quite short headers, but at the actual start of the chapter, you might want something longer).

LaTeX supports this as:

\chapter[short]{long long long}

I understand if this is considered out of scope, we mainly just want to know whether this might at some point be a feature or whether we have to hack around it.

(also paging @VerenaKasztantowicz).

[mb21]

I would guess that this is out of scope for the pandoc AST. However, you can enter the long title as an attribute:

echo '# long title {short="short title"}' | pandoc -t native

then write a pandoc filter to convert this to the rawTeX you mentioned...

[jgm]

See #2447 and the discussion there. I can see adding special support in the LaTeX and Markdown readers and writers for a short-title attribute that could be used for both figures and headers. But of course a simpler option is to leave this to special-purpose filters. Not sure.

[Nodraak]

I would love to see this feature implemented.

In the meantime, for future googlers, here is my filter that does the job :

#!/usr/bin/env python

from pandocfilters import toJSONFilter, RawBlock, get_value, stringify

SHORT_ATTRIBUTE_ID = 'short'

def f(key, value, format, meta):
    if not (format == 'latex' and key == 'Header'):
        return

    level, data, _ = value                              # level, data, internal_pandoc
    _, classes, keyvals = data                          # ident, classes, keyvals
    short, _ = get_value(keyvals, SHORT_ATTRIBUTE_ID)   # short, res

    if not short:
        return

    if classes:
        raise Exception(
            'short-title-for-toc.py: If class "%s" is used, I cant handle another one (Header="%s")'
            % (SHORT_ATTRIBUTE_ID, stringify(value))
        )

    try:
        tag = {
            -1: 'part',
            0: 'chapter',
            1: 'section',
            2: 'subsection',
            3: 'subsubsection',
        }[level]
    except:
        raise Exception('short-title-for-toc.py: level %d not handled' % level)

    return RawBlock('latex', '\\%s[%s]{%s}' % (tag, short, stringify(value)))

if __name__ == '__main__':
    toJSONFilter(f)

Disclaimer: hacked in a few minutes, probably far from perfect

[sjackman]

short-captions.lua is a filter that adds support for short captions on tables and figures. See #2447

@gtuckerkellogg Does it also work with chapter titles?

[rnuske]

@Nodraak I love your filter. It works for me if there is only # very long title {short="short title"} But I couldn't get it to work if pandoc-crossreferencing anchors are also present like # very long title {short="short title" #mylink} or # very long title {short="short title"} {#mylink}. Is there anything I could do differently?

[Nodraak]

Note: Updated filter with handling of link shared in pandoc/lua-filters/#76.

[ak9]

See #2447 and the discussion there. I can see adding special support in the LaTeX and Markdown readers and writers for a short-title attribute that could be used for both figures and headers. But of course a simpler option is to leave this to special-purpose filters. Not sure.

While filters such as those suggested in #2447 and here will work for standard LaTeX output, it seems hopeless for Beamer. It does not seem possible to push any data between \begin{frame} ... \end{frame} and a \section[...]{...} is not seen to be treated specially for this, so it looks to be up to some internal sauce to get this right.