From: Hugh Sasse Staff Elec Eng <hgs@...>
Date: 2000-09-30T03:03:26+09:00
Subject: [ruby-talk:5197] ANNOUNCE: rubyweb -- literate programming for ruby?

I have developed a system for re-sequencing embedded documentation
in Ruby programs.  This is designed to interoperate with RDtool, and
it is not in competition with it.  For example, it does not support
different kinds of emphasis, headings, and so on.  Also one can
use "\n=begin_rubyweb"..."\n=end_rubyweb" so that "\n=end " (with a
space) is not matched.

What it does is allow blocks to be given names and then used inside other
named blocks.  They may thus appear in any desired sequence for whatever
purpose.  This could be used for embedding internal and external
documentation in a program, or embedding LaTeX and troff documents in the
same file, or even as a pre-processor to avoid repeating your code.  I am
hoping that it will be useful enough to provide a way to do things I never
considered.

Caveats:

I have tested this and have used it to my own satisfaction.  I have not
written the RubyUnit tests for it, and I believe that from that viewpoint
the code is poorly structured.  Suggestions on re-factoring to enable
better testing, etc, would be welcome.

The code is supplied under the same terms as Ruby itself.  It is offered
in the hope that it might be useful to others, but without warranty.  I
have not really done much with literate programming, so Rubyweb may not be
sufficiently useful.  Constructive criticism is welcome.

The details and the code may be found at

http://www.eng.cse.dmu.ac.uk/~hgs/ruby/rubyweb/index.html

I'm not sure about how to submit this to the RAA, but I will
wait for some peer review first, anyway :-)

	Hugh
	hgs@dmu.ac.uk