[suggestion] - Documentation

classic Classic list List threaded Threaded
26 messages Options
12
Reply | Threaded
Open this post in threaded view
|

[suggestion] - Documentation

Charles Moulliard
Hi,

I would like to suggest that we split the page user documentation in several chapters - pages to provide more visibility on the project DeltaSpike

- Introduction - goals,
- Getting started,
- Modules
    - jpa,
    - security,
- Developers,
- Community

What do you think about that ?

Remark :
- Also, we should allow people to have access to this web page --> http://incubator.apache.org/deltaspike/ which is not the case today except the wiki page
- To build the documentation, we could use scalate (templating engine - http://scalate.fusesource.org/)) which is used by Apache Karaf, Apache Camel and Apache ServiceMix to generate static web sites but also PDF doc.
- GitHub repo has not link to the project (https://github.com/apache/incubator-deltaspike)
 

Regards,

Charles
Apache Committer / Sr. Pr. Consultant at FuseSource.com
Email: [hidden email]
Twitter : @cmoulliard, @fusenews
Blog : http://cmoulliard.blogspot.com
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Gerhard Petracek
Administrator
hi charles,

thx for the feedback!

@documentation:
this part of the wiki is called "Temporary Documentation" because we don't
plan to keep the documentation in the wiki.
-> for now we just collect information there (in a very simple style) to
avoid a lack of information.

regards,
gerhard



2012/6/14 Charles Moulliard <[hidden email]>

> Hi,
>
> I would like to suggest that we split the page user documentation in
> several
> chapters - pages to provide more visibility on the project DeltaSpike
>
> - Introduction - goals,
> - Getting started,
> - Modules
>    - jpa,
>    - security,
> - Developers,
> - Community
>
> What do you think about that ?
>
> Remark :
> - Also, we should allow people to have access to this web page -->
> http://incubator.apache.org/deltaspike/ which is not the case today except
> the wiki page
> - To build the documentation, we could use scalate (templating engine -
> http://scalate.fusesource.org/)) which is used by Apache Karaf, Apache
> Camel
> and Apache ServiceMix to generate static web sites but also PDF doc.
> - GitHub repo has not link to the project
> (https://github.com/apache/incubator-deltaspike)
>
>
> Regards,
>
> Charles
>
> --
> View this message in context:
> http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767.html
> Sent from the Apache DeltaSpike Incubator Discussions mailing list archive
> at Nabble.com.
>
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Jason Porter
Maybe we need to finish the documentation discussion and just be done with
it. I really like asciidoc there's lots of tools for it and it renders
docbook which we can take and do whatever with. The only problem right now
is that there's no maven plugin for it and jython is really slow :( The
GitHub guys are doing a ruby port which would work really well with jruby,
but I don't think they've released it yet.

For now the temporary wiki I think works decently.

On Thu, Jun 14, 2012 at 4:43 AM, Gerhard Petracek <
[hidden email]> wrote:

> hi charles,
>
> thx for the feedback!
>
> @documentation:
> this part of the wiki is called "Temporary Documentation" because we don't
> plan to keep the documentation in the wiki.
> -> for now we just collect information there (in a very simple style) to
> avoid a lack of information.
>
> regards,
> gerhard
>
>
>
> 2012/6/14 Charles Moulliard <[hidden email]>
>
> > Hi,
> >
> > I would like to suggest that we split the page user documentation in
> > several
> > chapters - pages to provide more visibility on the project DeltaSpike
> >
> > - Introduction - goals,
> > - Getting started,
> > - Modules
> >    - jpa,
> >    - security,
> > - Developers,
> > - Community
> >
> > What do you think about that ?
> >
> > Remark :
> > - Also, we should allow people to have access to this web page -->
> > http://incubator.apache.org/deltaspike/ which is not the case today
> except
> > the wiki page
> > - To build the documentation, we could use scalate (templating engine -
> > http://scalate.fusesource.org/)) which is used by Apache Karaf, Apache
> > Camel
> > and Apache ServiceMix to generate static web sites but also PDF doc.
> > - GitHub repo has not link to the project
> > (https://github.com/apache/incubator-deltaspike)
> >
> >
> > Regards,
> >
> > Charles
> >
> > --
> > View this message in context:
> >
> http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767.html
> > Sent from the Apache DeltaSpike Incubator Discussions mailing list
> archive
> > at Nabble.com.
> >
>



--
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
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Mark Struberg
Administrator
Hi!

Good topic!

finally we have our CMS!

It's really ugly as I don't have an eye for good web pages, but at least it exists ;)
But ignore the layout for now. We can easily change this later.


http://incubator.apache.org/deltaspike

You can find more infos at [1].

If you like to edit a page then simply add the following to your bookmarks:

javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))

add this manually as bookmark. Then visit any CMS page and click on the bookmark. You will get an auth window where you need to login via your apacheId and pwd.
Saving the change will do a svn commit in the background and publish the changes.

LieGrue,
strub

[1] http://wiki.apache.org/general/ApacheCms2010



----- Original Message -----

> From: Jason Porter <[hidden email]>
> To: [hidden email]
> Cc:
> Sent: Thursday, June 28, 2012 7:09 PM
> Subject: Re: [suggestion] - Documentation
>
> Maybe we need to finish the documentation discussion and just be done with
> it. I really like asciidoc there's lots of tools for it and it renders
> docbook which we can take and do whatever with. The only problem right now
> is that there's no maven plugin for it and jython is really slow :( The
> GitHub guys are doing a ruby port which would work really well with jruby,
> but I don't think they've released it yet.
>
> For now the temporary wiki I think works decently.
>
> On Thu, Jun 14, 2012 at 4:43 AM, Gerhard Petracek <
> [hidden email]> wrote:
>
>>  hi charles,
>>
>>  thx for the feedback!
>>
>>  @documentation:
>>  this part of the wiki is called "Temporary Documentation" because
> we don't
>>  plan to keep the documentation in the wiki.
>>  -> for now we just collect information there (in a very simple style) to
>>  avoid a lack of information.
>>
>>  regards,
>>  gerhard
>>
>>
>>
>>  2012/6/14 Charles Moulliard <[hidden email]>
>>
>>  > Hi,
>>  >
>>  > I would like to suggest that we split the page user documentation in
>>  > several
>>  > chapters - pages to provide more visibility on the project DeltaSpike
>>  >
>>  > - Introduction - goals,
>>  > - Getting started,
>>  > - Modules
>>  >    - jpa,
>>  >    - security,
>>  > - Developers,
>>  > - Community
>>  >
>>  > What do you think about that ?
>>  >
>>  > Remark :
>>  > - Also, we should allow people to have access to this web page -->
>>  > http://incubator.apache.org/deltaspike/ which is not the case today
>>  except
>>  > the wiki page
>>  > - To build the documentation, we could use scalate (templating engine
> -
>>  > http://scalate.fusesource.org/)) which is used by Apache Karaf, Apache
>>  > Camel
>>  > and Apache ServiceMix to generate static web sites but also PDF doc.
>>  > - GitHub repo has not link to the project
>>  > (https://github.com/apache/incubator-deltaspike)
>>  >
>>  >
>>  > Regards,
>>  >
>>  > Charles
>>  >
>>  > --
>>  > View this message in context:
>>  >
>>
> http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767.html
>>  > Sent from the Apache DeltaSpike Incubator Discussions mailing list
>>  archive
>>  > at Nabble.com.
>>  >
>>
>
>
>
> --
> 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
>
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Charles Moulliard
Hi Mark,

I have tried to create a directory but I cannot commit in the project :

Error

The operation is forbidden by the server: Commit failed (details follow):: Changing file '/usr/local/cms/wc/deltaspike/cmoulliard-OlVI4e/trunk/content/deltaspike/modules' is forbidden by the server: Access to '/repos/asf/!svn/txr/1355248-tlb2/incubator/deltaspike/site/trunk/content/deltaspike/modules' forbidden at /usr/local/cms/webgui/lib/ASF/CMS/WC/Commit.pm line 64
Regards,
Charles Moulliard

Apache Committer

Blog : http://cmoulliard.blogspot.com
Twitter : http://twitter.com/cmoulliard
Linkedin : http://www.linkedin.com/in/charlesmoulliard
Skype: cmoulliard


On Thu, Jun 28, 2012 at 7:21 PM, Mark Struberg [via Apache DeltaSpike Incubator Discussions] <[hidden email]> wrote:
Hi!

Good topic!

finally we have our CMS!

It's really ugly as I don't have an eye for good web pages, but at least it exists ;)
But ignore the layout for now. We can easily change this later.


http://incubator.apache.org/deltaspike

You can find more infos at [1].

If you like to edit a page then simply add the following to your bookmarks:

javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))

add this manually as bookmark. Then visit any CMS page and click on the bookmark. You will get an auth window where you need to login via your apacheId and pwd.
Saving the change will do a svn commit in the background and publish the changes.

LieGrue,
strub

[1] http://wiki.apache.org/general/ApacheCms2010



----- Original Message -----

> From: Jason Porter <[hidden email]>
> To: [hidden email]
> Cc:
> Sent: Thursday, June 28, 2012 7:09 PM
> Subject: Re: [suggestion] - Documentation
>

> Maybe we need to finish the documentation discussion and just be done with
> it. I really like asciidoc there's lots of tools for it and it renders
> docbook which we can take and do whatever with. The only problem right now
> is that there's no maven plugin for it and jython is really slow :( The
> GitHub guys are doing a ruby port which would work really well with jruby,
> but I don't think they've released it yet.
>
> For now the temporary wiki I think works decently.
>
> On Thu, Jun 14, 2012 at 4:43 AM, Gerhard Petracek <
> [hidden email]> wrote:
>
>>  hi charles,
>>
>>  thx for the feedback!
>>
>>  @documentation:
>>  this part of the wiki is called "Temporary Documentation" because
> we don't
>>  plan to keep the documentation in the wiki.
>>  -> for now we just collect information there (in a very simple style) to
>>  avoid a lack of information.
>>
>>  regards,
>>  gerhard
>>
>>
>>
>>  2012/6/14 Charles Moulliard <[hidden email]>
>>
>>  > Hi,
>>  >
>>  > I would like to suggest that we split the page user documentation in
>>  > several
>>  > chapters - pages to provide more visibility on the project DeltaSpike
>>  >
>>  > - Introduction - goals,
>>  > - Getting started,
>>  > - Modules
>>  >    - jpa,
>>  >    - security,
>>  > - Developers,
>>  > - Community
>>  >
>>  > What do you think about that ?
>>  >
>>  > Remark :
>>  > - Also, we should allow people to have access to this web page -->
>>  > http://incubator.apache.org/deltaspike/ which is not the case today
>>  except
>>  > the wiki page
>>  > - To build the documentation, we could use scalate (templating engine
> -
>>  > http://scalate.fusesource.org/)) which is used by Apache Karaf, Apache
>>  > Camel
>>  > and Apache ServiceMix to generate static web sites but also PDF doc.
>>  > - GitHub repo has not link to the project
>>  > (https://github.com/apache/incubator-deltaspike)
>>  >
>>  >
>>  > Regards,
>>  >
>>  > Charles
>>  >
>>  > --
>>  > View this message in context:
>>  >
>>
> http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767.html
>>  > Sent from the Apache DeltaSpike Incubator Discussions mailing list

>>  archive
>>  > at Nabble.com.
>>  >
>>
>
>
>
> --
> 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
>



If you reply to this email, your message will be added to the discussion below:
http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767p4652901.html
To unsubscribe from [suggestion] - Documentation, click here.
NAML

Apache Committer / Sr. Pr. Consultant at FuseSource.com
Email: [hidden email]
Twitter : @cmoulliard, @fusenews
Blog : http://cmoulliard.blogspot.com
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Mark Struberg
Administrator
Hi Charles!

Ok, I should have been more clear :)

That's because you are not yet a committer on DeltaSpike, right?

This all works via SVN rights, but the CMS documentation also has a section about providing a kind of svn diff and ship it as patch afterwards. This is done to get rid of the spamming problem we have right now in confluence.

Btw, if you use DeltaSpike and ship some patches then ... you know the game ;)

LieGrue,
strub



----- Original Message -----

> From: Charles Moulliard <[hidden email]>
> To: [hidden email]
> Cc:
> Sent: Friday, June 29, 2012 9:10 AM
> Subject: Re: [suggestion] - Documentation
>
> Hi Mark,
>
> I have tried to create a directory but I cannot commit in the project :
> Error
>
> The operation is forbidden by the server: Commit failed (details
> follow):: Changing file
> '/usr/local/cms/wc/deltaspike/cmoulliard-OlVI4e/trunk/content/deltaspike/modules'
> is forbidden by the server: Access to
> '/repos/asf/!svn/txr/1355248-tlb2/incubator/deltaspike/site/trunk/content/deltaspike/modules'
> forbidden at /usr/local/cms/webgui/lib/ASF/CMS/WC/Commit.pm line 64
>
> Regards,
>
> Charles Moulliard
>
> Apache Committer
>
> Blog : http://cmoulliard.blogspot.com
> Twitter : http://twitter.com/cmoulliard
> Linkedin : http://www.linkedin.com/in/charlesmoulliard
> Skype: cmoulliard
>
>
> On Thu, Jun 28, 2012 at 7:21 PM, Mark Struberg [via Apache DeltaSpike
> Incubator Discussions] <[hidden email]> wrote:
>
>>  Hi!
>>
>>  Good topic!
>>
>>  finally we have our CMS!
>>
>>  It's really ugly as I don't have an eye for good web pages, but at
> least
>>  it exists ;)
>>  But ignore the layout for now. We can easily change this later.
>>
>>
>>  http://incubator.apache.org/deltaspike
>>
>>  You can find more infos at [1].
>>
>>  If you like to edit a page then simply add the following to your
>>  bookmarks:
>>
>>  javascript:void(location.href='
>>  https://cms.apache.org/redirect?uri='+escape(location.href))
>>
>>  add this manually as bookmark. Then visit any CMS page and click on the
>>  bookmark. You will get an auth window where you need to login via your
>>  apacheId and pwd.
>>  Saving the change will do a svn commit in the background and publish the
>>  changes.
>>
>>  LieGrue,
>>  strub
>>
>>  [1] http://wiki.apache.org/general/ApacheCms2010
>>
>>
>>
>>  ----- Original Message -----
>>
>>  > From: Jason Porter <[hidden
> email]<http://user/SendEmail.jtp?type=node&node=4652901&i=0>>
>>
>>  > To: [hidden
> email]<http://user/SendEmail.jtp?type=node&node=4652901&i=1>
>>  > Cc:
>>  > Sent: Thursday, June 28, 2012 7:09 PM
>>  > Subject: Re: [suggestion] - Documentation
>>  >
>>  > Maybe we need to finish the documentation discussion and just be done
>>  with
>>  > it. I really like asciidoc there's lots of tools for it and it
> renders
>>  > docbook which we can take and do whatever with. The only problem right
>>  now
>>  > is that there's no maven plugin for it and jython is really slow
> :( The
>>  > GitHub guys are doing a ruby port which would work really well with
>>  jruby,
>>  > but I don't think they've released it yet.
>>  >
>>  > For now the temporary wiki I think works decently.
>>  >
>>  > On Thu, Jun 14, 2012 at 4:43 AM, Gerhard Petracek <
>>  > [hidden email]
> <http://user/SendEmail.jtp?type=node&node=4652901&i=2>>
>>  wrote:
>>  >
>>  >>  hi charles,
>>  >>
>>  >>  thx for the feedback!
>>  >>
>>  >>  @documentation:
>>  >>  this part of the wiki is called "Temporary
> Documentation" because
>>  > we don't
>>  >>  plan to keep the documentation in the wiki.
>>  >>  -> for now we just collect information there (in a very simple
> style)
>>  to
>>  >>  avoid a lack of information.
>>  >>
>>  >>  regards,
>>  >>  gerhard
>>  >>
>>  >>
>>  >>
>>  >>  2012/6/14 Charles Moulliard <[hidden
> email]<http://user/SendEmail.jtp?type=node&node=4652901&i=3>>
>>
>>  >>
>>  >>  > Hi,
>>  >>  >
>>  >>  > I would like to suggest that we split the page user
> documentation in
>>  >>  > several
>>  >>  > chapters - pages to provide more visibility on the project
>>  DeltaSpike
>>  >>  >
>>  >>  > - Introduction - goals,
>>  >>  > - Getting started,
>>  >>  > - Modules
>>  >>  >    - jpa,
>>  >>  >    - security,
>>  >>  > - Developers,
>>  >>  > - Community
>>  >>  >
>>  >>  > What do you think about that ?
>>  >>  >
>>  >>  > Remark :
>>  >>  > - Also, we should allow people to have access to this web
> page -->
>>  >>  > http://incubator.apache.org/deltaspike/ which is not the
> case today
>>  >>  except
>>  >>  > the wiki page
>>  >>  > - To build the documentation, we could use scalate
> (templating
>>  engine
>>  > -
>>  >>  > http://scalate.fusesource.org/)) which is used by Apache
> Karaf,
>>  Apache
>>  >>  > Camel
>>  >>  > and Apache ServiceMix to generate static web sites but also
> PDF doc.
>>  >>  > - GitHub repo has not link to the project
>>  >>  > (https://github.com/apache/incubator-deltaspike)
>>  >>  >
>>  >>  >
>>  >>  > Regards,
>>  >>  >
>>  >>  > Charles
>>  >>  >
>>  >>  > --
>>  >>  > View this message in context:
>>  >>  >
>>  >>
>>  >
>>
> http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767.html
>>  >>  > Sent from the Apache DeltaSpike Incubator Discussions
> mailing list
>>  >>  archive
>>  >>  > at Nabble.com.
>>  >>  >
>>  >>
>>  >
>>  >
>>  >
>>  > --
>>  > 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
>>  >
>>
>>
>>  ------------------------------
>>   If you reply to this email, your message will be added to the discussion
>>  below:
>>
>>
> http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767p4652901.html
>>   To unsubscribe from [suggestion] - Documentation, click
> here<
>>  .
>>
> NAML<
http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/template/NamlServlet.jtp?macro=macro_viewer&id=instant_html%21nabble%3Aemail.naml&base=nabble.naml.namespaces.BasicNamespace-nabble.view.web.template.NabbleNamespace-nabble.view.web.template.NodeNamespace&breadcrumbs=notify_subscribers%21nabble%3Aemail.naml-instant_emails%21nabble%3Aemail.naml-send_instant_email%21nabble%3Aemail.naml>
>>
>
>
> --
> View this message in context:
> http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767p4652904.html
> Sent from the Apache DeltaSpike Incubator Discussions mailing list archive at
> Nabble.com.
>
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Charles Moulliard
I'm not still a committer. So let's go for the patches ....

On Fri, Jun 29, 2012 at 12:37 PM, Mark Struberg [via Apache DeltaSpike Incubator Discussions] <[hidden email]> wrote:
Hi Charles!

Ok, I should have been more clear :)

That's because you are not yet a committer on DeltaSpike, right?

This all works via SVN rights, but the CMS documentation also has a section about providing a kind of svn diff and ship it as patch afterwards. This is done to get rid of the spamming problem we have right now in confluence.

Btw, if you use DeltaSpike and ship some patches then ... you know the game ;)

LieGrue,
strub



----- Original Message -----

> From: Charles Moulliard <[hidden email]>
> To: [hidden email]
> Cc:
> Sent: Friday, June 29, 2012 9:10 AM
> Subject: Re: [suggestion] - Documentation
>
> Hi Mark,

>
> I have tried to create a directory but I cannot commit in the project :
> Error
>
> The operation is forbidden by the server: Commit failed (details
> follow):: Changing file
> '/usr/local/cms/wc/deltaspike/cmoulliard-OlVI4e/trunk/content/deltaspike/modules'
> is forbidden by the server: Access to
> '/repos/asf/!svn/txr/1355248-tlb2/incubator/deltaspike/site/trunk/content/deltaspike/modules'
> forbidden at /usr/local/cms/webgui/lib/ASF/CMS/WC/Commit.pm line 64
>
> Regards,
>
> Charles Moulliard
>
> Apache Committer
>
> Blog : http://cmoulliard.blogspot.com
> Twitter : http://twitter.com/cmoulliard
> Linkedin : http://www.linkedin.com/in/charlesmoulliard
> Skype: cmoulliard
>
>
> On Thu, Jun 28, 2012 at 7:21 PM, Mark Struberg [via Apache DeltaSpike
> Incubator Discussions] <[hidden email]> wrote:

>
>>  Hi!
>>
>>  Good topic!
>>
>>  finally we have our CMS!
>>
>>  It's really ugly as I don't have an eye for good web pages, but at
> least
>>  it exists ;)
>>  But ignore the layout for now. We can easily change this later.
>>
>>
>>  http://incubator.apache.org/deltaspike
>>
>>  You can find more infos at [1].
>>
>>  If you like to edit a page then simply add the following to your
>>  bookmarks:
>>
>>  javascript:void(location.href='
>>  https://cms.apache.org/redirect?uri='+escape(location.href))
>>
>>  add this manually as bookmark. Then visit any CMS page and click on the
>>  bookmark. You will get an auth window where you need to login via your
>>  apacheId and pwd.
>>  Saving the change will do a svn commit in the background and publish the
>>  changes.
>>
>>  LieGrue,
>>  strub
>>
>>  [1] http://wiki.apache.org/general/ApacheCms2010
>>
>>
>>
>>  ----- Original Message -----
>>
>>  > From: Jason Porter <[hidden
> email]<http://user/SendEmail.jtp?type=node&node=4652901&i=0>>
>>
>>  > To: [hidden
> email]<http://user/SendEmail.jtp?type=node&node=4652901&i=1>
>>  > Cc:

>>  > Sent: Thursday, June 28, 2012 7:09 PM
>>  > Subject: Re: [suggestion] - Documentation
>>  >
>>  > Maybe we need to finish the documentation discussion and just be done
>>  with
>>  > it. I really like asciidoc there's lots of tools for it and it
> renders
>>  > docbook which we can take and do whatever with. The only problem right
>>  now
>>  > is that there's no maven plugin for it and jython is really slow
> :( The
>>  > GitHub guys are doing a ruby port which would work really well with
>>  jruby,
>>  > but I don't think they've released it yet.
>>  >
>>  > For now the temporary wiki I think works decently.
>>  >
>>  > On Thu, Jun 14, 2012 at 4:43 AM, Gerhard Petracek <
>>  > [hidden email]
> <http://user/SendEmail.jtp?type=node&node=4652901&i=2>>
>>  wrote:

>>  >
>>  >>  hi charles,
>>  >>
>>  >>  thx for the feedback!
>>  >>
>>  >>  @documentation:
>>  >>  this part of the wiki is called "Temporary
> Documentation" because
>>  > we don't
>>  >>  plan to keep the documentation in the wiki.
>>  >>  -> for now we just collect information there (in a very simple
> style)
>>  to
>>  >>  avoid a lack of information.
>>  >>
>>  >>  regards,
>>  >>  gerhard
>>  >>
>>  >>
>>  >>
>>  >>  2012/6/14 Charles Moulliard <[hidden
> email]<http://user/SendEmail.jtp?type=node&node=4652901&i=3>>
>>

>>  >>
>>  >>  > Hi,
>>  >>  >
>>  >>  > I would like to suggest that we split the page user
> documentation in
>>  >>  > several
>>  >>  > chapters - pages to provide more visibility on the project
>>  DeltaSpike
>>  >>  >
>>  >>  > - Introduction - goals,
>>  >>  > - Getting started,
>>  >>  > - Modules
>>  >>  >    - jpa,
>>  >>  >    - security,
>>  >>  > - Developers,
>>  >>  > - Community
>>  >>  >
>>  >>  > What do you think about that ?
>>  >>  >
>>  >>  > Remark :
>>  >>  > - Also, we should allow people to have access to this web
> page -->
>>  >>  > http://incubator.apache.org/deltaspike/ which is not the
> case today
>>  >>  except
>>  >>  > the wiki page
>>  >>  > - To build the documentation, we could use scalate
> (templating
>>  engine
>>  > -
>>  >>  > http://scalate.fusesource.org/)) which is used by Apache
> Karaf,
>>  Apache
>>  >>  > Camel
>>  >>  > and Apache ServiceMix to generate static web sites but also
> PDF doc.
>>  >>  > - GitHub repo has not link to the project
>>  >>  > (https://github.com/apache/incubator-deltaspike)
>>  >>  >
>>  >>  >
>>  >>  > Regards,
>>  >>  >
>>  >>  > Charles
>>  >>  >
>>  >>  > --
>>  >>  > View this message in context:
>>  >>  >
>>  >>
>>  >
>>
> http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767.html
>>  >>  > Sent from the Apache DeltaSpike Incubator Discussions

> mailing list
>>  >>  archive
>>  >>  > at Nabble.com.
>>  >>  >
>>  >>
>>  >
>>  >
>>  >
>>  > --
>>  > 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
>>  >
>>
>>
>>  ------------------------------
>>   If you reply to this email, your message will be added to the discussion
>>  below:
>>
>>
> http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767p4652901.html
>>   To unsubscribe from [suggestion] - Documentation, click
> here<

>>  .
>>
> NAML<
http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/template/NamlServlet.jtp?macro=macro_viewer&id=instant_html%21nabble%3Aemail.naml&base=nabble.naml.namespaces.BasicNamespace-nabble.view.web.template.NabbleNamespace-nabble.view.web.template.NodeNamespace&breadcrumbs=notify_subscribers%21nabble%3Aemail.naml-instant_emails%21nabble%3Aemail.naml-send_instant_email%21nabble%3Aemail.naml>
>>
>
>
> --
> View this message in context:
> http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767p4652904.html

> Sent from the Apache DeltaSpike Incubator Discussions mailing list archive at
> Nabble.com.
>



If you reply to this email, your message will be added to the discussion below:
http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767p4652906.html
To unsubscribe from [suggestion] - Documentation, click here.
NAML

Apache Committer / Sr. Pr. Consultant at FuseSource.com
Email: [hidden email]
Twitter : @cmoulliard, @fusenews
Blog : http://cmoulliard.blogspot.com
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Shane Bryzak-2
In reply to this post by Mark Struberg
I'd like to re-open the discussion on documentation format, as there
seems to have been a decision slip through the cracks on this that many
of us missed.  My greatest concern is that the selected tool needs to
meet the requirements stated in DELTASPIKE-13 [1].  Does the choice of
Apache CMS for hosting documentation meet the following requirements?

1) Making available the documentation for previously released versions
of DeltaSpike.

2) Making available the documentation in offline formats, such as HTML
or PDF available for download.


[1] https://issues.apache.org/jira/browse/DELTASPIKE-13

- Shane


On 29/06/12 03:21, Mark Struberg wrote:

> Hi!
>
> Good topic!
>
> finally we have our CMS!
>
> It's really ugly as I don't have an eye for good web pages, but at least it exists ;)
> But ignore the layout for now. We can easily change this later.
>
>
> http://incubator.apache.org/deltaspike
>
> You can find more infos at [1].
>
> If you like to edit a page then simply add the following to your bookmarks:
>
> javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))
>
> add this manually as bookmark. Then visit any CMS page and click on the bookmark. You will get an auth window where you need to login via your apacheId and pwd.
> Saving the change will do a svn commit in the background and publish the changes.
>
> LieGrue,
> strub
>
> [1] http://wiki.apache.org/general/ApacheCms2010
>
>
>
> ----- Original Message -----
>> From: Jason Porter <[hidden email]>
>> To: [hidden email]
>> Cc:
>> Sent: Thursday, June 28, 2012 7:09 PM
>> Subject: Re: [suggestion] - Documentation
>>
>> Maybe we need to finish the documentation discussion and just be done with
>> it. I really like asciidoc there's lots of tools for it and it renders
>> docbook which we can take and do whatever with. The only problem right now
>> is that there's no maven plugin for it and jython is really slow :( The
>> GitHub guys are doing a ruby port which would work really well with jruby,
>> but I don't think they've released it yet.
>>
>> For now the temporary wiki I think works decently.
>>
>> On Thu, Jun 14, 2012 at 4:43 AM, Gerhard Petracek <
>> [hidden email]> wrote:
>>
>>>   hi charles,
>>>
>>>   thx for the feedback!
>>>
>>>   @documentation:
>>>   this part of the wiki is called "Temporary Documentation" because
>> we don't
>>>   plan to keep the documentation in the wiki.
>>>   -> for now we just collect information there (in a very simple style) to
>>>   avoid a lack of information.
>>>
>>>   regards,
>>>   gerhard
>>>
>>>
>>>
>>>   2012/6/14 Charles Moulliard <[hidden email]>
>>>
>>>   > Hi,
>>>   >
>>>   > I would like to suggest that we split the page user documentation in
>>>   > several
>>>   > chapters - pages to provide more visibility on the project DeltaSpike
>>>   >
>>>   > - Introduction - goals,
>>>   > - Getting started,
>>>   > - Modules
>>>   >    - jpa,
>>>   >    - security,
>>>   > - Developers,
>>>   > - Community
>>>   >
>>>   > What do you think about that ?
>>>   >
>>>   > Remark :
>>>   > - Also, we should allow people to have access to this web page -->
>>>   > http://incubator.apache.org/deltaspike/ which is not the case today
>>>   except
>>>   > the wiki page
>>>   > - To build the documentation, we could use scalate (templating engine
>> -
>>>   > http://scalate.fusesource.org/)) which is used by Apache Karaf, Apache
>>>   > Camel
>>>   > and Apache ServiceMix to generate static web sites but also PDF doc.
>>>   > - GitHub repo has not link to the project
>>>   > (https://github.com/apache/incubator-deltaspike)
>>>   >
>>>   >
>>>   > Regards,
>>>   >
>>>   > Charles
>>>   >
>>>   > --
>>>   > View this message in context:
>>>   >
>>>
>> http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/suggestion-Documentation-tp4652767.html
>>>   > Sent from the Apache DeltaSpike Incubator Discussions mailing list
>>>   archive
>>>   > at Nabble.com.
>>>   >
>>>
>>
>>
>> --
>> 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
>>


Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

David Blevins
The answer to both these questions really that the CMS creates "websites", some details on that below

I'll note that the CMS is svn based -- maybe undesirable given the use of git.

On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:

> Does the choice of Apache CMS for hosting documentation meet the following requirements?
>
> 1) Making available the documentation for previously released versions of DeltaSpike.

If by "make available" the intention is browsable on the website, then sure there are ways to handle that.

> 2) Making available the documentation in offline formats, such as HTML or PDF available for download.

Certainly you can use the same source to generate non-website looking HTML.  Same goes for PDF.

You wouldn't be using the CMS to do this, but the CMS doesn't prevent it.  It'd be something we setup ourselves and could be done via a CI server or something done at release time.

Basically the CMS is a system that is for generate website html using the following layout:

 - content/<source-files-and-directories>
 - lib/<site-generating-perl-functions>
 - templates/<whatever-you-need-for-templates>

When something in 'content/' is updated, it will run it through lib/ (which leverages templates/) and save the resulting html to disk and take care of synching that html file from staging to production.

When something in 'lib/' or 'templates/' is updated, it pretends as if everything in 'content/' has changed and performs the above step on every source file.

You can organize the 'content/' dir however you want.  That could mean:

 - content/v0.1/
 - content/v0.2/
 - content/current/

Where 'current' gets versioned on release.  Or anything at all.  Maybe just:

 - content/<wild-wild-west>


So the short answer is there isn't anything there to prevent or help the two points.

In terms of generating outside the CMS which is what would be needed for say, turning many files into one file such as a zip of html or a PDF, it's up to us.  There are projects that do it via buildbot.  Buildbot is not so much a CI tool as it is "cron with a webUI" and also happens to have the ability to be trigger by commits.

Really, you can get anything done with buildbot without much in the way of restrictions.  It's a mediocre CI system and an amazing cron replacement.


-David

Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Mark Struberg
Administrator
David, the CMS is already set up and running (in SVN [1]). We just need a bit more stylish css. 

And you can perfectly create pdf docs out of markdown.

Of course we can also use alternative formats. But to me this is like a colour preference - markdown is supported out of the box and provides all needed options.

Shane, I don't think I bypassed anyone. We discussed this since 6 months and noone started working on it. Thus I finally dropped a mail and then implemented it. I also got no stop mail back then.
Honestly I really don't care which format we use, IF someone else is doing the work and others can easily add documentation.


LieGrue,
strub



[1] http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/



----- Original Message -----

> From: David Blevins <[hidden email]>
> To: [hidden email]
> Cc: Mark Struberg <[hidden email]>
> Sent: Wednesday, July 25, 2012 2:37 AM
> Subject: Re: [suggestion] - Documentation
>
>T he answer to both these questions really that the CMS creates
> "websites", some details on that below
>
> I'll note that the CMS is svn based -- maybe undesirable given the use of
> git.
>
> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
>
>>  Does the choice of Apache CMS for hosting documentation meet the following
> requirements?
>>
>>  1) Making available the documentation for previously released versions of
> DeltaSpike.
>
> If by "make available" the intention is browsable on the website, then
> sure there are ways to handle that.
>
>>  2) Making available the documentation in offline formats, such as HTML or
> PDF available for download.
>
> Certainly you can use the same source to generate non-website looking HTML. 
> Same goes for PDF.
>
> You wouldn't be using the CMS to do this, but the CMS doesn't prevent
> it.  It'd be something we setup ourselves and could be done via a CI server
> or something done at release time.
>
> Basically the CMS is a system that is for generate website html using the
> following layout:
>
> - content/<source-files-and-directories>
> - lib/<site-generating-perl-functions>
> - templates/<whatever-you-need-for-templates>
>
> When something in 'content/' is updated, it will run it through lib/
> (which leverages templates/) and save the resulting html to disk and take care
> of synching that html file from staging to production.
>
> When something in 'lib/' or 'templates/' is updated, it pretends
> as if everything in 'content/' has changed and performs the above step
> on every source file.
>
> You can organize the 'content/' dir however you want.  That could mean:
>
> - content/v0.1/
> - content/v0.2/
> - content/current/
>
> Where 'current' gets versioned on release.  Or anything at all.  Maybe
> just:
>
> - content/<wild-wild-west>
>
>
> So the short answer is there isn't anything there to prevent or help the two
> points.
>
> In terms of generating outside the CMS which is what would be needed for say,
> turning many files into one file such as a zip of html or a PDF, it's up to
> us.  There are projects that do it via buildbot.  Buildbot is not so much a CI
> tool as it is "cron with a webUI" and also happens to have the ability
> to be trigger by commits.
>
> Really, you can get anything done with buildbot without much in the way of
> restrictions.  It's a mediocre CI system and an amazing cron replacement.
>
>
> -David
>
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Romain Manni-Bucau
Hi,

