From: Jamis Buck <jgb3@...>
Date: 2004-10-25T09:07:44+09:00
Subject: Re: Writing documentation in YAML - any advice?

Its Me wrote:
> It will be a decent sized document. WinXP platform.
> 
> Where should I start / look for help with:
> 
> - Decent editor with decent YAML mode; if I don't find any I'll probably
> settle for JEdit.
> 
> - Useful YAML type declarations for a document
> 
> - Ability to mix in some formatting mark-up
> 
> - Useful ruby scripts to manipulate e.g. generate toc, index, html, check
> validity, ...
> 
> - Any ways to modularize into smaller documents/files a'la XInclude
> 
> All help appreciated. A ready gem would be great :-)  Suggestions along the
> lines of "don't do it ... do it this way instead" also welcome.

No "ready gems" available that I know of. However, if you don't mind 
mining other projects for ideas:

   * Why's Poignant Guide to Ruby 
(http://rubyforge.org/projects/poignant/). His entire book is done in 
YAML, using textile markup.

   * Copland (http://rubyforge.org/projects/copland). The user manual 
for Copland is done very similarly to the Poignant Guide.

   * Needle (http://rubyforge.org/projects/needle). The user manual for 
needle is done similarly to the Guide and Copland, but instead of 
putting the marked-up text directly in the YAML document, the YAML 
references external files that contain the content.

Those should give you some ideas, and hopefully get you started.

- Jamis


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