Addition of PDF targets allowing to build PDF version of docs with selection of the language.
For example:
make DOC_LANG="en,fr" pdf-books
or
make DOC_LANG="it" pdf-books pdf-articles
Details
Details
Diff Detail
Diff Detail
- Repository
- R9 FreeBSD doc repository
- Lint
Lint Skipped - Unit
Tests Skipped
Event Timeline
Comment Actions
Other generic nit is that this places its outputs into the content directories, whereas I think they should go into public/ somewhere. Not really clear what the correct structure would be, or if we can rely on public/ existing.
I'm also seeing a difference in how includes work in the fdp-primer when using the "make pdf-books" vs "make run", which might be me but I will dig into tomorrow.
| documentation/Makefile | ||
|---|---|---|
| 23 | Mental note to add rubygem-asciidoctor-pdf to textproc/docproj | |
| 24 | I think this behaves more sensibly as '&&' - failing that we should add a test to do nothing if DOC_LANG is empty to the other targets | |
| 135 | s/buil/build/ | |
Comment Actions
- Switch to other theme to allow CJK and other fonts to be embedded. Our default theme is less good than the one provided by asciidoctor-pdf.
- Updates with Ceri's comments. I still have to save the pdf to a better suited directory.
| documentation/Makefile | ||
|---|---|---|
| 23 | I added ${LOCALBASE}/bin/asciidoctor-pdf as RUN_DEPENDS. But textproc/docproj still has to be updated. | |
Comment Actions
Hi.
Testing here and I've seen this detail on articles/contributors.
$ cd documentation $ make DOC_LANG="en" pdf-books pdf-articles ... asciidoctor: ERROR: _index.adoc: line 117: include file not found: /usr/home/dbaio/FreeBSD/git/doc/documentation/content/en/articles/contributors/content/en/articles/contributors/contrib-committers.adoc asciidoctor: ERROR: _index.adoc: line 127: include file not found: /usr/home/dbaio/FreeBSD/git/doc/documentation/content/en/articles/contributors/content/en/articles/contributors/contrib-corealumni.adoc asciidoctor: ERROR: _index.adoc: line 137: include file not found: /usr/home/dbaio/FreeBSD/git/doc/documentation/content/en/articles/contributors/content/en/articles/contributors/contrib-develalumni.adoc asciidoctor: ERROR: _index.adoc: line 147: include file not found: /usr/home/dbaio/FreeBSD/git/doc/documentation/content/en/articles/contributors/content/en/articles/contributors/contrib-portmgralumni.adoc asciidoctor: ERROR: _index.adoc: line 157: include file not found: /usr/home/dbaio/FreeBSD/git/doc/documentation/content/en/articles/contributors/content/en/articles/contributors/contrib-develinmemoriam.adoc asciidoctor: ERROR: _index.adoc: line 172: include file not found: /usr/home/dbaio/FreeBSD/git/doc/documentation/content/en/articles/contributors/content/en/articles/contributors/contrib-additional.adoc ...
| documentation/Makefile | ||
|---|---|---|
| 23 | It's already there, but it's not enabled by default. I'll enable it. | |
Comment Actions
Built docs are now saved in matching public/lang/articles|books/ directory. Clean targets updated as well.
Comment Actions
One other note: the pgpkeys article takes about two hours to build on my (admittedly single-CPU 2GB RAM) machine - is that common and do we need to work around that somehow?
| documentation/Makefile | ||
|---|---|---|
| 53 | Can we add? pdf: pdf-articles pdf-books | |
| 95 | This needs a test for if there is no articles directory, for example: /usr/local/bin/asciidoctor-pdf -r ./shared/lib/man-macro.rb -r ./shared/lib/man-macro.rb -r ./shared/lib/git-macro.rb -r ./shared/lib/packages-macro.rb -r ./shared/lib/inter-document-references-macro.rb -r ./shared/lib/sectnumoffset-treeprocessor.rb --doctype=article -a skip-front-matter -a pdf-theme=default-with-fallback-font -o /usr/home/ceri/git/f/freebsd-doc/documentation/public/mn/articles/*/article.pdf /usr/home/ceri/git/f/freebsd-doc/documentation/content/mn/articles/*/_index.adoc
Stop. | |
Comment Actions
Same here now since we do it right with includes. I just launched a build on my machine (10 years old quad-core) 12 minutes ago and it's still running...
Indeed, we need a solution/workaround.
Comment Actions
- Add installation of static/articles/* files in articles target
- Put tests of doc existence in pdf-*-targets
Comment Actions
I've ruled out an include storm by pushing everything into a single file and it still takes over 90 minutes, so will rework the Makefile if I can to avoid as many .PHONY targets as there currently are. No need to hold up this review for it, I think.
Comment Actions
I cannot accept this review, due to some permission problem. Consider this comment as 'accepted'.
Comment Actions
I think for now is better skip pdf for articles/pgpkeys, it seems the issue is not the includes but its content.
See here:
https://github.com/asciidoctor/asciidoctor-pdf/issues/941
$ wc -l documentation/static/pgpkeys/*.key [...] 66 documentation/static/pgpkeys/zi.key 43 documentation/static/pgpkeys/zml.key 100 documentation/static/pgpkeys/zont.key 94964 total
Without articles/pgpkeys:
$ cd documentation $ time make DOC_LANG="en" pdf ... make DOC_LANG="en" pdf 218.75s user 3.15s system 99% cpu 3:41.94 total
Just articles/pgpkeys:
$ time /usr/local/bin/ruby27 \ /usr/local/bin/asciidoctor-pdf \ -r ./shared/lib/man-macro.rb \ -r ./shared/lib/man-macro.rb \ -r ./shared/lib/git-macro.rb \ -r ./shared/lib/packages-macro.rb \ -r ./shared/lib/inter-document-references-macro.rb \ -r ./shared/lib/sectnumoffset-treeprocessor.rb \ --doctype=article -a skip-front-matter \ -a pdf-theme=default-with-fallback-font \ -o /usr/home/dbaio/FreeBSD/git/doc/documentation/public/en/articles/pgpkeys/article.pdf \ /usr/home/dbaio/FreeBSD/git/doc/documentation/content/en/articles/pgpkeys/_index.adoc /usr/local/bin/ruby27 /usr/local/bin/asciidoctor-pdf -r -r -r -r -r -r 3575.63s user 3.02s system 99% cpu 59:39.77 total
Comment Actions
I've updated docs tree and applied this patch and I'm getting this error when not setting a language:
$ cd documentation $ time make pdf ... asciidoctor: ERROR: _index.adoc: line 50: include file not found: /usr/home/dbaio/FreeBSD/git/doc/documentation/shared/jp/mailing-lists.adoc asciidoctor: ERROR: _index.adoc: line 51: include file not found: /usr/home/dbaio/FreeBSD/git/doc/documentation/shared/jp/teams.adoc asciidoctor: ERROR: _index.adoc: line 52: include file not found: /usr/home/dbaio/FreeBSD/git/doc/documentation/shared/jp/urls.adoc asciidoctor: ERROR: _index.adoc: line 72: include file not found: /usr/home/dbaio/FreeBSD/git/doc/documentation/content/ja/books/design-44bsd/{chapters-path}toc-figures.adoc asciidoctor: ERROR: _index.adoc: line 74: include file not found: /usr/home/dbaio/FreeBSD/git/doc/documentation/content/ja/books/design-44bsd/{chapters-path}toc-tables.adoc asciidoctor: WARNING: image to embed not found or not readable: /usr/home/dbaio/FreeBSD/git/doc/documentation/content/ja/books/design-44bsd/fig1.png asciidoctor: WARNING: image to embed not found or not readable: /usr/home/dbaio/FreeBSD/git/doc/documentation/content/ja/books/design-44bsd/fig2.png ... /usr/local/bin/asciidoctor-pdf -r ./shared/lib/man-macro.rb -r ./shared/lib/man-macro.rb -r ./shared/lib/git-macro.rb -r ./shared/lib/packages-macro.rb -r ./shared/lib/inter-document-references-macro.rb -r ./shared/lib/sectnumoffset-treeprocessor.rb --doctype=book -a skip-front-matter -a pdf-theme=default-with-fallback-font -o /usr/home/dbaio/FreeBSD/git/doc/documentation/public/zh-tw/books/porters-handbook/book.pdf /usr/home/dbaio/FreeBSD/git/doc/documentation/content/zh-tw/books/porters-handbook/_index.adoc asciidoctor: ERROR: failed to parse formatted text: It will have <code>MASTER_SITES</code> set to “<a href="https://gitlab.example.com”" class="bare">https://gitlab.example.com”</a>; and <code>WRKSRC</code> to <code>${WRKDIR}/bar-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6</code>. /usr/local/bin/asciidoctor-pdf -r ./shared/lib/man-macro.rb -r ./shared/lib/man-macro.rb -r ./shared/lib/git-macro.rb -r ./shared/lib/packages-macro.rb -r ./shared/lib/inter-document-references-macro.rb -r ./shared/lib/sectnumoffset-treeprocessor.rb --doctype=book -a skip-front-matter -a pdf-theme=default-with-fallback-font -o /usr/home/dbaio/FreeBSD/git/doc/documentation/public/ru/books/arch-handbook/book.pdf /usr/home/dbaio/FreeBSD/git/doc/documentation/content/ru/books/arch-handbook/_index.adoc asciidoctor: FAILED: input file /usr/home/dbaio/FreeBSD/git/doc/documentation/content/ru/books/arch-handbook/_index.adoc is missing *** Error code 1 Stop. make: stopped in /usr/home/dbaio/FreeBSD/git/doc/documentation make pdf 4669.69s user 18.28s system 99% cpu 1:18:10.78 total
Comment Actions
I know about these errors, only the last one is a stopping one. I'll fix them before committing the diff.
Comment Actions
Indeed asciidoctor-pdf is not really good with multiple content. As a quick workaround, I'm going to make the includes point on nothing. We'll get errors but nothing fatal.