CMS should be fine for this requirements then it needs some work but offers
all the needed hooks.

At least for consistency with other apache projects (a lot migrated to the
cms) i think it is good to use it.

I know this topic will be frustrating for half of the people engaged here
since red hat and apahe guys doesn't currently use the same tools but i
think/hope nobody will feel frustrated once the doc will be in place.

Side note: on openejb website we have an anonymous edit function (not sure
it is cms or openejb hook but in all case can be used in DS for sure) which
is pretty interesting for OS projects IMO.

- Romain


2012/7/25 Mark Struberg <[hidden email]>

> David, the CMS is already set up and running (in SVN [1]). We just need a
> bit more stylish css.
>
> And you can perfectly create pdf docs out of markdown.
>
> Of course we can also use alternative formats. But to me this is like a
> colour preference - markdown is supported out of the box and provides all
> needed options.
>
> Shane, I don't think I bypassed anyone. We discussed this since 6 months
> and noone started working on it. Thus I finally dropped a mail and then
> implemented it. I also got no stop mail back then.
> Honestly I really don't care which format we use, IF someone else is doing
> the work and others can easily add documentation.
>
>
> LieGrue,
> strub
>
>
>
> [1] http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/
>
>
>
> ----- Original Message -----
> > From: David Blevins <[hidden email]>
> > To: [hidden email]
> > Cc: Mark Struberg <[hidden email]>
> > Sent: Wednesday, July 25, 2012 2:37 AM
> > Subject: Re: [suggestion] - Documentation
> >
> >T he answer to both these questions really that the CMS creates
> > "websites", some details on that below
> >
> > I'll note that the CMS is svn based -- maybe undesirable given the use of
> > git.
> >
> > On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
> >
> >>  Does the choice of Apache CMS for hosting documentation meet the
> following
> > requirements?
> >>
> >>  1) Making available the documentation for previously released versions
> of
> > DeltaSpike.
> >
> > If by "make available" the intention is browsable on the website, then
> > sure there are ways to handle that.
> >
> >>  2) Making available the documentation in offline formats, such as HTML
> or
> > PDF available for download.
> >
> > Certainly you can use the same source to generate non-website looking
> HTML.
> > Same goes for PDF.
> >
> > You wouldn't be using the CMS to do this, but the CMS doesn't prevent
> > it.  It'd be something we setup ourselves and could be done via a CI
> server
> > or something done at release time.
> >
> > Basically the CMS is a system that is for generate website html using the
> > following layout:
> >
> > - content/<source-files-and-directories>
> > - lib/<site-generating-perl-functions>
> > - templates/<whatever-you-need-for-templates>
> >
> > When something in 'content/' is updated, it will run it through lib/
> > (which leverages templates/) and save the resulting html to disk and
> take care
> > of synching that html file from staging to production.
> >
> > When something in 'lib/' or 'templates/' is updated, it pretends
> > as if everything in 'content/' has changed and performs the above step
> > on every source file.
> >
> > You can organize the 'content/' dir however you want.  That could mean:
> >
> > - content/v0.1/
> > - content/v0.2/
> > - content/current/
> >
> > Where 'current' gets versioned on release.  Or anything at all.  Maybe
> > just:
> >
> > - content/<wild-wild-west>
> >
> >
> > So the short answer is there isn't anything there to prevent or help the
> two
> > points.
> >
> > In terms of generating outside the CMS which is what would be needed for
> say,
> > turning many files into one file such as a zip of html or a PDF, it's up
> to
> > us.  There are projects that do it via buildbot.  Buildbot is not so
> much a CI
> > tool as it is "cron with a webUI" and also happens to have the ability
> > to be trigger by commits.
> >
> > Really, you can get anything done with buildbot without much in the way
> of
> > restrictions.  It's a mediocre CI system and an amazing cron replacement.
> >
> >
> > -David
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Mark Struberg
Administrator
The problem with anonymous edits is that it's really a spam honey pot :/

