mandown 0.0.9 → 0.0.10

data/lib/bibdown_lib.rb

@@ -20,7 +20,7 @@
 require 'yaml'
 
 # Define the text that is displayed when the user asks for documentation
-def documentation
+def bibdown_documentation
 <<END
 
 
@@ -504,7 +504,7 @@ end
 def bibdown_main
   # Handle request for documentation.
   if ARGV.length > 0 && ARGV[0] == '--help'
-    puts documentation
+    puts bobdown_documentation
     exit
   end
   

data/lib/mandown/version.rb

@@ -2,7 +2,7 @@ module Mandown #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
     MINOR = 0
-    TINY  = 9
+    TINY  = 10
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/secdown_lib.rb

@@ -18,13 +18,15 @@
 ################################################################################
 
 # Define the text that is displayed when the user asks for documentation
-def documentation
+def secdown_documentation
 <<END
 
 
   secdown --- part of the Mandown set of tools.
   
-  secdown processes standard input and inserts section numbers in titles.
+  secdown processes standard input and:
+    * inserts section numbers in titles;
+    * allows references to other sections to be made.
     
   Copyright © 2008 Chris Rose. 
   Distributed according to the GNU General Public License.
@@ -77,6 +79,39 @@ def documentation
   style.
   
   secdown does not insert a heading number for '# Bibliography'.
+  
+  secdown provides a way to reference other sections. To label a section (or 
+  subsection, etc.), insert a line containing a label of the form 
+  'label:some-label' somehwere in the section you want to reference. To 
+  reference the section, use the syntax 'sec:some-label'. secdown will remove 
+  the label definitions and replace the section references with something like 
+  'section 1.2'.
+  
+  ------------------------------- Example -------------------------------------
+
+  The following text
+
+      # This is a heading  
+      label:first-section
+  
+      This is a reference to the second section, sec:second-section.
+  
+      # This is another heading
+      label:second-section
+      
+      This is a reference to the first section, sec:first-section.
+  
+  Would be turned into
+  
+      # 1 This is a heading
+      
+      This is a reference to the second section, section 2.
+      
+      # 2 This is another heading
+      
+      This is a reference to the first section, section 1.  
+  
+  ------------------------------- End of example ------------------------------
 
   See also:
   ---------
@@ -204,12 +239,63 @@ def insert_header_levels(lines, ignore_bibliography = true)
   ret_val
 end
 
+# Take a header string that contains a leading section number and return that
+# number.
+def get_section_number_from_header(header)
+  tmp = header.scan(/(\d+((\.\d)+))/)
+  if tmp.empty?
+    header.scan(/(\d+)/)[0][0]
+  else
+    tmp[0][0]
+  end
+end
+
+
+# Take a manuscript, as an array of lines, that has been processed by
+# insert_header_levels, and replace isnstances of 'sec:some-label' with the
+# section number that the the label was defined in using 'label:some-label'.
+# Remove lines that contain the label definition and return the result.
+def replace_section_references(lines)
+  # First parse the lines to get a mapping between the label names and the
+  # section numbers they appear in.
+  current_section_number = nil
+  label_section_map = {} # Will map labels to section numbers.
+  ret_val = []
+  lines.each do |line|
+    # Get the label:some-label string, if it is on this line, as an array.
+    label_string_arr = line.scan(/^label:\w+[-_\.]*\w*/)
+    
+    if atx_header?(line)
+      current_section_number = get_section_number_from_header(line)
+    elsif !label_string_arr.empty?
+      label = label_string_arr[0].split('label:')[1] # Get the label.
+      label_section_map[label] = current_section_number
+      line = nil # Kill off the label.
+    else
+      # Do nothing.
+    end
+    ret_val.push(line) unless line.nil?
+  end
+
+  # Now process ret_val to replace instances of 'sec:some-label' with 'section
+  # 3.2' or whatever.
+  ret_val.each_index do |i|
+    label_section_map.each_pair do |key, value|
+      ret_val[i].gsub!("sec:#{key}", "section #{value}")
+    end
+    p ret_val[i]
+  end
+  
+  ret_val
+end
+
+
 
 # Read the manuscript from standard input and insert appropriately nested level numbering (e.g. '2.1') and send the result to standard output.
 def secdown_main
   # Handle request for documentation.
   if ARGV.length > 0 && ARGV[0] == '--help'
