1 2 3 4 Previous Next 50 Replies Latest reply on Jul 9, 2012 11:30 PM by sboscarine Go to original post
      • 30. Re: Asciidoc is the way forward
        lightguard
        • 31. Re: Asciidoc is the way forward
          dan.j.allen

          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.j.allen

            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
              lightguard

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

              • 34. Re: Asciidoc is the way forward
                dan.j.allen

                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
                  pmuir

                  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
                    pmuir

                    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.j.allen

                      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.j.allen

                        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
                          lightguard

                          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.j.allen

                            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.j.allen

                              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
                                davidecavestro

                                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
                                  sboscarine

                                  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
                                    lightguard

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