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 _______________________________________________ oi-dev mailing list [email protected] http://openindiana.org/mailman/listinfo/oi-dev
