Can we get a book version of the docs as epub and pdf please ? about checkmk-docs HOT 3 CLOSED

Hello, @godspeed-you I do not need "xref links to references for pages in the same document".
I would like to read the whole documentation in a sequence without jumping around.

Just page for page like a "real" book.
I am totally fine to go without any links at all.

@bili123 thank you for your suggested procedure. I am already getting nice results which are sufficient for me. As soon I implemented a good procedure how to generate a epub I'll post it here.

So far I did:

• Read https://github.com/asciidoctor/docker-asciidoctor/blob/main/README.adoc
• get the asciidoctor docker image

docker pull asciidoctor/docker-asciidoctor

• create an alias called ad
• the \ before $PWD is important here

alias ad="docker run -it -v \$PWD:/documents/ asciidoctor/docker-asciidoctor"

• I am using the git directory checkmk-docs as the base directory for all operations

git clone ....
cd checkmk-docs

• fix the file extensions as suggested by @bili123

sed 's/- link/include:/ ; s/\.html/\.asciidoc/' < de/menu.asciidoc  > de/das-checkmk-handbuch.asciidoc

• make the images available
• i tried many combinations of -a base=. .. ./de ../de etc .. and -a imagesdir=./images ../images etc
• finally i gave up and created a symlink like this

cd de
ln -s ../images .

• run asciidoctor-epub3 with the ad alias.

ad asciidoctor-epub3 -a imagesdir=images de/das-checkmk-handbuch.asciidoc

• now I am getting this error

asciidoctor: FAILED: /documents/de/das-checkmk-handbuch.asciidoc: Failed to load AsciiDoc document - undefined method `[]' for nil:NilClass

• I fixed this by commenting out the lines containing pass:q,m in attributes/global_attr.adoc

$ git diff
diff --git a/attributes/global_attr.adoc b/attributes/global_attr.adoc
index 7a2dad34..82fcb2c4 100644
--- a/attributes/global_attr.adoc
+++ b/attributes/global_attr.adoc
@@ -20,11 +20,11 @@
:CMKTITLEDE: Das offizielle {CMK} Benutzerhandbuch
:CMKTITLEEN: The official {CMK} user guide

-:CRE: pass:q,m[image:CRE.svg[CRE,title=Checkmk Raw Edition,width=20] Checkmk Raw Edition]
-:CFE: pass:q,m[image:CFE.svg[CFE,title=Checkmk Enterprise Free Edition,width=20] Checkmk Enterprise Free Edition]
-:CSE: pass:q,m[image:CSE.svg[CSE,title=Checkmk Enterprise Standard Edition,width=20] Checkmk Enterprise Standard Edition]
-:CME: pass:q,m[image:CME.svg[CME,title=Checkmk Enterprise Managed Services Edition,width=20] Checkmk Enterprise Managed Services Edition]
-:CEE: pass:q,m[image:CEE.svg[CEE,title=Checkmk Enterprise Editions,width=20] Checkmk Enterprise Editions]
+//:CRE: pass:q,m[image:CRE.svg[CRE,title=Checkmk Raw Edition,width=20] Checkmk Raw Edition]
+//:CFE: pass:q,m[image:CFE.svg[CFE,title=Checkmk Enterprise Free Edition,width=20] Checkmk Enterprise Free Edition]
+//:CSE: pass:q,m[image:CSE.svg[CSE,title=Checkmk Enterprise Standard Edition,width=20] Checkmk Enterprise Standard Edition]
+//:CME: pass:q,m[image:CME.svg[CME,title=Checkmk Enterprise Managed Services Edition,width=20] Checkmk Enterprise Managed Services Edition]
+//:CEE: pass:q,m[image:CEE.svg[CEE,title=Checkmk Enterprise Editions,width=20] Checkmk Enterprise Editions]

:RE: Raw Edition
:FE: Free Edition
@@ -32,8 +32,8 @@
:ME: Managed Services Edition
:EE: Enterprise Editions

-:cee-only: pass:q,m[image:CEE.svg[class=icon-left]]
-:cre-only: pass:q,m[image:CRE.svg[class=icon-left]]
+//:cee-only: pass:q,m[image:CEE.svg[class=icon-left]]
+//:cre-only: pass:q,m[image:CRE.svg[class=icon-left]]

• and again

ad asciidoctor-epub3 -a imagesdir=images de/das-checkmk-handbuch.asciidoc

• And voila, a file de/das-checkmk-handbuch.epub is created.
• fbreader and ebook-viewer can open the file and also show images.
• my tolino epos ebook reader crashed while loading the generated epub
• Therefore I opened the epub in calibre and did some "repair" and auto fixing and stuff like that, the final result is now working with my ebook reader. I can't explain what exactly calibre did. Perhaps I will find out later.

But I am happy now, I have a ~ 1800 pages checkmk ebook which I can now read at the beach.

from checkmk-docs.

As asciidoctor is not able to convert xref links to references for pages in the same document, it is not that easy to implement. Basically, we would need to implement this feature on our own. The same goes for the section of related articles.

from checkmk-docs.

This is definitly not an official recommendation but maybe quick and dirty is better than nothing ;)

You can build at least a PDF version pretty easily - if you can live without inline images (icons), some Checkmk specific formatting and internal links and with some not well formatted tables. But all in all it looks pretty good, images, TOC, terminal sessions, and so on work.

So, this is a quick & dirty solution I used with Bash on Windows: You need to install asciidoctor and asciidoctor-pdf (gem install ...), clone the Checkmk Docs repo and then for some reason asciidoctor-pdf wants images and asciidoc files in the same directory. You could just copy the contents of the "de" directory to the "images" directory if you don't plan to work on the repo. I copied everything to a separate "testingcmkpdf".

Then you can use the file "menu.asciidoc" to render the whole handbook in the original order. With a little but ... Instead of a list of HTML links ("- link:foobar.html[this is foo]") you need includes like "include::foobar.asciidoc[this is foo]" - which is done quickly with sed:

sed -i 's/- link/include:/ ; s/\.html/\.asciidoc/' testingcmkpdf/menu.asciidoc

And then you can build the PDF:

asciidoctor-pdf testingcmkpdf/menu.asciidoc

You'll geht a whole bunch of warnings about already used IDs, problems with some formatted texts and much more - and a 122 megabyte PDF with over 1.400 pages.

Again, just a quick and dirty way producing something non-official. Probably more useful to just convert single files or a small subset. Maybe there's a better way, but this worked for me first try, so I didn't try further.

I've never tried to do something like this with epub - it seems possible, with some effort, according to Asciidoctor: https://asciidoctor.cn/docs/convert-asciidoc-to-epub/
But have in mind, as @godspeed-you mentioned, not everything is implemented.

Here's a preview image:

from checkmk-docs.