Description
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
@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
One possible solution here is to have two or three
include-in-header-top. Placed as high up as possible in the header.include-in-header-middle. The current location. Which, for backward compatibility, the currentinclude-in-headerwould map to.include-in-headerwould be deprecated (supported but discouraged).include-in-header-bottom. Placed just before\begin{document}.
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".