On 2 Mar 2000, Yukihiro Matsumoto wrote:

> I write them in HTML directly, having plan to move to RD
> (Ruby Document format - simplified POD like text).
	[...]
> Patches, suggestions, document maintainers are always welcome.
> 
> 							matz.

I have looked at the docs for "embed_doc" in syntax.html.  May I suggest
the following (I did raise this on comp.lang.perl.misc, but got no
answers. Maybe it is silly in some way?):

There exists a pod2man, so presumably a Ruby version will appear (if
it hasn't already).  The main problem with pod is that you want to 
keep the docs with the code, but you often need the manual information
to come out in a different order.  So I suggest:

=name <NAME>
This block of text is associated with <NAME> and not displayed yet.
=end

=include <NAME>

The block of text named with =name is displayed at this point.

I suppose these could be called =define and =display, or anything
really.  The advantage I see over pod is that you could document
the methods once only, and have all the directives to create the manual
at the end, in the correct order for the manual.

Of course, then decisions must be made about whether to ignore or warn
or exit when references to undefined names and unused definitions are
encountered...

	Hugh
	hgs / dmu.ac.uk