We tried this for our WiKis but the effort needed to maintain the black-list and to remove spam is not low.

LieGrue,
strub




>________________________________
> From: Romain Manni-Bucau <[hidden email]>
>To: [hidden email]; Mark Struberg <[hidden email]>
>Sent: Wednesday, July 25, 2012 9:05 AM
>Subject: Re: [suggestion] - Documentation
>
>
>Hi,
>
>
>CMS should be fine for this requirements then it needs some work but offers all the needed hooks.
>
>
>At least for consistency with other apache projects (a lot migrated to the cms) i think it is good to use it.
>
>
>I know this topic will be frustrating for half of the people engaged here since red hat and apahe guys doesn't currently use the same tools but i think/hope nobody will feel frustrated once the doc will be in place.
>
>
>Side note: on openejb website we have an anonymous edit function (not sure it is cms or openejb hook but in all case can be used in DS for sure) which is pretty interesting for OS projects IMO.
>
>- Romain
>
>
>
>2012/7/25 Mark Struberg <[hidden email]>
>
>David, the CMS is already set up and running (in SVN [1]). We just need a bit more stylish css. 
>>
>>And you can perfectly create pdf docs out of markdown.
>>
>>Of course we can also use alternative formats. But to me this is like a colour preference - markdown is supported out of the box and provides all needed options.
>>
>>Shane, I don't think I bypassed anyone. We discussed this since 6 months and noone started working on it. Thus I finally dropped a mail and then implemented it. I also got no stop mail back then.
>>Honestly I really don't care which format we use, IF someone else is doing the work and others can easily add documentation.
>>
>>
>>LieGrue,
>>strub
>>
>>
>>
>>[1] http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/
>>
>>
>>
>>
>>----- Original Message -----
>>> From: David Blevins <[hidden email]>
>>> To: [hidden email]
>>> Cc: Mark Struberg <[hidden email]>
>>> Sent: Wednesday, July 25, 2012 2:37 AM
>>> Subject: Re: [suggestion] - Documentation
>>>
>>>T he answer to both these questions really that the CMS creates
>>
>>> "websites", some details on that below
>>>
>>> I'll note that the CMS is svn based -- maybe undesirable given the use of
>>> git.
>>>
>>> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
>>>
>>>>  Does the choice of Apache CMS for hosting documentation meet the following
>>> requirements?
>>>>
>>>>  1) Making available the documentation for previously released versions of
>>> DeltaSpike.
>>>
>>> If by "make available" the intention is browsable on the website, then
>>> sure there are ways to handle that.
>>>
>>>>  2) Making available the documentation in offline formats, such as HTML or
>>> PDF available for download.
>>>
>>> Certainly you can use the same source to generate non-website looking HTML. 
>>> Same goes for PDF.
>>>
>>> You wouldn't be using the CMS to do this, but the CMS doesn't prevent
>>> it.  It'd be something we setup ourselves and could be done via a CI server
>>> or something done at release time.
>>>
>>> Basically the CMS is a system that is for generate website html using the
>>> following layout:
>>>
>>> - content/<source-files-and-directories>
>>> - lib/<site-generating-perl-functions>
>>> - templates/<whatever-you-need-for-templates>
>>>
>>> When something in 'content/' is updated, it will run it through lib/
>>> (which leverages templates/) and save the resulting html to disk and take care
>>> of synching that html file from staging to production.
>>>
>>> When something in 'lib/' or 'templates/' is updated, it pretends
>>> as if everything in 'content/' has changed and performs the above step
>>> on every source file.
>>>
>>> You can organize the 'content/' dir however you want.  That could mean:
>>>
>>> - content/v0.1/
>>> - content/v0.2/
>>> - content/current/
>>>
>>> Where 'current' gets versioned on release.  Or anything at all.  Maybe
>>> just:
>>>
>>> - content/<wild-wild-west>
>>>
>>>
>>> So the short answer is there isn't anything there to prevent or help the two
>>> points.
>>>
>>> In terms of generating outside the CMS which is what would be needed for say,
>>> turning many files into one file such as a zip of html or a PDF, it's up to
>>> us.  There are projects that do it via buildbot.  Buildbot is not so much a CI
>>> tool as it is "cron with a webUI" and also happens to have the ability
>>> to be trigger by commits.
>>>
>>> Really, you can get anything done with buildbot without much in the way of
>>> restrictions.  It's a mediocre CI system and an amazing cron replacement.
>>>
>>>
>>> -David
>>>
>>
>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Shane Bryzak-2
In reply to this post by Mark Struberg
Yes, I saw the e-mail with subject "CMS area in SVN" on 2 June but it
didn't occur to me that this was for documentation (I thought it was
just for the web site).  Also, Jason attempted twice (both in the
mailing list and in DELTASPIKE-13) to start a discussion on
documentation format and no-one responded.

