diff options
author | Gerald Combs <gerald@wireshark.org> | 2017-10-19 08:24:58 -0700 |
---|---|---|
committer | Gerald Combs <gerald@wireshark.org> | 2017-10-19 16:09:49 +0000 |
commit | c1807eec7800c7b6ab8f99a42b1edca741d5da0b (patch) | |
tree | 9514c28065aa1f8cd6710077f57ac154b8ffa253 | |
parent | 0870f8586a1aef45d668127d0f3628a70bd0623d (diff) |
Add more notes about Asciidoctor.
Change-Id: I7fd12b9189448a637d1bebac6687168f017d8d8d
Reviewed-on: https://code.wireshark.org/review/23987
Reviewed-by: Gerald Combs <gerald@wireshark.org>
-rw-r--r-- | docbook/README.txt | 27 |
1 files changed, 18 insertions, 9 deletions
diff --git a/docbook/README.txt b/docbook/README.txt index 2014035212..dffcfc6e68 100644 --- a/docbook/README.txt +++ b/docbook/README.txt @@ -249,16 +249,25 @@ The makefile is written to be run with make on UNIX/Linux platforms. AsciiDoctor ----------- -At the time of this writing (November 2016) the AsciiDoctor project is much -more active than AsciiDoc. At some point it might be worth the effort to -migrate to AsciiDoctor. To do so we'd have to do the following at a minimum: +At the time of this writing (October 2017) the Asciidoctor project is +much more active than AsciiDoc. It also supports extra features +including additional markup and diagrams. At some point it might be +worth the effort to migrate to Asciidoctor. To do so we'd have to do the +following at a minimum: -- Require Ruby + AsciiDoctor or Java + AsciiDoctorj to build the documentation. +- Require Ruby + Asciidoctor or Java + AsciidoctorJ to build the + documentation. -- Either port the macros in asciidoc.conf to AsciiDoctor or stop using them. - -- Restrict ourselves to decimal entities since the PDF renderer doesn't - support hexadecimal ones: - https://github.com/asciidoctor/asciidoctorj/issues/439 +- Port the macros in asciidoc.conf to Asciidoctor extensions. + https://github.com/asciidoctor/asciidoctor-extensions-lab - Choose a "compat" mode: http://asciidoctor.org/docs/migration/ + +Targets +------- + +Asciidoctor alone doesn't entirely cover our various build targets. It +can generate single-page HTML, Docbook, PDF, Epub3, and a few other +formats. Our current toolchain generates single-page HTML, chunked HTML, +text, HTMLHelp, and PDF output. We would still depend on DocBook, XSLT, +and HTMLHelp for most targets. |