You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@deltaspike.apache.org by Jason Porter <li...@gmail.com> on 2012/05/04 21:42:15 UTC
Re: [jira] [Updated] (DELTASPIKE-13) Choose documentation format and tools
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
Re: [jira] [Updated] (DELTASPIKE-13) Choose documentation format and tools
Posted by Mark Struberg <st...@yahoo.de>.
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 <pm...@redhat.com>
> To: deltaspike-dev@incubator.apache.org
> Cc: Matt Benson <mb...@apache.org>; David Blevins <da...@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 <li...@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
>>>
>
Re: [jira] [Updated] (DELTASPIKE-13) Choose documentation format and tools
Posted by Pete Muir <pm...@redhat.com>.
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 <li...@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
>>
Re: [jira] [Updated] (DELTASPIKE-13) Choose documentation format and tools
Posted by Gerhard Petracek <ge...@gmail.com>.
@ 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 <li...@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
>