I honestly don't mind which documentation format we use, however before
we go any further I want to ensure that the tools that have been chosen
support the requirements that I listed earlier. David's description of
the CMS is helpful, but I just want to identify that we still have
missing gaps in terms of versioned-per-release documentation and
downloadable documentation in alternative formats.  From the sound of
it, these things both appear possible if we are using Apache CMS,
however it seems we need to do some extra work with the documentation
directory structure for the versioning side of things, and with the
release process for tagging/packaging the documentation.  If others are
in agreement, we should probably create JIRA issues to track these tasks.

Shane

On 25/07/12 16:17, Mark Struberg wrote:

> David, the CMS is already set up and running (in SVN [1]). We just need a bit more stylish css.
>
> And you can perfectly create pdf docs out of markdown.
>
> Of course we can also use alternative formats. But to me this is like a colour preference - markdown is supported out of the box and provides all needed options.
>
> Shane, I don't think I bypassed anyone. We discussed this since 6 months and noone started working on it. Thus I finally dropped a mail and then implemented it. I also got no stop mail back then.
> Honestly I really don't care which format we use, IF someone else is doing the work and others can easily add documentation.
>
>
> LieGrue,
> strub
>
>
>
> [1] http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/
>
>
>
> ----- Original Message -----
>> From: David Blevins <[hidden email]>
>> To: [hidden email]
>> Cc: Mark Struberg <[hidden email]>
>> Sent: Wednesday, July 25, 2012 2:37 AM
>> Subject: Re: [suggestion] - Documentation
>>
>> T he answer to both these questions really that the CMS creates
>> "websites", some details on that below
>>
>> I'll note that the CMS is svn based -- maybe undesirable given the use of
>> git.
>>
>> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
>>
>>>   Does the choice of Apache CMS for hosting documentation meet the following
>> requirements?
>>>   1) Making available the documentation for previously released versions of
>> DeltaSpike.
>>
>> If by "make available" the intention is browsable on the website, then
>> sure there are ways to handle that.
>>
>>>   2) Making available the documentation in offline formats, such as HTML or
>> PDF available for download.
>>
>> Certainly you can use the same source to generate non-website looking HTML.
>> Same goes for PDF.
>>
>> You wouldn't be using the CMS to do this, but the CMS doesn't prevent
>> it.  It'd be something we setup ourselves and could be done via a CI server
>> or something done at release time.
>>
>> Basically the CMS is a system that is for generate website html using the
>> following layout:
>>
>> - content/<source-files-and-directories>
>> - lib/<site-generating-perl-functions>
>> - templates/<whatever-you-need-for-templates>
>>
>> When something in 'content/' is updated, it will run it through lib/
>> (which leverages templates/) and save the resulting html to disk and take care
>> of synching that html file from staging to production.
>>
>> When something in 'lib/' or 'templates/' is updated, it pretends
>> as if everything in 'content/' has changed and performs the above step
>> on every source file.
>>
>> You can organize the 'content/' dir however you want.  That could mean:
>>
>> - content/v0.1/
>> - content/v0.2/
>> - content/current/
>>
>> Where 'current' gets versioned on release.  Or anything at all.  Maybe
>> just:
>>
>> - content/<wild-wild-west>
>>
>>
>> So the short answer is there isn't anything there to prevent or help the two
>> points.
>>
>> In terms of generating outside the CMS which is what would be needed for say,
>> turning many files into one file such as a zip of html or a PDF, it's up to
>> us.  There are projects that do it via buildbot.  Buildbot is not so much a CI
>> tool as it is "cron with a webUI" and also happens to have the ability
>> to be trigger by commits.
>>
>> Really, you can get anything done with buildbot without much in the way of
>> restrictions.  It's a mediocre CI system and an amazing cron replacement.
>>
>>
>> -David
>>


Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Romain Manni-Bucau
Just by curiosity, what do you expect as version management?

