On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <[email protected]> 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 <[email protected]> >>> To: [email protected] >>> Cc: Mark Struberg <[email protected]> >>> 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 >>> >
