Invalid link in ebook generating

[Bughouse1024]

Hi,

First, thanks a lot for sharing the linux knowledge in this book.

I'm reading through the README file and it looks like the link

linux-insides --Generating eBooks and PDFs - documentation

here is no longer valid.

[0xAX]

hello @Bughouse1024, thank you for the issue. I will take a look, but can't promise will fix it fast as gitbook seems does not provide ability, so I am planning to build script to export to ebook. Feel free to contribute if you want

[kyselejsyrecek]

Hello, I think I may have made some progress with that. The crucial part was running the Docker container present in the repository using:

make run

Well, among other Docker commands as the container is way too outdated now and so it requires a few tweaks before it is able to export a PDF or an e-book. Of course, you must have Docker installed on your host system first.

The Dockerfile I ended up with:

FROM lrx0014/gitbook:3.2.3
COPY ./ /srv/gitbook/
EXPOSE 4000

# Update sources.list for Debian Jessie.
RUN rm /etc/apt/sources.list
RUN echo "deb http://archive.debian.org/debian-security jessie/updates main" >> /etc/apt/sources.list.d/jessie.list
RUN echo "deb http://archive.debian.org/debian jessie main" >> /etc/apt/sources.list.d/jessie.list
RUN apt update
RUN apt install -y --force-yes calibre bzip2
RUN npm install svgexport@0.3.0 -g

# Examples:
#RUN gitbook pdf
#RUN gitbook epub

After running make run, you just want to connect to the Docker container and generate the output file with one of examples given above (or you can uncomment them) and copy the resulting file (e.g., book.pdf) to your host system with command:

docker cp linux-insides-book:/srv/gitbook/book.pdf .

which copies the file to the current working directory.

I have found some extra Make targets handy for that and for debugging or development of a proper book.json configuration (see kyselejsyrecek@8656e1a). Here is my Makefile:

### HELP

.PHONY: help
help: ## Print help
	@egrep "(^### |^\S+:.*##\s)" Makefile | sed 's/^###\s*//' | sed 's/^\(\S*\)\:.*##\s*\(.*\)/  \1 - \2/'

### DOCKER

.PHONY: run
run: image ## docker run ...
	(docker stop linux-insides-book 2>&1) > /dev/null || true
	docker run --detach -p 4000:4000 --name linux-insides-book --hostname linux-insides-book linux-insides-book 

.PHONY: start
start: ## start the docker container ...
	docker start linux-insides-book

.PHONY: image
image: ## docker image build ...
	docker image build --rm --squash --label linux-insides --tag linux-insides-book:latest -f Dockerfile . 2> /dev/null || \
	docker image build --rm --label linux-insides --tag linux-insides-book:latest -f Dockerfile . 

.PHONY: sh
sh: ## run interactive shell inside an already running docker container ...
	docker exec -it linux-insides-book sh

.PHONY: rm
rm: ## remove the docker container ...
	(docker stop linux-insides-book 2>&1) > /dev/null || true
	(docker rm linux-insides-book 2>&1) > /dev/null || true

.PHONY: logs
logs: ## gather logs from the docker container ...
	docker logs linux-insides-book

.PHONY: cp
cp: ## copy exported PDF book to current working directory ...
	docker cp linux-insides-book:/srv/gitbook/book.pdf .

### LAUNCH BROWSER

.PHONY: browse
browse: ## Launch broweser
	@timeout 60 sh -c 'until nc -z 127.0.0.1 4000; do sleep 1; done' || true
	@(uname | grep Darwin > /dev/null) && open http://127.0.0.1:4000 || true
	@(uname | grep Linux > /dev/null) && xdg-open http://127.0.0.1:4000 || true

Normally, I would execute these commands in one shell:

make run
make sh
gitbook pdf

and then, in a different shell:

make cp

Of course, if you wanted to have an .epub or .mobi file exported, you would have to update the cp Make target. But I found the EPUB format to be inappropriate for the book as it messes non-proportional font in code snippets and nothing is aligned as it should be as a result. The background was also invisible on my PocketBook. Of course, if you wanted to print the book out on A4 paper, you would have to alter the paperSize and possibly page margins within book.json.

@0xAX: Sadly, your last changes to the booting chapter, broke the export once again. gitbook now requires NPM package svgexport in order to export some new graphics, but this package is not installable under the outdated Node/NPM bundle available in the Docker container. I was able to at least export the PDF with svgexport 0.3.0 (see the contents of my Dockerfile at the beginning of this comment) but what I guess were the 2 new SVGs, turned out to be mostly black rectangles. The rest of the book is perfectly usable, though.