Kind of tool where you say "ok doc for vX is done copy it in another place"?

- Romain


2012/7/25 Shane Bryzak <[hidden email]>

> Yes, I saw the e-mail with subject "CMS area in SVN" on 2 June but it
> didn't occur to me that this was for documentation (I thought it was just
> for the web site).  Also, Jason attempted twice (both in the mailing list
> and in DELTASPIKE-13) to start a discussion on documentation format and
> no-one responded.
>
> I honestly don't mind which documentation format we use, however before we
> go any further I want to ensure that the tools that have been chosen
> support the requirements that I listed earlier. David's description of the
> CMS is helpful, but I just want to identify that we still have missing gaps
> in terms of versioned-per-release documentation and downloadable
> documentation in alternative formats.  From the sound of it, these things
> both appear possible if we are using Apache CMS, however it seems we need
> to do some extra work with the documentation directory structure for the
> versioning side of things, and with the release process for
> tagging/packaging the documentation.  If others are in agreement, we should
> probably create JIRA issues to track these tasks.
>
> Shane
>
>
> On 25/07/12 16:17, Mark Struberg wrote:
>
>> David, the CMS is already set up and running (in SVN [1]). We just need a
>> bit more stylish css.
>>
>> And you can perfectly create pdf docs out of markdown.
>>
>> Of course we can also use alternative formats. But to me this is like a
>> colour preference - markdown is supported out of the box and provides all
>> needed options.
>>
>> Shane, I don't think I bypassed anyone. We discussed this since 6 months
>> and noone started working on it. Thus I finally dropped a mail and then
>> implemented it. I also got no stop mail back then.
>> Honestly I really don't care which format we use, IF someone else is
>> doing the work and others can easily add documentation.
>>
>>
>> LieGrue,
>> strub
>>
>>
>>
>> [1] http://svn.apache.org/repos/**asf/incubator/deltaspike/site/**trunk/<http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/>
>>
>>
>>
>> ----- Original Message -----
>>
>>> From: David Blevins <[hidden email]>
>>> To: deltaspike-dev@incubator.**apache.org<[hidden email]>
>>> Cc: Mark Struberg <[hidden email]>
>>> Sent: Wednesday, July 25, 2012 2:37 AM
>>> Subject: Re: [suggestion] - Documentation
>>>
>>> T he answer to both these questions really that the CMS creates
>>> "websites", some details on that below
>>>
>>> I'll note that the CMS is svn based -- maybe undesirable given the use of
>>> git.
>>>
>>> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
>>>
>>>    Does the choice of Apache CMS for hosting documentation meet the
>>>> following
>>>>
>>> requirements?
>>>
>>>>   1) Making available the documentation for previously released
>>>> versions of
>>>>
>>> DeltaSpike.
>>>
>>> If by "make available" the intention is browsable on the website, then
>>> sure there are ways to handle that.
>>>
>>>    2) Making available the documentation in offline formats, such as
>>>> HTML or
>>>>
>>> PDF available for download.
>>>
>>> Certainly you can use the same source to generate non-website looking
>>> HTML.
>>> Same goes for PDF.
>>>
>>> You wouldn't be using the CMS to do this, but the CMS doesn't prevent
>>> it.  It'd be something we setup ourselves and could be done via a CI
>>> server
>>> or something done at release time.
>>>
>>> Basically the CMS is a system that is for generate website html using the
>>> following layout:
>>>
>>> - content/<source-files-and-**directories>
>>> - lib/<site-generating-perl-**functions>
>>> - templates/<whatever-you-need-**for-templates>
>>>
>>> When something in 'content/' is updated, it will run it through lib/
>>> (which leverages templates/) and save the resulting html to disk and
>>> take care
>>> of synching that html file from staging to production.
>>>
>>> When something in 'lib/' or 'templates/' is updated, it pretends
>>> as if everything in 'content/' has changed and performs the above step
>>> on every source file.
>>>
>>> You can organize the 'content/' dir however you want.  That could mean:
>>>
>>> - content/v0.1/
>>> - content/v0.2/
>>> - content/current/
>>>
>>> Where 'current' gets versioned on release.  Or anything at all.  Maybe
>>> just:
>>>
>>> - content/<wild-wild-west>
>>>
>>>
>>> So the short answer is there isn't anything there to prevent or help the
>>> two
>>> points.
>>>
>>> In terms of generating outside the CMS which is what would be needed for
>>> say,
>>> turning many files into one file such as a zip of html or a PDF, it's up
>>> to
>>> us.  There are projects that do it via buildbot.  Buildbot is not so
>>> much a CI
>>> tool as it is "cron with a webUI" and also happens to have the ability
>>> to be trigger by commits.
>>>
>>> Really, you can get anything done with buildbot without much in the way
>>> of
>>> restrictions.  It's a mediocre CI system and an amazing cron replacement.
>>>
>>>
>>> -David
>>>
>>>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Shane Bryzak-2
I guess something like that would work, although it would be nice if in
addition to that we packaged the documentation with the release itself.  
The requirement is simple, we need to make the documentation for
previous releases available in an easy to access location - for example
take a look at how Maven does it [1].  Maven also uses a static URL to
refer to the current version of the docs [2] which I think is important
also. However we achieve that I don't mind, so whether we copy it to
another place, or tag it as part of the release process or whatever.

