jgm/pandoc

Markdown header attributes with definition lists

rsmith-fhiso opened this issue · 13 comments

rsmith-fhiso commented

It seems to me it would be both useful and logical if when both the header_attributes and definition_lists extensions were enabled, header attributes were permitted on definition term lines. For example,

Term {#term}
    A paragraph giving its definition.

... should generate the following HTML:

<dl>
<dt id="term">Term</dt>
<dd>A paragraph giving its definition.</dd>
</dl>
ousia commented

@rsmith-fhiso 👍

But why limit this only to definition lists? Or even to lists?

mpickering commented

The implementation overhead is quite high as most formats don't support arbitrary attributes on elements.

rsmith-fhiso commented

I was limiting it to <dl>s because there seems to be strong case for that. A common (and the originally intended) use for a <dl> is a list of definitions, for example in a glossary. When used like that it's common and reasonable to want to link a use of the term in text to its definition. That seems a stronger case than the case for header_attrbitutes on arbitrary elements, though I'm certainly not against a broader implementation.

ousia commented

The implementation overhead is quite high as most formats don't support arbitrary attributes on elements.

@mpickering, I would limit these attributes to three special ones: :class, #id and :lang.

I think this is a reasonable implementation.

Right now, not even the YAML lang field works for LaTeX. And the issue is that TeX has hyphenation enabled by default.

So, if one happens to write documents other than US English, there is a need for a workaround in LaTeX because of this.

bpj commented

This works quite well and isn't very obtrusive with bracketed spans:

[Term]{#term}

:   A paragraph giving its definition.

Even Term []{#Term} works if the brackets around the actual term bother you, although the HTML or LaTeX output looks a bit funny.

  • 👀1
jgm commented

I agree with @bpj; the existing syntax for ids on spans is enough, and we don't need other changes.
Closing.

Mpic commented

This works quite well and isn't very obtrusive with bracketed spans:

[Term]{#term}

:   A paragraph giving its definition.

Even Term []{#Term} works if the brackets around the actual term bother you, although the HTML or LaTeX output looks a bit funny.

Does this require some filter or extension enabled ? It does not work for me, pandoc says that reference term is not found when I try to cite it with @term.
How are we supposed to use it ?

jgm commented

Citing with @term will only work for example lists. It isn't a general syntax for references.

Mpic commented

What do you mean with "example lists" ? Is it not "definition lists", like the example shown ?

[Term]{#term}

:   A paragraph giving its definition.
bpj commented
  • 👍1
Mpic commented

Thanks !

Ok then, how am I supposed to reference the term identified by #term, as you suggested earlier ?

jgm commented

You can use a regular internal link [like this](#term).

Mpic commented

Oh, I see. Thank you for the clarification !