From: Dave Thomas <dave@...>
Date: 2004-08-14T03:45:15+09:00
Subject: [ANN] RDocUsage

Luke Kanies was talking with me about implementing rdoc2man and 
rdocusage. I thought RDoc::usage would be a very cool thing to have, so 
I stole the idea and implemented it while waiting at the doctors' this 
morning.

Basically, if the main program file in your application has an RDoc 
comment describing the program, you can use it to generate a usage 
message for your users by calling

    RDoc::usage( )

If you just want to display the Synopsis section (which in the RDoc 
will have a heading "= Synopsis"), you'd instead say

    RDoc::usage('synopsis')

To display the author and copyright sections, you'd say

    RDoc::usage('author', 'copyright')

It honors the RI environment variable, so it will display using ANSI 
escape sequences or backspaces if that's what the end user has asked 
for. It'll also generate the usage message in HTML.

There's a page on the wiki describing it: 
http://www.rubygarden.org/ruby?RDocUsage

Forgive the slightly ugly HTML example at the end: the wiki seems to be 
touching about some HTML tags in its input.


RDoc::usage in the head of 1.9 and 1.8 CVS right now.


Cheers

Dave