ENH: Rendering into Journal-provided LaTeX templates

[michaelosthege]

Context

This is about file types in academic publishing.

I tried to illustrate the story below 👇

sequenceDiagram
    participant arXiv
    actor Alice
    participant Journal
    Alice->>+arXiv: Upload PDF
    Alice->>+Journal: Submission (PDF)
    arXiv-->>-Alice: It's online!
    note right of Alice: Alice is 😃
    Journal-->>-Alice: Major/minor revision
    Alice->>+Journal: Revision (PDF)
    Journal-->>-Alice: Accepted. Now upload DOCX or use our LaTeX template.
    note right of Alice: Alice is 😖

Loading

Note that for dissertations this is not a problem, because you print them yourself.

Also for books it's not a problem because book publishers accept EPUB.

Problem

Nice-looking, customized PDFs are cool, but an output format that the Journals accepts is cooler.

If it works at all, the only method to create DOCX would probably through pandoc. But it doesn't fit into the executablebooks/Sphinx toolchain and it's questionable wheather cross-references, citations etc. would work.

So the question is: How can we render a JupyterBook Article into a Journal-provided LaTeX template?

Solution

Here are two examples of LaTeX templates, and I'm sure there are more:

• All PLOS journals use the same plos_latex_template.tex
• All Elsevier journals use the elsarticle.cls class

More are listed on https://www.latextemplates.com/cat/academic-journals

Benefit
Right now the jb build manuscript --builder pdflatex output doesn't look anything like a scientific article by default.
^{Or did I overlook a tutorial?}

By rendering into Journal-provided templates, there would be an immediate benefit of nice-looking, standardized PDF output.

Guide for implementation

There's a jupyterBook.cls.

Could this be replaced with a (curated) collection journal-provided templates?

@AakashGfude @mmcky

Tasks and updates

No response

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[mmcky]

thanks for opening this issue @michaelosthege -- it's a great idea -- and we would like to be able to support articles in the future. Currently jupyter-book is primarily focused on building beautiful books, but the stack is building better support for articles and the _toc.yml now supports jbarticle (for example).

We would like to make use of these _toc formats jbarticle and jbbook in this extension to better support LaTeX.

We are also working with the good folks at curvenote (@rowanc1 @stevejpurves) and they are doing some really nice work on building support for a large range of LaTeX templates through jtex. We are looking at how we might be able to integrate this work in jupyter-book.

[michaelosthege]

Thanks @mmcky, I'm already using jb-article. I just searched the codebase for jb-article to better understand its implications, but apart from docs & test suite, I found just three lines of code in all of executablebooks that changed some behavior based on the jb-article setting:

1. Something in migrate_jupyter_book (not relevant)
2. The sphinx_external_toc.parsing.FILE_FORMATS lookup dict
3. And a different latex_toplevel_sectioning setting which was linked to jb-articles contains no top level headings jupyter-book/jupyter-book#1552

I'm new to jupyter-books and know little about it's architecture and how it integrates with Sphinx. Where's the code that produces the .tex file?!
So far I was mostly confused by the _toc.yml supporting two similar "formats".
But given that jb-article makes little differences at the moment (actually breaking headline numbering) and given that jb-book also renders through sphinx_jupyterbook_latex/theme/jupyterBook.cls, I wonder if having format: jb-book | jb-article is the right approach.
^{Plus in my opinion, YAML is a terribly intransparent format for making configurations to begin with.}

Since jb-book is also LaTeX-rendered through sphinx-jupyterbook-latex, doesn't the idea of templating apply to books too?

Jinja-templating is certainly a good idea too, but it sounds like a completely different approach. Regarding publisher-provided LaTeX templates I have no idea whether the current, or a jtex driven approach is easier or more sustainable.

Personally, I'm also under a lot of time pressure, but I'm also very interested in writing my next article & thesis with jupyter-book, so I'm trying to figure out how realistic that is.

[mmcky]

@michaelosthege currently it is used by sphinx-external-toc to assist with defining the _toc.yml structure parsing. But this format can be used by sphinx-jupyterbook-latex as we can make more assumptions around the sphinx document tree which will enable better more targeted support for articles etc.

The project is building support from the ground for articles up but it hasn't really gotten past the foundations yet.

Where's the code that produces the .tex file?!

The actual TeX/LaTeX is written by sphinx.writers.latex and we adopted the strategy in sphinx-jupyterbook-latex to adjust the sphinx.AST and retain use of the downstream writer in sphinx to reduce code duplication.

or a jtex driven approach is easier or more sustainable.

Yeah we would need to translate the sphinx.AST to the jinja template structure used by jtex so we are looking at the feasibility of this. It would be nice to integrate with a wider community effort to increase sustainability etc. and at the same time get much great functionality and support. This work is in the early days though.

Good luck with your thesis and articles. We would welcome any feedback you have -- you may also want to checkout https://curvenote.com for the article if you like using MyST.