search

programminghistorian / jekyll

Jekyll-based static site for The Programming Historian
http://programminghistorian.org
520 stars 229 forks source link

Sustainable Authorship Using Pandoc and Markdown - Pdf creation bug #2840

Closed arockenberger closed 7 months ago

arockenberger commented 1 year ago

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:

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 commented 1 year ago

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:

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 8 months ago

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 commented 8 months ago

thanks a lot for this, @charlottejmc!

davvalent commented 8 months ago

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.