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

[Ken Gunderson]

On Mon, 2011-05-30 at 11:23 -0500, TJ Yang wrote:
> On Mon, May 30, 2011 at 10:49 AM, Ken Gunderson <kgunders at teamcool.net> 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

Interesting.  Plus added advantage that's it's going to be easy access
via emacs, wh/is readily available for pretty much any platform.  Yeah,
docbook is going to be too, but goes to show you that sometime old
school tools are old school because they're the best tools....