[0xAX]

Hello, I think I may have made some progress with that.

Great, many thanks for that!

Sadly, your last changes to the booting chapter, broke the export once again. gitbook now requires NPM package svgexport in order to export some new graphics, but this package is not installable under the outdated Node/NPM bundle available in the Docker container.

IIRC I have never used the existing docker image, so maybe have silly questions:

Did you try to update base image in order to get newer node/npm?

More rhetorical question - interesting is it something wrong with SVGs themselves or svgexport 🤔

I will try to look into that (many thanks again fir your help with the Docker image and makefile) but cant promise it will be fast because I need to adjust content to modern kernels and it is higher priority for me now.

[kyselejsyrecek]

IIRC I have never used the existing docker image, so maybe have silly questions:

Oh, really? I thought that was how you would normally be exporting the book. It is okay with me if none of it does get merged just yet. At least there is a step-by-step tutorial on exports now.

Did you try to update base image in order to get newer node/npm?

Frankly, I did not dig that deep. The very same version of gitbook (3.2.3) does not work at all on my Ubuntu 24.04.3 LTS with newer versions of Node.js and NPM. This is why I was surprised to see it working on the 10-years-old Debian Jessie out of the box and I just felt no urge to update any of those, other than the installation of svgexport yesterday when I found out that the content of the first chapter has changed considerably.

I just did some fiddling around with CommandBox (https://github.com/scottsteinbeck/commandbox-gitbook) as I really found the default A4 paper size somewhat broken/clumsy until I found this piece of documentation of the book.json file: https://gitbook-ng.github.io/config.html. Mr. Wood and his colleagues did some amazing job with an alternative gitbook-exporter: https://stackoverflow.com/a/57514917/3187261 But this one also did not work due to the missing JSON files. And that is a different story.

More rhetorical question - interesting is it something wrong with SVGs themselves or svgexport 🤔

I did not have any opinion on that at the time of writing my first comment. It could pretty much be that the svgexport package does not support all features of the SVG 1.1 standard in version 0.3.0. Afterall, all of these SVGs seem to be rendered correctly by the Firefox's engine, even if with some errors in the DevTools Console. But I was surprised to see some HTML code in the SVG source. That is not valid even according to the W3C validator.

I do not know much about the SVG 1.1 standard but it shall provide its own elements for text positioning and styling if you wrote these "by hand". I would normally just export such an image from a vector graphics application, Inkscape probably.

Many thanks for your incredible work!

[kyselejsyrecek]

If I recall correctly, the main issue I had with the A4 paper size (apart from it being too large for an e-book, although still suitable for printing) was that attached images were stretched across the whole width of a page. Unlike it is in the web version. So while the paper size made the book's content too tiny to read, the text in terminal screenshots was way too large, even blurred.

I guess it could be fixed with an additional set of CSS rules. Possibly a using special rule set together with the media print construct if put into the right file, at the right location in the repository. If, however, gitbook does honour these at all during export. I can imagine that something like this might do:

@media print {
    img {
        object-fit: scale-down;
    }
}

[0xAX]

But I was surprised to see some HTML code in the SVG source. That is not valid even according to the W3C validator.

I drew/exported them using draw.io, so yes, could be that they add something which is not conform to the standard. We can take a look can we clean-it up.

[0xAX]

Also maybe we can take something from #837

[kyselejsyrecek]

Also maybe we can take something from #837

Thank you for the link. I have integrated the original gitbook-based solution into a GitHub action inspired by the referenced pull request. Issues with SVGs remain, more so while you are adding new ones. The rest is working pretty fine. I am afraid that files created using draw.io are somewhat flawed and only web browsers and heavy-weight vector editors can work with them somewhat correctly. Integrating inkscape into the gitbook process, however, would require creating own gitbook plugin or even altering gitbook. I am not planning to try that, sorry. What I did try was to pre-process these SVGs with Inkscape (even using CLI) and ImageMagick or rsvg-convert. None of these were able to fix resulting images in e-books completely.

I have created a pull request to your original repository anyway as I find these actions quite helpful. Even more so if the input SVGs are fixed. See #874.

Oh and thank you for your acknowledgement in the list of contributors. Hopefully it was not too early to make such a statement.

Best regards.