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

[Bayard Bell]

On 30 May 2011, at 20:13, Alan Coopersmith wrote:

> Yes - SolBook is still used as the source markup, from which the nroff output
> is generated for man pages in the OS, and the html & pdf output for the site
> formerly known as docs.sun.com.   The DTD is in the ON gate/packages - see
> /usr/share/lib/sgml/locale/C/dtds/solbookv2 from pkg:/text/doctools .
> 
> For what it's worth, most of the html/pdf/txt docs on
> 	http://www.x.org/releases/X11R7.6/doc/
> were generated from Docbook/XML on a Solaris 11 Express machine, though I did
> have to install a couple extra open source packages that aren't currently
> in any of the consolidations/package repos:
> 	https://fedorahosted.org/xmlto/
> 	http://xmlgraphics.apache.org/fop/
> as well as updating to a slightly newer version of the Docbook style sheets
> than the JDS consolidation currently packages.
> 
> Personally, I just use emacs to edit docbook files, but I do the same for
> html too, never having found (or looked that hard for) a more user-friendly
> front end editor.

Tales from the trenches are extremely helpful, thanks, Alan. I did a little searching around, trying to get a sense of how people who were maintaining documentation for large project, either as developers or as tech writers saw the state of the art. Here's a fairly random sample, which also provides some incidental name-dropping to give a sense of where different formats are being used:

http://www.scons.org/wiki/DeveloperGuide/Documentation/Discussion
http://freerangelibrarian.com/2009/06/07/docbook-xml-and-homebrew/
http://lethargy.org/~jesus/writes/xmlxslt-and-docbook-for-docs
http://blog.raspberry.nl/2011/04/12/documentation/
http://ffeathers.wordpress.com/2009/05/18/scroll-converts-wiki-to-docbook-and-pdf/
https://docs.jboss.org/author/display/AUTHGUIDE/How+to+release+documentation
http://www.dmncommunications.com/weblog/?p=199
http://lists.cs.uiuc.edu/pipermail/llvmdev/2010-August/034044.html
http://mark-story.com/posts/view/generating-documentation-with-sphinx

If anyone else has some points of reference that speak to what's worked for whom where, please share.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110530/c07f3974/attachment-0005.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 1515 bytes
Desc: not available
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110530/c07f3974/attachment-0010.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 841 bytes
Desc: This is a digitally signed message part
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110530/c07f3974/attachment-0011.bin>