Re: [rdf4j-dev] archive site

[Jeen Broekstra <jeen.broekstra@xxxxxxxxx>]

On 19/08/16 22:08, Rick Moynihan wrote:

If you're intending to do formal documentation I was going to suggest looking at AsciiDoc (not used it though)...  I did use docbook a long time ago, and thought it was pretty good - but the XML is a pain, and as far as I recall the XSLT/DSSL styling is pretty complex if you want to edit it.

The Sesame documentation actually used to be in Docbook format, and I remember it being tricky to customize. That got better when we started using Callimachus (which could do server-side on-the-fly rendering of Docbook, and James did a pretty awesome job at providing good stylesheets), but it had other issues.

I think AsciiDoc is my current fave. What we'll do is the following: I'll set up a separate Github repo for the documentation (rdf4j-doc), and I'll make a first attempt at setting up an AsciiDoc-based project.

As for publication: for now I'll just work on the assumption that we'll do occassional manual builds from the doc-repo to rdf4j.org.

Regarding the archive site, one thing to bear in mind is that it contains about 2gb of javadocs in a git repo (because of github pages); so it's a bit unweildy to work in that repo.  It might be worth considering a different sub domain for the non-legacy user docs.  We could perhaps share the HTML/styling/nav across the doc/archive site if we really wanted; but it would most likely need to be maintained/synchronised by hand

I'm quite keen to keep the Sesame legacy docs and the "proper" RDF4J documentation separate, so I'll start a new Github repo for it.

Cheers,

Jeen