Make HTML attributes actionable

[Witiko]

Since version 2.7.0, the Markdown package has supported the headerAttributes Lua option, which makes the Lua parser recognize HTML attributes on headings as a way of typesetting only small parts of markdown documents via the slice Lua option. However, the HTML attributes are currently not actionable, which means that users can't react to them from TeX.

The Markdown package has always supported the hybrid Lua option, which allows users to use LaTeX commands such as \label and \ref inside markdown:

I conclude in Section~\ref{sec:conclusion}.

Conclusion
==========
\label{sec:conclusion}
In this paper, we have discovered that most
grandmas would rather eat dinner with their
grandchildren than get eaten. Begone, wolf!

If the HTML element identifiers were actionable, we could rewrite the above code without the hybrid mode and all its shortcomings. Additionally, if HTML class names were actionable, we could apply setup snippets without switching between markdown and LaTeX:

I conclude in Section <#conclusion>.

Conclusion {#conclusion .some-snippet}
==========
In this paper, we have discovered that most
grandmas would rather eat dinner with their
grandchildren than get eaten. Begone, wolf!

Here are the current TODOs:

• Produce headerAttributeContextBegin and headerAttributeContextEnd renderers when the headerAttributes Lua option is enabled. The renderers should parenthesize sections. The renderer prototypes should expand to \relax.
• Produce attribute renderer when the headerAttributes Lua option is enabled. The renderer prototype should expand to \relax in plain TeX and to \label{#1} in LaTeX for ids. Attributes should be applied with deterministic ordering to mitigate the fact that CSS classes are commutative, so the order in which attributes are typed should not matter, but LaTeX code is not commutative, so the order of attribute invocation does matter.
• Add Lua option relativeLinks that enables the use of relative URLs in autolinks. In LaTeX, the link renderer prototype should expand to \ref{#3'} for relative URL autolinks that only consist of a URL fragment and to \hyperref[#3']{#1} for labeled links that only consist of a URL fragment, where #3' denotes #3 without the leading character of the fragment. Document this addition at Stack Exchange.
• Ping @drehak and mention the jgm/pandoc issue when the renderers are final, so that support for Pandoc's element attributes can be added.

Future development should add syntax extensions such as Pandoc's link_attributes, fenced_divs, bracketed_spans, inline_code_attributes, fenced_code_attributes for specifying HTML attributes on elements other than headings.

[Witiko]

Dear Lloyd, there is a proposal for actionable attributes on headings, currently scheduled for tacking by the end of February: <#91> At the moment, it is unclear how we should implement these actionable attributes on headings, let alone how we should implement actionable attributes on images and arbitrary other elements. Let me briefly outline the difficulty. In the following example, the CSS class `.dropcap` should invoke the setup snippet `dropcap` and it should stay in effect until the heading `# No dropcap`. # A section with a dropcap {.dropcap} some text ## A subsection, the snippet is still in effect some other text ## Another subsection, the snippet is still in effect # No dropcap However, in the following example, the CSS class `.large` should invoke the setup snippet `large` just for the image: {.large} It's difficult to design a unifying mechanism that would be general enough to cover both sections and arbitrary inline (or block) elements. *** I am playing around with the idea that any sort of element that may be targeted by attributes would produce an `attributeContextBegin` and `attributeContextEnd` elements that would surround it and would expand to `\begingroup` and `\endgroup`, effectively parenthesizing the text. Then, the attribute assignments would just invoke an `attribute` renderer, which would, by default, expand to `\markdownSetup{snippet=class}` for class names. Here is how the document with headings would look to TeX: \markdownRendererAttributeContextBegin \markdownRendererAttribute{.dropcap} \markdownHeadingOne{A section with a dropcap} \markdownInterblockSeparator some text \markdownInterblockSeparator \markdownRendererAttributeContextBegin \markdownHeadingTwo{A subsection, the snippet is still in effect} \markdownInterblockSeparator some other text \markdownInterblockSeparator \markdownRendererAttributeContextEnd \markdownRendererAttributeContextBegin \markdownHeadingTwo{Another subsection, the snippet is still in effect} \markdownInterblockSeparator \markdownRendererAttributeContextEnd \markdownRendererAttributeContextEnd \markdownRendererAttributeContextBegin \markdownHeadingOne{No dropcap} \markdownRendererAttributeContextEnd Here is how the document with an image would look to TeX: \markdownRendererAttributeContextBegin \markdownRendererAttribute{.large} \markdownRendererImage{an image}{images/image.jpg}{images/image.jpg}{Lovely image} \markdownRendererAttributeContextEnd I am quite in favor of this idea and it is a good thing that you made me consider both cases (the headings and the images) together, because I would not have come up with the above idea if we tackled them one by one. Too convoluted for either one of them, but it seems to be the right direction in the general case. Still, I estimate that just the initial implementation will take up to 15 hours of effort. Best, Vít

…

On Tue, Jan 25, 2022 at 02:04:34PM -0700, Lloyd R. Prentice wrote: Hi Vit, Sounds promising—particularly if it addresses the majority of book styling issues likely to arise. Can you document for me how it would work from the markdown author’s perspective? Perhaps with an example. Do you need support to implement it? As you know, my concern is books and the tech-adverse sub-population of folks who write them. If isn’t simple and abundantly documented, we’ll never reach those folks, potentially tens to hundreds of thousands of LaTeX markdown adopters. Best, Lloyd

[Witiko]

Now, what I described is just one part of what needs to be done before the authors can benefit. After programmers can react to the attributes, the next step is for them to produce Markdown themes that define standard behavior such as snippets that implement the CSS class .large or TeX code that will react to attributes such as width=1cm and height=100% when they are used around images. The beauty of the mechanism is that we don't dictate the behavior of the attributes. Instead, the programmers of the Markdown themes get to produce their own tiny domain-specific languages by deciding what the attributes should mean. This allows them to target specific use cases such as book publishing. The downside is that the meaning of the attributes will be fragmented. The upside is that you won't need me to add a book publishing extension to Markdown; you can build it on top. Best, Vit

…

On Tue, Jan 25, 2022 at 11:27:20PM +0100, Vítek Novotný wrote: Dear Lloyd, there is a proposal for actionable attributes on headings, currently scheduled for tacking by the end of February: <#91> At the moment, it is unclear how we should implement these actionable attributes on headings, let alone how we should implement actionable attributes on images and arbitrary other elements. Let me briefly outline the difficulty. In the following example, the CSS class `.dropcap` should invoke the setup snippet `dropcap` and it should stay in effect until the heading `# No dropcap`. # A section with a dropcap {.dropcap} some text ## A subsection, the snippet is still in effect some other text ## Another subsection, the snippet is still in effect # No dropcap However, in the following example, the CSS class `.large` should invoke the setup snippet `large` just for the image: {.large} It's difficult to design a unifying mechanism that would be general enough to cover both sections and arbitrary inline (or block) elements. *** I am playing around with the idea that any sort of element that may be targeted by attributes would produce an `attributeContextBegin` and `attributeContextEnd` elements that would surround it and would expand to `\begingroup` and `\endgroup`, effectively parenthesizing the text. Then, the attribute assignments would just invoke an `attribute` renderer, which would, by default, expand to `\markdownSetup{snippet=class}` for class names. Here is how the document with headings would look to TeX: \markdownRendererAttributeContextBegin \markdownRendererAttribute{.dropcap} \markdownHeadingOne{A section with a dropcap} \markdownInterblockSeparator some text \markdownInterblockSeparator \markdownRendererAttributeContextBegin \markdownHeadingOTwo{A subsection, the snippet is still in effect} \markdownInterblockSeparator some other text \markdownInterblockSeparator \markdownRendererAttributeContextEnd \markdownRendererAttributeContextBegin \markdownHeadingOTwo{Another subsection, the snippet is still in effect} \markdownInterblockSeparator \markdownRendererAttributeContextEnd \markdownRendererAttributeContextEnd \markdownRendererAttributeContextBegin \markdownHeadingOne{No dropcap} \markdownRendererAttributeContextEnd Here is how the document with an image would look to TeX: \markdownRendererAttributeContextBegin \markdownRendererAttribute{.large} \markdownRendererImage{an image}{images/image.jpg}{images/image.jpg}{Lovely image} \markdownRendererAttributeContextEnd I am quite in favor of this idea and it is a good thing that you made me consider both cases (the headings and the images) together, because I would not have come up with the above idea if we tackled them one by one. Too convoluted for either one of them, but it seems to be the right direction in the general case. Still, I estimate that just the initial implementation will take up to 15 hours of effort. Best, Vít On Tue, Jan 25, 2022 at 02:04:34PM -0700, Lloyd R. Prentice wrote: > Hi Vit, > > Sounds promising—particularly if it addresses the majority of book > styling issues likely to arise. > > Can you document for me how it would work from the markdown author’s > perspective? Perhaps with an example. > > Do you need support to implement it? > > As you know, my concern is books and the tech-adverse sub-population > of folks who write them. If isn’t simple and abundantly documented, > we’ll never reach those folks, potentially tens to hundreds of > thousands of LaTeX markdown adopters. > > Best, > > Lloyd

[Witiko]

As uncovered by e8078b0, we must take special care to ensure that we produce the same number of headerAttributeContextBegin and headerAttributeContextEnd renderers when we use the slice Lua option. Then, at the beginning of a slice, we should apply all attributes that are in effect at that point of the document. At the end of a slice, we should close all attribute contexts even if the attributes would otherwise continue to be in effect. At the end of a document, we should only close attribute contexts if the end of the document is part of the slice.

[Witiko]

@writersglen Starting with cad83f6, header attributes are actionable. Headings with an identifier such as # Heading {#an-identifier} will cause \label{an-identifier} to be issued in LaTeX. This will allow us to reference sections from Markdown when the second part of this issue -- support for URL fragments -- has been implemented

[Witiko]

@drehak This feature adds new renderers to the Markdown package:

• \markdownRendererHeaderAttributeContextBegin – The beginning of a context surrounding a section with attributes
• \markdownRendererHeaderAttributeContextEnd – The end of a context surrounding a section with attributes
• \markdownRendererAttributeIdentifier – An HTML id="IDENTIFIER" attribute, which equals {#IDENTIFIER} in markdown
• \markdownRendererAttributeClassName – An HTML class="... CLASS ..." attribute, which equals {.CLASS} in markdown
• \markdownRendererAttributeKeyValue – An HTML attribute other than id and `class

To give an example, here is a markdown document:

I conclude in Section <#conclusion>.

Conclusion {#conclusion .some-snippet key=value}
==========
In this paper, we have discovered that most grandmas would rather eat dinner with their
grandchildren than get eaten. Begone, wolf!

Here is the output of the Markdown package when the headerAttributes and relativeReferences Lua options are enabled:

\markdownDocumentBegin
I conclude in Section
\markdownRendererLink{\markdownRendererHash conclusion}{\markdownRendererHash conclusion}{#conclusion}{}.%
\markdownRendererInterblockSeparator
\markdownRendererHeaderAttributeContextBegin
\markdownRendererAttributeIdentifier{conclusion}
\markdownRendererAttributeClassName{some-snippet}
\markdownRendererAttributeKeyValue{key}{value}
\markdownRendererHeadingOne{Conclusion}
In this paper, we have discovered that most grandmas would rather eat dinner with their
grandchildren than get eaten. Begone, wolf!
\markdownRendererHeaderAttributeContextEnd
\markdownDocumentEnd

With respect to #25, this means that we now have a mechanism to pass heading attributes from Pandoc to Markdown. No luck for elements other than headings yet, but the plan is only to add new types of attribute contexts, the attribute renderers themselves will be shared between different types of elements.