[1] http://maven.apache.org/ref/
[2] http://maven.apache.org/ref/current/

Shane

On 25/07/12 18:20, Romain Manni-Bucau wrote:

> Just by curiosity, what do you expect as version management?
>
> Kind of tool where you say "ok doc for vX is done copy it in another place"?
>
> - Romain
>
>
> 2012/7/25 Shane Bryzak <[hidden email]>
>
>> Yes, I saw the e-mail with subject "CMS area in SVN" on 2 June but it
>> didn't occur to me that this was for documentation (I thought it was just
>> for the web site).  Also, Jason attempted twice (both in the mailing list
>> and in DELTASPIKE-13) to start a discussion on documentation format and
>> no-one responded.
>>
>> I honestly don't mind which documentation format we use, however before we
>> go any further I want to ensure that the tools that have been chosen
>> support the requirements that I listed earlier. David's description of the
>> CMS is helpful, but I just want to identify that we still have missing gaps
>> in terms of versioned-per-release documentation and downloadable
>> documentation in alternative formats.  From the sound of it, these things
>> both appear possible if we are using Apache CMS, however it seems we need
>> to do some extra work with the documentation directory structure for the
>> versioning side of things, and with the release process for
>> tagging/packaging the documentation.  If others are in agreement, we should
>> probably create JIRA issues to track these tasks.
>>
>> Shane
>>
>>
>> On 25/07/12 16:17, Mark Struberg wrote:
>>
>>> David, the CMS is already set up and running (in SVN [1]). We just need a
>>> bit more stylish css.
>>>
>>> And you can perfectly create pdf docs out of markdown.
>>>
>>> Of course we can also use alternative formats. But to me this is like a
>>> colour preference - markdown is supported out of the box and provides all
>>> needed options.
>>>
>>> Shane, I don't think I bypassed anyone. We discussed this since 6 months
>>> and noone started working on it. Thus I finally dropped a mail and then
>>> implemented it. I also got no stop mail back then.
>>> Honestly I really don't care which format we use, IF someone else is
>>> doing the work and others can easily add documentation.
>>>
>>>
>>> LieGrue,
>>> strub
>>>
>>>
>>>
>>> [1] http://svn.apache.org/repos/**asf/incubator/deltaspike/site/**trunk/<http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/>
>>>
>>>
>>>
>>> ----- Original Message -----
>>>
>>>> From: David Blevins <[hidden email]>
>>>> To: deltaspike-dev@incubator.**apache.org<[hidden email]>
>>>> Cc: Mark Struberg <[hidden email]>
>>>> Sent: Wednesday, July 25, 2012 2:37 AM
>>>> Subject: Re: [suggestion] - Documentation
>>>>
>>>> T he answer to both these questions really that the CMS creates
>>>> "websites", some details on that below
>>>>
>>>> I'll note that the CMS is svn based -- maybe undesirable given the use of
>>>> git.
>>>>
>>>> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
>>>>
>>>>     Does the choice of Apache CMS for hosting documentation meet the
>>>>> following
>>>>>
>>>> requirements?
>>>>
>>>>>    1) Making available the documentation for previously released
>>>>> versions of
>>>>>
>>>> DeltaSpike.
>>>>
>>>> If by "make available" the intention is browsable on the website, then
>>>> sure there are ways to handle that.
>>>>
>>>>     2) Making available the documentation in offline formats, such as
>>>>> HTML or
>>>>>
>>>> PDF available for download.
>>>>
>>>> Certainly you can use the same source to generate non-website looking
>>>> HTML.
>>>> Same goes for PDF.
>>>>
>>>> You wouldn't be using the CMS to do this, but the CMS doesn't prevent
>>>> it.  It'd be something we setup ourselves and could be done via a CI
>>>> server
>>>> or something done at release time.
>>>>
>>>> Basically the CMS is a system that is for generate website html using the
>>>> following layout:
>>>>
>>>> - content/<source-files-and-**directories>
>>>> - lib/<site-generating-perl-**functions>
>>>> - templates/<whatever-you-need-**for-templates>
>>>>
>>>> When something in 'content/' is updated, it will run it through lib/
>>>> (which leverages templates/) and save the resulting html to disk and
>>>> take care
>>>> of synching that html file from staging to production.
>>>>
>>>> When something in 'lib/' or 'templates/' is updated, it pretends
>>>> as if everything in 'content/' has changed and performs the above step
>>>> on every source file.
>>>>
>>>> You can organize the 'content/' dir however you want.  That could mean:
>>>>
>>>> - content/v0.1/
>>>> - content/v0.2/
>>>> - content/current/
>>>>
>>>> Where 'current' gets versioned on release.  Or anything at all.  Maybe
>>>> just:
>>>>
>>>> - content/<wild-wild-west>
>>>>
>>>>
>>>> So the short answer is there isn't anything there to prevent or help the
>>>> two
>>>> points.
>>>>
>>>> In terms of generating outside the CMS which is what would be needed for
>>>> say,
>>>> turning many files into one file such as a zip of html or a PDF, it's up
>>>> to
>>>> us.  There are projects that do it via buildbot.  Buildbot is not so
>>>> much a CI
>>>> tool as it is "cron with a webUI" and also happens to have the ability
>>>> to be trigger by commits.
>>>>
>>>> Really, you can get anything done with buildbot without much in the way
>>>> of
>>>> restrictions.  It's a mediocre CI system and an amazing cron replacement.
>>>>
>>>>
>>>> -David
>>>>
>>>>
>>


Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Pete Muir
In reply to this post by Mark Struberg

On 25 Jul 2012, at 07:17, Mark Struberg wrote:

> David, the CMS is already set up and running (in SVN [1]). We just need a bit more stylish css.
>
> And you can perfectly create pdf docs out of markdown.
>
> Of course we can also use alternative formats. But to me this is like a colour preference - markdown is supported out of the box and provides all needed options.

My only concern here is that Markdown doesn't support a few useful things for full on docs (vs readmes and snippets of text):

* admonitions
* callouts on code
* a standard way of indicating what the source language of a code block is
* definition lists
* tables (though there are extensions to Markdown that support this, idk if Apache CMS' implementation of Markdown does?)

I find all of these things useful when writing docs.

It was for these reasons that we decided at JBoss we needed more than MarkDown for docs. We choose AsciiDoc as our extended format for docs:

* It can process 95% of markdown's syntax
* It supports all of the above deficiencies in markdown
* It has a good toolchain built in, that spits out pdf and epub
* It can convert to docbook
* It has good docs

I'm not suggesting that DeltaSpike should do the same, just contributing our findings :-)

>
> Shane, I don't think I bypassed anyone. We discussed this since 6 months and noone started working on it. Thus I finally dropped a mail and then implemented it. I also got no stop mail back then.
> Honestly I really don't care which format we use, IF someone else is doing the work and others can easily add documentation.
>
>
> LieGrue,
> strub
>
>
>
> [1] http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/
>
>
>
> ----- Original Message -----
>> From: David Blevins <[hidden email]>
>> To: [hidden email]
>> Cc: Mark Struberg <[hidden email]>
>> Sent: Wednesday, July 25, 2012 2:37 AM
>> Subject: Re: [suggestion] - Documentation
>>
>> T he answer to both these questions really that the CMS creates
>> "websites", some details on that below
>>
>> I'll note that the CMS is svn based -- maybe undesirable given the use of
>> git.
>>
>> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
>>
>>> Does the choice of Apache CMS for hosting documentation meet the following
>> requirements?
>>>
>>> 1) Making available the documentation for previously released versions of
>> DeltaSpike.
>>
>> If by "make available" the intention is browsable on the website, then
>> sure there are ways to handle that.
>>
>>> 2) Making available the documentation in offline formats, such as HTML or
>> PDF available for download.
>>
>> Certainly you can use the same source to generate non-website looking HTML.  
>> Same goes for PDF.
>>
>> You wouldn't be using the CMS to do this, but the CMS doesn't prevent
>> it.  It'd be something we setup ourselves and could be done via a CI server
>> or something done at release time.
>>
>> Basically the CMS is a system that is for generate website html using the
>> following layout:
>>
>> - content/<source-files-and-directories>
>> - lib/<site-generating-perl-functions>
>> - templates/<whatever-you-need-for-templates>
>>
>> When something in 'content/' is updated, it will run it through lib/
>> (which leverages templates/) and save the resulting html to disk and take care
>> of synching that html file from staging to production.
>>
>> When something in 'lib/' or 'templates/' is updated, it pretends
>> as if everything in 'content/' has changed and performs the above step
>> on every source file.
>>
>> You can organize the 'content/' dir however you want.  That could mean:
>>
>> - content/v0.1/
>> - content/v0.2/
>> - content/current/
>>
>> Where 'current' gets versioned on release.  Or anything at all.  Maybe
>> just:
>>
>> - content/<wild-wild-west>
>>
>>
>> So the short answer is there isn't anything there to prevent or help the two
>> points.
>>
>> In terms of generating outside the CMS which is what would be needed for say,
>> turning many files into one file such as a zip of html or a PDF, it's up to
>> us.  There are projects that do it via buildbot.  Buildbot is not so much a CI
>> tool as it is "cron with a webUI" and also happens to have the ability
>> to be trigger by commits.
>>
>> Really, you can get anything done with buildbot without much in the way of
>> restrictions.  It's a mediocre CI system and an amazing cron replacement.
>>
>>
>> -David
>>

Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Pete Muir
In reply to this post by Romain Manni-Bucau

