Wireshark mailing list archives
Re: Replacing AsciiDoc by Asciidoctor for faster documentation?
From: Peter Wu <peter () lekensteyn nl>
Date: Wed, 26 Oct 2016 19:55:13 +0200
On Wed, Oct 26, 2016 at 05:55:03PM +0100, Graham Bloice wrote:
On 26 October 2016 at 15:35, Peter Wu <peter () lekensteyn nl> wrote:Hi, The current documentation generator is really, really, really slow. It takes 35 seconds to generate developer-guide.xml using a2x (asciidoc.py). Looking for ways to make it faster, I found Asciidoctor. An initial attempt showed that it could generate a document within a second. Seeing references to Asciidoctor in the source tree, I was wondering if somebody has actually looked at adding Asciidoctor support? One obstacle I have now run into is missing support for a .conf file[1] which would enable use of attributes (?) and macros. Without any changes, currently Asciidoctor outputs HTML files without the links being corrected. By the way, Debian (and Ubuntu) do have an asciidoctor package in the repositories, others can install a Ruby gem if the distribution/OS does not provide appropriate packages. -- Kind regards, Peter Wu https://lekensteyn.nl [1]: https://github.com/asciidoctor/asciidoctor/wiki/ Does-Asciidoctor-support-AsciiDoc-.conf-files%3FThe requirement for Ruby is a bit of a bind, yet another script language runtime to install and therefore more manual steps in the Windows build env setup.
Since the syntax is supposedly backwards compatible (Asciidoctor claims this and backs it up through its tests), it should be possible to provide for both a2x and asciidoctor. The Ubuntu buildbots could benefit from this change as well.
While the time saving might be attractive is there that much churn in the docs that you actually rebuild them a lot?
The Lua documentation is part of the WSDG, I plan to make more changes in that area, but the delay makes it mildly annoying. The required changes should not be evasive, but I could not quickly find how to to the modifications. The manual mentions "user-defined configuration", but it is unclear how to do it exactly: http://asciidoctor.org/docs/user-manual/#subs-mac -- Kind regards, Peter Wu https://lekensteyn.nl ___________________________________________________________________________ Sent via: Wireshark-dev mailing list <wireshark-dev () wireshark org> Archives: https://www.wireshark.org/lists/wireshark-dev Unsubscribe: https://www.wireshark.org/mailman/options/wireshark-dev mailto:wireshark-dev-request () wireshark org?subject=unsubscribe
Current thread:
- Replacing AsciiDoc by Asciidoctor for faster documentation? Peter Wu (Oct 26)
- Re: Replacing AsciiDoc by Asciidoctor for faster documentation? Graham Bloice (Oct 26)
- Re: Replacing AsciiDoc by Asciidoctor for faster documentation? Peter Wu (Oct 26)
- Re: Replacing AsciiDoc by Asciidoctor for faster documentation? Graham Bloice (Oct 26)