-    puts documentation
+    puts secdown_documentation
     exit
   end
   

data/test/test_secdown.rb

@@ -142,8 +142,59 @@ class TestSecdown < Test::Unit::TestCase
     # Test that it ignores bibliography headings by default.
     bib_line = ["# Bibliography"]
     assert_equal(bib_line, insert_header_levels(bib_line))
+  end
+  
+  def test_get_section_number_from_header
+    assert_equal('2', get_section_number_from_header('# 2 Some Header'))
+    assert_equal('2.1', get_section_number_from_header('## 2.1 Some Header'))
+    assert_equal('1.2.3', get_section_number_from_header('### 1.2.3 Header'))
+  end
+  
+  
+  def test_replace_section_references
+    source = [
+      '# 1 First Heading',
+      '',
+      'This is a reference to the third heading label sec:lab3.',
+      '',
+      '# 2 Second Heading',
+      '',
+      'label:lab2',
+      '',
+      'This is a reference to sec:lab2.',
+      '',
+      '## 2.1 A subheading',
+      '',
+      'label:lab2.1',
+      '',
+      'This is a reference to the first label in sec:lab2.',
+      'This is a reference the second label in sec:lab2, sec:lab2.1.',
+      '',
+      '# 3 Third heading',
+      '',
+      'label:lab3']
+    
+      expected = [
+        '# 1 First Heading',
+        '',
+        'This is a reference to the third heading label section 3.',
+        '',
+        '# 2 Second Heading',
+        '',
+        '',
+        'This is a reference to section 2.',
+        '',
+        '## 2.1 A subheading',
+        '',
+        '',
+        'This is a reference to the first label in section 2.',
+        'This is a reference the second label in section 2, section 2.1.',
+        '',
+        '# 3 Third heading',
+        '']
+      assert_equal(expected, replace_section_references(source))
     
   end
-
-
+  
+  
 end

data/website/index.html

@@ -33,7 +33,7 @@
     <h1>Academic writing extensions to Markdown</h1>
     <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/mandown"; return false'>
       <p>Get Version</p>
-      <a href="http://rubyforge.org/projects/mandown" class="numbers">0.0.9</a>
+      <a href="http://rubyforge.org/projects/mandown" class="numbers">0.0.10</a>
     </div>
     <h1>&#x2192; &#8216;mandown&#8217;</h1>
 
@@ -50,16 +50,19 @@
 	<p>&#8216;Mandown&#8217; is a portmanteau of &#8216;Markdown&#8217; and &#8216;manuscript&#8217; which I found appropriately amusing (&#8220;Man down!!&#8221;).</p>
 
 
+	<p>Mandown is at an early stage of development and is not quite ready for use on real work. However, it still might be useful to you and I&#8217;d appreciate early feedback. It is easy to install, upgrade and uninstall Mandown, so if you&#8217;re interested, please give it a try.</p>
+
+
 	<h2>Why?</h2>
 
 
 	<p>Academics typically write papers using either LaTeX or Microsoft Word. Word is often favoured by the less technically inclined (or those who are simply ignorant of the existence of alternatives). LaTeX is used for some combination of the following reasons: it&#8217;s free software; it can produce typographically excellent output; LaTeX documents are plain text files which can be edited using powerful text editors (vi, Emacs, TextMate etc.). Those who would otherwise choose LaTeX are often forced to use Word by their co-authors or the publishers of their work, and would like a way to maintain the benefits of their LaTeX environment while being able to produce Word documents. Mandown provides tools to allow this.</p>
 
 
