literate_maruku 0.1.0

data/tasks/deployment.rake

@@ -0,0 +1,27 @@
+desc 'Release the website and new gem version'
+task :deploy => [:check_version, :website, :release] do
+  puts "Remember to create SVN tag:"
+  puts "svn copy svn+ssh://rubyforge.org/var/svn/#{PATH}/trunk " +
+    "svn+ssh://rubyforge.org/var/svn/#{PATH}/tags/REL-#{VERS} "
+  puts "Suggested comment:"
+  puts "Tagging release #{CHANGES}"
+end
+
+desc 'Runs tasks website_generate and install_gem as a local deployment of the gem'
+task :local_deploy => [:website_generate, :install_gem]
+
+task :check_version do
+  unless ENV['VERSION']
+    puts 'Must pass a VERSION=x.y.z release version'
+    exit
+  end
+  unless ENV['VERSION'] == VERS
+    puts "Please update your version.rb to match the release version, currently #{VERS}"
+    exit
+  end
+end
+
+desc 'Install the package as a gem, without generating documentation(ri/rdoc)'
+task :install_gem_no_doc => [:clean, :package] do
+  sh "#{'sudo ' unless Hoe::WINDOZE }gem install pkg/*.gem --no-rdoc --no-ri"
+end

data/tasks/environment.rake

@@ -0,0 +1,7 @@
+task :ruby_env do
+  RUBY_APP = if RUBY_PLATFORM =~ /java/
+    "jruby"
+  else
+    "ruby"
+  end unless defined? RUBY_APP
+end

data/tasks/website.rake

