Issues building docs for recent master branch

[distortedsignal]

I was trying to build the cowboy docs and I ran into a slight issue - log below:

> make docs
erlang.mk:26: Please upgrade to GNU Make 4 or later: https://erlang.mk/guide/installation.html
 GEN    distclean-asciidoc-guide
 DEP    asciideck (master)
/Users/tom/Documents/src/projects/cowboy/erlang.mk:26: Please upgrade to GNU Make 4 or later: https://erlang.mk/guide/installation.html
 DEPEND asciideck.d
/Users/tom/Documents/src/projects/cowboy/erlang.mk:26: Please upgrade to GNU Make 4 or later: https://erlang.mk/guide/installation.html
 ERLC   asciideck.erl asciideck_attributes_parser.erl asciideck_attributes_pass.erl asciideck_block_parser.erl asciideck_inline_pass.erl asciideck_line_reader.erl asciideck_lists_pass.erl asciideck_reader.erl asciideck_source_highlight.erl asciideck_stdin_reader.erl asciideck_tables_pass.erl asciideck_to_html.erl asciideck_to_manpage.erl asciideck_transform_pass.erl
 APP    asciideck
a2x -v -f pdf doc/src/guide/book.asciidoc && mv doc/src/guide/book.pdf doc/guide.pdf
a2x: args: ['--dblatex-opts', '-P latex.output.revhistory=0 -P doc.publisher.show=0 -P index.numbered=0', '--dblatex-opts', '-s cowboy', '-d', 'book', '--attribute', 'tabsize=4', '-v', '-f', 'pdf', 'doc/src/guide/book.asciidoc']
a2x: resource files: []
a2x: resource directories: ['/usr/local/etc/asciidoc/images', '/usr/local/etc/asciidoc/stylesheets']
a2x: executing: "/usr/local/bin/asciidoc.py" --backend docbook -a "a2x-format=pdf"  --doctype book --attribute "tabsize=4" --verbose  --out-file "/Users/tom/Documents/src/projects/cowboy/doc/src/guide/book.xml" "/Users/tom/Documents/src/projects/cowboy/doc/src/guide/book.asciidoc"

asciidoc: reading: /usr/local/etc/asciidoc/asciidoc.conf
...
asciidoc: reading: /usr/local/etc/asciidoc/lang-en.conf
asciidoc: writing: /Users/tom/Documents/src/projects/cowboy/doc/src/guide/book.xml
asciidoc: include: /Users/tom/Documents/src/projects/cowboy/doc/src/guide/modern_web.asciidoc
...
asciidoc: include: /Users/tom/Documents/src/projects/cowboy/doc/src/guide/specs.asciidoc
asciidoc: book.asciidoc: line 92: reading: /Users/tom/Documents/src/projects/cowboy/doc/src/guide/specs.asciidoc

a2x: executing: "xmllint" --nonet --noout --valid "/Users/tom/Documents/src/projects/cowboy/doc/src/guide/book.xml"

I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
/Users/tom/Documents/src/projects/cowboy/doc/src/guide/book.xml:2: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
D DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
                                                                               ^
/Users/tom/Documents/src/projects/cowboy/doc/src/guide/book.xml:6: validity error : Validation failed: no DTD found !
<book lang="en">
               ^

a2x: ERROR: "xmllint" --nonet --noout --valid "/Users/tom/Documents/src/projects/cowboy/doc/src/guide/book.xml" returned non-zero exit status 4
make: *** [asciidoc-guide] Error 1

I'm a little surprised that it's so complicated to make the docs, but that's fine. Note that I snipped some lines, represented by the ellipsis.

I think this is an issue with my a2x install, but I'm not clear on what versions of a2x are supported. My a2x version is as follows:

> a2x --version
a2x 8.6.9

Any help would be appreciated.

[distortedsignal]

I'm on MacOS 10.14.6 (18G103) if that would make a difference. While we're at it, I'm using zsh.

[essen]

It has a pass involving XML and therefore requires either Internet access or that the DTD files be on the system already (though I do not know how to do that, never looked). This is the relevant part:

I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
/Users/tom/Documents/src/projects/cowboy/doc/src/guide/book.xml:2: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
D DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"

It's possible that the error was intermittent as well. Works fine for me right now.

I had started to work on an alternative that would not require this to produce HTML (though it still would for PDF, not much choice there at the moment), but ran out of time so the guide still requires the old Asciidoc/DocBook. Manual pages on the other hand don't have non-Erlang dependencies anymore. I have more time now so maybe I'll manage to convert the HTML guide to this as well, would be great to finally get it over with.

[distortedsignal]

@essen I'm not sure that's the issue. I am online, and I can pull the dtd file down and open it in other applications. I think it might be that my version of a2x may require the capitalization of en to match the dtd file. Note these lines in the logs:

$cowboy/doc/src/guide/book.xml:2: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
D DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
                                                                               ^
$cowboy/doc/src/guide/book.xml:6: validity error : Validation failed: no DTD found !
<book lang="en">
               ^

Note especially that the first line has the property D DocBook XML V4.5//EN while the validation appears to be looking for lang="en". Could you give me your a2x version so that we could eliminate that as a variable?

[essen]

Doubt it, should be case insensitive.

$ a2x --version
a2x 8.6.10

Do you have the DTD on your system? Perhaps it's just configured not to download it and instead only use from the file system. Mine is at /usr/share/xml/docbook/xml-dtd-4.5/docbookx.dtd.

[distortedsignal]

Ok, we're a bugfix apart, and I pulled mine from the sourceforge tar last week (I think?). The docbook is on my system, but it's unclear how to point the doc builder to the file. Is there a flag for that? How would I learn about that flag?

[essen]

I have no idea, you shouldn't have to do anything, but I don't know macOS enough to know if that's true.

I don't think it's worth looking too much into it. My Erlang version of Asciidoc is super close to being able to build the HTML guide, so my time would be better spent working on that if anything. Wouldn't help for PDF but I suppose that's OK.

[distortedsignal]

Since this is (demonstrably) not fixed (I still can't build the docs with make docs), and you don't have the time to work on it, should we leave this open and see if we can get to it later?

[essen]

Looks like you're not the first with this issue, and the other ticket is still open, plus is in the right repo (the Erlang Asciidoc I mentioned) so please subscribe to that ticket: ninenines/asciideck#2

The goal is to no longer require this huge toolchain at least for HTML and man pages.

[distortedsignal]

👍