fix(whitepaper): build fails on Ubuntu 18 due to glibc 2.29 #703

[petermetz]

Refactored the whitepaper build toolchain to be based on
entirely just containers so that it is easier to set up the build
which now only requires a working docker installation and
make (for the Makefile).

Also refactored the generated files to be placed under the
./whitepaper/build/ directory instead of being dumped
straight into the ./whitepaper/ directory so that it is
easier to differentiate between what are build files and
what are not.

There are 3 different pdf generation tasks in order to provide
contributors with a way of comparing the differnet pdfs rendring
issues (since we have a few bugs active in that sense still).
The supposedly "best" pdf render is produced by the make
target called "pdf-wk-with-flags" which is exported to the
build directory with a similar suffix in the filename as well.

The new way to do a full build is by issuing the make command
from the ./whitepaper/ directory of the project.

A Dockerfile was added accordingly and is tagged for the current
revision on DockerHub as:
petermetz/cactus-whitepaper-builder:2021-03-22-fix-703

Fixes #703

Signed-off-by: Peter Somogyvari peter.somogyvari@accenture.com

[petermetz]

cc: @AzaharaC

[AzaharaC]

I have been testing this change but not working for me. I have the following error because I don't have access to the docker image:

Unable to find image 'petermetz/cactus-whitepaper-builder:2021-03-22-fix-703' locally
docker: Error response from daemon: pull access denied for petermetz/cactus-whitepaper-builder, repository does not exist or may require 'docker login': denied: requested access to the resource is denied.
See 'docker run --help'.
Makefile:34: recipe for target 'html' failed
make: *** [html] Error 125

[takeutak]

Why do you use Docker in the whitepaper? It seems that latex container is not needed because whitepaper is markdown style.
In the first place, whitepaper is a markdown document, so it is meaningless to prepare a Docker container.

[petermetz]

@takeutak It's incidental: I need pandoc (docker container) for the Markdown => HTML conversion. I picked their latex image instead of the one they called 'core' because according to their docs the 'core' is lacking most features (some may not be related to latex) compared to the image called 'latex'.

[takeutak]

@petermetz Thanks for your replying. I understand that you need pandoc.
However, this is just a document, so I think it is enough for users to install pandoc by themselves. I don't know why you want to offer it as a Docker container, but could you tell me why you need it?

[petermetz]

so I think it is enough for users to install pandoc by themselves.

It's for the convenience of the users/contributors. My guiding principle here is that anything that takes more than 3 clicks to achieve is something I want to make simpler to reduce cognitive overhead especially for newcomers.

I don't know why you want to offer it as a Docker container

I don't mean to use the docker container as a way of distributing the document itself.
This container is for the tool-chain used to build/compile different formats of the document such as HTML and PDF.
There are other issues open with tasks to have automated publishing of the most up to date version of the whitepaper in PDF format as well and having a container will play nicely into that.

@takeutak

[petermetz]

@takeutak Kindly requesting that you review or follow-up on the review discussion within this pull request (whichever is applicable). Thank you very much in advance.

[jonathan-m-hamilton]

LGTM