On 25 Jul 2012, at 08:05, Romain Manni-Bucau wrote:

> Hi,
>
> CMS should be fine for this requirements then it needs some work but offers
> all the needed hooks.
>
> At least for consistency with other apache projects (a lot migrated to the
> cms) i think it is good to use it.

I agree, it seems like a good tool.

>
> I know this topic will be frustrating for half of the people engaged here
> since red hat and apahe guys doesn't currently use the same tools but i
> think/hope nobody will feel frustrated once the doc will be in place.

We're not really that far apart.

We've started to move over to a very similar set of tools:

* awestruct, which is kinda like the CMS, but different
* markdown, for shorter docs (e.g. READMEs)
* asciidoc for longer docs (explained the differences elsewhere :-)

Awestruct is addresses half of what Apache CMS does, it is the bit that reads in a source file, and spits out the HTML. It doesn't do the "continuous integration" and "workflow" bits, where you check into some SCM, and then the CMS picks this up, and asks for confirmation to publish, you are left to do that yourself.

So the overall idea is very similar, just the details are different.

>
> Side note: on openejb website we have an anonymous edit function (not sure
> it is cms or openejb hook but in all case can be used in DS for sure) which
> is pretty interesting for OS projects IMO.
>
> - Romain
>
>
> 2012/7/25 Mark Struberg <[hidden email]>
>
>> David, the CMS is already set up and running (in SVN [1]). We just need a
>> bit more stylish css.
>>
>> And you can perfectly create pdf docs out of markdown.
>>
>> Of course we can also use alternative formats. But to me this is like a
>> colour preference - markdown is supported out of the box and provides all
>> needed options.
>>
>> Shane, I don't think I bypassed anyone. We discussed this since 6 months
>> and noone started working on it. Thus I finally dropped a mail and then
>> implemented it. I also got no stop mail back then.
>> Honestly I really don't care which format we use, IF someone else is doing
>> the work and others can easily add documentation.
>>
>>
>> LieGrue,
>> strub
>>
>>
>>
>> [1] http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/
>>
>>
>>
>> ----- Original Message -----
>>> From: David Blevins <[hidden email]>
>>> To: [hidden email]
>>> Cc: Mark Struberg <[hidden email]>
>>> Sent: Wednesday, July 25, 2012 2:37 AM
>>> Subject: Re: [suggestion] - Documentation
>>>
>>> T he answer to both these questions really that the CMS creates
>>> "websites", some details on that below
>>>
>>> I'll note that the CMS is svn based -- maybe undesirable given the use of
>>> git.
>>>
>>> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
>>>
>>>> Does the choice of Apache CMS for hosting documentation meet the
>> following
>>> requirements?
>>>>
>>>> 1) Making available the documentation for previously released versions
>> of
>>> DeltaSpike.
>>>
>>> If by "make available" the intention is browsable on the website, then
>>> sure there are ways to handle that.
>>>
>>>> 2) Making available the documentation in offline formats, such as HTML
>> or
>>> PDF available for download.
>>>
>>> Certainly you can use the same source to generate non-website looking
>> HTML.
>>> Same goes for PDF.
>>>
>>> You wouldn't be using the CMS to do this, but the CMS doesn't prevent
>>> it.  It'd be something we setup ourselves and could be done via a CI
>> server
>>> or something done at release time.
>>>
>>> Basically the CMS is a system that is for generate website html using the
>>> following layout:
>>>
>>> - content/<source-files-and-directories>
>>> - lib/<site-generating-perl-functions>
>>> - templates/<whatever-you-need-for-templates>
>>>
>>> When something in 'content/' is updated, it will run it through lib/
>>> (which leverages templates/) and save the resulting html to disk and
>> take care
>>> of synching that html file from staging to production.
>>>
>>> When something in 'lib/' or 'templates/' is updated, it pretends
>>> as if everything in 'content/' has changed and performs the above step
>>> on every source file.
>>>
>>> You can organize the 'content/' dir however you want.  That could mean:
>>>
>>> - content/v0.1/
>>> - content/v0.2/
>>> - content/current/
>>>
>>> Where 'current' gets versioned on release.  Or anything at all.  Maybe
>>> just:
>>>
>>> - content/<wild-wild-west>
>>>
>>>
>>> So the short answer is there isn't anything there to prevent or help the
>> two
>>> points.
>>>
>>> In terms of generating outside the CMS which is what would be needed for
>> say,
>>> turning many files into one file such as a zip of html or a PDF, it's up
>> to
>>> us.  There are projects that do it via buildbot.  Buildbot is not so
>> much a CI
>>> tool as it is "cron with a webUI" and also happens to have the ability
>>> to be trigger by commits.
>>>
>>> Really, you can get anything done with buildbot without much in the way
>> of
>>> restrictions.  It's a mediocre CI system and an amazing cron replacement.
>>>
>>>
>>> -David
>>>
>>

Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Matt Benson
In reply to this post by Pete Muir
On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <[hidden email]> wrote:

>
> On 25 Jul 2012, at 07:17, Mark Struberg wrote:
>
>> David, the CMS is already set up and running (in SVN [1]). We just need a bit more stylish css.
>>
>> And you can perfectly create pdf docs out of markdown.
>>
>> Of course we can also use alternative formats. But to me this is like a colour preference - markdown is supported out of the box and provides all needed options.
>
> My only concern here is that Markdown doesn't support a few useful things for full on docs (vs readmes and snippets of text):

FWIW,
>
> * admonitions
I.e., warnings?  What are you looking for here?

> * callouts on code
Again, not sure I know what you're meaning here.

> * a standard way of indicating what the source language of a code block is
Apache CMS has this.

> * definition lists
Example?

> * tables (though there are extensions to Markdown that support this, idk if Apache CMS' implementation of Markdown does?)
Apache CMS has this extension enabled.

Matt

>
> I find all of these things useful when writing docs.
>
> It was for these reasons that we decided at JBoss we needed more than MarkDown for docs. We choose AsciiDoc as our extended format for docs:
>
> * It can process 95% of markdown's syntax
> * It supports all of the above deficiencies in markdown
> * It has a good toolchain built in, that spits out pdf and epub
> * It can convert to docbook
> * It has good docs
>
> I'm not suggesting that DeltaSpike should do the same, just contributing our findings :-)
>
>>
>> Shane, I don't think I bypassed anyone. We discussed this since 6 months and noone started working on it. Thus I finally dropped a mail and then implemented it. I also got no stop mail back then.
>> Honestly I really don't care which format we use, IF someone else is doing the work and others can easily add documentation.
>>
>>
>> LieGrue,
>> strub
>>
>>
>>
>> [1] http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/
>>
>>
>>
>> ----- Original Message -----
>>> From: David Blevins <[hidden email]>
>>> To: [hidden email]
>>> Cc: Mark Struberg <[hidden email]>
>>> Sent: Wednesday, July 25, 2012 2:37 AM
>>> Subject: Re: [suggestion] - Documentation
>>>
>>> T he answer to both these questions really that the CMS creates
>>> "websites", some details on that below
>>>
>>> I'll note that the CMS is svn based -- maybe undesirable given the use of
>>> git.
>>>
>>> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
>>>
>>>> Does the choice of Apache CMS for hosting documentation meet the following
>>> requirements?
>>>>
>>>> 1) Making available the documentation for previously released versions of
>>> DeltaSpike.
>>>
>>> If by "make available" the intention is browsable on the website, then
>>> sure there are ways to handle that.
>>>
>>>> 2) Making available the documentation in offline formats, such as HTML or
>>> PDF available for download.
>>>
>>> Certainly you can use the same source to generate non-website looking HTML.
>>> Same goes for PDF.
>>>
>>> You wouldn't be using the CMS to do this, but the CMS doesn't prevent
>>> it.  It'd be something we setup ourselves and could be done via a CI server
>>> or something done at release time.
>>>
>>> Basically the CMS is a system that is for generate website html using the
>>> following layout:
>>>
>>> - content/<source-files-and-directories>
>>> - lib/<site-generating-perl-functions>
>>> - templates/<whatever-you-need-for-templates>
>>>
>>> When something in 'content/' is updated, it will run it through lib/
>>> (which leverages templates/) and save the resulting html to disk and take care
>>> of synching that html file from staging to production.
>>>
>>> When something in 'lib/' or 'templates/' is updated, it pretends
>>> as if everything in 'content/' has changed and performs the above step
>>> on every source file.
>>>
>>> You can organize the 'content/' dir however you want.  That could mean:
>>>
>>> - content/v0.1/
>>> - content/v0.2/
>>> - content/current/
>>>
>>> Where 'current' gets versioned on release.  Or anything at all.  Maybe
>>> just:
>>>
>>> - content/<wild-wild-west>
>>>
>>>
>>> So the short answer is there isn't anything there to prevent or help the two
>>> points.
>>>
>>> In terms of generating outside the CMS which is what would be needed for say,
>>> turning many files into one file such as a zip of html or a PDF, it's up to
>>> us.  There are projects that do it via buildbot.  Buildbot is not so much a CI
>>> tool as it is "cron with a webUI" and also happens to have the ability
>>> to be trigger by commits.
>>>
>>> Really, you can get anything done with buildbot without much in the way of
>>> restrictions.  It's a mediocre CI system and an amazing cron replacement.
>>>
>>>
>>> -David
>>>
>
Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Pete Muir

On 25 Jul 2012, at 16:16, Matt Benson wrote:

> On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <[hidden email]> wrote:
>>
>> On 25 Jul 2012, at 07:17, Mark Struberg wrote:
>>
>>> David, the CMS is already set up and running (in SVN [1]). We just need a bit more stylish css.
>>>
>>> And you can perfectly create pdf docs out of markdown.
>>>
>>> Of course we can also use alternative formats. But to me this is like a colour preference - markdown is supported out of the box and provides all needed options.
>>
>> My only concern here is that Markdown doesn't support a few useful things for full on docs (vs readmes and snippets of text):
>
> FWIW,
>>
>> * admonitions
> I.e., warnings?  What are you looking for here?

