search

deoren / notes

Various notes for topics I'm learning
2 stars 0 forks source link

Icinga2 - Build PDF from Markdown files #3

Open deoren opened 6 years ago

deoren commented 6 years ago

Found this on the Icinga mailing list:

git clone http://git.icinga.org/icinga2.git icinga2
cd icinga2/doc
pandoc --toc --latex-engine=xelatex -o Manual.pdf 1-about.md \
2-getting-started.md 3-monitoring-basics.md 4-configuring-icinga-2.md \
5-advanced-topics.md 6-object-types.md 7-icinga-template-library.md \
8-cli-commands.md 9-icinga2-api.md 10-monitoring-remote-systems.md \
11-icinga2-client.md 12-agent-based-checks.md 13-distributed-monitoring-ha.md \
14-addons-plugins.md 15-features.md 16-troubleshooting.md \
17-upgrading-icinga-2.md 18-language-reference.md 19-library-reference.md \
20-script-debugger.md 21-development.md 22-migrating-from-icinga-1x.md \
23-appendix.md

with this remark:

supposing latex2pdf and pandoc are installed and properly set up.

After some trial/error, this appears to provide a usable build environment for the Icinga documentation on an Ubuntu 16.04 x64 VM:

sudo apt-get update
sudo apt-get install -y pandoc git texlive-latex-recommended texlive-xetex
git clone https://github.com/Icinga/icinga2
cd icinga2/doc
pandoc --toc --latex-engine=xelatex -o Manual.pdf $(ls *.md)

I've not tested further to see if some packages can be excluded.

deoren commented 6 years ago

https://pandoc.org/epub.html

Based on the example there it appears that the only thing I had to change to produce an epub file was to change the extension; both of the following commands produced (seemingly) equivalent results:

deoren commented 6 years ago

Looks like the epub files are failing http://validator.idpf.org checks and Google Play Books as well, so evidently there is more work yet to be done for epub conversion.

deoren commented 6 years ago

This also seems to work fine (at least with Bash as my shell):

pandoc --toc -o Manual.epub *.md

If the files need to be processed in a specific order then specifying them one-by-one is probably a better approach.

deoren commented 6 years ago

Note: The epubs generated this way should probably be touched up with Calibre to add missing metadata (and a cover) so that Google Play Books and other epub readers can better sort or display them.

deoren commented 5 years ago

Note: The epubs generated this way should probably be touched up with Calibre to add missing metadata (and a cover) so that Google Play Books and other epub readers can better sort or display them.

Built today using an Ubuntu 18.04 LXD image and the build steps from https://github.com/deoren/notes/issues/3#issue-354769962 and https://github.com/deoren/notes/issues/3#issuecomment-433538200.

I then ran the epub through Calibre 3.40.1 (Windows x64) and uploaded to Google Play Books. No obvious issues with it thus far.

EDIT: The "original" epub (without Calibre conversion) failed to process properly when uploading to Google Play Books. Calibre (once again) proves itself invaluable for touch-up work.