@@ -0,0 +1,17 @@
+desc 'Generate website files'
+task :website_generate => :ruby_env do
+  (Dir['website/**/*.txt'] - Dir['website/version*.txt']).each do |txt|
+    sh %{ #{RUBY_APP} script/txt2html #{txt} > #{txt.gsub(/txt$/,'html')} }
+  end
+end
+
+desc 'Upload website files to rubyforge'
+task :website_upload do
+  host = "#{rubyforge_username}@rubyforge.org"
+  remote_dir = "/var/www/gforge-projects/#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+  local_dir = 'website'
+  sh %{rsync -aCv #{local_dir}/ #{host}:#{remote_dir}}
+end
+
+desc 'Generate and upload website files'
+task :website => [:website_generate, :website_upload, :publish_docs]

data/test/test_document.mkd

@@ -0,0 +1,25 @@
+Test Literate Maruku Document
+=============================
+
+This contains some code examples, that are used for testing.
+
+Normal markdown code environments are simply rendered
+
+    $this_code_block_will_not_be_executed = true
+
+Annotated code environments are rendered and executed - in the root context.
+
+    $this_code_block_will_be_executed = true
+{: execute}
+
+Code definitions also work across code environments, of course.
+
+    a_test_method = lambda do |string|
+      string
+    end
+{: execute}
+
+And you may automatically attach the output of your code blocks.
+
+    a_test_method.call("a test string")
+{: execute attach_output}

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/literate_maruku'

data/test/test_literate_maruku.rb

@@ -0,0 +1,70 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+class TestMaRuKu < Test::Unit::TestCase
+  def test_should_not_execute_each_and_every_code_environment
+    doc = Maruku.new(%q{    THIS_CONSTANT_WILL_NOT_BE_DEFINED = true})
+
+    output = %q{
+<pre><code>THIS_CONSTANT_WILL_NOT_BE_DEFINED = true</code></pre>
+}
+
+    assert_equal output, doc.to_html 
+    assert !Object.const_defined?("THIS_CONSTANT_WILL_NOT_BE_DEFINED")
+  end
+
+  def test_should_execute_code_with_metadata
+    doc = Maruku.new(%q{
+    TEST_WORKS = true
+{: execute}})
+
+    output = %q{
+<pre><code>TEST_WORKS = true</code></pre>
+}
+
+    assert_equal output, doc.to_html 
+    assert Object.const_defined?("TEST_WORKS")
+    assert TEST_WORKS
+  end
+  
+  def test_should_attach_output_if_requested
+    doc = Maruku.new(%q{
+    1 + 1 == 2
+{: execute attach_output}})
+
+    output = %q{
+<pre><code>1 + 1 == 2
+&gt;&gt; true</code></pre>
+}
+
+    assert_equal output, doc.to_html 
+  end
+end
+
+class LiterateMarukuTest < Test::Unit::TestCase
+  def setup
+    @dirname = File.dirname(__FILE__)
+    @base_filename = "test_document"
+
+    @mkd_filename =  @base_filename + ".mkd"
+    @html_filename =  @base_filename + ".html"
+
+    @full_filename = File.join(@dirname, @html_filename)
+
+    File.delete(@full_filename) if File.exists?(@full_filename)
+  end
+
+  def teardown
+    File.delete(@full_filename) if File.exists?(@full_filename)
+  end
+
+  def test_require_should_execute_annotated_code_environments
+    LiterateMaruku.require(@mkd_filename)
+    assert $this_code_block_will_be_executed 
+  end
+
+  def test_require_should_generate_an_html_file
+    LiterateMaruku.require(@mkd_filename, :output => @dirname)
+
+    assert File.exists?(@full_filename)
+  end
+end

data/website/index.html

@@ -0,0 +1,209 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <link rel="stylesheet" href="stylesheets/screen.css" type="text/css" media="screen" />
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>
+      literate_maruku
+  </title>
+  <script src="javascripts/rounded_corners_lite.inc.js" type="text/javascript"></script>
+<style>
+
+</style>
+  <script type="text/javascript">
+    window.onload = function() {
+      settings = {
+          tl: { radius: 10 },
+          tr: { radius: 10 },
+          bl: { radius: 10 },
+          br: { radius: 10 },
+          antiAlias: true,
+          autoPad: true,
+          validTags: ["div"]
+      }
+      var versionBox = new curvyCorners(settings, document.getElementById("version"));
+      versionBox.applyCornersToAll();
+    }
+  </script>
+</head>
+<body>
+<div id="main">
+
+    <h1>literate_maruku</h1>
+    <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/literate_maruku"; return false'>
+      <p>Get Version</p>
+      <a href="http://rubyforge.org/projects/literate_maruku" class="numbers">0.1.0</a>
+    </div>
+    <h1>&#x2192; &#8216;literate_maruku&#8217;</h1>
+
+
+	<h2>What</h2>
+
+
+	<p>Literate Maruku is a literate programming libary for ruby based on the markdown
+libary maruku. This is basically what the name say, isn&#8217;t it?</p>
+
+
+	<h2>Installing</h2>
+
+
+	<p><pre class='syntax'><span class="ident">sudo</span> <span class="ident">gem</span> <span class="ident">install</span> <span class="ident">literate_maruku</span></pre></p>
+
+
+	<h2>The basics</h2>
+
+
+	<p>There are to possible accesses to the libary. A programming <span class="caps">API</span> and a command 
+line interface. The first may be used to write better documented tests, 
+for example. Just write a little bit of code in your test_helper and call
+Literate Maruku there and your markdown formatted tests will be executed.</p>
+
+
+	<p>The command line interface may the be used inside of a rake task for example to
+generate some html files out of your test files, that demonstrate their usage. 
+We have used this approach in ContextR, so have a look there to get some input.</p>
+
+
+	<h2>Demonstration of usage</h2>
+
+
+	<h3>The Markdown Syntax</h3>
+
+
+	<p>Literate Maruku simply extends the functionality of Maruku and adds some methods
+to make standard use cases easier. You may find detailed information about maruku at <a href="http://maruku.rubyforge.org/">their project page</a> . They added some nice
+features to 
+<a href="http://daringfireball.net/projects/markdown/syntax">Markdown formatting</a> , esp.
+the <a href="http://maruku.rubyforge.org/proposal.html">meta data syntax</a> which made
+implementing literate maruku a charm.</p>
+
+
+	<p>Wanna see examples? Okay, here they are:</p>
+
+
+	<h4>Markdown</h4>
+
+
+<pre><code>
+This is a normal paragraph, followed by a plain old code block
+
+    literate_maruku == maruku + ruby
+
+And the following code block will not only be rendered, but also executed.
+
+    def echo_block(string)
+      (0...(text.size)).map{|i| text[0..i]}.reverse.join(" ... ")
+    end
+{: execute}
+
+And, finally, the following block will be executed and its output will be 
+rendered as well.
+
+    echo_block("hallo")
+{: execute attach_output}
+</code></pre>
+
+	<p>This is how you may write your ruby code. And this is what will be generated 
+out of it:</p>
+
+
+	<h4><span class="caps">HTML</span></h4>
+
+
+	<p>This is a normal paragraph, followed by a plain old code block</p>
+
+
+<pre><code>literate_maruku == maruku + ruby
+</code></pre>
+
+	<p>And the following code block will not only be rendered, but also executed.</p>
+
+
+	<pre><code>def echo_block(string)
+  (0...(text.size)).map{|i| text[0..i]}.reverse.join(" ... ")
+end</code></pre>
+
+
+	<p>And, finally, the following block will be executed and its output will be 
+rendered as well.</p>
+
+
+	<pre><code>echo_block("hallo")
+&gt;&gt; "hello ... hell ... hel ... he ... h"</code></pre>
+
+
+	<h3>The command line interface</h3>
+
+
+	<p>Simply call <code>literate_maruku filename.mkd</code> to load your markdown formatted ruby
+files. This will execute the code but not generate any output. It basically works like a simpe <code>ruby filename.rb</code> call, but without all the command line parameters the <code>ruby</code> command supports.</p>
+
+
+	<p>If you like to generate some html files, append an additional parameter, which
+tells literate_maruku where to put the output.  
+<code>literate_maruku --output_path=test filename.mkd</code> would file the output of 
+<code>filename.mkd</code> to <code>test/filename.html</code>. That&#8217;s all, folks.</p>
+
+
+	<h3>The programming interface</h3>
+
+
+	<p>To use Literate Maruku in your own special way simply use the 
+<code>LiterateMaruku#require</code> method.</p>
+
+
+	<pre><code>require 'literate_maruku'</code></pre>
+
+
+	<pre><code>LiterateMaruku.require('filename.mkd') # or
+LiterateMaruku.require('filename.mkd', :output =&gt; "test")</code></pre>
+
+
+	<p>These will have the same result as the command line examples.</p>
+
+
+	<p>If you are unhappy with these little possibilities, no problem: You may still
+use the standard maruku interface to do with your markdown string, what you like
+after require&#8217;ing literate_maruku the maruku code base is extended for the 
+literate programming style.</p>
+
+
+	<h2>Other resources</h2>
+
+
+	<ul>
+	<li><a href="http://groups.google.com/group/rug-b">Mailing list</a></li>
+		<li><a href="http://rug-b.rubyforge.org/literate_maruku/rdoc">RDoc</a></li>
+	</ul>
+
+
+	<h2>How to submit patches</h2>
+
+
+	<p>Read the <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/">8 steps for fixing other people&#8217;s code</a> and for section <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups">8b: Submit patch to Google Groups</a>, use the Google Group above.</p>
+
+
+	<p>The trunk repository is <code>svn://rubyforge.org/var/svn/rug-b/literate_maruku/trunk</code> for anonymous access.</p>
+
+
+	<h2>License</h2>
+
+
+	<p>This code is free to use under the terms of the <span class="caps">MIT</span> license.</p>
+
+
+	<h2>Contact</h2>
+
+
+	<p>Comments are welcome. Send an email to <a href="mailto:ruby@schmidtwisser.de">Gregor Schmidt</a> or via the <a href="http://groups.google.com/group/literate_maruku">mailing list</a></p>
+    <p class="coda">
+      <a href="ruby@schmidtwisser.de">Gregor Schmidt</a>, 30th September 2007<br>
+      Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
+    </p>
+</div>
+
+<!-- insert site tracking codes here, like Google Urchin -->
+
+</body>
+</html>

data/website/index.txt

@@ -0,0 +1,131 @@
+h1. literate_maruku
+
+h1. → 'literate_maruku'
+
+
+h2. What
+
+Literate Maruku is a literate programming libary for ruby based on the markdown
+libary maruku. This is basically what the name say, isn't it?
+
+
+h2. Installing
+
+<pre syntax="ruby">sudo gem install literate_maruku</pre>
+
+h2. The basics
+
+There are to possible accesses to the libary. A programming API and a command 
+line interface. The first may be used to write better documented tests, 
+for example. Just write a little bit of code in your test_helper and call
+Literate Maruku there and your markdown formatted tests will be executed.
+
+The command line interface may the be used inside of a rake task for example to
+generate some html files out of your test files, that demonstrate their usage. 
+We have used this approach in ContextR, so have a look there to get some input.
+
+h2. Demonstration of usage
+
+h3. The Markdown Syntax
+
+Literate Maruku simply extends the functionality of Maruku and adds some methods
+to make standard use cases easier. You may find detailed information about maruku at "their project page":http://maruku.rubyforge.org/ . They added some nice
+features to 
+"Markdown formatting":http://daringfireball.net/projects/markdown/syntax , esp.
+the "meta data syntax":http://maruku.rubyforge.org/proposal.html which made
+implementing literate maruku a charm.
+
+Wanna see examples? Okay, here they are:
+
+h4. Markdown
+
+<pre><code>
+This is a normal paragraph, followed by a plain old code block
+
+    literate_maruku == maruku + ruby
+
+And the following code block will not only be rendered, but also executed.
+
+    def echo_block(string)
+      (0...(text.size)).map{|i| text[0..i]}.reverse.join(" ... ")
+    end
+{: execute}
+
+And, finally, the following block will be executed and its output will be 
+rendered as well.
+
+    echo_block("hallo")
+{: execute attach_output}
+</code></pre>
+
+This is how you may write your ruby code. And this is what will be generated 
+out of it:
+
+h4. HTML
+
+
+
+This is a normal paragraph, followed by a plain old code block
+
+<pre><code>literate_maruku == maruku + ruby
+</code></pre>
+
+And the following code block will not only be rendered, but also executed.
+
+  def echo_block(string)
+    (0...(text.size)).map{|i| text[0..i]}.reverse.join(" ... ")
+  end
+
+And, finally, the following block will be executed and its output will be 
+rendered as well.
+
+  echo_block("hallo")
+  >> "hello ... hell ... hel ... he ... h"
+
+
+h3. The command line interface
+
+Simply call @literate_maruku filename.mkd@ to load your markdown formatted ruby
+files. This will execute the code but not generate any output. It basically works like a simpe @ruby filename.rb@ call, but without all the command line parameters the @ruby@ command supports.
+
+If you like to generate some html files, append an additional parameter, which
+tells literate_maruku where to put the output.  
+@literate_maruku --output_path=test filename.mkd@ would file the output of 
+@filename.mkd@ to @test/filename.html@. That's all, folks.
+
+h3. The programming interface
+
+To use Literate Maruku in your own special way simply use the 
+@LiterateMaruku#require@ method.
+
+    require 'literate_maruku'
+    
+    LiterateMaruku.require('filename.mkd') # or
+    LiterateMaruku.require('filename.mkd', :output => "test")
+
+These will have the same result as the command line examples.
+
+If you are unhappy with these little possibilities, no problem: You may still
+use the standard maruku interface to do with your markdown string, what you like
+after require'ing literate_maruku the maruku code base is extended for the 
+literate programming style.
+
+h2. Other resources 
+
+* "Mailing list":http://groups.google.com/group/rug-b
+* "RDoc":http://rug-b.rubyforge.org/literate_maruku/rdoc
+
+h2. How to submit patches
+
+Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8b: Submit patch to Google Groups":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.
+
+The trunk repository is <code>svn://rubyforge.org/var/svn/rug-b/literate_maruku/trunk</code> for anonymous access.
+
+h2. License
+
+This code is free to use under the terms of the MIT license. 
+
+h2. Contact
+
+Comments are welcome. Send an email to "Gregor Schmidt":mailto:ruby@schmidtwisser.de or via the "mailing list":http://groups.google.com/group/literate_maruku
+