A quick recap on how to update documentation on the web site:
The site is generated by the Apache CMS, a home-grown content generation
system based on Perl and markdown. General info and instructions on the
CMS here:
http://wiki.apache.org/general/ApacheCms2010
http://www.apache.org/dev/cmsref.html
However, the documentation isn't great. The salient points are:
* The source is Markdown, with a few extensions (tables, etc). There is
one non-standard feature: the document needs to start with a Title
element, which is used to generate an h1 at the top of the page (i.e. so
you don't need an initial '# This is my page')
* All the source is in svn at:
https://svn.apache.org/repos/asf/incubator/jena/site/trunk/
* you can svn co that URL to get a local working copy of the site. When
you commit, buildbot will notice and automatically run the conversion
scripts to turn the markdown into html on the staging site:
http://jena.staging.apache.org/jena/
* For major editing, I've found working on a local copy is easiest. For
more lightweight editing, there is a link to go direct to a 'working
copy' model in which you can edit wiki-like in the browser. See 'get
Jena working copy' on:
https://cms.apache.org/jena/
You can also activate this mode via a bookmarklet; there are
instructions on that page.
* To publish the external site from staging, use this link (which is
also available from the cms.apage.org/jena page):
https://cms.apache.org/jena/publish
This will require one more commit (and log message), and will trigger
buildbot to copy staging to external.
* Markdown is pretty straightforward, and has all of HTML as a subset.
This means that taking files from the old site and dropping them into
the CMS site sort-of 'just works'. You'll need to strip off some chrome
(css links, etc), and adjust links.
* I've had pretty good success with using pandoc to auto-convert html to
markdown. The only thing it fails on is tables, since these are not part
of standard markdown. I've manually edited the files I've converted to
put the markdown table syntax back in. Enterprising perl programmers may
be able to automate this process, but I'm not sure it's worth the candle.
* The CMS should support the markdown ToC plugin, but it's borked. I
have a JIRA bugrep in, but it has received no love from Infra as yet. I
don't know who, if anyone, is maintaining the CMS code (and I fear to
ask too stridently for fear of accidentally volunteering :)
* When doing major edits, it's possible to run the CMS scripts locally
(so you can preview without going via staging). Bit of a pain to set up,
but when it's working it does seem reliable - at least on Linux. I have
no idea if it's easy, or even possible, on Windows.
I'll carry on with some of my general gardening and migrating content,
but please feel free to start adding and editing content. Shout if you
need any help.
Ian
