[oi-dev] OI User documentation

[Michael Kruger]

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