-	<p>Mandown is not attempting to be a document preparation system like LaTeX; if you can use LaTeX you probably should&#8212;-it&#8217;s far more powerful than Mandown. For example, Mandown will have no support for controlling page layout or inserting and controlling graphics (though it will support the concept of figures).</p>
+	<p>Mandown is not attempting to be a document preparation system like LaTeX; if you can use LaTeX you probably should&#8212;it&#8217;s far more powerful than Mandown. For example, Mandown will have no support for controlling page layout or inserting and controlling graphics (though it will support the concept of figures).</p>
 
 
-	<p>Mandown is implemented as a set of command line tools that can be chained together into a pipeline. At this stage of development, only one component of Mandown has been implemented: bibdown allows one to maintain a bibliography in <span class="caps">YAML</span> format and cite papers from it; bibdown replaces citation keys with citation numbers and renders the bibliography using appropriate Markdown syntax. In future, further extensions to Markdown will be developed and implemented (e.g. figdown will support figures, another tool will support sectioning, labels and referring, etc.). Mandown is distributed as a gem for ease of installation (see the next section).</p>
+	<p>Mandown is implemented as a set of command line tools that can be chained together into a pipeline. In future, further extensions to Markdown will be developed and implemented (e.g. figdown will support figures, another tool will support sectioning, labels and referring, etc.). Mandown is distributed as a gem for ease of installation (see the next section).</p>
 
 
 	<h2>Installing</h2>
@@ -70,13 +73,13 @@
 
 <pre>sudo gem install mandown</pre>
 
