1 2 3 4 Previous Next 50 Replies Latest reply: Jul 9, 2012 11:30 PM by Steven Boscarine Go to original post RSS
  • 31. Re: Asciidoc is the way forward
    Dan Allen Master

    Interesting. a2x is already using xmllint to validate the generated docbook XML. It wouldn't take much to also use it to format the output.

  • 32. Re: Asciidoc is the way forward
    Dan Allen Master

    xmllint shouldn't touch it if it's in CDATA tags. Which it's not, but that can be easily configured in AsciiDoc. But I'm noticing that xmllint is smart enough to recognize the docbook schema and is not reflowing programlisting blocks. Interesting.

  • 33. Re: Asciidoc is the way forward
    Jason Porter Master

    That is interesting, had no clue it had that kind of power.

  • 34. Re: Asciidoc is the way forward
    Dan Allen Master

    AsciiDoc has not yet ceased to amaze me. The entire processing is done via a configuration pipeline, so you could make AsciiDoc behave like reStructuredText or Markdown if you really wanted to. That's great for use as a templating engine (think Awestruct) because you can tweak how it creates the HTML it creates. With Textile (RedCloth) you would have to modify generated Java code and recompile the whole gem. Not nearly as convenient

     

    The only big downside I see to AsciiDoc (if you held my hand to the fire to come up with something), it's that the code itself is not modularized. Instead, it's two very large python scripts. That's why my hope is that in the long run, someone reimplements the same pipeline in a very clean and modular way. I have hopes for this Ruby project, but it's still early.

     

    ...I would also like to see AsciiDoc make less use of commandline tools. I like the idea that it supports plugging in a commandline tool at any stage in the process....that's good for people building on it, but I would hope that in the long run it can bundle all this up to be self-contained (for the core functionality).

  • 35. Re: Asciidoc is the way forward
    Pete Muir Master

    Dan, I'm happy to adopt whatever approach you think is best. Could you write this all up? I'm looking for:

     

    • Overview, when to use what tool (e.g. when should we use Markdown, when should we use asciidoc?)
    • Preamble, why this is a good tool
    • Basic usage - link to some good authoring guides
    • Description of toolchain - how to get this setup on Mac, Windows and Linux
    • Some starter scripts we can use to do the generation that we can customise

     

    This will give us a good starting point to actually use this :-)

  • 36. Re: Asciidoc is the way forward
    Pete Muir Master

    My current understanding is that we plan to use Markdown for things like READMES (I'm against changing this, we've got a lot of investment in using Markdown here now), and something like Ascidoc for longer documentation. We'll then generate HTML from it, which can be embedded into JBoss.org pages as needed.

  • 37. Re: Asciidoc is the way forward
    Dan Allen Master

    I agree with that strategy.

     

    Additionally, if you start out writing something in Markdown and it happens to grow/mature into full-length documentation, the switch to AsciiDoc is easy--probably even scriptable.

  • 38. Re: Asciidoc is the way forward
    Dan Allen Master

    Sounds like a good starting point for switching this thread into a wiki page. I'll put the information I have gathered in the context of those questions and then we can build on it.

  • 39. Re: Asciidoc is the way forward
    Jason Porter Master

    Dan Allen wrote:

     

    ...I would also like to see AsciiDoc make less use of commandline tools. I like the idea that it supports plugging in a commandline tool at any stage in the process....that's good for people building on it, but I would hope that in the long run it can bundle all this up to be self-contained (for the core functionality).

     

    Sounds like a rewrite is needed. One of the things I loved about docutils (at the code level) is that it's very modular and it creates an intermediate representation of the file so it becomes easy to create other outputs. I don't like how it can't be extended save by other declarations, you can't add syntax. A more modular structure to ASCIIDOC may allow this and make it easier to use / extend. Probably won't happen though unless we fork it.

  • 40. Re: Asciidoc is the way forward
    Dan Allen Master

    Call it a refactoring AsciiDoc does write temporary files in some cases. But not really for the same reason that docutils does.

     

    There are really two options. The more lightweight approach is helping flesh out the Ruby port, since that has a good foundation for modularity already. What it's missing so far is block-level templating (it only supports templating at the line and char level). If it had that, things would progress quickly. I'll file an issue just to get the ball rolling.

  • 41. Re: Asciidoc is the way forward
    Dan Allen Master

    It looks like someone has put together an API wrapper for AsciiDoc for support in the Github markup engine. That simplifies integration with Python and would likely make it easier to use the JSR-233 APIs (except there is still that bug with script size).

     

    I wonder if AsciiDoc would consider accepting this API wrapper into the mainline? I suppose we could submit it upstream. First, I want to play around with it.

  • 42. Re: Asciidoc is the way forward
    Davide Cavestro Newbie

    I'm definitely an asciidoc fan. It has a great potential. Even its support for graphical contents like plantuml/ditaa is great.

    Dan Allen ha scritto:

    Dan Allen ha scritto:

    But that's just one pipeline. Since AsciiDoc is remarkably portable and readable, we can easily reuse it in many other areas. We can paste it into a gist, paste it into a github wiki page, paste it into a blog entry, paste it on Google+, and so on.

    At http://dag.wieers.com/home-made/wascii/ I've seen there was also

    a web frontend intended to display an AsciiDoc documentation repository. It allows to search and browse your documentation files and automatically converts AsciiDoc to HTML, PDF and ODF documents. It is intended to work directly from a subversion repository containing your AsciiDoc files.

    but I've not been able to give it a test. You could be interested, and maybe it could resurrect...

    IMHO asciidoc is also a good candidate for a deeper integration into any software production system (see Gather All Your Development Documentation In One Place).

     

    Just my two cents.

  • 43. Re: Asciidoc is the way forward
    Steven Boscarine Novice

    Any updates on this?  I'd like to see if we can get this running in Java.  Should I create a github project or do you have one available?

     

    Here would be my ideal:

    1. Check out a Maven (or Gradle if you strongly prefer) project
    2. Build, using nothing but Java and Maven/Gradle installed on the box
    3. Have the vast majority of functionality of the native binaries, without cygwin.
    4. Run as standalone jar
    5. Once that's proven to work, run as maven plugin.

     

    WDYT?

     

    In my company, documentation is handled by technical writers, specialists who are not as adventurous as most developers when it comes to installing software.  Like most corporate shops, it has to run on Windows.  A java implementation that could be run from maven is far friendlier than http://blog.rainwebs.net/2010/02/25/how-to-create-handsome-pdf-documents-without-frustration/

     

    The tech writers loved the markup language and would love to try it out, but the themes in your Java EE 6 Workshop doc didn't run in cygwin for me or them.  We got:

    asciidoc: WARNING: missing backend conf file: html5.conf
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [literalblock]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [verseblock]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [quoteblock]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [listingblock]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [image-blockmacro]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [sect1]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [sect1]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [sect1]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [sect1]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [sect1]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [sect1]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [sect1]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [sect1]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [sect1]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [image-blockmacro]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [image-blockmacro]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [image-blockmacro]
    asciidoc: WARNING: tutorial.asciidoc: line 10: missing section: [listingblock]
    asciidoc: FAILED: incomplete configuration files
    

    We obviously are continuing our prototype with other themes. 

  • 44. Re: Asciidoc is the way forward
    Jason Porter Master

    You'd have to use jython and create a maven plugin.