search

jgm / pandoc

Universal markup converter
https://pandoc.org
Other
33.33k stars 3.31k forks source link

$header-includes$ in default.latex #7286

Closed JohnLukeBentley closed 3 years ago

JohnLukeBentley commented 3 years ago

This is a restatement, with some variation, of the post Google groups > pandoc-discuss > Is $header-includes$ too high in default.latex?.

The option --include-in-header is specified to "Include contents of FILE, verbatim, at the end of the header". https://pandoc.org/MANUAL.html#option--include-in-header

The option --include-in-header sets the template variable $header-includes$.

However, in default.latex the $header-includes variable is placed quite high in the header, preceding quite a number of latex header commands. Shouldn't $header-includes be placed just before \begin{document}?

My motivation is to override prior default settings. Specifically I'm trying to override a range of \csl commands that gets spit out in the header when processing citations.

I can do this by using --include-before-body/$include-before$ instead. But that seems like abusing what should be a content option rather than a coding option. In addition it precludes wrapping my overriding commands in a \usepackage{MyOverrides}, as latex will complain about \usagepackage commands coming after \begin{document}.

Of course I could alter default.latex at my end, and use a custom default template. But I'm trying to avoid that path.

So, is $header-includes$ too high in default.latex?

@jgm wrote, in esssence,

We've put it as late as possible in the template. The reason it's not at the very end is that some things really need to be loaded as late as possible ... go ahead and submit an issue on the GitHub tracker so we can think more about this.

My (limited) experience with latex matches what you mention here. That is, the order of things in the header can get very particular. Some packages rely on the definition of prior commands, or the declaration of prior packages. Some commands can only be defined after declarations of prior packages. Etc.

I'm not sure if there's some overall latex header architecture that provides a general best practice for the order of command types that could help us here (I'll research this). I suspect not and that it boils down to an ad hoc dependency relationship depending on the particular packages used.

Anyway I very much appreciate why, over time, you've found the need to rise the $header-includes$ in the header.

One possible solution here is to have two or three $header-includes$/header-includes/--include-in-header. E.g. (using my suggested best naming)

In my particular real world case I'd find great use for include-in-header-bottom. However, for completeness, I suppose there could be a use for include-in-header-top. In addition, that is, to the current location of include-in-header (which would become include-in-header-middle under my scheme).

As a separate but related matter it would be nice to harmonize the naming of all the includes variables, regardless of location. E.g. Under https://pandoc.org/MANUAL.html#variables-set-automatically we have ...

include-before contents specified by -B/--include-before-body ...

... "include-before" ought be renamed "include-before-body".

jgm commented 3 years ago

I would prefer not to make big changes (adding complexity) unless absolutely necessary. It seems that your needs would be met if we could move the csl commands before header-includes, and I can think of no reason why we couldn't (but I'll give it a bit more thought).

JohnLukeBentley commented 3 years ago

It seems that your needs would be met if we could move the csl commands before header-includes.

Yes that would do it at least for this particular case (of overriding CSL commands); and it may well be that in practice this particular case is the only, or almost only, reason to complain about the order of $header-includes$.

I've just done a quick test of this using your change to default.latex. And it's working all OK at my end.

(That is, for inserting latex CSL overrides directly into $header-includes$. Attempting to wrap those commands in package and use $includes-header$ to merely insert \usepackage{MyOverrides} fails for reasons that are separate to this issue. Reasons that I may or may not raise elsewhere).

So thanks @jgm. You are a god and I will pray at your temple.

JohnLukeBentley commented 3 years ago

For completeness, for any users using $header-includes$ to override pandoc's latex CSL output, @jgm's update to default.latex does allow one to wrap one's overrides in a package and use $includes-header$ to merely insert \usepackage{MyOverrides}.

To achieve this one only has to make one's latex install be aware of the location one's custom packages.

Windows and Miktex users, for example, can follow the procedures at Stackexchange > Tex > Where do I place my own .sty or .cls files, to make them available to all my .tex files? > Answer by John Bentley.