-	<p>If you are confused already, read the <a href="http://rubygems.org/read/chapter/1#page1">Really Quick Start guide</a> from the RubyGems user guide and note that you may or may not need the <a href="http://en.wikipedia.org/wiki/Sudo">sudo</a> command (it&#8217;s necessary on Mac <span class="caps">OS X</span>); on some systems you might need to become the super user first by running the <code>su</code> command and entering the super user&#8217;s password, and then running <code>gem install mandown</code>.</p>
+	<p>(If you are confused already, read the <a href="http://rubygems.org/read/chapter/1#page1">Really Quick Start guide</a> from the RubyGems user guide and note that you may or may not need the <a href="http://en.wikipedia.org/wiki/Sudo">sudo</a> command: it&#8217;s necessary on Mac <span class="caps">OS X</span>, but on other systems you might need to become the super user first by running the <code>su</code> command and entering the super user&#8217;s password, and then running <code>gem install mandown</code>.)</p>
 
 
-	<p>This will add the Mandown executables (executable Ruby scripts) to your $PATH, which include the following: bibdown.</p>
+	<p>This will add the Mandown programs (executable Ruby scripts).</p>
 
 
-	<p>You will also need to install a suitable Markdown processor; I recommend <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> which can convert Markdown to multiple output formats, including <span class="caps">RTF</span> which can be opened using Microsoft Word.</p>
+	<p>You will also need to install a suitable Markdown processor. I recommend <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> which can convert Markdown to multiple output formats, including <span class="caps">RTF</span> which can be opened using Microsoft Word.</p>
 
 
 	<h2>The tools</h2>
@@ -96,11 +99,10 @@
 
 
 	<p>First you need to write a manuscript using a combination of the Markdown and
-Mandown syntaxes, but to get you started Mandown includes a sample Mandown document (see the example, below). Markdown and Mandown are very simple and all you need is a plain text editor.</p>
+Mandown syntaxes, but to get you started Mandown includes a sample Mandown document (see the example, below). Markdown and Mandown are very simple and all you need is a plain text editor (don&#8217;t save your Mandown files as Word documents, they must be plain text files).</p>
 
 
-	<p>To
-learn Markdown, see the <a href="http://daringfireball.net/projects/markdown/syntax">Markdown
+	<p>To learn Markdown, see the <a href="http://daringfireball.net/projects/markdown/syntax">Markdown
 documentation</a> (note that
 <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> is the recommended Markdown processor
 for academic applications).</p>
@@ -131,7 +133,7 @@ for academic applications).</p>
 	<p>The <code>mandown-sample</code> program simply outputs the sample manuscript.</p>
 
 
-	<p>(Note how papers are cited using the <code>cite:</code> command and have a quick look at the <span class="caps">YAML</span>-format bibliography towards the end of the file.)</p>
+	<p>(Note how papers are cited using the <code>cite:</code> command. Also scroll to the bottom and have a quick look at the <span class="caps">YAML</span>-format bibliography.)</p>
 
 
 	<p>We want to process this document using Mandown (and then Pandoc), so first save the sample to a file:</p>
@@ -160,6 +162,30 @@ for academic applications).</p>
 <pre>cat my-manu.txt | bibdown | secdown &gt; my-manu-out.txt</pre>
 <pre>pandoc ...</pre>
 
+	<h2>Upgrading</h2>
+
+
+	<p>Mandown is undergoing steady development and currently has a 0.0.x release number. I&#8217;m hoping to get first versions of the most important tools finished soon. At this point Mandown will be given the 0.1.0 version number, to indicate that it is suitable for people to start using it (even if just in an experimental context).</p>
+
+
+	<p>If you use the early versions of Mandown and want to keep up-to-date, simply run</p>
+
+
+<pre>sudo gem update mandown</pre>
+
+	<p>You may also optionally remove previous versions using:</p>
+
+
+<pre>sudo gem uninstall mandown --version x.y.z</pre>
+
+	<p>or</p>
+
+
+<pre>sudo gem uninstall mandown</pre>
+
+	<p>and then install Mandown as usual.</p>
+
+
 	<h2>Help, gotchas and <span class="caps">FAQ</span></h2>
 
 

data/website/index.txt

@@ -10,14 +10,16 @@ Writing a paper using Mandown is simple: write your paper using standard Markdow
 
 'Mandown' is a portmanteau of 'Markdown' and 'manuscript' which I found appropriately amusing ("Man down!!").
 
+Mandown is at an early stage of development and is not quite ready for use on real work. However, it still might be useful to you and I'd appreciate early feedback. It is easy to install, upgrade and uninstall Mandown, so if you're interested, please give it a try.
+
 
 h2. Why?
 
 Academics typically write papers using either LaTeX or Microsoft Word. Word is often favoured by the less technically inclined (or those who are simply ignorant of the existence of alternatives). LaTeX is used for some combination of the following reasons: it's free software; it can produce typographically excellent output; LaTeX documents are plain text files which can be edited using powerful text editors (vi, Emacs, TextMate etc.). Those who would otherwise choose LaTeX are often forced to use Word by their co-authors or the publishers of their work, and would like a way to maintain the benefits of their LaTeX environment while being able to produce Word documents. Mandown provides tools to allow this.
 
-Mandown is not attempting to be a document preparation system like LaTeX; if you can use LaTeX you probably should---it's far more powerful than Mandown. For example, Mandown will have no support for controlling page layout or inserting and controlling graphics (though it will support the concept of figures).
+Mandown is not attempting to be a document preparation system like LaTeX; if you can use LaTeX you probably should--it's far more powerful than Mandown. For example, Mandown will have no support for controlling page layout or inserting and controlling graphics (though it will support the concept of figures).
 
-Mandown is implemented as a set of command line tools that can be chained together into a pipeline. At this stage of development, only one component of Mandown has been implemented: bibdown allows one to maintain a bibliography in YAML format and cite papers from it; bibdown replaces citation keys with citation numbers and renders the bibliography using appropriate Markdown syntax. In future, further extensions to Markdown will be developed and implemented (e.g. figdown will support figures, another tool will support sectioning, labels and referring, etc.). Mandown is distributed as a gem for ease of installation (see the next section).
+Mandown is implemented as a set of command line tools that can be chained together into a pipeline. In future, further extensions to Markdown will be developed and implemented (e.g. figdown will support figures, another tool will support sectioning, labels and referring, etc.). Mandown is distributed as a gem for ease of installation (see the next section).
 
 
 h2. Installing
@@ -26,11 +28,12 @@ Mandown is distributed as a Ruby gem (so you'll need Ruby and RubyGems installed
 
 <pre>sudo gem install mandown</pre>
 
-If you are confused already, read the "Really Quick Start guide":http://rubygems.org/read/chapter/1#page1 from the RubyGems user guide and note that you may or may not need the "sudo":http://en.wikipedia.org/wiki/Sudo command (it's necessary on Mac OS X); on some systems you might need to become the super user first by running the <code>su</code> command and entering the super user's password, and then running <code>gem install mandown</code>.
+(If you are confused already, read the "Really Quick Start guide":http://rubygems.org/read/chapter/1#page1 from the RubyGems user guide and note that you may or may not need the "sudo":http://en.wikipedia.org/wiki/Sudo command: it's necessary on Mac OS X, but on other systems you might need to become the super user first by running the <code>su</code> command and entering the super user's password, and then running <code>gem install mandown</code>.)
+
+This will add the Mandown programs (executable Ruby scripts).
 
-This will add the Mandown executables (executable Ruby scripts) to your $PATH, which include the following: bibdown.
+You will also need to install a suitable Markdown processor. I recommend "Pandoc":http://johnmacfarlane.net/pandoc/ which can convert Markdown to multiple output formats, including RTF which can be opened using Microsoft Word.
 
-You will also need to install a suitable Markdown processor; I recommend "Pandoc":http://johnmacfarlane.net/pandoc/ which can convert Markdown to multiple output formats, including RTF which can be opened using Microsoft Word.
 
 h2. The tools
 
@@ -44,10 +47,9 @@ The following Mandown tools are provided in the latest release:
 h2. Usage
 
 First you need to write a manuscript using a combination of the Markdown and
-Mandown syntaxes, but to get you started Mandown includes a sample Mandown document (see the example, below). Markdown and Mandown are very simple and all you need is a plain text editor.
+Mandown syntaxes, but to get you started Mandown includes a sample Mandown document (see the example, below). Markdown and Mandown are very simple and all you need is a plain text editor (don't save your Mandown files as Word documents, they must be plain text files).
 
-To
-learn Markdown, see the "Markdown
+To learn Markdown, see the "Markdown
 documentation":http://daringfireball.net/projects/markdown/syntax (note that
 "Pandoc":http://johnmacfarlane.net/pandoc/ is the recommended Markdown processor
 for academic applications).
@@ -70,7 +72,7 @@ Let's read an example Mandown manuscript using the <code>less</code> pager:
 
 The <code>mandown-sample</code> program simply outputs the sample manuscript.
 
-(Note how papers are cited using the <code>cite:</code> command and have a quick look at the YAML-format bibliography towards the end of the file.)
+(Note how papers are cited using the <code>cite:</code> command. Also scroll to the bottom and have a quick look at the YAML-format bibliography.)
 
 We want to process this document using Mandown (and then Pandoc), so first save the sample to a file:
 
@@ -94,6 +96,24 @@ The Mandown tools are designed to be chained together into a pipeline, so for ex
 <pre>pandoc ...</pre>
 
 
+h2. Upgrading
+
+Mandown is undergoing steady development and currently has a 0.0.x release number. I'm hoping to get first versions of the most important tools finished soon. At this point Mandown will be given the 0.1.0 version number, to indicate that it is suitable for people to start using it (even if just in an experimental context).
+
+If you use the early versions of Mandown and want to keep up-to-date, simply run
+
+<pre>sudo gem update mandown</pre>
+
+You may also optionally remove previous versions using:
+
+<pre>sudo gem uninstall mandown --version x.y.z</pre>
+
+or
+
+<pre>sudo gem uninstall mandown</pre>
+
+and then install Mandown as usual.
+
 
 h2. Help, gotchas and FAQ
 

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: mandown
 version: !ruby/object:Gem::Version 
-  version: 0.0.9
-date: 2008-01-18 00:00:00 +00:00
+  version: 0.0.10
+date: 2008-01-24 00:00:00 +00:00
 summary: Provides simple extensions to Markdown that are useful for academic writing
 require_paths: 
 - lib