Bug 253178 - asciidoc documentation needs recipe to build PDF
Summary: asciidoc documentation needs recipe to build PDF
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: Sergio Carlavilla Delgado
Depends on:
Reported: 2021-02-02 15:29 UTC by Konstantin Belousov
Modified: 2021-03-10 20:20 UTC (History)
4 users (show)

See Also:


Note You need to log in before you can comment on or make changes to this bug.
Description Konstantin Belousov freebsd_committer 2021-02-02 15:29:27 UTC
I want to (and regularly use) PDF build of our docs.  Currently there is
no Makefile target nor manual recipe in fdp-primer how to build PDF for docs
converted to asciidoc.

Please provide.
Comment 1 Li-Wen Hsu freebsd_committer 2021-02-02 15:32:02 UTC
carlavilla: I think we need a make target to generate PDF files, can you provide the commands to generate PDF files and then we can put them in the Makefile?
Comment 2 commit-hook freebsd_committer 2021-03-03 20:15:47 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=4f24ed91c23be2045691a1e916e85f54f6122b70

commit 4f24ed91c23be2045691a1e916e85f54f6122b70
Author:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
AuthorDate: 2021-03-03 20:13:08 +0000
Commit:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2021-03-03 20:13:08 +0000

    Add example to generate pdf document in FDP

    PR:             253178
    Submitted by:   kib@

 .../en/books/fdp-primer/doc-build/chapter.adoc     | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)
Comment 3 Sergio Carlavilla Delgado freebsd_committer 2021-03-03 20:19:26 UTC
I also need to add a target in the Makefile
Comment 4 Konstantin Belousov freebsd_committer 2021-03-04 00:56:24 UTC
The recipe does not work for me.

That is, handbook pdf is build (with the name book, without extension), but
neither xpdf on FreeBSD nor Acrobat Reader on windows do not render anything
useful.  In fact xpdf error dialog spills hundreds of error messages, and
Acrobat shows a 'broken file' dialog.

It renders somehow in Chrome, but the fact that pdf cannot be opened by proper
viewers kill the whole purpose of rendering into pdf.

I used the command from the commit, verbatim:
asciidoctor-pdf -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=./themes/default-pdf-theme.yml content/en/books/handbook/book.adoc

resulting pdf is available at
Comment 5 Sergio Carlavilla Delgado freebsd_committer 2021-03-04 18:57:51 UTC
Really weird, works well in my laptop. Maybe I have installed something else. Let me take a look.
Comment 6 Ed Maste freebsd_committer 2021-03-04 19:23:22 UTC
I tried it, xpdf opened the file without complaint but it renders as 799 nearly-blank pages.
Comment 7 Konstantin Belousov freebsd_committer 2021-03-04 19:32:09 UTC
(In reply to Ed Maste from comment #6)
xpdf has a strange way to report errors.  There is a button on the bar, which
becomes red when stream parse error is encountered.  Then you can press it, and
a dialog window with error list is displayed.

Ed, did you used mine book.pdf or generated the pdf file locally?
Comment 8 Ed Maste freebsd_committer 2021-03-04 19:52:11 UTC
> Ed, did you used mine book.pdf or generated the pdf file locally?

I generated it locally (and was surprised to find the output generated as content/en/books/handbook/book with no extension).

> xpdf has a strange way to report errors.  There is a button on the bar, which
becomes red when stream parse error is encountered.  Then you can press it, and
a dialog window with error list is displayed.

Ah, I see. I have four errors reported, 2 each of 8063 Arg #0 to 'Tf' operator is wrong type (string) and 8075 No font in show/space.
Comment 9 Konstantin Belousov freebsd_committer 2021-03-04 21:37:02 UTC
I tried the same asciidoctor-pdf command on up to date Fedora Core 33, and the
result it much better.  The pdf renders correctly and does contain text.

So it probably something with our asciidoctor/asciidoctor-pdf port that is wrong?
Comment 10 Konstantin Belousov freebsd_committer 2021-03-06 12:43:50 UTC
I believe it is prawn that is buggy or packaged with error.  The following
minimal example taken from prawn doc generates invalid pdf:

require "prawn"

Prawn::Document.generate("hello.pdf") do
  text "Hello World!"

Again, the error is that generated Tf pdf command has invalid font specification.
Comment 11 commit-hook freebsd_committer 2021-03-07 22:34:19 UTC
A commit references this bug:

Author: sunpoet
Date: Sun Mar  7 22:33:01 UTC 2021
New revision: 567782
URL: https://svnweb.freebsd.org/changeset/ports/567782

  Change RUN_DEPENDS from rubygem-pdf-core to rubygem-pdf-core07

  - Update version requirement of RUN_DEPENDS
  - Bump PORTREVISION for dependency change

  It should fix the resulting FDP pdf file.

  PR:		253178

Comment 12 Sunpoet Po-Chuan Hsieh freebsd_committer 2021-03-07 22:37:35 UTC
This is the generated PDF [1] using the following command and patched rubygem-prawn (r567782).

% asciidoctor-pdf -b pdf -d book -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-a skip-front-matter -a pdf-theme=documentation/themes/default-pdf-theme.yml documentation/content/en/books/handbook/book.adoc
asciidoctor: WARNING: image to embed not found or not readable: /tmp/freebsd-doc-main/documentation/static/images/books/handbook/wine/wine-config-1

[1] https://people.FreeBSD.org/~sunpoet/temp/freebsd-handbook.pdf
Comment 13 Konstantin Belousov freebsd_committer 2021-03-08 02:01:52 UTC
Worked for me, thanks.
Comment 14 Sergio Carlavilla Delgado freebsd_committer 2021-03-10 20:20:28 UTC
Thanks Sunpoet Po-Chuan Hsieh for the fix in the rubygem-prawn library