Template variables vs metadata variables

Template variables vs metadata variables

[mb21]

[-- Attachment #1.1: Type: text/plain, Size: 1041 bytes --]

Among new users, there often is confusion about the difference between 
template variables and metadata variables (e.g. this question receives 
quite some traffic: https://stackoverflow.com/questions/26395374/).

I was therefore asking myself: do we really still need template variables? 
Setting a metadata variable already affects the template. But is there a 
use-case for setting a template variable that absolutely most not be 
available in the document metadata?

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/d02165a6-eb50-45f6-9b59-3dbe3084fe9a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 1473 bytes --]

Re: Template variables vs metadata variables

[John MacFarlane]

It's a good question.  I can think of a few reasons not to shovel
everything into metadata.

One has to do with escaping:  currently metadata values are interpreted
and escaped when they're inserted into the template.  (Metadata values
in the document itself are treated as Markdown; those on the command
line as strings.)  Variables are just inserted raw into the template.
It's nice to be able to do both.

Another is that one might want to encode metadata systematically in the
output.  This is done in markdown output, where all your metadata will
appear in the output.  So, anything that one wants to affect template
rendering without being in the output needs to be in a variable.

In addition, there are some variables that are computed by the writer
that just affect conditionals in the templates.  For example, there
might is a variable that tells the latex template whether a beamer
document is being produced.  In some formats there's a variable that
tells the template whether math is being produced.  And so on.
Now, one could argue for keeping these internally and removing
the -V flag from the command line, but users may want to use
their own flags and set them on the command line.



