On Mon, May 30, 2011 at 10:49 AM, Ken Gunderson <[email protected]> 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. > > 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.
Hi, All This is my personal experience on this matter. Having use both Docbook and LaTeX to on a few manuals before. I actually retracted back to use LaTeX from docbook as documentation tools to create Manual/Book. > I've never heard of Sphinx. Me either. So to me, Docbook is acceptable but LaTeX is the best tool, IMHO. tj > > > > My $0.02, fwiw. > > > > > _______________________________________________ > oi-dev mailing list > [email protected] > http://openindiana.org/mailman/listinfo/oi-dev > -- T.J. Yang _______________________________________________ oi-dev mailing list [email protected] http://openindiana.org/mailman/listinfo/oi-dev
