Bug 14357

Summary: No PDF and EPUB versions of the manuals available on the website
Product: [Documentation] Mega Manual Reporter: Michael Opdenacker <michael.opdenacker>
Component: mega-manualAssignee: Antonin Godard <antonin.godard>
Status: RESOLVED FIXED QA Contact:
Severity: enhancement    
Priority: Medium+ CC: mhalstead, randy.macleod, richard.purdie
Version: 3.3   
Target Milestone: 5.2 M4   
Hardware: x86   
OS: Multiple   
Whiteboard:
OS type for building Yocto: --- Type of Regression: ---
Verified: Documentation change: Don't know

Description Michael Opdenacker 2021-04-22 14:09:38 UTC
There should be PDF and EPUB versions of the mega manual available for direct download on the https://docs.yoctoproject.com/, for off-line viewing on computers, and e-book readers.

Such versions are easy to build:
make latexpdf
make epub

Could the autobuilder take care of this?
Comment 1 Randy MacLeod 2021-04-22 14:50:53 UTC
We're concerned about having to add many dependencies on each autobuilder, please work this out with Michael Halstead and RP.
Comment 2 Randy MacLeod 2021-04-22 14:51:44 UTC
We're concerned about having to add many dependencies on each autobuilder, please work this out with Michael Halstead and RP. There was a similar problem with mingw...
Comment 3 Michael Opdenacker 2021-10-21 08:25:43 UTC
I cannot really fix this by myself.
It would be very useful to propose our manuals in PDF and EPUB formats too.

Setting back this bug to "Unassigned".
When such formats are generated and available on the website, you could assign it to me again, so that I update the pages to link to the PDF and EPUB downloads.

Thanks in advance
Michael.
Comment 4 Michael Opdenacker 2021-10-21 08:49:49 UTC
Didn't manage to unassign this bug.
Instead, assigned it to "Michael Halstead", but feel free to assign it to someone else.

An update by the way... To generate HTML, EPUB and PDF outputs at the same time, you just need to run "make all".

Thanks in advance
Comment 5 Michael Opdenacker 2022-04-28 15:27:43 UTC
I'll need to propose a patch against run-docs-build to achieve this.
Comment 6 Michael Opdenacker 2022-06-15 09:15:57 UTC
Actually, a change to "make publish" in yocto-docs's Makefile should be sufficient.

Such a patch has been submitted:
https://lists.yoctoproject.org/g/docs/message/3001
Comment 7 Michael Halstead 2022-09-30 17:17:17 UTC
The patch looks good. Should we pull it into the repo? Otherwise we could close this with a comments explaining why we aren't publishing epub and pdf.
Comment 8 Antonin Godard 2024-10-09 12:49:31 UTC
I have tried compiling the pdf with pdflatex but I am getting the following message:

  ! LaTeX Error: Unicode character 张 (U+5F20)
                 not set up for use with LaTeX.

The release notes contain these characters from the contributor list. An example of such character would be: https://git.yoctoproject.org/yocto-docs/tree/documentation/migration-guides/release-notes-4.2.rst#n924.

A solution would be to use XeLaTeX, as documented here:
https://docs.readthedocs.io/en/stable/guides/pdf-non-ascii-languages.html

I've tried that but leads to a lot of additional errors, which require new packages to be installed on the host. We might not want to go down the obscure LaTeX errors rabbit hole…

I've had no issue compiling the epub from the documentation, though, so we could at least add that?

Another question I have: `run-docs-build` just copies the epub file into the final directory. While this will offer the html version by default for the user, the epub file remains "hidden", so maybe we should link the file in the documentation somewhere?

Example of a final build:

_build/final
├── bitbake.html
├── brief-yoctoprojectqs
├── bsp-guide
├── contributor-guide
├── dev-manual
├── genindex.html
├── _images
├── index.html
├── kernel-dev
├── migration-guides
├── objects.inv
├── overview-manual
├── profile-manual
├── ref-manual
├── releases.html
├── sdk-manual
├── search.html
├── searchindex.js
├── singleindex.html
├── _sources
├── _static
├── test-manual
├── TheYoctoProject.epub  <- copied epub file
├── toaster-manual
├── transitioning-to-a-custom-environment.html
└── what-i-wish-id-known.html
Comment 9 Michael Opdenacker 2024-10-09 14:02:04 UTC
I can reproduce the Unicode problem :/

As LaTeX is old, it sounds like a good thing to upgrade to XeLaTeX to avoid such problems in the future. Even if it takes extra work. 

If the EPUB and PDF files are now accessible somewhere on the https server (if I understood correctly), it would be good to link to them from a visible place in the HTML docs. This was the main idea of creating this bug.

I found it convenient to read the EPUB version on my e-ink reader.
Comment 10 Randy MacLeod 2024-10-24 15:04:02 UTC
Bulk move of 5.1 M4 to 5.2 M2 as approved by AlexB.
Comment 11 Antonin Godard 2024-11-12 12:38:23 UTC
We now have a "Documentation Downloads" page on the website: https://docs.yoctoproject.org/dev/downloads.html.

With PDF/Epub download links. Final support was added with patch series: https://lists.yoctoproject.org/g/docs/topic/patch_0_5_add_support_for/109421240

The PDFs are generated with XeLaTeX, to solve the issues described in this thread.

Closing this bug. :)
Comment 12 Michael Opdenacker 2024-11-12 13:41:47 UTC
Great, many thanks!
Michael