search

quarto-journals / article-format-template

Template for creating a new journal article format for Quarto
MIT License
66 stars 16 forks source link

leftover includes from default pandoc template #1

Closed jmbuhr closed 2 years ago

jmbuhr commented 2 years ago

Please let me know if this is too early for issues, since this seems to be fairly new :)

I was trying to implement a pdf/tex template for a journal and run into a latex package conflict and can't figure out where the conflicting package is coming from. The default pandoc template includes amsmath: https://github.com/quarto-dev/quarto-cli/blob/8d2e1ab9e2a1f2a0dcd93e0f396a85cdba617a48/src/resources/formats/pdf/pandoc/template.tex#L67 And this also makes its way into the processed tex file of my format: https://github.com/jmbuhr/bps-quarto-format/blob/1cc9465d2d602633c2bce93dcae264fe1359a5f4/template.tex#L9

However, I am not including the package myself anywhere in the partials. The latex class that implements the style for the journal uses a different math package (hence the clash).

Are there some residuals from the default pandoc `tex' template even when using a custom template?

jmbuhr commented 2 years ago

Looks like this happens for all extensions. I just checked the tex output of https://github.com/quarto-journals/acm, which even features the line % doesn't load epsfig, amssymb, amsmath, and amsfont.( https://github.com/quarto-journals/acm/blob/dd624dba96b3bbbb62243be328507ad4e200bc96/_extensions/quarto-journals/acm/sensys-abstract.cls#L31), but it still does.

jmbuhr commented 2 years ago

I'm on the latest quarto version: v0.9.624

cderv commented 2 years ago

Hi @jmbuhr,

Thanks for the report, especially for ACM format that we'll obviously need to fix.

Please let me know if this is too early for issues, since this seems to be fairly new :)

Yes this repo is brand new and hopefully offer a way for us (and others) to more easily create a custom format. The extension mechanism is also not yet documented, but will be soon. So you're quite early, but it is good to have some early adopters to work with.

We are currently working in quarto-journals to create formats for a number of journals (based on what rticles covers already

Which journal are you working on ? We are interested to help you do it, and moreover not create a duplicate. Happy to host this journal format repo in quarto-journals organisation also if you want.

Anyway, let's dig more into the current topic.

Looks like this happens for all extensions

Yes this will happen with every format that uses the default Pandoc template. If is not a leftover really, it is just that those package are loaded in default Pandoc template, because they are probably require by some Pandoc features (https://pandoc.org/MANUAL.html#creating-a-pdf).

As you notice, sometimes this could conflict with guidelines for other type of output, or one just want to tweak this. This is why we have an extension mechanism to have some custom formats. With Pandoc only, one would need to provide a full new .tex template to use, but with Quarto we offer a more simple mechanism we believe as a partials mechanism will be used to tweak some part of the template. Future documentation will make that more clear.

This repo offers a template one to create new format, but it will include all the default file one could tweak (or not) to modify the default template. So there will be no removal in this repo.

Hope this is more clear.

Bad news regarding your finding however is that this specific part you linked to (https://github.com/quarto-dev/quarto-cli/blob/8d2e1ab9e2a1f2a0dcd93e0f396a85cdba617a48/src/resources/formats/pdf/pandoc/template.tex#L67), is not something that can be easily tweak without tweaking the full template.tex file that I forgot to ship with this repo.

I'll see how we should proceed for such format by fixing ACM format. The idea would be for now:

However, as this is not a partial but the main template, I am not sure our mechanism cover this yet 🤔

I'll report back.

cc @dragonstyle this could be of interest to you.

cderv commented 2 years ago

However @jmbuhr just to be clear:

ACM cls file says in https://github.com/quarto-journals/acm/blob/dd624dba96b3bbbb62243be328507ad4e200bc96/_extensions/quarto-journals/acm/sensys-abstract.cls#L31

% Here are the main changes to acm_proc_article-sp.cls, as far as the % interface is concerned:

% It doesn't load any of the utility packages, specifically, it % doesn't load epsfig, amssymb, amsmath, and amsfont.

Does it means that those packages should not be loaded ?

Or is it just that you are surprised they are ?

Just to understand what would need to be done in ACM.

I was trying to implement a pdf/tex template for a journal and run into a latex package conflict and can't figure out where the conflicting package is coming from.

Regarding this, the partials mechanism is here to help modify part of the main default template (which is https://github.com/quarto-dev/quarto-cli/blob/8d2e1ab9e2a1f2a0dcd93e0f396a85cdba617a48/src/resources/formats/pdf/pandoc/template.tex#L67)

If you want to completely replace this template, as I said above, then you need to provide your own version of template.tex (that may or not use a partial mechanism too). Hopefully our (undocumented) extension mechanism supports that.

jmbuhr commented 2 years ago

Yes, it would be cool to host it here once finished. I am working on the Biophysical Journal (https://www.cell.com/biophysj/home), specifically their overleaf latex template: https://www.overleaf.com/articles/biophysical%E2%80%90journaltemplate/pxxcptphxdhv

If I understand correctly, the idea behind having template partials is to make it easier to replace or change parts of the default pandoc template without having to change the whole thing. This is why expected the overall template (template.tex), when used with partials, to be made up entirely out of those partials. This would make it completely modular. Otherwise the need for a completely bring-your-own template.tex might arise too early even when changing just little things because they are tied to the overall template implicitly. Does that make sense? This would mean the entire template.tex is refactored into partials and only brings those partials together, like in these lines: $doc-class.tex()$ or $title.tex()$.

dragonstyle commented 2 years ago

Great to see you working on this @jmbuhr! A couple of notes:

We ended up trying to strike a balance between making partials for small frequently replaced portions of the template, but not creating partials for everything (which we felt would make the list of partials very long and very hard for many users to reason about / understand). In your case, if you're thinking you'd like to start with a clean slate, I think as @cderv said, providing a template.tex yourself is probably the right path. We stage your template alongside our partials, so you can start with an empty file and include any of our partials that are useful (or include none if that works better).

We did try to get at just what you're suggesting - e.g. not require the switch to a template.tex too early, so if you find cases that are requiring that, this might be a good justification to make a partial out of those portions of the template (though I still think we should seek to be parsimonious with the creation of partials)...

jmbuhr commented 2 years ago

I honestly don't know what packages should or should not be loaded :see_no_evil: This template business is quite a task! And I am glad you are on it. With so many interlocking systems and different standards, paired with archaic LaTeX as a whole is sure is a challenge. I am always surprised by the amount of LaTeX I am willing to write in order to not have to write LaTeX.

It will be quite hard to keep track of all the different things. Quarto adds tex through lua filters, pandoc creates the tex and uses a template and/or quarto's partials, and then we try to make in compatible with some article class by a journal template.

For example, whenever we have a table, quarto automatically adds the longtable package via a lua filter. However, longtable does not play nicely with multi-column layouts. So for example the quarto-journals/acm-pdf fails as soon as there is a markdown table in the document.

cderv commented 2 years ago

@dragonstyle this discussion makes me wonder if we should have something like minimal mode in HTML but for PDF or equivalent to theme: none but regarding Pandoc's LaTeX feature.

It is not something straighforward because creating Quarto format that would no be able to work with Quarto feature is probably quite limited. The advantage over using Pandoc directly with a custom templates remains small in that case. But I see cases where it would be interesting as Quarto offers a nice wrapping workflow around calling Pandoc.

@jmbuhr this relates to your comment of Quarto more content in addition to Pandoc. Having something with the bare minimum would mean loosing most of the feature. But it will always be difficult to triage this, as we could also add like R packages that would also require some other dependencies when used in a document, instead of using bare LaTeX directly.

Just curious btw, which Lua filters is adding longtable ?

jmbuhr commented 2 years ago

oh, my bad, longtable can either come directly from pandoc or the tables.tex partial. It was just being processed by quarto in format-pdf.ts

jmbuhr commented 2 years ago

Thanks for the help, I finished the extension now: https://github.com/jmbuhr/biophysical-journal

cderv commented 2 years ago

Awesome! It looks good !

I think what we could do is :

What do you think ?

jmbuhr commented 2 years ago

Sounds good :) I am alreay using the namespace in the readme in anticipation of this.

jmbuhr commented 2 years ago

I can't transfer it just yet, I think, because You don’t have the permission to create public repositories on quarto-journals

cderv commented 2 years ago

OK I'll see about that and report back

cderv commented 2 years ago

@jmbuhr can you add me to your repo so I can move it here ? That would be the easiest I think.

jmbuhr commented 2 years ago

Sent the invite

jmbuhr commented 2 years ago

I assume I need to make you and admin or something once you accept.

Maybe for a general workflow the easiest would be to add people to the quarto-journals organization and then have them transfer the repo? Not sure if this is how gh works.

cderv commented 2 years ago

I assume I need to make you and admin or something once you accept.

Yeah it seems you're right. I can't do it right now. Only an admin can do it.

Maybe for a general workflow the easiest would be to add people to the quarto-journals organization and then have them transfer the repo? Not sure if this is how gh works.

We are still deciding how we want to do that. But let me explain our current thinking.

The above would mean that quarto-journals organization member (which would be quarto team) would have access to all the repo, so that we can contribute easily. Regarding external collaborators, they would not be part of the Quarto Journals organization itself has this should not be necessary - e.g we want to control new repositories creations, and don't want everyone to have access to all repos of the organization.

Does it make sense ? I am still looking through the doc and trying to come up with the best solution for us regarding what quarto-journals is and how we want to manage it. It is pretty new.

So concretely, in order for you to transfer, we would need to add you as a member of the organization so that you can create repository which is required for the transfer. But then we would remove you for the organization so that you have access only to the repo you are maintainer of.

That is why I asked the other way: Give access to your repo to one of the quarto-journals member so that we can transfert the repository and give you the admin right on this one once transfer. We will have access anyway after the transfer.

Does it also make sense ?

Nothing is set in stone here. As I said, I am still learning and thinking. Once all set up, we'll have a write-up about that probably. Thanks for giving us the opportunity to think this through now.

jmbuhr commented 2 years ago

I think I now sent the request to transfer ownership to you

cderv commented 2 years ago

Ok ok. Do you think it is easier than adding me as admin to your current repo ? I did not thought of that, but it will surely work. 🤔

jmbuhr commented 2 years ago

Under "collaborators" I was only able to add you as a collaborator, not specify the level of access. I think this is only available for organization-owned repos

jmbuhr commented 2 years ago

So I think the transfer is the closes to just making you an admin

cderv commented 2 years ago

Ok it seems you're right. this is for an organization. Let's try the first idea of adding you to the organization. I'll adjust later the permission. Thanks for staying with me for this tests - I like to understand how this works.

jmbuhr commented 2 years ago

No problem :)

cderv commented 2 years ago

Great invit sent. Once accepted you should be able to transfer your repo.

jmbuhr commented 2 years ago

I think it's working :)

jmbuhr commented 2 years ago

Maybe within the organization you can use teams, e.g. one for external contributors to further specify access rights

cderv commented 2 years ago

Yes I am looking at that. For now you are the first external collaborator so I don't think team is needed yet. I'll consider those though.

What happened in the last few minutes :)

Does it looks ok to you ? Do you have the correct access right on your project repo ?

jmbuhr commented 2 years ago

Looks good! I will also try to push a commit to test this

jmbuhr commented 2 years ago

Works like a charm (figuratively).

Quick question: I thought about including a screenshot of the rendered template to make the format easier to discern at a glance. I have now put it in the style-guide readme, because this is excluded from the quarto template download by default (https://github.com/quarto-journals/biophysical-journal/tree/main/style-guide). But it would make more sense in the overall README. Would it make sense to .quartoignore the README as well or should this usually say in the bundle?

jmbuhr commented 2 years ago

Oh, never mind, the README is already excluded by default