Hello All, I've started migrating my own documentation from AsciiDoc (Python2 based) to Asciidoctor (Ruby 1.9/2.x based). The transition has been virtually seamless. The original source code works in all most all circumstances, when proper formation was applied. The build invocations are almost identical with the exception of the app name itself (asciidoctor v.s. asciidoc) and you use the same name to build man pages also ( asciidoctor -b manpage 12345.1.txt ). No xmlproc or other package dependencies are needed, just Ruby and the gem module Asciidoctor. It has both an API and cli client.
There are many reasons why this change would be good for the WSJT documentation projects; to name just a few: * Removes the need for Python2 completely * In JTSDK-Win, removes Python2 and JTSDK-DOC (Cyg32 environment) requirements * Asciidoctor is very easy to install on Win, OSX and Linux, an has a minimal footprint, Win32 47.4MB ( Ruby + Asciidoctor). * Virtually all previous syntax works, plus there are many new features and functions. * Asciidoc has not been me updated in a couple years. There is effort (minimal at best) going into a port for Python3 by a very small dev team. ( 2 or three last I looked ), they simply do not have enough traction yet to get the project moving. * Asciidoctor on the other hand, has a very active development group. * It is *extremely fast* at compiling documents, =< 0.4 seconds for the WSJT guide, with data-uri enabled (lots of images). * The default CSS sheets are well polished, and IMHO, present a very nice looking document. It also has a CSS generator * Asciidoctor, by default, produces html5 documents and supports all the backends AsciiDoc supported. * There is a whole host of refinements around tables, adding Keyboard buttons, Markdown support, and general syntax cleanup. A change over for WSJT applications would be fairy painless. WSJT-X would require the most work, due to the Cmake find module and Python version check that is currently in place. The rest of the WSJT apps would be easy to update. In fact, I built the WSJT-X user guide with no modifications to the doc sources at all. I'll be putting together a JTSDK-Win32 installer for Ruby and the pre-installed gem module. For Linux, it's an extremely easy update / change, use the package manager to install asciidoctor or you can add the module manually, similar to the way Python modules are installed, but for Ruby, use gem:( gem install asciidoctor ) and that's it. I will also add asciidoctor to the dependency list for *Nix, which will pull in the Ruby interrupter if it's not installed. No changes to the WSJT apps / doc builds themselves will be made, but the Ruby + Asciidoctor tool chain will be in place, if and when you want to make the switch. 73's Greg, KI7MT ------------------------------------------------------------------------------ _______________________________________________ wsjt-devel mailing list wsjt-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/wsjt-devel
