tables and code highlighting comes out of the box with the Apache CMS integration.
But basically the ApacheCMS supports anything which can be triggered via a perl file and runs on a FreeBSD box. LieGrue, strub ----- Original Message ----- > From: Pete Muir <[email protected]> > To: [email protected] > Cc: Matt Benson <[email protected]>; David Blevins <[email protected]> > Sent: Friday, May 4, 2012 10:39 PM > Subject: Re: [jira] [Updated] (DELTASPIKE-13) Choose documentation format and > tools > > 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 >>> >
