From: Ruby Quiz <james@...>
Date: 2006-11-17T22:56:55+09:00
Subject: [QUIZ] Literate Ruby (#102)

The three rules of Ruby Quiz:

1.  Please do not post any solutions or spoiler discussion for this quiz until
48 hours have passed from the time on this message.

2.  Support Ruby Quiz by submitting ideas as often as you can:

http://www.rubyquiz.com/

3.  Enjoy!

Suggestion:  A [QUIZ] in the subject of emails about the problem helps everyone
on Ruby Talk follow the discussion.  Please reply to the original quiz message,
if you can.

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

by Justin Bailey

"Literate Programming"[1] is an idea popularized by Donald Knuth, where the
traditional order of code and comments in a source file is switched. Instead of
using special delimiters to mark comments, special delimiters are used to mark
*code*.

Innocuous as it sounds, this style of programming makes for a great way to post
code snippets, tutorials, or even whole libraries to mailing lists, blogs, and
web pages. It's also an excellent way to develop your CS homework ;)

There are, of course, a variety of ways to make a source file "literate". One
popular method is called "bird notation". Code is delimited by lines starting
with ">":

	> puts "The first line of literate Ruby you may have ever seen"

Another method, used in the Haskell language, is borrowed from LateX and makes
it very easy to embed working code into longer papers:

	\begin{code}
	puts "And here, we have"
	puts "the second and third lines of literate Ruby to be produced."
	\end{code}

Beyond *how* to represent literate code, a host of issues present themselves.
Can a class, method, or even string span multiple code sections? Can the
different styles of code demarcation be mixed in one file? How do you "escape"
code demarcation? What about inserting the output of code lines into the same
literate file?

Your task is to enable literate Ruby. What that means is up to you. Is literate
programming only available at the file level (e.g. only files ending in ".lrb"
are considered literate)? Or is literate programming supported with
eval/class_eval/module_eval? Would this enable embedded literated here (i.e. <<)
docs?

At the minimum, this quiz should be seen as a literate program, and your code
should be able to run it!  [Editor's Note: The indention added to Ruby blocks in
this quiz are a side effect of the Ruby Quiz software.  Feel free to remove them
when treating this quiz as literate code.  --JEG2]

Justin

	> puts "Here's to hoping you enjoyed the quiz!"

[1] http://en.wikipedia.org/wiki/Literate_programming