[oi-dev] OI User documentation
Michael Kruger
makruger2000 at gmail.com
Thu Jan 7 20:59:38 UTC 2016
On 01/07/2016 05:04 AM, Damian Wojsław wrote:
> On the topic of re-using old OpenSolaris docs, I wouldn't mind, for one,
> to build on ZFS Administrator Guide. While differences are many, most of
> text would still be useful. Writing such a guide from start is a tedious
> task. I know, having started http://wiki.openindiana.org/oi/ZFS some
> time ago.
>
> Also OpenSolaris resource management and containers guide is probably a
> perfect starting point to build a more recent docs. Zones and resource
> management are one of prime time features of illumos, IMHO.
>
> Damian
Hi Damian,
I agree much of this content is still valid. It would just need to be
updated to reflect changes since the docs were last updated (2009).
As Alan Coopersmith pointed out, there is the work previously done by
Robert Mustacchi. He wrote a nice script that helps to automate the
translation process from SolBook 3.5 XML to HTML 4.
See: https://github.com/rmustacc/illumos-docbooks
And: http://illumos.org/books/
I have not used Robert's script yet, but have run the java transform
tool (SolBookTrans.JAR) manually from the command line.
The transform JAR is unfortunately a bit broken. It fails to produce an
index, and refuses to run in GUI mode. There may be other bugs as well.
Otherwise, it seems to work OK. It was written to run on Sun Java 1.6,
but I have used it successfully with OpenJdk 1.7.
I'm not a developer, so this is beyond my abilities, but the java source
code is there in case anyone cares to take a crack at fixing the
indexing problem.
As for the docs themselves, most were written in Sun's SolBook 3.5 XML,
but at least one of them (and possibly more), were written in Solbook
3.6, which the transform tool cannot handle (due to the absence of an
appropriate DTD).
SolBook XML is basically a simplified version of docbook...but still
very painful to work with. So perhaps as a long term strategy, the
content should be ported over to something easier to work with (such as
Asciidoc - http://www.methods.co.nz/asciidoc/).
Michael
More information about the oi-dev
mailing list