From: Jamis Buck <jgb3@...>
Date: 2004-10-06T22:19:26+09:00
Subject: Re: The Making of Copland's User Manual

Bil Kleb wrote:
> Jamis,
> 
> During the conference, I only caught the tail end of your
> remarks about how you created Copland's user manual.  Our
> team is currently facing a similar task (in addition to
> getting the rest of our website, http://fun3d.larc.nasa.gov
> on Rails).  Is the process you used described somewhere that
> all can benefit from?
> 
> Thanks,

Bil,

For my Copland manual, I took a page (quite literally) from _why's book. 
The "Poignant Guide" uses a ruby script to process a YAML document, 
turning it into a lovely, attractive suite of HTML pages. I lifted 
_why's ruby script and erb templates, tweaked them a bit, and dropped 
them into my Copland project.

The process is something like this:

1) Create a YAML document that contains your manual metadata, as well as 
the content of your manual in textile format. (A few gotchas to be 
avoided there, if you decide to go that route--just let me know.) Use 
YAML to structure your manual, defining chapters and sections as array 
and hash elements.

2) Create (or modify) erb templates to suit the look you want for your 
manual.

3) Create (or modify) a stylesheet to define the look of your manual.

4) Create (or modify) a ruby script to process your YAML document.

5) Run the ruby script to convert your YAML document into HTML.

Feel free to grab Copland and look at the "doc/manual" subdirectory. You 
can build the manual easily by running "rake manual".

Incidentally, my Net::SSH project uses the same process for its user 
manual. And of course, WPGTR is the definitive source for the whole 
process, incorporating many more features than mine does (like sidebars, 
and a printable version).

Hope that helps,

Jamis

-- 
Jamis Buck
jgb3@email.byu.edu
http://www.jamisbuck.org/jamis