[oi-dev] Fwd: [OpenIndiana-discuss] Documentation-Project

[Chris Ridd]

On 30 May 2011, at 16:49, Ken Gunderson wrote:

> On Mon, 2011-05-30 at 08:24 +0400, Garrett D'Amore wrote:
>> Switching to another less popular doc format doesn't seem like a great idea.  I don't work with the documentation frequently, but I'd ask people that do.
>> 
>> One thing is that some of these formats are like fads... they come and go.  I remember not long ago when SGML was all the rage. :-)  From my perspective it would be good to have a format that has good tools available (multiple implementations, at least some of which are portable to other platforms), displays nicely, and provides some basic structure capabitilities to assist in parsing for content or format conversion (e.g. to HTML).
>> 
>> If you make me install a bunch of new tools, or learn a format that nobody else uses, I probably will be less inclined to write documentation.  (That said, I've not written much except a few man pages, and the format of *those* is relatively constrained by the need to be able to display them with the man command. :-)
>> 
>>  -- Garrett D'Amore
> 
> I would think Docbook would be the way to go.  Yeah, it's going to
> require some specific libraries and tools but it's transformable to many
> different formats.  I haven't dealt with it for a while now but easily
> to morph to man, text, html, and pdf, which I think pretty much covers
> all reasonable bases.

Yes, and epub. RTFM on your iPhone :-)

> XML situps are a pain after the first few thousand.  Last I looked most
> good XML editors out there were proprietary. All fine and dandy if
> you're a commercial corp with a documentation staff but such would seem
> to raise the bar w/o much of any real gain for a small FOSS project.

There are reasonable docbook-aware editors around which work on Solaris, and which are free for use by non-commercial outfits. Most are Java.

XXE (www.xmlmind.com) is the one I use, based on our tech author's recommendation.

The fact there *are* many ways to maintain Docbook content is a point in its favour.

Are the Solaris man pages still authored in some kind of customized Docbook?

Chris