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. 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. Else maybe the old standard Latex, wh/facilitates same, and although out of vogue at present, I don't think it's not going to disappear anytime soon. Advantage here might be that lots of science and math types will already be somewhat familiar w/it from thesis writing and such, but I'd also think this would not encompass a significant number of OS/IllumOS contributors. I've never heard of Sphinx. My $0.02, fwiw. _______________________________________________ oi-dev mailing list oi-dev@openindiana.org http://openindiana.org/mailman/listinfo/oi-dev
