Conditionals evaluate truthiness

[gl-eb]

I've recently been working on a Typst template for Quarto via pandoc. I had a moment of confusion when I was setting a variable to false in the YAML block of the source file. My Typst template included the following conditional to pass the variable onto a Typst function in case it was set by the user.

$if(variable)$
  variable: $variable$,
$endif$

The Pandoc user guide states that "the if section is used if variable has a non-empty value". Thus I could not understand why the conditional was evaluating to false. After some research I learned that conditionals actually check for truthiness of the variable. This used to be reflected in the manual in the past (see #4631) but was removed again with commit ac4067f

Judging by the PR mentioned above this is expected behaviour. I would have found it helpful had the documentation explained this. I'm happy to draft a PR to add back the removed lines.

[jgm]

The documentation for doctemplates say that the string false is interpreted as a true value. But the boolean value False is interpreted as a false value.

In YAML,

foo: false

will set foo to the boolean value False, and your conditional will not trigger. Contrast

foo: "false"

which will cause your conditional to trigger.

Does that clear things up?

[gl-eb]

Ah, I did not know that pandoc's templating system had a separate repo and documentation. This indeed clears it up. Maybe the pandoc user guide could link to it? In any case, thanks for taking the time to explain!

[jgm]

I think that most of the relevant text has been copied into the pandoc manual, but if you find things that are missing, let us know.

[gl-eb]

I can't seem to find the section on what counts as true in conditionals in the pandoc manual/user guide. It just mentions that values should be non-empty, but does not elaborate. The doctemplates documentation meanwhile says that variables need to have a true value and then elaborates what counts as true.

I've highlighted the differences in bold below.

pandoc:

A conditional begins with if(variable) (enclosed in matched delimiters) and ends with endif (enclosed in matched delimiters). It may optionally contain an else (enclosed in matched delimiters). The if section is used if variable has a non-empty value, otherwise the else section is used (if present).

doctemplates:

A conditional begins with if(variable) (enclosed in matched delimiters) and ends with endif (enclosed in matched delimiters). It may optionally contain an else (enclosed in matched delimiters). The if section is used if variable has a true value, otherwise the else section is used (if present). The following values count as true:

• any map
• any array containing at least one true value
• any nonempty string (even false)
• boolean True

[jgm]

I can't seem to find the section on what counts as true in conditionals in the pandoc manual/user guide. It just mentions that values should be non-empty, but does not elaborate.

This is just YAML. We should make this clearer and explain what is interpreted as a Boolean value in YAML.

[jgm]

Let me know if this looks ok

[gl-eb]

Looks good to me! Thanks a lot for taking the time. All the work you put into pandoc is greatly appreciated