deltaspike-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mark Struberg <strub...@yahoo.de>
Subject Re: [jira] [Updated] (DELTASPIKE-13) Choose documentation format and tools
Date Fri, 04 May 2012 20:44:41 GMT
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 <pmuir@redhat.com>
> To: deltaspike-dev@incubator.apache.org
> Cc: Matt Benson <mbenson@apache.org>; David Blevins <david.blevins@gmail.com>
> 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 <lightguard.jp@gmail.com>
>> 
>>>  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) <
>>>  jira@apache.org> 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
>>> 
> 

Mime
View raw message