5 Replies Latest reply on Jun 6, 2012 9:32 AM by pmuir

    Running AsciiDoc on Windows


      Steven Boscarine raised concern about Windows support for AsciiDoc.

      I have some concerns that this won't run in Windows since it relies on having programs in PATH.  I couldn't get Windows to work the same as Ubuntu.


      I respect the concern about running AsciiDoc on windows and would like to suggest some ideas that can begin to close the gap.


      First, I'll mention that in the last release (8.6.7), the release notes state that AsciiDoc no longer drops down to a shell when it needs to execute another python script (such as filters). It loads those into the current runtime and invokes them. That fix should save any hassles of using the main AsciiDoc script on Windows.

      All Python filters are executed with the same Python interpreter that executes the asciidoc parent (previously filters were hardwired to execute the python interpreter). This prevents Python mix-ups.


      I discovered an effort to create a Windows installer for AsciiDoc on code.google.com. It's a few releases old, but it shouldn't be too hard to bring it up to latest AsciiDoc. At the very least, it's a start.


      I've recently adopted the position of recommending a virtual machine over cygwin [1]. Virtual machines have gotten so good that there is hardly a measurable difference (in human perception) between using a virtual machine at full screen and a native operating install. I've been using JBoss AS 7, JBoss Tools and Maven inside a virtual machine running Fedora 17 and I can hardly detect the VM sweating. You can have this up and running in < 30 minutes (or faster). Just grab the Fedora 17 (or Ubuntu 12.04) Live CD, use the VM manager of your choice (VirtualBox, Parallels, Virt Manager) and rev it up.


      Finally, I think for day-to-day usage nothing more than the AsciiDoc script is needed (asciidoc.py or a2x.py). The callouts to GNU source-highlight or python-pygments, dblatex, etc could all be done on a build server. Those filters and sub-commands are really intended to generate production output. The AsciiDoc script is only needed locally to syntax check and to convert the document into a draft form to check formatting, indentation and missing section breaks (e.g., paragraphs that get merged into source code). A web-based previewer might also be a nice help here.


      In summary, I agree that being able to run AsciiDoc on windows is important. I think there are several paths to get there both in the short run and in the long run. And, finally, remember that AsciiDoc is just a markup syntax, not a tool chain, per se. It's possible to write a clean-room parser for AsciiDoc to port it to a different language, which is already underway for Ruby (Ruby is much more JVM friendly, IMO, than python).

        • 1. Re: Running AsciiDoc on Windows

          The ideal would be something that could run purely in Java.  Then we can encapsulate the complexity and this would be just an ordinary Maven plugin.  Part of Java's success is because it doesn't rely on native programs and 1 jar can run consistently from machine to machine.


          I have a tiny proof of concept that downloaded Jython from maven and supported a subset of the commands, but didn't go far because it expected several programs to be in the path.  If we could get Java to call easy_install (https://community.jboss.org/message/721269#721269), it would be "funky," but decent enough to get a community started.


          I definitely agree that cygwin is incredibly unfriendly.  Do you think we can get a VM solution that a non-technical English major can run?


          Earlier today, Jason suggested a webapp.  We can certainly build a REST API quickly that makes native shell calls.  That could be another option.  It still means you need a modern *NIX running somewhere, but we could build an interim Maven plugin that allows windows users to preview their efforts by hitting a remote server. 

          • 2. Re: Running AsciiDoc on Windows

            We can definitely make a VM solution that a typical computer user can run. If it's pre-built, you open the VM file in a virtual machine manager and press play. I've used this approach for workshops and it works out great (even when my instructions weren't that great).


            To build a virtual machine in a non-point and clicky way, we can use BoxGrinder. BoxGrinder is an automatic Virtual Machine builder and OS installation executor. Keep in mind BoxGrinder is for building the virtual machine, not for playing it. It's our build tool, not anything the documentation writer would use.

            • 3. Re: Running AsciiDoc on Windows

              How much effort would we realistically be talking to build something simple in rails or even Java which uses git as the backend storage and calls out to the native calls? It doesn't have to look pretty, just usage for now. If O'Rielly is dragging their feet here with Atlas we ought to be able to create something usable in a fairly reasonable amount of time I would think. Maybe a week?

              • 4. Re: Running AsciiDoc on Windows

                What's Atlas?

                • 5. Re: Running AsciiDoc on Windows

                  If GitHub can improve their AsciiDoc support sufficiently, then having people clone the repo, and edit the source there, viewing it, then creating a pull, seems a good alternative, for non-heavy usage.