Sustainable Authorship Using Pandoc and Markdown - Pdf creation bug

[arockenberger]

Hei!

I have used the "Sustainable Authorship Using Pandoc and Markdown" (https://programminghistorian.org/en/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown) for teaching two weeks ago on 2023-01-10.

Problem: It works very well; however, when trying to create a .pdf file from a markdown file or any other file format, at least half of the participants were unsuccessful due to an error where pdflatex was unable to run. We found out that re-installing the TeX distribution (in our case MikTeX) in a rather peculiar way helped (see bottom of Issue).

Interestingly, the problem occurred on both Mac and Windows machines, but only for some participants. We could not detect any pattern.

Specs for one participant:

• Installed version of LaTeX: MikTex for Mac, miktex-22.1-darwin-x86_64.dmg (https://miktex.org/download)
• System: Mac OS Ventura 13.0.1 (22A400)
• Pandoc: pandoc 2.19.2

Suggestion:

Update the lesson with a short paragraph on troubleshooting, especially when creating .pdf files where a LaTeX distribution is necessary.

Solution (provided by @eriskar):

Deinstall all versions of MikTex Deinstall Adobe Reader (if installed) Restart computer Move installation folder for MikTex to the Desktop Create a folder MikTex 2.9 in Applications Move MikTex into that folder Run pandoc again - should work

[eriskar]

Dear all,

As we had similar issues at our Digital Area Studies (DAS) seminar series last Tuesday (https://ikos-dighum.github.io/), an easier approach may be to simply uninstall MikTex and download and install TeX Live instead: https://tug.org/texlive/windows.html.

It is a pain and the installation process may take at least one hour, but it proved pretty stable once done.

P.S. We have a seminar on how to use Markdown with Zotero and BetterBibTex next Wednesday (https://ikos-dighum.github.io/calendar.html). Please feel free to join us.

All my best wishes,

Erik

---

From: Annika Rockenberger @.***> Sent: 26 January 2023 13:40:08 To: programminghistorian/jekyll Cc: Erik Skare; Mention Subject: [programminghistorian/jekyll] Sustainable Authorship Using Pandoc and Markdown - Pdf creation bug (Issue #2840)

Hei!

I have used the "Sustainable Authorship Using Pandoc and Markdown" (https://programminghistorian.org/en/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown) for teaching two weeks ago on 2023-01-10.

Problem: It works very well; however, when trying to create a .pdf file from a markdown file or any other file format, at least half of the participants were unsuccessful due to an error where pdflatex was unable to run. We found out that re-installing the TeX distribution (in our case MikTeX) in a rather peculiar way helped (see bottom of Issue).

Interestingly, the problem occurred on both Mac and Windows machines, but only for some participants. We could not detect any pattern.

Specs for one participant:

• Installed version of LaTeX: MikTex for Mac, miktex-22.1-darwin-x86_64.dmg (https://miktex.org/download)
• System: Mac OS Ventura 13.0.1 (22A400)
• Pandoc: pandoc 2.19.2

Suggestion:

Update the lesson with a short paragraph on troubleshooting, especially when creating .pdf files where a LaTeX distribution is necessary.

Solution (provided by @eriskarhttps://github.com/eriskar):

Deinstall all versions of MikTex Deinstall Adobe Reader (if installed) Restart computer Move installation folder for MikTex to the Desktop Create a folder MikTex 2.9 in Applications Move MikTex into that folder Run pandoc again - should work

— Reply to this email directly, view it on GitHubhttps://github.com/programminghistorian/jekyll/issues/2840, or unsubscribehttps://github.com/notifications/unsubscribe-auth/A2OTJAIRW2RKOPPVGJD2Z6TWUJWCRANCNFSM6AAAAAAUHON76Y. You are receiving this because you were mentioned.Message ID: @.***>

[anisa-hawes]

Hello @arockenberger and @eriskar,

Thank you for getting in touch and for providing this detailed report + proposed solution.

It is wonderful to hear that you've both been integrating PH lessons into your teaching!

I will investigate this Issue, and test the steps you propose.

With very best wishes, Anisa

[anisa-hawes]

P.S. Your Digital Area Studies seminar series looks very interesting.

I already have something in my calendar during that slot next Wednesday, but I will make some time to peruse the Suggested Readings. I'm tagging my colleague @GeeAlmeida incase they might be available/interested in joining you for the session (or another in the future – the events calendar is online).

[GeeAlmeida]

Hi @eriskar and @anisa-hawes

Thanks for the invitation. I'll keep an eye on the calendar and might turn up for a session in the near future.

[hawc2]

@anisa-hawes any updates on this bug? I can reach out to the authors to get their input if that's ok with you

[anisa-hawes]

Thank you, @hawc2. That would be much appreciated.

(I hadn't realised that Grant Wythoff was one of your collaborators on the Philly Community Wireless initiative!)

[hawc2]

Yeah, Grant was one of the founders! I've emailed him this bug so hopefully we'll hear back in next week or so

[gwijthoff]

Hi everyone! Thanks so much for using the lesson in your teaching, and for filing this bug report.

Because the tutorial doesn't specify a LaTeX version (i.e. MiKTeX, BasicTeX, MacTeX, etc.), it would be difficult to provide troubleshooting recommendations for PDF creation: everyone will get slightly different results.

One approach would be to recommend that users switch their LaTeX engine in the Pandoc command if they have trouble making a PDF. More info is available in the Pandoc documentation, but an example would be to add --pdf-engine=xelatex to the end of a pandoc command.

@denten may have further thoughts.

[anisa-hawes]

Thank you, @gwijthoff! This advice is much appreciated!

I will wait to hear your colleague Dennis's thoughts before preparing a note to add to the lesson.

[denten]

I agree with @gwijthoff. We should avoid duplicating installation instructions from Pandoc, as these will change and occasionally fail in unpredictable ways. I also suggest adding a note about installing Pandoc and flavor of Latex well before the workshop, due to size.

If you have good replication please also file a bug with Pandoc.

[charlottejmc]

I ran through the lesson today to see if I encountered the same errors as reported above.

Specs: MacOS Sonoma 14.1.1 pandoc 3.1.12 basictex (https://mirror.ctan.org/systems/mac/mactex/mactex-basictex-20230314.pkg)

I installed both using $ brew install [pandoc/basictex] as I have homebrew installed already.

I did indeed also encounter a problem when I entering the command:

$ pandoc main.md -o main.pdf`

The terminal returned:

pdflatex not found. Please select a different --pdf-engine or install pdflatex

I tried pointing pandoc to an engine with --pdf-engine=pdflatex and --pdf-engine=xelatex, but still no luck.

Finally, the solution I found online was to enter:

$ pandoc main.md --to=pdf -t latex -o main.pdf --pdf-engine=/Library/TeX/texbin/pdflatex

This worked perfectly.

It also works with the lesson's original syntax:

$ pandoc main.md -o main.pdf --pdf-engine=/Library/TeX/texbin/pdflatex

So it seems like pandoc just needs to know the path for the engine it's using! I imagine it would be the same for xelatex: add --pdf-engine=/Library/TeX/texbin/xelatex.

I think this could be easily solved by adding this bit of code to the lesson. Let me know what you think, and I'd happy to make that update.

Best,

Charlotte ✨

[spapastamkou]

thanks a lot for this, @charlottejmc!

[davvalent]

As stated here this solution will break for most of users. @denten @gwijthoff @anisa-hawes @charlottejmc, is it a solution to provide instructions to add /Library/TeX/texbin to PATH for users in that case? For example: if you use that distribution make sure /Library/TeX/texbin is on yout PATH by doing x.