You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@deltaspike.apache.org by Shane Bryzak <sb...@redhat.com> on 2012/07/25 01:54:33 UTC
Re: [suggestion] - Documentation
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 <li...@gmail.com>
>> To: deltaspike-dev@incubator.apache.org
>> 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 <
>> gerhard.petracek@gmail.com> 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 <cm...@gmail.com>
>>>
>>> > 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
>>
Re: [suggestion] - Documentation
Posted by Shane Bryzak <sb...@redhat.com>.
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 <sb...@redhat.com>
>
>> 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 <da...@gmail.com>
>>>> To: deltaspike-dev@incubator.**apache.org<de...@incubator.apache.org>
>>>> Cc: Mark Struberg <st...@yahoo.de>
>>>> 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
>>>>
>>>>
>>
Re: [suggestion] - Documentation
Posted by Romain Manni-Bucau <rm...@gmail.com>.
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 <sb...@redhat.com>
> 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 <da...@gmail.com>
>>> To: deltaspike-dev@incubator.**apache.org<de...@incubator.apache.org>
>>> Cc: Mark Struberg <st...@yahoo.de>
>>> 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
>>>
>>>
>
>
Re: [suggestion] - Documentation
Posted by Shane Bryzak <sb...@redhat.com>.
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 <da...@gmail.com>
>> To: deltaspike-dev@incubator.apache.org
>> Cc: Mark Struberg <st...@yahoo.de>
>> 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
>>
Re: [suggestion] - Documentation
Posted by David Blevins <da...@gmail.com>.
On Jul 25, 2012, at 12:48 AM, Mark Struberg wrote:
> 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.
FYI, that it's part of the CMS package and not an opt-in feature (at least not yet).
That said it's really just a local checkout of the site with some minimal tooling to let the project know via email there's something there they might want to merge into the docs. The only way you can see the temporary checkout is if you attempt to edit anonymously.
As a spammer at best you can do is dirty up the anonymous checkout and annoy anyone else attempting to edit anonymously.
-David
Re: [suggestion] - Documentation
Posted by Mark Struberg <st...@yahoo.de>.
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 <rm...@gmail.com>
>To: deltaspike-dev@incubator.apache.org; Mark Struberg <st...@yahoo.de>
>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 <st...@yahoo.de>
>
>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 <da...@gmail.com>
>>> To: deltaspike-dev@incubator.apache.org
>>> Cc: Mark Struberg <st...@yahoo.de>
>>> 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
>>>
>>
>
>
>
Re: [suggestion] - Documentation
Posted by Pete Muir <pm...@redhat.com>.
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 <st...@yahoo.de>
>
>> 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 <da...@gmail.com>
>>> To: deltaspike-dev@incubator.apache.org
>>> Cc: Mark Struberg <st...@yahoo.de>
>>> 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
>>>
>>
Re: [suggestion] - Documentation
Posted by Romain Manni-Bucau <rm...@gmail.com>.
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 <st...@yahoo.de>
> 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 <da...@gmail.com>
> > To: deltaspike-dev@incubator.apache.org
> > Cc: Mark Struberg <st...@yahoo.de>
> > 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
> >
>
Re: [suggestion] - Documentation
Posted by Jason Porter <li...@gmail.com>.
On Wed, Jul 25, 2012 at 9:16 AM, Matt Benson <gu...@gmail.com> wrote:
> On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <pm...@redhat.com> 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 <da...@gmail.com>
> >>> To: deltaspike-dev@incubator.apache.org
> >>> Cc: Mark Struberg <st...@yahoo.de>
> >>> 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
Re: [suggestion] - Documentation
Posted by Romain Manni-Bucau <rm...@gmail.com>.
i think we can either to send a mail to
http://apache.org/dev/infra-mail.html , or to ping on #asfinfra.
another way could be to open a jira on infra project but i think we should
talk with them before.
- Romain
2012/7/27 Pete Muir <pm...@redhat.com>
> Romain, what is the best way to take this forward?
>
> I can write up a summary if that helps?
>
> On 25 Jul 2012, at 17:05, Romain Manni-Bucau wrote:
>
> > Hmm, these feedbacks are really relevant and should be pushed to infra i
> > think, no?
> >
> > it is simply a matter of adding some hooks in the cms but i think it is
> > better to had them in the cms instead of "by project"
> >
> > wdyt?
> >
> > - Romain
> >
> >
> > 2012/7/25 Pete Muir <pm...@redhat.com>
> >
> >>
> >> On 25 Jul 2012, at 16:36, Matt Benson wrote:
> >>
> >>> On Wed, Jul 25, 2012 at 10:22 AM, Pete Muir <pm...@redhat.com> wrote:
> >>>>
> >>>> On 25 Jul 2012, at 16:16, Matt Benson wrote:
> >>>>
> >>>>> On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <pm...@redhat.com> 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?
> >>>
> >>> Yes; the code highlighting is done with
> >>> http://freewisdom.org/projects/python-markdown/CodeHilite; depending
> >>> on the structure of whatever mechanism would be theoretically used to
> >>> produce other formats, we'd presumably just make the same extensions
> >>> available.
> >>
> >> That works :-)
> >>
> >>
>
>
Re: [suggestion] - Documentation
Posted by Pete Muir <pm...@redhat.com>.
Romain, what is the best way to take this forward?
I can write up a summary if that helps?
On 25 Jul 2012, at 17:05, Romain Manni-Bucau wrote:
> Hmm, these feedbacks are really relevant and should be pushed to infra i
> think, no?
>
> it is simply a matter of adding some hooks in the cms but i think it is
> better to had them in the cms instead of "by project"
>
> wdyt?
>
> - Romain
>
>
> 2012/7/25 Pete Muir <pm...@redhat.com>
>
>>
>> On 25 Jul 2012, at 16:36, Matt Benson wrote:
>>
>>> On Wed, Jul 25, 2012 at 10:22 AM, Pete Muir <pm...@redhat.com> wrote:
>>>>
>>>> On 25 Jul 2012, at 16:16, Matt Benson wrote:
>>>>
>>>>> On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <pm...@redhat.com> 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?
>>>
>>> Yes; the code highlighting is done with
>>> http://freewisdom.org/projects/python-markdown/CodeHilite; depending
>>> on the structure of whatever mechanism would be theoretically used to
>>> produce other formats, we'd presumably just make the same extensions
>>> available.
>>
>> That works :-)
>>
>>
Re: [suggestion] - Documentation
Posted by Romain Manni-Bucau <rm...@gmail.com>.
Hmm, these feedbacks are really relevant and should be pushed to infra i
think, no?
it is simply a matter of adding some hooks in the cms but i think it is
better to had them in the cms instead of "by project"
wdyt?
- Romain
2012/7/25 Pete Muir <pm...@redhat.com>
>
> On 25 Jul 2012, at 16:36, Matt Benson wrote:
>
> > On Wed, Jul 25, 2012 at 10:22 AM, Pete Muir <pm...@redhat.com> wrote:
> >>
> >> On 25 Jul 2012, at 16:16, Matt Benson wrote:
> >>
> >>> On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <pm...@redhat.com> 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?
> >
> > Yes; the code highlighting is done with
> > http://freewisdom.org/projects/python-markdown/CodeHilite; depending
> > on the structure of whatever mechanism would be theoretically used to
> > produce other formats, we'd presumably just make the same extensions
> > available.
>
> That works :-)
>
>
Re: [suggestion] - Documentation
Posted by Pete Muir <pm...@redhat.com>.
On 25 Jul 2012, at 16:36, Matt Benson wrote:
> On Wed, Jul 25, 2012 at 10:22 AM, Pete Muir <pm...@redhat.com> wrote:
>>
>> On 25 Jul 2012, at 16:16, Matt Benson wrote:
>>
>>> On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <pm...@redhat.com> 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?
>
> Yes; the code highlighting is done with
> http://freewisdom.org/projects/python-markdown/CodeHilite; depending
> on the structure of whatever mechanism would be theoretically used to
> produce other formats, we'd presumably just make the same extensions
> available.
That works :-)
Re: [suggestion] - Documentation
Posted by Matt Benson <gu...@gmail.com>.
On Wed, Jul 25, 2012 at 10:22 AM, Pete Muir <pm...@redhat.com> wrote:
>
> On 25 Jul 2012, at 16:16, Matt Benson wrote:
>
>> On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <pm...@redhat.com> 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?
Yes; the code highlighting is done with
http://freewisdom.org/projects/python-markdown/CodeHilite; depending
on the structure of whatever mechanism would be theoretically used to
produce other formats, we'd presumably just make the same extensions
available.
>
>>
>>> * definition lists
>> Example?
>
> http://www.w3schools.com/tags/tag_dl.asp
As it turns out,
http://freewisdom.org/projects/python-markdown/Definition_Lists is
also enabled in the Apache CMS. The full list of enabled extensions
is at http://www.apache.org/dev/cmsref#markdown .
Matt
>
>>
>>> * 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 <da...@gmail.com>
>>>>> To: deltaspike-dev@incubator.apache.org
>>>>> Cc: Mark Struberg <st...@yahoo.de>
>>>>> 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
>>>>>
>>>
>
Re: [suggestion] - Documentation
Posted by Pete Muir <pm...@redhat.com>.
On 25 Jul 2012, at 16:16, Matt Benson wrote:
> On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <pm...@redhat.com> 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 <da...@gmail.com>
>>>> To: deltaspike-dev@incubator.apache.org
>>>> Cc: Mark Struberg <st...@yahoo.de>
>>>> 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
>>>>
>>
Re: [suggestion] - Documentation
Posted by Matt Benson <gu...@gmail.com>.
On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <pm...@redhat.com> 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 <da...@gmail.com>
>>> To: deltaspike-dev@incubator.apache.org
>>> Cc: Mark Struberg <st...@yahoo.de>
>>> 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
>>>
>
Re: [suggestion] - Documentation
Posted by Pete Muir <pm...@redhat.com>.
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 <da...@gmail.com>
>> To: deltaspike-dev@incubator.apache.org
>> Cc: Mark Struberg <st...@yahoo.de>
>> 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
>>
Re: [suggestion] - Documentation
Posted by Mark Struberg <st...@yahoo.de>.
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 <da...@gmail.com>
> To: deltaspike-dev@incubator.apache.org
> Cc: Mark Struberg <st...@yahoo.de>
> 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
>
Re: [suggestion] - Documentation
Posted by David Blevins <da...@gmail.com>.
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