adding labeling environment

[kompre]

Description

Hello,

The Markdown/qmd syntax for description get translated to the \begin{description} latex environment, i.e. in the pdf output is rendered as a bold item followed by the description, with a fixed space between them. This works best if the item is some text, but the fixed space doesn't look good with a math symbol followed by its description because the space between them is not enough (probably can be fixed with some option in the preamble), but mostly because the descriptions do not align.

In order to align the descriptions, i.e. having a variable space between item and description, I could use the labeling environment provided also by KOMA-Script which let you define a separator, and, more importantly, a fixed amount of space from the left margin, so that all descriptions starts aligned (i.e. the space between item and description is variable).

Here a minimal example:

---
title: Description in Quarto
format:
  pdf:
    pdf-engine: xelatex
    include-in-header: 
      - text: "\\usepackage{tabto}"
jupyter: python3
keep-tex: true
---

# Description in Quarto

A `description` in quarto get translated to the `\begin{description}` enviroment:

item1
: description1

item2
: very long description that likely will overflow to the next line in order to show how it is handled the indent


it3
: description3

it4
: very long description that likely will overflow to the next line in order to show how it is handled the indent

Doesn't look so nice when defining some math symbol:

$V_{Rd}$  
: description of symbol 1

$V_{Sd}$ 
:  description of symbol 2

$x$ 
:  very short math symbol

$M = F d$
: very long math symbol

It would be nice to use the `labeling` environment provided by `KOMA-Script`, where I can define the padding as variable space between item and description, and also a custom separator:

\begin{labeling}[:]{00000000}

  \item[$V_{Rd}$] description of symbol 1 \\

  \item[$V_{Sd}$] description of symbol 2 \\

  \item[$x$]  very short math symbol \\

  \item[$M = F d$] very long math symbol \\

\end{labeling}

I can achieve similar results using the `\tabto{}` command provided by the `tabto` package:

$V_{Rd}$  
: \tabto{2em} description of symbol 1

$V_{Sd}$ 
: \tabto{2em} description of symbol 2

$x$ 
: \tabto{2em} very short math symbol

$M = F d$
: \tabto{2em} very long math symbol

desc.pdf

(Note that the above variant render the same in html, it does not make any difference)

I would like to minimize the amount of raw latex in my qmd file, and write it similarly to the quarto description syntax. I propose to wrap the description into a content block like this:

::: {.labeling sep="" pattern="00000"}

$V_{Rd}$  
: description of symbol 1

$V_{Sd}$ 
:  description of symbol 2

$x$ 
:  very short math symbol

$M = F d$
: very long math symbol

:::

this way it could be defined as its own div block, that possibly could also be handled correctly by the html render engine if the proper ad hoc class is specified.

[cderv]

You should check this Quarto extension https://github.com/quarto-ext/latex-environment

It will allow you to use a markdown syntax to create a LaTeX environment or a command.

I believe the code above can be written this way

---
title: "Test"
filters:
   - latex-environment
environments: [labeling]
commands: [item]
keep-tex: true
---

::: {.labeling options="" arguments="00000"}

[description of symbol 1]{.item options="$V_{Rd}$"} 

[description of symbol 2]{.item options="$V_{Sd}$"} 

[very short math symbol]{.item options="$x$"} 

[very long math symbol]{.item options="$M = F d$"} 

:::

Not sure it is simpler than raw LaTeX, but it would compile HTML doc without missing part.

[mcanouil]

I’ve changed this from feature request to Q&A.

[kompre]

That's a very nice extension to keep in mind for general purpose, but you're right, it become quite verbose when defining the item, so kinda defeat the purpose. Also I don't like that the position of the symbol and its description get switched. I guess I could "hack" the syntax
like this:

::: {.labeling options="" arguments="000000000"}

[]{.item options="$V_{Rd}$"} 
description of symbol 1

[]{.item options="$V_{Sd}$"} 
description of symbol 2

[]{.item options="$x$"}
very short math symbol

[]{.item options="$M = F d$"} 
very long math symbol

:::

This way I preserve the structure of the description environment (symbol first, description in the next line) and it render correctly in the pdf, but I may lose some html compatibility.

Leveraging the extension, I could also define the tabto command and have the most close to the native description syntax.

$V_{Rd}$  
: [description of symbol 1]{.tabto arguments="2em"}

$V_{Sd}$ 
: [description of symbol 2]{.tabto arguments="2em"}

$x$ 
: [very short math symbol]{.tabto arguments="2em"}

$M = F d$
: [very long math symbol]{.tabto arguments="2em"}

[mcanouil]

If you don't like something, you have two options:

1. make a PR to suggest/argument changes
2. make your own extension derived/based on the extension.

Leveraging extension mechanism, especially Lua filter can really help you do nearly anything you want.

[cderv]

Thanks for your feedback.

To be clear regarding your initial feature request

I propose to wrap the description into a content block like this:

The definition list LaTeX rendering is really done by Pandoc itself (https://pandoc.org/MANUAL.html#extension-definition_lists).

> pandoc -t latex
$V_{Rd}$
: description of symbol 1

$V_{Sd}$
:  description of symbol 2

$x$
:  very short math symbol

$M = F d$
: very long math symbol
^Z
\begin{description}
\tightlist
\item[\(V_{Rd}\)]
description of symbol 1
\item[\(V_{Sd}\)]
description of symbol 2
\item[\(x\)]
very short math symbol
\item[\(M = F d\)]
very long math symbol
\end{description}

I doubt we want to tweak this from Quarto (if we could, even not sure about that).

So you could also ask on pandoc repo for options to tweak it or provide new extensions for labelling environment.

Otherwise, using the existing Quarto extensions mentioned, or following the Lua filter tweaking path is your best bet IMO.