doc: Move Asciidoctor HTML and PDF builds to a script

[dbaio]

Summary

The idea is always to treat our documentation from Hugo's perspective.
The 'includes' and other changes for HTML/PDF builds, be handled in the
script that will copy each document source to a temporary directory
before the build.

This change is the prerequisite to remove all include if blocks and add
"Hugo's lang shortcode"/"Asciidoctor lang" support in the build process.
It also makes future changes easier (Makefile vs shell script) and
simplifies all includes in code.

Test Plan

$ cd documentation
$ make DOC_LANG="en" pdf
./tools/asciidoctor.sh articles en pdf
asciidoctor build_pdf: articles en bsdl-gpl pdf
asciidoctor build_pdf: articles en building-products pdf
asciidoctor build_pdf: articles en committers-guide pdf
asciidoctor build_pdf: articles en contributing pdf
asciidoctor build_pdf: articles en contributors pdf
asciidoctor build_pdf: articles en cups pdf
asciidoctor build_pdf: articles en explaining-bsd pdf
asciidoctor build_pdf: articles en filtering-bridges pdf
asciidoctor build_pdf: articles en fonts pdf
asciidoctor build_pdf: articles en freebsd-questions pdf
asciidoctor build_pdf: articles en freebsd-releng pdf
asciidoctor build_pdf: articles en freebsd-src-lsp pdf
asciidoctor build_pdf: articles en freebsd-update-server pdf
asciidoctor build_pdf: articles en geom-class pdf
asciidoctor build_pdf: articles en gjournal-desktop pdf
asciidoctor build_pdf: articles en hubs pdf
asciidoctor build_pdf: articles en ipsec-must pdf
asciidoctor build_pdf: articles en ldap-auth pdf
asciidoctor build_pdf: articles en leap-seconds pdf
asciidoctor build_pdf: articles en linux-emulation pdf
asciidoctor build_pdf: articles en linux-users pdf
asciidoctor build_pdf: articles en mailing-list-faq pdf
asciidoctor build_pdf: articles en nanobsd pdf
asciidoctor build_pdf: articles en new-users pdf
asciidoctor build_pdf: articles en pam pdf
asciidoctor build_pdf: articles en port-mentor-guidelines pdf
asciidoctor build_pdf: articles en pr-guidelines pdf
asciidoctor build_pdf: articles en problem-reports pdf
asciidoctor build_pdf: articles en rc-scripting pdf
asciidoctor build_pdf: articles en releng pdf
asciidoctor build_pdf: articles en remote-install pdf
asciidoctor build_pdf: articles en serial-uart pdf
asciidoctor build_pdf: articles en solid-state pdf
asciidoctor build_pdf: articles en vinum pdf
asciidoctor build_pdf: articles en vm-design pdf
/usr/local/bin/python3 ./tools/books-toc-parts-creator.py -l    en
/usr/local/bin/python3 ./tools/books-toc-creator.py -l          en
/usr/local/bin/python3 ./tools/books-toc-figures-creator.py -l  en
/usr/local/bin/python3 ./tools/books-toc-tables-creator.py -l   en
/usr/local/bin/python3 ./tools/books-toc-examples-creator.py -l en
./tools/asciidoctor.sh books en pdf
asciidoctor build_pdf: books en arch-handbook pdf
asciidoctor build_pdf: books en design-44bsd pdf
asciidoctor build_pdf: books en dev-model pdf
asciidoctor build_pdf: books en developers-handbook pdf
asciidoctor build_pdf: books en faq pdf
asciidoctor build_pdf: books en fdp-primer pdf
asciidoctor build_pdf: books en handbook pdf
asciidoctor build_pdf: books en porters-handbook pdf

$ find public/
public
public/en
public/en/articles
public/en/articles/solid-state
public/en/articles/solid-state/solid-state_en.pdf
public/en/articles/freebsd-questions
public/en/articles/freebsd-questions/freebsd-questions_en.pdf
public/en/articles/contributors
public/en/articles/contributors/contributors_en.pdf
public/en/articles/freebsd-update-server
public/en/articles/freebsd-update-server/freebsd-update-server_en.pdf
public/en/articles/filtering-bridges
public/en/articles/filtering-bridges/filtering-bridges_en.pdf
[...]

$ make DOC_LANG="en" html
./tools/asciidoctor.sh articles en html
asciidoctor build_html: articles en bsdl-gpl html
asciidoctor build_html: articles en building-products html
asciidoctor build_html: articles en committers-guide html
asciidoctor build_html: articles en contributing html
[...]
/usr/local/bin/python3 ./tools/books-toc-parts-creator.py -l    en
/usr/local/bin/python3 ./tools/books-toc-creator.py -l          en
/usr/local/bin/python3 ./tools/books-toc-figures-creator.py -l  en
/usr/local/bin/python3 ./tools/books-toc-tables-creator.py -l   en
/usr/local/bin/python3 ./tools/books-toc-examples-creator.py -l en
./tools/asciidoctor.sh books en html
asciidoctor build_html: books en arch-handbook html
asciidoctor build_html: books en design-44bsd html
asciidoctor build_html: books en dev-model html
asciidoctor build_html: books en developers-handbook html
asciidoctor build_html: books en faq html
asciidoctor build_html: books en fdp-primer html
asciidoctor build_html: books en handbook html
asciidoctor build_html: books en porters-handbook html

$ find public/
[...]
public/en/books/dev-model
public/en/books/dev-model/docbook.css
public/en/books/dev-model/dev-model_en.tar.gz   <-- archive
public/en/books/dev-model/font-awesome-min.css
public/en/books/dev-model/index.html            <-- index
public/en/books/dev-model/dev-model_en.pdf      <-- Here because public/ wasn't cleaned
[...]

[carlavilla]

Works for me :)

Let others say their opinion

[hrs]

Replacements by sed can break literal "include" in the adoc source files. Is it always safe?

And another question: is there any reason why not to use OBJDIR for the temporary build directory? I personally believe the complexity of the current Makefile comes from the fact that it is trying to handle multiple directories in the single Makefile without proper OBJDIR support. I can understarnd your motivation, but using it is a way to solve similar issues in the src (and ports) tree. Mixing Makefile and shell scripts usually makes things complicated.

[dbaio]

• Improve sed's regex in pdf build

[carlavilla]

Please, don’t commit this, we have a way to do that using only Hugo and AsciiDoctor, we don’t need any script.

Let me handle this please