My 2p. Markdown is great for short docs e.g. README, CONTRIBUTING, RELEASE-PROCESS, and when you just want to get something down. Setting up some of the fancy stuff like code highlighting, nice formatting, table of contents is not very easy, I haven't yet found a good toolchain wrapper for this. It's also missing some critical support e.g. tables.
Asciidoc is all round brilliant. It has everything you could need (supports everything docbok/latex does), it comes with a good toolchain, built in code highlighting, toc etc. Asciidoc doesn't have a java toolchain that I know of, so you are stuck with a native toolchain. IMO not a problem, we can wrap it easily in bat/sh files. On 4 May 2012, at 21:22, Gerhard Petracek wrote: > @ our apache-cms experts: > it would be nice if you share your experience at the previous thread (see > [1]). > > regards, > gerhard > > [1] http://s.apache.org/QIe > > > > 2012/5/4 Jason Porter <[email protected]> > >> I'm going to resurrect this thread, see if we can come to a consensus on >> what we want to use for documentation. >> >> As I currently understand things there are a few options on the table for >> documentation of DeltaSpike: >> >> * Apache CMS -- AIUI, this is a perl script that runs some extra stuff. >> More info and history is available at http://www.apache.org/dev/cms. Not >> sure if you have to be using SVN to get the rebuild on checkin support or >> not. >> >> * DocBook -- I think we're all familiar with DocBook. >> >> * Sphinx or plain ReStructuredText -- A wiki markup. Somewhat difficult to >> use and remember, heavily used in the Python community >> >> * Markdown -- We all know what that is. It has native support in >> apache-cms. Great for simple stuff, starts breaking down quickly when used >> for technical documentation >> >> * asciidoc -- Another wiki markup.http://www.methods.co.nz/asciidoc/. Easy >> to use, very similar to markdown, more expressive, very similar feature set >> to docbook. >> >> Earlier in this thread we wanted to have the ability to have buildable docs >> by maven. However, if there isn't a plugin already available, which to my >> knowledge would take out everything but docbook and sphinx, possibly >> markdown, we'd have to build one. We also want it easy for contributors to >> use, which is a downside to docbook and sphinx. If anyone has any others >> they'd like to put into the match, please speak up. >> >> On Fri, Apr 13, 2012 at 5:57 PM, Gerhard Petracek (Updated) (JIRA) < >> [email protected]> wrote: >> >>> >>> [ >>> >> https://issues.apache.org/jira/browse/DELTASPIKE-13?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel >> ] >>> >>> Gerhard Petracek updated DELTASPIKE-13: >>> --------------------------------------- >>> >>> Fix Version/s: 0.4-incubating >>> >>>> Choose documentation format and tools >>>> ------------------------------------- >>>> >>>> Key: DELTASPIKE-13 >>>> URL: >> https://issues.apache.org/jira/browse/DELTASPIKE-13 >>>> Project: DeltaSpike >>>> Issue Type: Task >>>> Reporter: Shane Bryzak >>>> Assignee: Jason Porter >>>> Fix For: 0.4-incubating >>>> >>>> >>>> We need to decide on a documentation format for the DeltaSpike >>> documentation. Requirements are: >>>> 1. Kept in the VCS with the DeltaSpike codebase >>>> 2. Buildable with Maven >>>> 3. Can generate multiple formats, including HTML and PDF >>>> Currently the "industry standard" is DocBook, however there may be >> other >>> alternatives which are more suitable. Suggestions welcome here. >>> >>> -- >>> This message is automatically generated by JIRA. >>> If you think it was sent incorrectly, please contact your JIRA >>> administrators: >>> https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa >>> For more information on JIRA, see: >> http://www.atlassian.com/software/jira >>> >>> >>> >> >> >> -- >> Jason Porter >> http://lightguard-jp.blogspot.com >> http://twitter.com/lightguardjp >> >> Software Engineer >> Open Source Advocate >> Author of Seam Catch - Next Generation Java Exception Handling >> >> PGP key id: 926CCFF5 >> PGP key available at: keyserver.net, pgp.mit.edu >>
