Introductory talk on Literate Maruku, the first gem released by the Ruby User Group Berlin - rug-b.

1. Literate Maruku
www.rug-b.com/wiki/show/schmidt
2007-10-04

2. Literate Programming
Instead of imagining that our main task is to
instruct a computer what to do, let us
concentrate rather on explaining to human
beings what we want a computer to do.
--- Donald E. Knuth (1984)

3. Implemented in
• WEB, CWEB, noweb
• (Pascal, C, any) Code embedded in LaTeX
• RubyWeb
• Extended RDoc syntax
• Literate Ruby (Ruby Quiz #102)

4. but my problem was ...

5. Primary use case
• Write documentation for a library
• Usage examples
• Tutorials
• How-Tos

6. Primary use case
• Write documentation for a library
• Usage examples
Be sure that
• Tutorials they work !
• How-Tos Make them
tests !!!

7. Some lines in test_helper.rb
• For more information see
Executable code in usage examples (rubyurl.com/0fO)
# The String class provides a * method
# which allows easy duplication.
example do
output_of(quot;blaquot; * 2) == quot;blablaquot;
output_of(quot;blaquot; * 3) == quot;blablablaquot;
end

8. Want that on a website?

9. RDoc ???

10. RDoc ???
Annotates
methods and
classes,
not blocks

11. Literate Maruku

12. Libraries and Names
• Maruku is as Markdown library for Ruby
• Markdown was originally done for Perl
• BlueCloth is the most popular implementation
• Maruku is better !!!

13. Markdown
Markdown Heading
================
A paragraph is separated by nn.
* a bullet list
> a quote
a code block

14. Maruku brings Meta data
Markdown Heading
================
A paragraph is separated by nn.
{: class=introduction}
This will be replaced with a table
of contents...
{: toc}

15. Literate Maruku brings fun
### String#*
The String class provides a `*` method
which allows easy duplication.
example do
output_of(quot;blaquot; * 2) == quot;blablaquot;
output_of(quot;blaquot; * 3) == quot;blablablaquot;
end
{: execute}
string.mkd

16. Literate Maruku brings fun
### String#*
$ literate_maruku string.mkd
The String class provides a `*` method
# executes the file
which allows easy duplication.
# like “ruby string.rb“ does
example do
$ literate_maruku --output-dir=. string.mkd
output_of(quot;blaquot; * 2) == quot;blablaquot;
# executes the file
output_of(quot;blaquot; * 3) == quot;blablablaquot;
# and end
generates string.html
{: execute}
string.mkd

17. But ...
No stack traces !

18. Where can I get it?
$ gem install literate_maruku
rug-b.rubyforge.org/literate_maruku

19. Example usage
in ContextR

20. ???