mb21 <mauro.bieg-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> Among new users, there often is confusion about the difference between 
> template variables and metadata variables (e.g. this question receives 
> quite some traffic: https://stackoverflow.com/questions/26395374/).
>
> I was therefore asking myself: do we really still need template variables? 
> Setting a metadata variable already affects the template. But is there a 
> use-case for setting a template variable that absolutely most not be 
> available in the document metadata?
>
> -- 
> You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/d02165a6-eb50-45f6-9b59-3dbe3084fe9a%40googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

Re: Template variables vs metadata variables

[mb21]

[-- Attachment #1.1: Type: text/plain, Size: 1351 bytes --]

Thanks for the explanations (and reminders)... it seems like merging the 
two would cause more trouble than it's worth. But I've tried to clarify the 
wording in the MANUAL a bit at 
least: https://github.com/jgm/pandoc/pull/4501


On Monday, March 26, 2018 at 2:08:49 PM UTC+2, mb21 wrote:
>
> Among new users, there often is confusion about the difference between 
> template variables and metadata variables (e.g. this question receives 
> quite some traffic: https://stackoverflow.com/questions/26395374/).
>
> I was therefore asking myself: do we really still need template variables? 
> Setting a metadata variable already affects the template. But is there a 
> use-case for setting a template variable that absolutely most not be 
> available in the document metadata?
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/baa9e633-5dab-40d7-98f5-2905a34f8933%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 2455 bytes --]

Re: Template variables vs metadata variables

[John MacFarlane]

Good, I've merged your improvements.

mb21 <mauro.bieg-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> Thanks for the explanations (and reminders)... it seems like merging the 
> two would cause more trouble than it's worth. But I've tried to clarify the 
> wording in the MANUAL a bit at 
> least: https://github.com/jgm/pandoc/pull/4501

Re: Template variables vs metadata variables

[Pranesh Prakash]

[-- Attachment #1.1: Type: text/plain, Size: 3249 bytes --]

Dear John and Mauro,
(Is it against this list's etiquette to resurrect old threads? If so, my 
apologies, but I wanted to provide context.)

The differences as I understood them from John's explanation are:
1. Variables are literal, in-file YAML metadata (though not in defaults or 
--metadata-file) are read as markdown.
2. Variables aren't carried through to output, whereas metadata are.
3. -V variables can affect some computed template variables that -M 
metadata cannot.
and, from a different discussion: 
(https://groups.google.com/g/pandoc-discuss/c/zOaLjUqYmg0/m/K1hX3v2OAgAJ):
4. Some command-line options like `--bibliography`, do nothing but set a 
metadata value, but that's not interchangeable with "variable". 

So I thought I can use most things that are in the YAML metadata instead as 
variables.  But I realized that some of the things in the YAML metadata 
that can't be set as variables.

For instance, in a defaults file: 
  * I cannot set "reference-section-title" as a variable nor as an option 
(a regular YAML key like "standalone:", since there is no 
`--reference-section-title`), only as an element in the `metadata:` array 
(metadata field key, as per the manual), but:
  * I can set "toc-title" as a variable or as a metadata field key. 

Is there a real difference between "toc-title" and 
"reference-section-title", or is this just an accident of the histories of 
their development?

I also tested a few other options, and found that the following can be set 
as metadata field keys, or as options, but not as variables:
  * "suppress-bibliography" 
  * "citation-style" or "csl" (only the latter can be set as an option)
  * "bibliography"

"bibliography' and "csl" are I would have guessed (but I didn't realize 
"citation-style" wouldn't work as an option), but I wouldn't have guessed 
"suppress-bibliography".

I noticed something strange with "toc"/"table-of-contents":
If I set "table-of-contents: true" as a metadata key/value or variable, 
nothing happens. If I set "toc: true" as a metadata field key/value or 
variable, then "toc-title" variable gets printed in the HTML output (so 
"Contents" shows up) but no table of contents appears in HTML, but a table 
of contents does appear in PDF!  If I set "toc"/"table-of-contents" as an 
option, then the TOC shows up in both HTML and PDF.  I feel this may be a 
flaw in the HTML5 template.

Regards,
Pranesh


On Tuesday, 27 March, 2018 at 9:45:29 pm UTC+5:30 John MacFarlane wrote:

>
> Good, I've merged your improvements.
>
> mb21 <mauro...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>
> > Thanks for the explanations (and reminders)... it seems like merging the 
> > two would cause more trouble than it's worth. But I've tried to clarify 
> the 
> > wording in the MANUAL a bit at 
> > least: https://github.com/jgm/pandoc/pull/4501
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/cd4b6cf0-2a68-4858-b595-b9c842f82cdcn%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 4554 bytes --]

Re: Template variables vs metadata variables

[John MacFarlane]

Pranesh Prakash <the.solipsist-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> For instance, in a defaults file: 
>   * I cannot set "reference-section-title" as a variable nor as an option 
> (a regular YAML key like "standalone:", since there is no 
> `--reference-section-title`), only as an element in the `metadata:` array 
> (metadata field key, as per the manual), but:
>   * I can set "toc-title" as a variable or as a metadata field key. 
>
> Is there a real difference between "toc-title" and 
> "reference-section-title", or is this just an accident of the histories of 
> their development?

Yes, there's a difference. reference-section-title is added by
citeproc, to a Div within the document, so it can't be handled
via template variables.

> I also tested a few other options, and found that the following can be set 
> as metadata field keys, or as options, but not as variables:
>   * "suppress-bibliography" 
>   * "citation-style" or "csl" (only the latter can be set as an option)
>   * "bibliography"

Same reason as above.  citeproc processing needs access to these,
and since this occursr at the AST level, they need to be in metadata.

> I noticed something strange with "toc"/"table-of-contents":
> If I set "table-of-contents: true" as a metadata key/value or variable, 
> nothing happens. If I set "toc: true" as a metadata field key/value or 
> variable, then "toc-title" variable gets printed in the HTML output (so 
> "Contents" shows up) but no table of contents appears in HTML, but a table 
> of contents does appear in PDF!  If I set "toc"/"table-of-contents" as an 
> option, then the TOC shows up in both HTML and PDF.  I feel this may be a 
> flaw in the HTML5 template.

Best to regard the toc variable as for internal use only.  In
some formats it does something, in others not, and what it does
can be different, due to differences in the formats. In LaTeX,
all we need for a table of contents is a single command in the
preamble; this can be set with a template so `toc: true`
suffices.  In HTML, the `toc` variable activates a toc section in the
template, but the contents of this section must be generated
by the writer, which only happens if you selected `--toc` on
the command line. That is the documented way to do it.