-
-
Notifications
You must be signed in to change notification settings - Fork 3.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Command-line options --css and --include-in-header override corresponding metadata fields instead of accumulating #3139
Comments
There's some sort of discussion about this in #3138. @jgm mentioned it is simple to make the change, but since it breaks backward compatibility (some people might rely on this to override YAML's metadata), it requires a discussion in pandoc-discuss: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option - Google Groups. |
Use "header-extras" in yaml instead. See: jgm/pandoc#3139
+1 to making The current behavior is leading to a poor user experience in the wild. See manubot/rootstock#275: the pandoc-eqnos: Wrote the following blocks to header-includes. If you
use pandoc's --include-in-header option then you will need to manually
include these yourself.
<!-- pandoc-eqnos: equation style -->
<style>
.eqnos { display: inline-block; position: relative; width: 100%; }
.eqnos br { display: none; }
.eqnos-number { position: absolute; right: 0em; top: 50%; line-height: 0; }
</style> |
|
The issue here is a subtle one: when pandoc populates variables for a template, metadata values are used only if the corresponding variable doesn't have a value set on the command line. And the effect of One solution in your filter would be to check the metadata. If there is a |
I see. So it is out of the question to change metadata values such that they are not discarded, but added to, when command line options are also specified? Currently ec043e0 seems like it will give a way accumulate
My earlier example was in relation to @tomduck's How does a |
Thanks for tagging me in, @dhimmel. Pandoc-eqnos does what @jgm suggests: it appends to the header-includes metadata if it exists. A warning is printed in the case that there is a risk of the header-includes being overridden. Instructions are given so that the user knows what to write into header-includes files. Cheers, Tom. |
I wouldn't say "out of the question," but a big change like this could break behaviors that others are relying on, so I'm reluctant to do this without sufficient discussion and reflection.
No, I wouldn't say it's the whole purpose. But one thing it is good for is getting rid of "abuse of metadata." Ideally, metadata should be metadata, not option settings and instructions for creating output. That belongs elsewhere. With default files, you'd be able to put this in a defaults file and focus on content (and genuine metadata) in your markdown file. |
This is not a great solution IMO because it shows requires always showing a warning, regardless of whether it's relevant (can confuse users as seen in tomduck/pandoc-tablenos#16). And if it is relevant, the user is required to duplicate content that belongs as part of the upstream filter. Here's what a filter has access to when the > echo " " | pandoc --to=json --include-in-header=README.md
{"blocks":[],"pandoc-api-version":[1,20],"meta":{}} Here's what a filter has access to when the include-in-header:
- build/themes/default.html
- build/plugins/anchors.html > echo " " | pandoc --defaults defaults/html.yaml --to=json --include-in-header=README.md
{"blocks":[],"pandoc-api-version":[1,20],"meta":{}}
# note that if --to=json, --include-in-header and defaults.include-in-header accumulate So the filter is in a tough position, because it cannot know whether
Balancing metadata, defaults, and command line options is complicated! |
+1 to have include-in-header append to header-includes instead of overwriting it. |
Could we have a practical example of why the appendment-supporters would want to include CSS/Headers in both YAML metadata as well as on the commandline during invocation? If you're using CSS/headers in the YAML metadata:
If the commandline argument also becomes equivalent to appending, then there is no clear way to override. This would be a loss of functionality. So there seem to be reasons apart from backward compatibility for maintaining the current behaviour. But confusingly, when it comes to other metadata, the behaviour is very inconsistent. I tried adding "author:" metadata in 5 places: the in-file pandoc-style metadata (using
So while there is an argument to be made for allowing for overriding/overwriting, there is also a need to have some non-arbitrary rule as to the rules of precedence, and when and how they differ between different classes of things (like metadata vs. variables), especially when some things have their own flag and can be part of YAML metadata as well ( There are at least two other open issues linked to this: #3115 (comment) and #4057 |
My use case is to produce different versions of the document / in scripting contexts. Some headers are required by all versions of the document, so it makes sense to add them to the file itself, others are customizations that depend on the specific versions, which are overridden on the command line on a per-production case. Of course there are workable alternatives (like creating huge command lines with all the includes or running the document through a preprocessor like |
The manual currently states:
(text introduced by this commit: ec043e0) However, the example I've cited above shows that a metadata value set in Footnotes
|
Adding a +1. I have a set of common macros for note-taking and other writing. For certain inputs, I want to use additional packages, including some that are relatively heavyweight. Ideally, I'd be able to add to header-includes in the file itself, while still sharing the common header includes file. I could fork the template and modify it myself, but frankly, maintaining and updating a template is something that I'd rather not spend time doing, even if it's as simple as I also have a Makefile, so I could just write the Python for a pre-pandoc step to generate a metadata file, or even hack something together ( |
I think you're misreading the manual. The manual says that the value given to the |
@Oblomov, could you satisfy this use case by simply having different defaults files (with, if need be, different |
I see the metadata file as a different hack / workaround, but still not a “clean” solution. I could create different metadata files for the different use cases, which just shifts the problem around from humongous command lines to some kind of scripting to create the metadata file. The fundamental issue —i.e. that some options override each other with different priorities, and there is no way to specify they should be merged instead— remains unsolved, regardless of interface. |
Weighing in with another +1. My use case is that I have a Lua filter used to render certain classes of |
I think it starts to look like a bit of a mess if filters can not only alter the AST, but also change writer options. Then filters are two things, not one. So my first instinct is that this isn't a good idea. |
I'm not sure what the right solution is, but I would urge that the solution ensures that there are clear ways both to accumulate metadata fields / defaults values as well as to override (perhaps with a special flag, if need be). Please don't remove an existing method of overriding values without providing an alternative. |
+1 to making --include-in-header append to header-includes rather than overwriting it. |
This issue is open for years, and I also agree with some commenters that it would be great to be able to combine metadata from If you need a command across the whole document, you cannot define it in the markdown body since it is surrounded with |
+1 to making --include-in-header append to header-includes rather than overwriting it. |
+1 to making --include-in-header append to header-includes rather than overwriting it. |
It is pretty easy to modify your local (possibly local default) templates for any sets of includes which don’t interact with after
and then just before
(See Templates in the Pandoc manual!) and then in your metadata: before-header:
latex:
- |
```{=latex}
\usepackage{mypackage}
\include{myinclude.ltx}
```
html:
- |
```{=html}
<link rel="stylesheet" href="mystyle.css" />
```
after-header:
html:
- |
```{=html}
<style>
.red { color: red }
</style>
``` Note that you still have to wrap the actual markup in raw blocks to avoid Markdown escaping! Or you could put it in a defaults file like this to avoid that: (See Defaults files in the Pandoc manual!) variables:
before-header:
latex:
- |
\usepackage{mypackage}
\include{myinclude.ltx}
html:
- |
<link rel="stylesheet" href="mystyle.css" />
after-header:
html:
- |
<style>
.red { color: red }
</style> You can of course also have includes:
latex:
header:
before:
# list of markup blocks
after:
# list of markup blocks
body:
before:
# list of markup blocks
after:
# list of markup blocks
html:
# You get the idea and then in your latex template
etc. Of course in your html template you could have $for(link-css)$
<link rel="stylesheet" href="$link-css$" />
$endfor$
$if(css-style)$
<style>
$for(css-style)$
$css-style$
$endfor$
</style>
$endif$ and then in your defaults file variables:
link-css:
- mystyle.css
css-style:
- |
.red { color: red } In other words you can include anything from metadata and variables you like however you like in your templates, and as long as you use other names than those variables which pandoc associates with its commandline options your custom fields will be totally independent. In my custom latex template I for example have: $for(ltx-pkg)$
$if(ltx-pkg.opts)$
\usepackage[$--
$for(ltx-pkg.opts)$
$ltx-pkg.opts$$sep$,
$endfor$
]{$ltx-pkg.name$}
$else$
\usepackage{$if(ltx-pkg.name)$$ltx-pkg.name$$else$$ltx-pkg$$endif$}
$endif$
$endfor$ which with this in a defaults file variables:
ltx-pkg:
- foopack
- name: ulem
opts: normalem
- name: mypack
opts:
- tic=tac
- toc
- tuc
- name: barpack gives this in my latex header \usepackage{foopack}
\usepackage[
normalem]{ulem}
\usepackage[
tic=tac,
toc,
tuc]{mypack}
\usepackage{barpack} Now I guess someone ought to make a PR for adding all those |
Hello,
I just noticed that using the command-line
-c
(respectively,-H
) option overrides anycss:
(respectively,header-includes:
) keys in the YAML metadata sections.This is a bit surprising, since the options themselves are otherwise cumulative (one can specify multiple
-c
and-H
options, and they get all used), and makes it much harder to have both common and file-specific CSS and header includes (in this sense, this bug is related to #3115).I believe that, to avoid violating the principle of least surprise, the -c and -H options should be cumulative with the file metatada (and specifically added after the internal ones). OTOH, such a change in behavior would break backwards compatibility, so maybe a way to specify additional CSS and header-includes from the command line should be given?
(If the replacing behavior is preserved, it would also be a nice idea to document it in the manual.)
The text was updated successfully, but these errors were encountered: