diff options
| author | Gerald Combs <gerald@wireshark.org> | 2016-11-01 14:35:29 -0700 |
|---|---|---|
| committer | Gerald Combs <gerald@wireshark.org> | 2016-11-11 17:18:25 +0000 |
| commit | 65ab2a97018877ec3a8664d7422c3ee4662e97ca (patch) | |
| tree | f6068d14ae9493c400eca66019dedbb76a2c42f4 /docbook/README.txt | |
| parent | aba4d3a3a7d8c7f97290621085a8fb7a33942847 (diff) | |
AsciiDoc: Create an include file for attributes.
Move the replacement definitions in asciidoc.conf to
attributes.asciidoc. This makes the markup a bit cleaner and is more
compatible with AsciiDoctor. Use a standard naming scheme for URLs.
Change-Id: Ica73aaadb013be2a4e6a3963fb54e6db6e02e98f
Reviewed-on: https://code.wireshark.org/review/18655
Reviewed-by: Peter Wu <peter@lekensteyn.nl>
Reviewed-by: Gerald Combs <gerald@wireshark.org>
Diffstat (limited to 'docbook/README.txt')
| -rw-r--r-- | docbook/README.txt | 20 |
1 files changed, 19 insertions, 1 deletions
diff --git a/docbook/README.txt b/docbook/README.txt index 83664ffc41..deb7b7ad42 100644 --- a/docbook/README.txt +++ b/docbook/README.txt @@ -13,7 +13,8 @@ Requirements are listed below. The guides and release notes are written in AsciiDoc (http://asciidoc.org), but use many Asciidoctor (http://asciidoctor.org/) markup extensions which are provided in asciidoctor-asciidoc.conf. The documentation toolchain may -switch exclusively to Asciidoctor at some point in the future. +switch exclusively to Asciidoctor at some point in the future. See the +AsciiDoctor section at the end of this document for details. To get HTML, PDF or other output formats, conversions are done using XSL stylesheets, which provides a flexible way for these conversions. @@ -244,3 +245,20 @@ Using the prefix wsdg_ instead of wsug_ will build the same targets but for the Wireshark Developer's Guide. 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: + +- 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 + +- Choose a "compat" mode: http://asciidoctor.org/docs/migration/
\ No newline at end of file |