On 25 Jul 2012, at 16:16, Matt Benson wrote: > 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?
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 <[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 >>>> >>