Yes, admonitions is the term given (I think by docbook) to the boxouts that are e.g. Warning, Info, Important.

>
>> * callouts on code
> Again, not sure I know what you're meaning here.

I can have a little icon (e.g. a 1), next to a line of code, then a table at the bottom of the codeblock that links to that. Allows you to annotate a code block with notes.

>
>> * a standard way of indicating what the source language of a code block is
> Apache CMS has this.

Cool. How would this work if we were also producing pdfs and epubs? Is this a standard extension to markdown?

>
>> * definition lists
> Example?

http://www.w3schools.com/tags/tag_dl.asp

>
>> * tables (though there are extensions to Markdown that support this, idk if Apache CMS' implementation of Markdown does?)
> Apache CMS has this extension enabled.
>
> Matt
>
>>
>> I find all of these things useful when writing docs.
>>
>> It was for these reasons that we decided at JBoss we needed more than MarkDown for docs. We choose AsciiDoc as our extended format for docs:
>>
>> * It can process 95% of markdown's syntax
>> * It supports all of the above deficiencies in markdown
>> * It has a good toolchain built in, that spits out pdf and epub
>> * It can convert to docbook
>> * It has good docs
>>
>> I'm not suggesting that DeltaSpike should do the same, just contributing our findings :-)
>>
>>>
>>> Shane, I don't think I bypassed anyone. We discussed this since 6 months and noone started working on it. Thus I finally dropped a mail and then implemented it. I also got no stop mail back then.
>>> Honestly I really don't care which format we use, IF someone else is doing the work and others can easily add documentation.
>>>
>>>
>>> LieGrue,
>>> strub
>>>
>>>
>>>
>>> [1] http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/
>>>
>>>
>>>
>>> ----- Original Message -----
>>>> From: David Blevins <[hidden email]>
>>>> To: [hidden email]
>>>> Cc: Mark Struberg <[hidden email]>
>>>> Sent: Wednesday, July 25, 2012 2:37 AM
>>>> Subject: Re: [suggestion] - Documentation
>>>>
>>>> T he answer to both these questions really that the CMS creates
>>>> "websites", some details on that below
>>>>
>>>> I'll note that the CMS is svn based -- maybe undesirable given the use of
>>>> git.
>>>>
>>>> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
>>>>
>>>>> Does the choice of Apache CMS for hosting documentation meet the following
>>>> requirements?
>>>>>
>>>>> 1) Making available the documentation for previously released versions of
>>>> DeltaSpike.
>>>>
>>>> If by "make available" the intention is browsable on the website, then
>>>> sure there are ways to handle that.
>>>>
>>>>> 2) Making available the documentation in offline formats, such as HTML or
>>>> PDF available for download.
>>>>
>>>> Certainly you can use the same source to generate non-website looking HTML.
>>>> Same goes for PDF.
>>>>
>>>> You wouldn't be using the CMS to do this, but the CMS doesn't prevent
>>>> it.  It'd be something we setup ourselves and could be done via a CI server
>>>> or something done at release time.
>>>>
>>>> Basically the CMS is a system that is for generate website html using the
>>>> following layout:
>>>>
>>>> - content/<source-files-and-directories>
>>>> - lib/<site-generating-perl-functions>
>>>> - templates/<whatever-you-need-for-templates>
>>>>
>>>> When something in 'content/' is updated, it will run it through lib/
>>>> (which leverages templates/) and save the resulting html to disk and take care
>>>> of synching that html file from staging to production.
>>>>
>>>> When something in 'lib/' or 'templates/' is updated, it pretends
>>>> as if everything in 'content/' has changed and performs the above step
>>>> on every source file.
>>>>
>>>> You can organize the 'content/' dir however you want.  That could mean:
>>>>
>>>> - content/v0.1/
>>>> - content/v0.2/
>>>> - content/current/
>>>>
>>>> Where 'current' gets versioned on release.  Or anything at all.  Maybe
>>>> just:
>>>>
>>>> - content/<wild-wild-west>
>>>>
>>>>
>>>> So the short answer is there isn't anything there to prevent or help the two
>>>> points.
>>>>
>>>> In terms of generating outside the CMS which is what would be needed for say,
>>>> turning many files into one file such as a zip of html or a PDF, it's up to
>>>> us.  There are projects that do it via buildbot.  Buildbot is not so much a CI
>>>> tool as it is "cron with a webUI" and also happens to have the ability
>>>> to be trigger by commits.
>>>>
>>>> Really, you can get anything done with buildbot without much in the way of
>>>> restrictions.  It's a mediocre CI system and an amazing cron replacement.
>>>>
>>>>
>>>> -David
>>>>
>>

Reply | Threaded
Open this post in threaded view
|

Re: [suggestion] - Documentation

Jason Porter
In reply to this post by Matt Benson
On Wed, Jul 25, 2012 at 9:16 AM, Matt Benson <[hidden email]> wrote:

> On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <[hidden email]> wrote:
> >
> > On 25 Jul 2012, at 07:17, Mark Struberg wrote:
> >
> >> David, the CMS is already set up and running (in SVN [1]). We just need
> a bit more stylish css.
> >>
> >> And you can perfectly create pdf docs out of markdown.
> >>
> >> Of course we can also use alternative formats. But to me this is like a
> colour preference - markdown is supported out of the box and provides all
> needed options.
> >
> > My only concern here is that Markdown doesn't support a few useful
> things for full on docs (vs readmes and snippets of text):
>
> FWIW,
> >
> > * admonitions
> I.e., warnings?  What are you looking for here?
>

Warnings, notes, tips, info, etc. Often times they're sidebars.

>
> > * callouts on code
> Again, not sure I know what you're meaning here.
>
>
If you're familiar with docbook, they call them callouts. They're numbered
sections from a code snippet with their own section beneath the code layout
explaining what each number is.


> > * a standard way of indicating what the source language of a code block
> is
> Apache CMS has this.
>
> > * definition lists
> Example?
>

In HTML the DL, DD and DT tags


>
> > * tables (though there are extensions to Markdown that support this, idk
> if Apache CMS' implementation of Markdown does?)
> Apache CMS has this extension enabled.
>
> Matt
>
> >
> > I find all of these things useful when writing docs.
> >
> > It was for these reasons that we decided at JBoss we needed more than
> MarkDown for docs. We choose AsciiDoc as our extended format for docs:
> >
> > * It can process 95% of markdown's syntax
> > * It supports all of the above deficiencies in markdown
> > * It has a good toolchain built in, that spits out pdf and epub
> > * It can convert to docbook
> > * It has good docs
> >
> > I'm not suggesting that DeltaSpike should do the same, just contributing
> our findings :-)
> >
> >>
> >> Shane, I don't think I bypassed anyone. We discussed this since 6
> months and noone started working on it. Thus I finally dropped a mail and
> then implemented it. I also got no stop mail back then.
> >> Honestly I really don't care which format we use, IF someone else is
> doing the work and others can easily add documentation.
> >>
> >>
> >> LieGrue,
> >> strub
> >>
> >>
> >>
> >> [1] http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/
> >>
> >>
> >>
> >> ----- Original Message -----
> >>> From: David Blevins <[hidden email]>
> >>> To: [hidden email]
> >>> Cc: Mark Struberg <[hidden email]>
> >>> Sent: Wednesday, July 25, 2012 2:37 AM
> >>> Subject: Re: [suggestion] - Documentation
> >>>
> >>> T he answer to both these questions really that the CMS creates
> >>> "websites", some details on that below
> >>>
> >>> I'll note that the CMS is svn based -- maybe undesirable given the use
> of
> >>> git.
> >>>
> >>> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
> >>>
> >>>> Does the choice of Apache CMS for hosting documentation meet the
> following
> >>> requirements?
> >>>>
> >>>> 1) Making available the documentation for previously released
> versions of
> >>> DeltaSpike.
> >>>
> >>> If by "make available" the intention is browsable on the website, then
> >>> sure there are ways to handle that.
> >>>
> >>>> 2) Making available the documentation in offline formats, such as
> HTML or
> >>> PDF available for download.
> >>>
> >>> Certainly you can use the same source to generate non-website looking
> HTML.
> >>> Same goes for PDF.
> >>>
> >>> You wouldn't be using the CMS to do this, but the CMS doesn't prevent
> >>> it.  It'd be something we setup ourselves and could be done via a CI
> server
> >>> or something done at release time.
> >>>
> >>> Basically the CMS is a system that is for generate website html using
> the
> >>> following layout:
> >>>
> >>> - content/<source-files-and-directories>
> >>> - lib/<site-generating-perl-functions>
> >>> - templates/<whatever-you-need-for-templates>
> >>>
> >>> When something in 'content/' is updated, it will run it through lib/
> >>> (which leverages templates/) and save the resulting html to disk and
> take care
> >>> of synching that html file from staging to production.
> >>>
> >>> When something in 'lib/' or 'templates/' is updated, it pretends
> >>> as if everything in 'content/' has changed and performs the above step
> >>> on every source file.
> >>>
> >>> You can organize the 'content/' dir however you want.  That could mean:
> >>>
> >>> - content/v0.1/
> >>> - content/v0.2/
> >>> - content/current/
> >>>
> >>> Where 'current' gets versioned on release.  Or anything at all.  Maybe
> >>> just:
> >>>
> >>> - content/<wild-wild-west>
> >>>
> >>>
> >>> So the short answer is there isn't anything there to prevent or help
> the two
> >>> points.
> >>>
> >>> In terms of generating outside the CMS which is what would be needed
> for say,
> >>> turning many files into one file such as a zip of html or a PDF, it's
> up to
> >>> us.  There are projects that do it via buildbot.  Buildbot is not so
> much a CI
> >>> tool as it is "cron with a webUI" and also happens to have the ability
> >>> to be trigger by commits.
> >>>
> >>> Really, you can get anything done with buildbot without much in the
> way of
> >>> restrictions.  It's a mediocre CI system and an amazing cron
> replacement.
> >>>
> >>>
> >>> -David
> >>>
> >
>



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