@ 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 >
