Build docs with latest pandoc version

[mikewallace1979]

Currently we need to use pandoc version 2.2.1 in order to keep the formatting the same when we build the docs.

Newer versions of pandoc make different formatting choices which we don't necessarily want.

We need to determine how to invoke the current pandoc to reduce the formatting changes to only those that are acceptable to us.

[didiermichel]

Here is an example of changes from barman-wal-archive.1 (L 20 -> 23) cmd: pandoc -s -f markdown-smart -t man -o barman-wal-archive.1 barman-wal-archive.1.md

pandoc 2.2.1:

python 3 then avoid the compression options \f[C]\-\-gzip\f[] or
\f[C]\-\-bzip2\f[] as barman\-cloud\-wal\-restore is unable to restore
gzip\-compressed WALs on python < 3.2 or bzip2\-compressed WALs on
python < 3.3.

pandoc 2.14.2:

python 3 then avoid the compression options \f[C]--gzip\f[R] or
\f[C]--bzip2\f[R] as barman-cloud-wal-restore is unable to restore
gzip-compressed WALs on python < 3.2 or bzip2-compressed WALs on python
< 3.3.

[didiermichel]

If the issue is in html transformation, then it will probably be useful to use a css style sheet and pass it as argument

[didiermichel]

CSS can be added with --css=file.css when rendering html

[didiermichel]

Adding some information to run pandoc 2.2.1 This will mitigate the issue until we take action to use a newer pandoc version.

Docker file

FROM debian:buster

RUN apt-get update && apt-get install -y make pandoc texlive-latex-base texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra

WORKDIR /data

Create Image debian/buster/pandoc:latest

Execute from barman/doc:

docker run --rm --volume "`pwd`:/data" -w="/data" --user `id -u`:`id -g` debian/buster/pandoc:latest make clean all