DOC: pdflatex build failed on RTD

[pllim]

https://readthedocs.org/projects/ginga/builds/7126415/

My LaTeX-fu is not strong enough to know why it is failing at a glance. Did #647 break it somehow?

HTML build is fine and seems to have been updated properly online. FYI.

[ejeschke]

Looks like it is choking on the Japanese Kanji I have in there. But I'm not sure why it should start doing that all of a sudden.

Chapter 5.

! Package inputenc Error: Unicode char 銀 (U+9280)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.2589 銀
          河

! Package inputenc Error: Unicode char 河 (U+6CB3)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.2589 銀河

[ejeschke]

Then there is this one:

Document Substyle `EXPDLIST'. Released 22.09.1999 (V 2.4)
English Documentation  22.09.99
)

! LaTeX Error: Environment notice undefined.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.93 \renewenvironment{notice}
                              [2]{
Writing index file ginga.idx

[pllim]

I don't understand why builds only fail sometimes, not all the time, if it is indeed something wrong with the content: https://readthedocs.org/projects/ginga/builds/

Before we jump down the rabbit hole (:rabbit: :hole: )... Do we really need the PDF and EPUB builds? Who uses them? Can we simply disable those formats and use HTML exclusively?

[ejeschke]

I think that only some errors are fatal to the PDF build. I know I had one error that was related to moving the IRAF plugin to experimental-- that was fixed. The unicode error seems to be non-fatal. I read some threads (see here, here, and here) that seem to indicate that the unicode problem may soon be solvable on the readthedocs side.

[ejeschke]

I think those builds are relatively unimportant compared to the HTML build, but I think it would be better to have those other builds succeed. I suspect that it is related to the "\renewenvironment{notice}" error.

[pllim]

OK, I opened an issue at readthedocs/readthedocs.org#4098 . Let's wait and see. 🤞

[ejeschke]

@pllim, cautiously optimistic that I fixed the PDF build with the solution outlined here. At least, it looks like the current build succeeded. 😀

[ejeschke]

Looks like the RTD builds are succeeding again without errors.

[pllim]

Wow, great find! f579597 looks like some magical incantations. 👏

However, while it got rid of the error, it is not rendering Japanese characters properly in PDF:

Not sure how much this is an issue for you. AFAIK, not many download the PDF doc, which also has other rendering issues besides those characters (e.g., unnecessary empty pages). So, just FYI.

[ejeschke]

Yes, I know that it makes problems for the PDF. But at least there is a PDF--and the characters aren't that significant for the bulk of the manual. Hopefully RTD will get this problem sorted out with better unicode support and then we can easily revert it. Thankfully the change only involves adding some lines to the conf file, so the HTML still retains the characters and looks good online!