Issue 2840

[charlottejmc]

These changes should fix the issue encountered in /en/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown and its counterparts in ES, FR and PT. I have made the changes in EN and FR, but I will need some support to extend them to the FR and PT translations.

Closes #2840

Checklist

• [x] Assign yourself in the "Assignees" menu
• [x] Add the appropriate "Label"
• [x] If this PR closes an Issue, add the phrase Closes #ISSUENUMBER to your summary above
• [ ] Ensure the status checks pass: if you have difficulty fixing build errors, please contact our Publishing Manager @anisa-hawes
• [ ] Check the Netlify Preview: navigate to netlify/ph-preview/deploy-preview and click 'details' (at right)
• [ ] Assign at least one individual or team to "Reviewers"
  • [ ] if the text needs to be translated, please follow the translation request guidelines, then assign the relevant language team(s) as "Reviewers" and tag both the team as well as the managing editor in your PR.

[charlottejmc]

Hello @jenniferisasi and @ericbrasiln,

I've managed to get to the bottom of a lesson maintenance issue in the lesson about pandoc and markdown, by Dennis Tenen and Grant Wythoff.

As you can see from my files changed (in the EN and FR versions), we only needed to add a short component to two of the lines of code, and add a brief sentence to explain it to the reader.

Could you please make the same changes in the ES and PT files? escritura-sostenible-usando-pandoc-y-markdown autoria-sustentavel-texto-simples-pandoc-markdown

I hope it will be quite straightforward!

Thank you very much for your help.

[denten]

Folks, I recommend against this change. It will break for Windows and Linux users, and for a significant subset of Mac users who did not install into /Library/TeX/texbin/pdflatex. At best, it can be a foonote with a reference to the Pandoc --pdf-engine installation instructions.

[anisa-hawes]

Hello @denten,

Many thanks for taking the time to contribute. We really appreciate your insight.

As @davvalent suggests, ideally we would like to provide Windows and Linux users with alternative instructions to add /Library/TeX/texbin to PATH.

For example:

Whether you are working on mac, Windows or Linux, it is important to ensure that the pdflatex engine is installed in the location /Library/TeX/texbin by doing [THIS]. For more information, readers are advised to review pandoc's manual.

I wonder if you might be able to help us by suggest what the specific instruction needed here might be?

All best wishes, Anisa

[denten]

Review this discussion on Stack Overflow in consideration.

The path handling has changed in recent versions of MacOS. Providing explicit instructions for the current state will create a dependency in the tutorial. We will have to update the installation instructions for future versions, along with keeping the old ones for those who have not updated / older computers. And then the same with caveats for other operating systems.

That is not sustainable. The installation aspects should be linked from the tutorial to the package maintainers with a short note saying "follow the current instructions for installation." I would think other tutorials have a similar issue, and the journal should have a general and consistent approach to installation of tutorial dependencies.

I strongly recommend against duplicating the developer's installation guides. We just won't have the human power necessary to keep updating individual installations paths across the site, in a way that supports all possible platforms (and without testing!)

[anisa-hawes]

Thank you, @denten. That makes good sense.

In that case, I think this should be sufficient:

Whether you are working on mac, Windows or Linux, it is important to ensure that you provide the full path to the LaTeX engine you are using. For example, ours is installed in the location /Library/TeX/texbin/pdflatex. Readers are advised to check theirs, and follow the current installation instructions.

[denten]

That's great! Well put.

[davvalent]

Hi everybody,

I agree with your last comments, but in that case my understanding is that there's no need to change the pdf engine option. It seems that you are going to change --pdf-engine=xelatex, which is a valid value for this option according to the documentation (and the standard way to tell Pandoc which engine to use), by --pdf-engine=/Library/TeX/texbin/xelatex which is the full path to use when the engine is not in your PATH.

Is this what you want?

[charlottejmc]

Hi @davvalent, I'm not sure I understand your question exactly – what I can say is the previous instruction, which only told the user to write $ pandoc main.md -o main.pdf, failed for many users (including me). I think this is because pandoc isn't able to find this engine if we don't point directly to it with the extra --pdf-engine=/Library/TeX/texbin/pdflatex command (or --pdf-engine=/Library/TeX/texbin/xelatex, when we need to switch to an engine that can handle non-English).

I didn't realize that we use the full path when the engine is not yet in the PATH... I found the workaround from this comment on stackoverflow. There are other very different answers in that post, but this one seemed the simplest to me – with my very limited understanding of PATH environments, I must add!

[davvalent]

Hi @charlottejmc,

I'm sorry if I'm not clear enough.

I do understand the previous instructions failed for many users. The point is that these changes, as proposed, will also fail for many user for whom it wasn't failing before (Linux, Windows, and some Mac users too, as @denten has warned: https://github.com/programminghistorian/jekyll/pull/3171#issuecomment-1949268942). In these circumstances I wonder what is the point to apply these changes.

And the full path, whether it's /Library/TeX/texbin/pdflatex or /Library/TeX/texbin/xelatex, should be provided only when valid value failed (so it's a workaround). Of course it is important to ensure that the engine is in your PATH, or to provide the full path when it's not. That said providing the full path /Library/TeX/texbin/pdflatex in this lesson, for example, is providing explicit instructions for the current state that will create a dependency in the tutorial, and it already fails for other users as explained.

So my understanding of the situation at this point is that the lesson should remain as is (as the previous state for Pandoc instructions), and amended with a short note as proposed. The Pandoc manual on pdf-engine option could help: https://pandoc.org/MANUAL.html#option--pdf-engine

Is that clearer?

[ericbrasiln]

Dear @anisa-hawes and @charlottejmc,

I will await the finalization of the English and French versions before proceeding with updates to the Portuguese version. I believe @denten and @davvalent 's approachs are appropriate for this situation.

[ericbrasiln]

Dear @anisa-hawes, I've included the changes in the Portuguese version. GH is running the tests. Please check that everything is OK.

[anisa-hawes]

Thanks to all who have contributed here.

Reviewing the advice, I am a suggesting that we revert the commands at lines 500 and 511 to their original form, and we adjust the alert-box slightly to read:

If this command fails, you may need to add a component that provides pandoc with the full path to the LaTeX engine you want to use, specifying where it's stored. The location will vary depending whether you are working on mac, Windows or Linux. Readers are advised to check the correct path to the LaTeX engine within their system, and follow the current installation instructions