[GH-28]: Descriptive section names.

Header sections will get a descriptive hash anchor: rather than
`section-1`, the section will be given an id containing the header text
with spaces stripped and replaced with `_`.  `section-Header_Goes_Here`
for instance.

Thanks to [Luke Andrew][1] for the initial work on this patch.

[1]: https://github.com/zyx

lib/rocco/layout.mustache

@@ -29,10 +29,10 @@
   </thead>
   <tbody>
     {{#sections}}
-    <tr id='section-{{ num }}'>
+    <tr id='section-{{ section_id }}'>
       <td class=docs>
         <div class="pilwrap">
-          <a class="pilcrow" href="#section-{{ num }}">&#182;</a>
+          <a class="pilcrow" href="#section-{{ section_id }}">&#182;</a>
         </div>
         {{{ docs }}}
       </td>

lib/rocco/layout.rb

@@ -18,16 +18,19 @@ class Rocco::Layout < Mustache
   def sections
     num = 0
     @doc.sections.map do |docs,code|
+      is_header = /^<h.>(.+)<\/h.>$/.match( docs )
+      header_text = is_header && is_header[1].split.join("_")
+      num += 1
       {
         :docs       =>  docs,
         :docs?      =>  !docs.empty?,
-        :header?    =>  /^<h.>.+<\/h.>$/.match( docs ),
+        :header?    =>  is_header,
 
         :code       =>  code,
         :code?      =>  !code.empty?,
 
         :empty?     =>  ( code.empty? && docs.empty? ),
-        :num        =>  (num += 1)
+        :section_id =>  is_header ? header_text : num
       }
     end
   end

test/test_descriptive_section_names.rb

@@ -0,0 +1,29 @@
+require File.dirname(__FILE__) + '/helper'
+
+class RoccoDescriptiveSectionNamesTests < Test::Unit::TestCase
+  def test_section_name
+    r = roccoize( "filename.rb", "# # Comment 1\ndef codeblock\nend\n" )
+    html = r.to_html
+    assert(
+      html.include?( "<tr id='section-Comment_1'>" ),
+      "The first section should be named"
+    )
+    assert(
+      html.include?( '<a class="pilcrow" href="#section-Comment_1">' ),
+      "The rendered HTML should link to a named section"
+    )
+  end
+  def test_section_numbering
+    r = roccoize( "filename.rb", "# # Header 1\ndef codeblock\nend\n# Comment 1\ndef codeblock1\nend\n# # Header 2\ndef codeblock2\nend" )
+    html = r.to_html
+    assert(
+      html.include?( '<a class="pilcrow" href="#section-Header_1">' ) &&
+      html.include?( '<a class="pilcrow" href="#section-Header_2">' ),
+      "First and second headers should be named sections"
+    )
+    assert(
+      html.include?( '<a class="pilcrow" href="#section-2">' ),
+      "Sections should continue numbering as though headers were counted."
+    )
+  end
+end