RubyGems - codnar - Versions diffs - 0.1.68 → 0.1.73 - Mend

codnar 0.1.68 → 0.1.73

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

data/ChangeLog +17 -0
data/codnar.html +1368 -527
data/doc/system.markdown +56 -15
data/lib/codnar.rb +6 -0
data/lib/codnar/configuration/code.rb +87 -0
data/lib/codnar/configuration/comments.rb +234 -0
data/lib/codnar/configuration/documentation.rb +65 -0
data/lib/codnar/configuration/highlighting.rb +107 -0
data/lib/codnar/data/contents.js +2 -1
data/lib/codnar/haddock.rb +72 -0
data/lib/codnar/rake/split_task.rb +6 -0
data/lib/codnar/scanner.rb +34 -11
data/lib/codnar/split_configurations.rb +4 -382
data/lib/codnar/string_extensions.rb +4 -3
data/lib/codnar/version.rb +1 -1
data/test/expand_haddock.rb +23 -0
data/test/expand_rdoc.rb +2 -2
data/test/format_comment_configurations.rb +1 -1
data/test/run_weave.rb +2 -3
data/test/split_code.rb +1 -1
data/test/split_combined_configurations.rb +1 -1
data/test/{split_complex_comment_configurations.rb → split_delimited_comment_configurations.rb} +11 -11
data/test/split_denoted_comment_configurations.rb +62 -0
data/test/split_documentation.rb +1 -1
data/test/split_documentation_configurations.rb +1 -1
metadata +16 -7

data/ChangeLog CHANGED Viewed

@@ -1,3 +1,20 @@
+2012-03-18	Oren Ben-Kiki <github-oren@ben-kiki.org>
+	* Fix JS comment.
+	* Fix JS issue; remove unneeded files.
+2012-01-07	Oren Ben-Kiki <github-oren@ben-kiki.org>
+	* Add support for Haddock comments.
+2012-01-04	Oren Ben-Kiki <github-oren@ben-kiki.org>
+	* Support additional ("denoted") kind of comments.
+2011-09-23	Oren Ben-Kiki <github-oren@ben-kiki.org>
+	* Add support for CodeRay syntax highlighting.
 2011-09-13	Oren Ben-Kiki <github-oren@ben-kiki.org>
 	* Add support for GraphViz documentation.

data/codnar.html CHANGED Viewed

@@ -678,14 +678,14 @@ This module contains all the code narrator code.
 <div class='rdoc comment markup'>
 <p>
 This version number. The third number is automatically updated to track the
-number of Git commits by running <tt>rake version</tt>.
+number of Git commits by running <code>rake version</code>.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-  <span class="Type">VERSION</span> = <span class="Special">&quot;</span><span class="Constant">0.1.68</span><span class="Special">&quot;</span>
+  <span class="Type">VERSION</span> = <span class="Special">&quot;</span><span class="Constant">0.1.73</span><span class="Special">&quot;</span>
 end
 </pre>
@@ -1018,7 +1018,9 @@ equal to [ “indentation”, “payload” ].
 </li><li>
 <p>
 The kind field of a transition can be ommitted; by default it is assumed to
-be identical to the pattern kind.
+be identical to the pattern kind. If it ends up <tt>nil</tt>, this
+indicates that there’s no kind assigned by the pattern, and the current
+line should be classified again by the next state.
 </p>
 </li><li>
 <p>
@@ -1250,6 +1252,31 @@ Fill in the name field for state or pattern object.
 <div class="chunk html">
 <pre class='ruby code syntax'>
+</pre>
+<table class='layout'>
+<tr>
+<td class='indentation'>
+<pre></pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+A pattern that matches any line and extracts no data; is meant to be used
+for catch-all transitions that transfer the scanning to a different state.
+It is used if no explicit pattern is specified in a transition (that is,
+you can think of this as the <tt>nil</tt> pattern).
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+<span class="Type">CATCH_ALL_PATTERN</span> = {
+  <span class="Special">&quot;</span><span class="Constant">kind</span><span class="Special">&quot;</span> =&gt; <span class="Constant">nil</span>,
+  <span class="Special">&quot;</span><span class="Constant">groups</span><span class="Special">&quot;</span> =&gt; [],
+  <span class="Special">&quot;</span><span class="Constant">regexp</span><span class="Special">&quot;</span> =&gt; <span class="Special">//</span>
+}
 </pre>
 <table class='layout'>
 <tr>
@@ -1269,7 +1296,7 @@ Expand all the shorthands used in the state.
 <span class="PreProc">def</span> <span class="Identifier">expand_state_shorthands</span>(name, state)
   fill_name(name, state, <span class="Special">&quot;</span><span class="Constant">State</span><span class="Special">&quot;</span>)
   state.transitions.each <span class="Statement">do</span> |<span class="Identifier">transition</span>|
-    pattern = transition.pattern = lookup(<span class="Identifier">@syntax</span>.patterns, <span class="Special">&quot;</span><span class="Constant">pattern</span><span class="Special">&quot;</span>, transition.pattern)
+    pattern = transition.pattern = lookup(<span class="Identifier">@syntax</span>.patterns, <span class="Special">&quot;</span><span class="Constant">pattern</span><span class="Special">&quot;</span>, transition.pattern || <span class="Type">CATCH_ALL_PATTERN</span>)
     transition.kind ||= pattern.andand.kind
     transition.next_state = lookup(<span class="Identifier">@syntax</span>.states, <span class="Special">&quot;</span><span class="Constant">state</span><span class="Special">&quot;</span>, transition.next_state || state)
   <span class="Statement">end</span>
@@ -1428,10 +1455,51 @@ Scan the next file line.
 </table>
 <pre class='ruby code syntax'>
 <span class="PreProc">def</span> <span class="Identifier">scan_line</span>(line)
+  <span class="Statement">until</span> state_classified_line(line)
+</pre>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Do nothing
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+  end
+end
+</pre>
+<table class='layout'>
+<tr>
+<td class='indentation'>
+<pre></pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Scan the current line using the current state transitions. Return true if
+the line was classified, of false if we need to try and classify it again
+using the updated (next) state.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+<span class="PreProc">def</span> <span class="Identifier">state_classified_line</span>(line)
   <span class="Identifier">@state</span>.transitions.each <span class="Statement">do</span> |<span class="Identifier">transition</span>|
-    <span class="Statement">return</span> <span class="Statement">if</span> transition.pattern &amp;&amp; transition.next_state &amp;&amp; classify_matching_line(line, transition)
+    match = transition.pattern.andand.regexp.andand.match(line) <span class="Statement">if</span> transition.next_state
+    <span class="Statement">return</span> classify_matching_line(line, transition, match) <span class="Statement">if</span> match
   <span class="Statement">end</span>
-  unclassified_line(line, <span class="Identifier">@state</span>.name)
+  classify_error_line(line, <span class="Identifier">@state</span>.name)
+  <span class="Statement">return</span> <span class="Constant">true</span>
 <span class="PreProc">end</span>
 </pre>
@@ -1476,15 +1544,15 @@ Handle a file line, only if it matches the pattern.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="PreProc">def</span> <span class="Identifier">classify_matching_line</span>(line, transition)
-  match = (pattern = transition.pattern).regexp.match(line)
-  <span class="Statement">return</span> <span class="Constant">false</span> <span class="Statement">unless</span> match
-  <span class="Identifier">@lines</span> &lt;&lt; <span class="Type">Scanner</span>.extracted_groups(match, pattern.groups).update({
+<span class="PreProc">def</span> <span class="Identifier">classify_matching_line</span>(line, transition, match)
+  <span class="Identifier">@state</span> = transition.next_state
+  kind = transition.kind
+  <span class="Statement">return</span> <span class="Constant">false</span> <span class="Statement">unless</span> kind <span class="Comment"># A +nil+ kind indicates the next state will classify the line.</span>
+  <span class="Identifier">@lines</span> &lt;&lt; <span class="Type">Scanner</span>.extracted_groups(match, transition.pattern.groups || []).update({
     <span class="Special">&quot;</span><span class="Constant">line</span><span class="Special">&quot;</span> =&gt; line,
-    <span class="Special">&quot;</span><span class="Constant">kind</span><span class="Special">&quot;</span> =&gt; transition.kind,
+    <span class="Special">&quot;</span><span class="Constant">kind</span><span class="Special">&quot;</span> =&gt; kind,
     <span class="Special">&quot;</span><span class="Constant">number</span><span class="Special">&quot;</span> =&gt; <span class="Identifier">@errors</span>.line_number
   })
-  <span class="Identifier">@state</span> = transition.next_state
   <span class="Statement">return</span> <span class="Constant">true</span>
 <span class="PreProc">end</span>
@@ -1530,7 +1598,7 @@ Handle a file line that couldn’t be classified.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="PreProc">def</span> <span class="Identifier">unclassified_line</span>(line, state_name)
+<span class="PreProc">def</span> <span class="Identifier">classify_error_line</span>(line, state_name)
   <span class="Identifier">@lines</span> &lt;&lt; {
     <span class="Special">&quot;</span><span class="Constant">line</span><span class="Special">&quot;</span> =&gt; line,
     <span class="Special">&quot;</span><span class="Constant">indentation</span><span class="Special">&quot;</span> =&gt; line.indentation,
@@ -2941,12 +3009,12 @@ Test expanding RDoc text.
   <span class="PreProc">end</span>
   <span class="PreProc">def</span> <span class="Identifier">test_strong_text</span>
-    <span class="Type">Codnar</span>::<span class="Type">RDoc</span>.to_html(<span class="Special">&quot;</span><span class="Constant">*text*</span><span class="Special">&quot;</span>).should == <span class="Special">&quot;</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Constant">&lt;b&gt;text&lt;/b&gt;</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>
+    <span class="Type">Codnar</span>::<span class="Type">RDoc</span>.to_html(<span class="Special">&quot;</span><span class="Constant">*text*</span><span class="Special">&quot;</span>).should == <span class="Special">&quot;</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Constant">&lt;strong&gt;text&lt;/strong&gt;</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>
   <span class="PreProc">end</span>
   <span class="PreProc">def</span> <span class="Identifier">test_indented_pre</span>
     <span class="Type">Codnar</span>::<span class="Type">RDoc</span>.to_html(<span class="Special">&quot;</span><span class="Constant">base</span><span class="Special">\n</span><span class="Constant">  indented</span><span class="Special">\n</span><span class="Constant">    more</span><span class="Special">\n</span><span class="Constant">back</span><span class="Special">\n</span><span class="Special">&quot;</span>).should \
-                      == <span class="Special">&quot;</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Constant">base</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Constant">&lt;pre&gt;</span><span class="Special">\n</span><span class="Constant">indented</span><span class="Special">\n</span><span class="Constant">  more</span><span class="Special">\n</span><span class="Constant">&lt;/pre&gt;</span><span class="Special">\n</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Constant">back</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>
+                      == <span class="Special">&quot;</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Constant">base</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Constant">&lt;pre&gt;indented</span><span class="Special">\n</span><span class="Constant">  more&lt;/pre&gt;</span><span class="Special">\n</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Constant">back</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>
   <span class="PreProc">end</span>
 <span class="PreProc">end</span>
@@ -3229,20 +3297,22 @@ end
 </div>
 </p>
 </li>
-</ul>
+<li>
 <p>
-In both cases, the HTML generated by the markup format conversion is a bit
-messy. We therefore clean it up:
+Haddock, a specific markup syntax used in comments to document Haskell code.
+Here is a simple test that demonstrates using Haddock:
 </p>
 <p>
 <div class="named_with_containers chunk">
 <div class="chunk name">
-<a name="clean-html">
-<span>Clean HTML</span>
+<a name="test-expand-haddock-rb">
+<span>test/expand_haddock.rb</span>
 </a>
 </div>
 <div class="chunk html">
 <pre class='ruby code syntax'>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar</span><span class="Special">&quot;</span>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">test/spec</span><span class="Special">&quot;</span>
 </pre>
 <table class='layout'>
@@ -3253,176 +3323,164 @@ messy. We therefore clean it up:
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Clean HTML generated by markup formatters. Such HTML tends to have extra
-empty lines for no apparent reason. Cleaning it up seems to be safe enough,
-and eliminates the ugly additional vertical space in the final HTML.
+Test expanding Haddock text.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="PreProc">def</span> <span class="Identifier">clean_markup_html</span>
-  <span class="Statement">return</span> gsub(<span class="Special">/</span><span class="Special">\n</span><span class="Special">*</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Special">*</span><span class="Special">/</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>) \
-        .gsub(<span class="Special">/</span><span class="Special">\n</span><span class="Special">*</span><span class="Constant">&lt;</span><span class="Special">\/</span><span class="Constant">p&gt;</span><span class="Special">\n</span><span class="Special">*</span><span class="Special">/</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>) \
-        .gsub(<span class="Special">/</span><span class="Special">\n</span><span class="Special">*</span><span class="Constant">&lt;pre&gt;</span><span class="Special">\n</span><span class="Special">*</span><span class="Special">/</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Constant">&lt;pre&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>) \
-        .gsub(<span class="Special">/</span><span class="Special">\n</span><span class="Special">*</span><span class="Constant">&lt;</span><span class="Special">\/</span><span class="Constant">pre&gt;</span><span class="Special">\n</span><span class="Special">*</span><span class="Special">/</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Constant">&lt;/pre&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>) \
-        .sub(<span class="Special">/</span><span class="Special">^</span><span class="Special">\n</span><span class="Special">*</span><span class="Special">/</span>, <span class="Special">&quot;&quot;</span>)
-<span class="PreProc">end</span>
+<span class="PreProc">class</span> <span class="Type">TestExpandHaddock</span> &lt; <span class="Type">Test</span>::<span class="Type">Unit</span>::<span class="Type">TestCase</span>
+  <span class="PreProc">def</span> <span class="Identifier">test_normal_text</span>
+    <span class="Type">Codnar</span>::<span class="Type">Haddock</span>.to_html(<span class="Special">&quot;</span><span class="Constant">normal</span><span class="Special">&quot;</span>).should == <span class="Special">&quot;</span><span class="Constant">&lt;p&gt;normal</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>
+  <span class="PreProc">end</span>
+  <span class="PreProc">def</span> <span class="Identifier">test_identifier_text</span>
+    <span class="Type">Codnar</span>::<span class="Type">Haddock</span>.to_html(<span class="Special">&quot;</span><span class="Constant">'Int'</span><span class="Special">&quot;</span>).should == <span class="Special">&quot;</span><span class="Constant">&lt;p&gt;&lt;code&gt;Int&lt;/code&gt;</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>
+  <span class="PreProc">end</span>
+  <span class="PreProc">def</span> <span class="Identifier">test_emphasis_text</span>
+    <span class="Type">Codnar</span>::<span class="Type">Haddock</span>.to_html(<span class="Special">&quot;</span><span class="Constant">/emphasis/</span><span class="Special">&quot;</span>).should == <span class="Special">&quot;</span><span class="Constant">&lt;p&gt;&lt;em&gt;emphasis&lt;/em&gt;</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>
+  <span class="PreProc">end</span>
+  <span class="PreProc">def</span> <span class="Identifier">test_code_text</span>
+    <span class="Type">Codnar</span>::<span class="Type">Haddock</span>.to_html(<span class="Special">&quot;</span><span class="Constant">@code@</span><span class="Special">&quot;</span>).should == <span class="Special">&quot;</span><span class="Constant">&lt;pre&gt;code&lt;/pre&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>
+  <span class="PreProc">end</span>
+<span class="PreProc">end</span>
 </pre>
 </div>
-<div class="chunk containers">
-<span class="chunk containers header">Contained in:</span>
-<ul class="chunk containers">
-<li class="chunk container">
-<a class="chunk container" href="#lib-codnar-string-extensions-rb">lib/codnar/string_extensions.rb</a>
-</li>
-</ul>
-</div>
 </div>
 </p>
-<h4>Generating diagrams using GraphViz</h4>
-<p>
-If you have <code>graphviz</code> installed, it is possible to use it to generate SVG
-diagrams that can be embedded directly into the HTML. This is implemented as an
-additional formatter; in principle, you this allows embeding the GraphViz
-directives directly in the code, but in practice people prefer keeping the
-diagrams as separate files.
-</p>
-<p>
-We pre-process the GraphViz directives using the <code>m4</code> macro processor. This
-allows dramatically reducing the amount of repeated boilerplate in the diagram
-definitions, by defining macros for node and edge styles and, if desired, more
-advanced techniques.
-</p>
 <p>
-Here is a simple test that demonstrates generating SVG from a GraphViz diagram:
+And here is the implementation:
 </p>
 <p>
 <div class="named_with_containers chunk">
 <div class="chunk name">
-<a name="test-graphviz-diagrams-rb">
-<span>test/graphviz_diagrams.rb</span>
+<a name="lib-codnar-haddock-rb">
+<span>lib/codnar/haddock.rb</span>
 </a>
 </div>
 <div class="chunk html">
 <pre class='ruby code syntax'>
-<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar</span><span class="Special">&quot;</span>
-<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">test/spec</span><span class="Special">&quot;</span>
+<span class="PreProc">module</span> <span class="Type">Codnar</span>
 </pre>
-<table class='layout'>
+  <table class='layout'>
 <tr>
 <td class='indentation'>
-<pre></pre>
+<pre>  </pre>
 </td>
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Test highlighting syntax using GVim.
+Convert Haddoc to HTML.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="PreProc">class</span> <span class="Type">TestGraphVizDiagrams</span> &lt; <span class="Type">Test</span>::<span class="Type">Unit</span>::<span class="Type">TestCase</span>
+  <span class="PreProc">class</span> <span class="Type">Haddock</span>
-  <span class="Type">MINIMAL_DIAGRAM_SVG</span> = &lt;&lt;-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( svg</span>
-</pre>
-<pre class='svg code syntax'>
-    <span class="Identifier">&lt;</span><span class="Identifier">svg</span><span class="Identifier"> </span><span class="Type">width</span>=<span class="Constant">&quot;62pt&quot;</span><span class="Identifier"> </span><span class="Type">height</span>=<span class="Constant">&quot;116pt&quot;</span>
-<span class="Identifier">     </span><span class="Type">viewBox</span>=<span class="Constant">&quot;0.00 0.00 62.00 116.00&quot;</span><span class="Identifier"> </span><span class="Type">xmlns</span>=<span class="Constant">&quot;<a href="http://www.w3.org/2000/svg">http://www.w3.org/2000/svg</a>&quot;</span><span class="Identifier"> </span><span class="Type">xmlns</span><span class="Comment">:</span><span class="Type">xlink</span>=<span class="Constant">&quot;<a href="http://www.w3.org/1999/xlink">http://www.w3.org/1999/xlink</a>&quot;</span><span class="Identifier">&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">&quot;graph1&quot;</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">&quot;graph&quot;</span><span class="Identifier"> </span><span class="Type">transform</span>=<span class="Constant">&quot;scale(1 1) rotate(0) translate(4 112)&quot;</span><span class="Identifier">&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">title</span><span class="Identifier">&gt;</span>_anonymous_0<span class="Identifier">&lt;/title&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">polygon</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">&quot;white&quot;</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">&quot;white&quot;</span><span class="Identifier"> </span><span class="Type">points</span>=<span class="Constant">&quot;-4,5 -4,-112 59,-112 59,5 -4,5&quot;</span><span class="Identifier">/&gt;</span>
-    <span class="Comment">&lt;!</span><span class="Comment">-- A --</span><span class="Comment">&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">&quot;node1&quot;</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">&quot;node&quot;</span><span class="Identifier">&gt;&lt;</span><span class="Identifier">title</span><span class="Identifier">&gt;</span>A<span class="Identifier">&lt;/title&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">ellipse</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">&quot;none&quot;</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">&quot;black&quot;</span><span class="Identifier"> </span><span class="Type">cx</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">cy</span>=<span class="Constant">&quot;-90&quot;</span><span class="Identifier"> </span><span class="Type">rx</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">ry</span>=<span class="Constant">&quot;18&quot;</span><span class="Identifier">/&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">text</span><span class="Identifier"> </span><span class="Type">text-anchor</span>=<span class="Constant">&quot;middle&quot;</span><span class="Identifier"> </span><span class="Type">x</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">y</span>=<span class="Constant">&quot;-85.4&quot;</span><span class="Identifier"> </span><span class="Type">font-family</span>=<span class="Constant">&quot;Times New Roman,serif&quot;</span><span class="Identifier"> </span><span class="Type">font-size</span>=<span class="Constant">&quot;14.00&quot;</span><span class="Identifier">&gt;</span>A<span class="Identifier">&lt;/text&gt;</span>
-    <span class="Identifier">&lt;/g&gt;</span>
-    <span class="Comment">&lt;!</span><span class="Comment">-- B --</span><span class="Comment">&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">&quot;node3&quot;</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">&quot;node&quot;</span><span class="Identifier">&gt;&lt;</span><span class="Identifier">title</span><span class="Identifier">&gt;</span>B<span class="Identifier">&lt;/title&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">ellipse</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">&quot;none&quot;</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">&quot;black&quot;</span><span class="Identifier"> </span><span class="Type">cx</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">cy</span>=<span class="Constant">&quot;-18&quot;</span><span class="Identifier"> </span><span class="Type">rx</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">ry</span>=<span class="Constant">&quot;18&quot;</span><span class="Identifier">/&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">text</span><span class="Identifier"> </span><span class="Type">text-anchor</span>=<span class="Constant">&quot;middle&quot;</span><span class="Identifier"> </span><span class="Type">x</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">y</span>=<span class="Constant">&quot;-13.4&quot;</span><span class="Identifier"> </span><span class="Type">font-family</span>=<span class="Constant">&quot;Times New Roman,serif&quot;</span><span class="Identifier"> </span><span class="Type">font-size</span>=<span class="Constant">&quot;14.00&quot;</span><span class="Identifier">&gt;</span>B<span class="Identifier">&lt;/text&gt;</span>
-    <span class="Identifier">&lt;/g&gt;</span>
-    <span class="Comment">&lt;!</span><span class="Comment">-- A&amp;#45;&amp;gt;B --</span><span class="Comment">&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">&quot;edge2&quot;</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">&quot;edge&quot;</span><span class="Identifier">&gt;&lt;</span><span class="Identifier">title</span><span class="Identifier">&gt;</span>A<span class="Type">&amp;</span><span class="Statement">#45</span><span class="Type">;&amp;</span><span class="Statement">gt</span><span class="Type">;</span>B<span class="Identifier">&lt;/title&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">path</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">&quot;none&quot;</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">&quot;black&quot;</span><span class="Identifier"> </span><span class="Type">d</span>=<span class="Constant">&quot;M27,-71.8314C27,-64.131 27,-54.9743 27,-46.4166&quot;</span><span class="Identifier">/&gt;</span>
-    <span class="Identifier">&lt;</span><span class="Identifier">polygon</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">&quot;black&quot;</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">&quot;black&quot;</span><span class="Identifier"> </span><span class="Type">points</span>=<span class="Constant">&quot;30.5001,-46.4132 27,-36.4133 23.5001,-46.4133 30.5001,-46.4132&quot;</span><span class="Identifier">/&gt;</span>
-    <span class="Identifier">&lt;/g&gt;</span>
-    <span class="Identifier">&lt;/g&gt;</span>
-    <span class="Identifier">&lt;/svg&gt;</span>
-  EOF
 </pre>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Process a Haddock String and return the resulting HTML.
+</p>
+</div>
+</td>
+</tr>
+</table>
 <pre class='ruby code syntax'>
-  <span class="Comment">#! ))) svg</span>
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">to_html</span>(haddock)
+      with_temporary_directory <span class="Statement">do</span> |<span class="Identifier">path</span>|
+        write_temporary_file(path, haddock)
+        run_haddock(path)
+        html = read_html_file(path)
+        clean_html(html)
+      <span class="Statement">end</span>
+    <span class="PreProc">end</span>
-  <span class="PreProc">def</span> <span class="Identifier">test_valid_diagram</span>
-    diagram = &lt;&lt;-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( dot</span>
-</pre>
-<pre class='dot code syntax'>
-      <span class="Identifier">define</span><span class="Statement">(</span>`<span class="Identifier">X</span>', `<span class="Identifier">A</span>'<span class="Statement">)</span>
-      <span class="Statement">digraph</span> <span class="Statement">{</span>
-        <span class="Identifier">X</span> <span class="Statement">-&gt;</span> <span class="Identifier">B</span><span class="Statement">;</span>
-      <span class="Statement">}</span>
-    <span class="Identifier">EOF</span>
-</pre>
-<pre class='ruby code syntax'>
-    <span class="Comment">#! ))) dot</span>
-    <span class="Type">Codnar</span>::<span class="Type">GraphViz</span>.to_html(diagram).should == <span class="Type">MINIMAL_DIAGRAM_SVG</span>
-  end
+  <span class="Statement">protected</span>
-  <span class="PreProc">def</span> <span class="Identifier">test_invalid_diagram</span>
-    diagram = &lt;&lt;-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( dot</span>
-</pre>
-<pre class='dot code syntax'>
-      <span class="Statement">digraph</span> <span class="Statement">{</span>
-        <span class="Identifier">A</span> <span class="Statement">-&gt;</span>
-    <span class="Identifier">EOF</span>
 </pre>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Run a block using a temporary directory, that is then removed. TODO: This
+should be in some more generic place.
+</p>
+</div>
+</td>
+</tr>
+</table>
 <pre class='ruby code syntax'>
-    <span class="Comment">#! ))) dot</span>
-    <span class="Statement">lambda</span> { <span class="Type">Codnar</span>::<span class="Type">GraphViz</span>.to_html(diagram) }.should.raise
-  end
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">with_temporary_directory</span>
+      path = create_temporary_directory
+      result = <span class="Statement">yield</span> path
+      <span class="Type">FileUtils</span>.rm_rf(path)
+      <span class="Statement">return</span> result
+    <span class="PreProc">end</span>
-end
 </pre>
-</div>
-</div>
-</p>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
 <p>
-And here is the implementation:
+Create a temporary directory to run Haddock in.
 </p>
-<p>
-<div class="named_with_containers chunk">
-<div class="chunk name">
-<a name="lib-codnar-graphviz-rb">
-<span>lib/codnar/graphviz.rb</span>
-</a>
 </div>
-<div class="chunk html">
+</td>
+</tr>
+</table>
 <pre class='ruby code syntax'>
-<span class="PreProc">module</span> <span class="Type">Codnar</span>
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">create_temporary_directory</span>
+      file = <span class="Type">Tempfile</span>.open(<span class="Special">&quot;</span><span class="Constant">dir</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">.</span><span class="Special">&quot;</span>)
+      path = file.path
+      <span class="Type">File</span>.delete(path)
+      <span class="Type">Dir</span>.mkdir(path)
+      <span class="Statement">return</span> path
+    <span class="PreProc">end</span>
 </pre>
-  <table class='layout'>
+    <table class='layout'>
 <tr>
 <td class='indentation'>
-<pre>  </pre>
+<pre>    </pre>
 </td>
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Generate diagrams using GraphViz.
+Minimal header to insert before the Haddock String to trick Haddock into
+generating HTML from it.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-  <span class="PreProc">class</span> <span class="Type">GraphViz</span>
+    <span class="Type">HADDOCK_HEADER</span> = &lt;&lt;-<span class="Special">EOF</span>.unindent
+<span class="Constant">      module Wrapper where</span>
+<span class="Constant">      -- $doc</span>
+<span class="Constant">    </span><span class="Special">EOF</span>
 </pre>
     <table class='layout'>
@@ -3433,26 +3491,21 @@ Generate diagrams using GraphViz.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Convert a string containing a GraphViz diagram into SVG suitable for
-embedding into the HTML documentation. We pre-process the diagram using M4
-to allow cutting down on the boilerplate (repeating the same styles in many
-nodes etc.). This should not be harmful for diagrams that do not use M4
-commands.
+Write the Haddock String into a wrapper Haskell file so we’ll be able to
+run Haddock to generate HTML from it.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">to_html</span>(diagram)
-      stdin, stdout, stderr = <span class="Type">Open3</span>.popen3(<span class="Special">&quot;</span><span class="Constant">m4 | dot -Tsvg</span><span class="Special">&quot;</span>)
-      write_diagram(stdin, diagram)
-      check_for_errors(stderr)
-      <span class="Statement">return</span> clean_output(stdout)
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">write_temporary_file</span>(path, haddock)
+      <span class="Type">File</span>.open(path + <span class="Special">&quot;</span><span class="Constant">/wrapper.hs</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">w</span><span class="Special">&quot;</span>) <span class="Statement">do</span> |<span class="Identifier">file</span>|
+        file.write(<span class="Type">HADDOCK_HEADER</span>)
+        file.write(<span class="Special">&quot;</span><span class="Constant">-- </span><span class="Special">&quot;</span> + haddock.gsub(<span class="Special">&quot;</span><span class="Special">\n</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Constant">-- </span><span class="Special">&quot;</span>))
+      <span class="Statement">end</span>
     <span class="PreProc">end</span>
-  <span class="Statement">protected</span>
 </pre>
     <table class='layout'>
 <tr>
@@ -3462,16 +3515,15 @@ commands.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Send the diagram to the commands pipe.
+Run Haddock to convert the wrapper Haskell file into HTML documentation.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">write_diagram</span>(stdin, diagram)
-      stdin.write(diagram)
-      stdin.close
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">run_haddock</span>(path)
+      system(<span class="Special">&quot;</span><span class="Constant">cd </span><span class="Special">#{</span>path<span class="Special">}</span><span class="Constant"> &amp;&amp; haddock --html wrapper.hs &gt; haddock.out 2&gt;&amp;1</span><span class="Special">&quot;</span>)
     <span class="PreProc">end</span>
 </pre>
@@ -3483,17 +3535,15 @@ Send the diagram to the commands pipe.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Ensure we got no processing errors from either m4 or dot. If we did, raise
-them, and they will be handled by the formatter wrapping code.
+Read the HTML generated by Haddock.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">check_for_errors</span>(stderr)
-      errors = stderr.read
-      <span class="Statement">raise</span> errors.sub(<span class="Special">/</span><span class="Constant">Error: &lt;stdin&gt;:</span><span class="Special">\d</span><span class="Special">+</span><span class="Constant">: </span><span class="Special">/</span>, <span class="Special">&quot;&quot;</span>) <span class="Statement">if</span> errors != <span class="Special">&quot;&quot;</span>
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">read_html_file</span>(path)
+      <span class="Statement">return</span> <span class="Type">File</span>.read(path + <span class="Special">&quot;</span><span class="Constant">/Wrapper.html</span><span class="Special">&quot;</span>)
     <span class="PreProc">end</span>
 </pre>
@@ -3505,15 +3555,18 @@ them, and they will be handled by the formatter wrapping code.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Clean the SVG we got to make it suitable for embedding in HTML.
+Extract the clean generated HTML from Haddock’s output.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">clean_output</span>(stdout)
-      <span class="Statement">return</span> stdout.read.sub(<span class="Special">/</span><span class="Special">.</span><span class="Special">*</span><span class="Constant">&lt;svg</span><span class="Special">/m</span>, <span class="Special">&quot;</span><span class="Constant">&lt;svg</span><span class="Special">&quot;</span>).gsub(<span class="Special">/</span><span class="Special">\r</span><span class="Special">/</span>, <span class="Special">&quot;&quot;</span>)
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">clean_html</span>(html)
+      html.gsub!(<span class="Special">&quot;</span><span class="Special">\r\n</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Special">&quot;</span>)
+      html.sub!(<span class="Special">/</span><span class="Special">.</span><span class="Special">*</span><span class="Constant">&lt;div class=&quot;doc&quot;&gt;</span><span class="Special">/m</span>, <span class="Special">''</span>)
+      html.sub!(<span class="Special">/</span><span class="Constant">&lt;</span><span class="Special">\/</span><span class="Constant">div&gt;&lt;</span><span class="Special">\/</span><span class="Constant">div&gt;&lt;</span><span class="Special">\/</span><span class="Constant">div&gt;&lt;div id=&quot;footer&quot;&gt;</span><span class="Special">.</span><span class="Special">*</span><span class="Special">/m</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Special">&quot;</span>)
+      <span class="Statement">return</span> html
     <span class="PreProc">end</span>
   end
@@ -3523,20 +3576,83 @@ end
 </div>
 </div>
 </p>
-<h4>Syntax highlighting using GVIM</h4>
+</li>
+</ul>
 <p>
-If you have GVim istalled, it is possible to use it to generate syntax
-highlighting. This is a <em>slow</em> operation, as GVim was never meant to be used as
-a command-line tool. However, what it lacks in speed it compensates for in
-scope; almost any language you can think of has a GVim syntax highlighting
-definition. Here is a simple test that demonstrates using GVim for syntax
-highlighting:
+In all cases, the HTML generated by the markup format conversion is a bit
+messy. We therefore clean it up:
 </p>
 <p>
 <div class="named_with_containers chunk">
 <div class="chunk name">
-<a name="test-gvim-highlight-syntax-rb">
-<span>test/gvim_highlight_syntax.rb</span>
+<a name="clean-html">
+<span>Clean HTML</span>
+</a>
+</div>
+<div class="chunk html">
+<pre class='ruby code syntax'>
+</pre>
+<table class='layout'>
+<tr>
+<td class='indentation'>
+<pre></pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Clean HTML generated by markup formatters. Such HTML tends to have extra
+empty lines for no apparent reason. Cleaning it up seems to be safe enough,
+and eliminates the ugly additional vertical space in the final HTML.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+<span class="PreProc">def</span> <span class="Identifier">clean_markup_html</span>
+  <span class="Statement">return</span> gsub(<span class="Special">&quot;</span><span class="Special">\r\n</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Special">&quot;</span>) \
+        .gsub(<span class="Special">/</span><span class="Special">\n</span><span class="Special">*</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Special">*</span><span class="Special">/</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>) \
+        .gsub(<span class="Special">/</span><span class="Special">\n</span><span class="Special">*</span><span class="Constant">&lt;</span><span class="Special">\/</span><span class="Constant">p&gt;</span><span class="Special">\n</span><span class="Special">*</span><span class="Special">/</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>) \
+        .gsub(<span class="Special">/</span><span class="Special">\n</span><span class="Special">*</span><span class="Constant">&lt;pre&gt;</span><span class="Special">\n</span><span class="Special">+</span><span class="Special">/</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Constant">&lt;pre&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>) \
+        .gsub(<span class="Special">/</span><span class="Special">\n</span><span class="Special">+</span><span class="Constant">&lt;</span><span class="Special">\/</span><span class="Constant">pre&gt;</span><span class="Special">\n</span><span class="Special">*</span><span class="Special">/</span>, <span class="Special">&quot;</span><span class="Special">\n</span><span class="Constant">&lt;/pre&gt;</span><span class="Special">\n</span><span class="Special">&quot;</span>) \
+        .sub(<span class="Special">/</span><span class="Special">^</span><span class="Special">\n</span><span class="Special">*</span><span class="Special">/</span>, <span class="Special">&quot;&quot;</span>)
+<span class="PreProc">end</span>
+</pre>
+</div>
+<div class="chunk containers">
+<span class="chunk containers header">Contained in:</span>
+<ul class="chunk containers">
+<li class="chunk container">
+<a class="chunk container" href="#lib-codnar-string-extensions-rb">lib/codnar/string_extensions.rb</a>
+</li>
+</ul>
+</div>
+</div>
+</p>
+<h4>Generating diagrams using GraphViz</h4>
+<p>
+If you have <code>graphviz</code> installed, it is possible to use it to generate SVG
+diagrams that can be embedded directly into the HTML. This is implemented as an
+additional formatter; in principle, you this allows embeding the GraphViz
+directives directly in the code, but in practice people prefer keeping the
+diagrams as separate files.
+</p>
+<p>
+We pre-process the GraphViz directives using the <code>m4</code> macro processor. This
+allows dramatically reducing the amount of repeated boilerplate in the diagram
+definitions, by defining macros for node and edge styles and, if desired, more
+advanced techniques.
+</p>
+<p>
+Here is a simple test that demonstrates generating SVG from a GraphViz diagram:
+</p>
+<p>
+<div class="named_with_containers chunk">
+<div class="chunk name">
+<a name="test-graphviz-diagrams-rb">
+<span>test/graphviz_diagrams.rb</span>
 </a>
 </div>
 <div class="chunk html">
@@ -3560,56 +3676,64 @@ Test highlighting syntax using GVim.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="PreProc">class</span> <span class="Type">TestGVimHighlightSyntax</span> &lt; <span class="Type">Test</span>::<span class="Type">Unit</span>::<span class="Type">TestCase</span>
-  <span class="PreProc">def</span> <span class="Identifier">setup</span>
-    <span class="Type">Codnar</span>::<span class="Type">GVim</span>.force_recompute = <span class="Constant">true</span>
-  <span class="PreProc">end</span>
+<span class="PreProc">class</span> <span class="Type">TestGraphVizDiagrams</span> &lt; <span class="Type">Test</span>::<span class="Type">Unit</span>::<span class="Type">TestCase</span>
-  <span class="PreProc">def</span> <span class="Identifier">teardown</span>
-    <span class="Type">Codnar</span>::<span class="Type">GVim</span>.force_recompute = <span class="Constant">false</span>
-  <span class="PreProc">end</span>
+  <span class="Type">MINIMAL_DIAGRAM_SVG</span> = &lt;&lt;-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( svg</span>
+</pre>
+<pre class='svg code syntax'>
+    <span class="Identifier">&lt;</span><span class="Identifier">svg</span><span class="Identifier"> </span><span class="Type">width</span>=<span class="Constant">&quot;62pt&quot;</span><span class="Identifier"> </span><span class="Type">height</span>=<span class="Constant">&quot;116pt&quot;</span>
+<span class="Identifier">     </span><span class="Type">viewBox</span>=<span class="Constant">&quot;0.00 0.00 62.00 116.00&quot;</span><span class="Identifier"> </span><span class="Type">xmlns</span>=<span class="Constant">&quot;<a href="http://www.w3.org/2000/svg">http://www.w3.org/2000/svg</a>&quot;</span><span class="Identifier"> </span><span class="Type">xmlns</span><span class="Comment">:</span><span class="Type">xlink</span>=<span class="Constant">&quot;<a href="http://www.w3.org/1999/xlink">http://www.w3.org/1999/xlink</a>&quot;</span><span class="Identifier">&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">&quot;graph1&quot;</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">&quot;graph&quot;</span><span class="Identifier"> </span><span class="Type">transform</span>=<span class="Constant">&quot;scale(1 1) rotate(0) translate(4 112)&quot;</span><span class="Identifier">&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">title</span><span class="Identifier">&gt;</span>_anonymous_0<span class="Identifier">&lt;/title&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">polygon</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">&quot;white&quot;</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">&quot;white&quot;</span><span class="Identifier"> </span><span class="Type">points</span>=<span class="Constant">&quot;-4,5 -4,-112 59,-112 59,5 -4,5&quot;</span><span class="Identifier">/&gt;</span>
+    <span class="Comment">&lt;!</span><span class="Comment">-- A --</span><span class="Comment">&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">&quot;node1&quot;</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">&quot;node&quot;</span><span class="Identifier">&gt;&lt;</span><span class="Identifier">title</span><span class="Identifier">&gt;</span>A<span class="Identifier">&lt;/title&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">ellipse</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">&quot;none&quot;</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">&quot;black&quot;</span><span class="Identifier"> </span><span class="Type">cx</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">cy</span>=<span class="Constant">&quot;-90&quot;</span><span class="Identifier"> </span><span class="Type">rx</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">ry</span>=<span class="Constant">&quot;18&quot;</span><span class="Identifier">/&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">text</span><span class="Identifier"> </span><span class="Type">text-anchor</span>=<span class="Constant">&quot;middle&quot;</span><span class="Identifier"> </span><span class="Type">x</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">y</span>=<span class="Constant">&quot;-85.4&quot;</span><span class="Identifier"> </span><span class="Type">font-family</span>=<span class="Constant">&quot;Times New Roman,serif&quot;</span><span class="Identifier"> </span><span class="Type">font-size</span>=<span class="Constant">&quot;14.00&quot;</span><span class="Identifier">&gt;</span>A<span class="Identifier">&lt;/text&gt;</span>
+    <span class="Identifier">&lt;/g&gt;</span>
+    <span class="Comment">&lt;!</span><span class="Comment">-- B --</span><span class="Comment">&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">&quot;node3&quot;</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">&quot;node&quot;</span><span class="Identifier">&gt;&lt;</span><span class="Identifier">title</span><span class="Identifier">&gt;</span>B<span class="Identifier">&lt;/title&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">ellipse</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">&quot;none&quot;</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">&quot;black&quot;</span><span class="Identifier"> </span><span class="Type">cx</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">cy</span>=<span class="Constant">&quot;-18&quot;</span><span class="Identifier"> </span><span class="Type">rx</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">ry</span>=<span class="Constant">&quot;18&quot;</span><span class="Identifier">/&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">text</span><span class="Identifier"> </span><span class="Type">text-anchor</span>=<span class="Constant">&quot;middle&quot;</span><span class="Identifier"> </span><span class="Type">x</span>=<span class="Constant">&quot;27&quot;</span><span class="Identifier"> </span><span class="Type">y</span>=<span class="Constant">&quot;-13.4&quot;</span><span class="Identifier"> </span><span class="Type">font-family</span>=<span class="Constant">&quot;Times New Roman,serif&quot;</span><span class="Identifier"> </span><span class="Type">font-size</span>=<span class="Constant">&quot;14.00&quot;</span><span class="Identifier">&gt;</span>B<span class="Identifier">&lt;/text&gt;</span>
+    <span class="Identifier">&lt;/g&gt;</span>
+    <span class="Comment">&lt;!</span><span class="Comment">-- A&amp;#45;&amp;gt;B --</span><span class="Comment">&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">g</span><span class="Identifier"> </span><span class="Type">id</span>=<span class="Constant">&quot;edge2&quot;</span><span class="Identifier"> </span><span class="Type">class</span>=<span class="Constant">&quot;edge&quot;</span><span class="Identifier">&gt;&lt;</span><span class="Identifier">title</span><span class="Identifier">&gt;</span>A<span class="Type">&amp;</span><span class="Statement">#45</span><span class="Type">;&amp;</span><span class="Statement">gt</span><span class="Type">;</span>B<span class="Identifier">&lt;/title&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">path</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">&quot;none&quot;</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">&quot;black&quot;</span><span class="Identifier"> </span><span class="Type">d</span>=<span class="Constant">&quot;M27,-71.8314C27,-64.131 27,-54.9743 27,-46.4166&quot;</span><span class="Identifier">/&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Identifier">polygon</span><span class="Identifier"> </span><span class="Type">fill</span>=<span class="Constant">&quot;black&quot;</span><span class="Identifier"> </span><span class="Type">stroke</span>=<span class="Constant">&quot;black&quot;</span><span class="Identifier"> </span><span class="Type">points</span>=<span class="Constant">&quot;30.5001,-46.4132 27,-36.4133 23.5001,-46.4133 30.5001,-46.4132&quot;</span><span class="Identifier">/&gt;</span>
+    <span class="Identifier">&lt;/g&gt;</span>
+    <span class="Identifier">&lt;/g&gt;</span>
+    <span class="Identifier">&lt;/svg&gt;</span>
+  EOF
+</pre>
+<pre class='ruby code syntax'>
+  <span class="Comment">#! ))) svg</span>
-  <span class="PreProc">def</span> <span class="Identifier">test_ruby_no_css</span>
-    ruby = &lt;&lt;-<span class="Special">EOF</span>.unindent
-<span class="Constant">      def foo</span>
-<span class="Constant">        return bar = baz</span>
-<span class="Constant">      end</span>
-<span class="Constant">    </span><span class="Special">EOF</span>
-    <span class="Type">Codnar</span>::<span class="Type">GVim</span>.cached_syntax_to_html(ruby, <span class="Special">&quot;</span><span class="Constant">ruby</span><span class="Special">&quot;</span>).should == &lt;&lt;-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( html</span>
+  <span class="PreProc">def</span> <span class="Identifier">test_valid_diagram</span>
+    diagram = &lt;&lt;-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( dot</span>
 </pre>
-<pre class='html code syntax'>
-      <span class="Identifier">&lt;</span><span class="Statement">div</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">'ruby code syntax'</span><span class="Identifier"> </span><span class="Type">bgcolor</span><span class="Identifier">=</span><span class="Constant">&quot;#ffffff&quot;</span><span class="Identifier"> </span><span class="Type">text</span><span class="Identifier">=</span><span class="Constant">&quot;#000000&quot;</span><span class="Identifier">&gt;</span>
-      <span class="Identifier">&lt;</span><span class="Statement">font</span><span class="Identifier"> </span><span class="Type">face</span><span class="Identifier">=</span><span class="Constant">&quot;monospace&quot;</span><span class="Identifier">&gt;</span>
-      <span class="Identifier">&lt;</span><span class="Statement">font</span><span class="Identifier"> </span><span class="Type">color</span><span class="Identifier">=</span><span class="Constant">&quot;#ff40ff&quot;</span><span class="Identifier">&gt;</span>def<span class="Identifier">&lt;/</span><span class="Statement">font</span><span class="Identifier">&gt;</span><span class="Special">&amp;nbsp;</span><span class="Identifier">&lt;</span><span class="Statement">font</span><span class="Identifier"> </span><span class="Type">color</span><span class="Identifier">=</span><span class="Constant">&quot;#00ffff&quot;</span><span class="Identifier">&gt;</span>foo<span class="Identifier">&lt;/</span><span class="Statement">font</span><span class="Identifier">&gt;</span><span class="Identifier">&lt;</span><span class="Statement">br</span><span class="Identifier"> /&gt;</span>
-      <span class="Special">&amp;nbsp;&amp;nbsp;</span><span class="Identifier">&lt;</span><span class="Statement">font</span><span class="Identifier"> </span><span class="Type">color</span><span class="Identifier">=</span><span class="Constant">&quot;#ffff00&quot;</span><span class="Identifier">&gt;</span>return<span class="Identifier">&lt;/</span><span class="Statement">font</span><span class="Identifier">&gt;</span><span class="Special">&amp;nbsp;</span>bar = baz<span class="Identifier">&lt;</span><span class="Statement">br</span><span class="Identifier"> /&gt;</span>
-      <span class="Identifier">&lt;</span><span class="Statement">font</span><span class="Identifier"> </span><span class="Type">color</span><span class="Identifier">=</span><span class="Constant">&quot;#ff40ff&quot;</span><span class="Identifier">&gt;</span>end<span class="Identifier">&lt;/</span><span class="Statement">font</span><span class="Identifier">&gt;</span><span class="Identifier">&lt;</span><span class="Statement">br</span><span class="Identifier"> /&gt;</span>
-      <span class="Identifier">&lt;/</span><span class="Statement">font</span><span class="Identifier">&gt;</span>
-      <span class="Identifier">&lt;/</span><span class="Statement">div</span><span class="Identifier">&gt;</span>
-    EOF
+<pre class='dot code syntax'>
+      <span class="Identifier">define</span><span class="Statement">(</span>`<span class="Identifier">X</span>', `<span class="Identifier">A</span>'<span class="Statement">)</span>
+      <span class="Statement">digraph</span> <span class="Statement">{</span>
+        <span class="Identifier">X</span> <span class="Statement">-&gt;</span> <span class="Identifier">B</span><span class="Statement">;</span>
+      <span class="Statement">}</span>
+    <span class="Identifier">EOF</span>
 </pre>
 <pre class='ruby code syntax'>
-    <span class="Comment">#! ))) html</span>
+    <span class="Comment">#! ))) dot</span>
+    <span class="Type">Codnar</span>::<span class="Type">GraphViz</span>.to_html(diagram).should == <span class="Type">MINIMAL_DIAGRAM_SVG</span>
   end
-  <span class="PreProc">def</span> <span class="Identifier">test_ruby_css</span>
-    ruby = &lt;&lt;-<span class="Special">EOF</span>.unindent
-<span class="Constant">      def foo</span>
-<span class="Constant">        return bar = baz</span>
-<span class="Constant">      end</span>
-<span class="Constant">    </span><span class="Special">EOF</span>
-    <span class="Type">Codnar</span>::<span class="Type">GVim</span>.cached_syntax_to_html(ruby, <span class="Special">&quot;</span><span class="Constant">ruby</span><span class="Special">&quot;</span>, [ <span class="Special">&quot;</span><span class="Constant">+:let html_use_css=1</span><span class="Special">&quot;</span> ]).should == &lt;&lt;-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( html</span>
+  <span class="PreProc">def</span> <span class="Identifier">test_invalid_diagram</span>
+    diagram = &lt;&lt;-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( dot</span>
 </pre>
-<pre class='html code syntax'>
-      <span class="Identifier">&lt;</span><span class="Statement">pre</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">'ruby code syntax'</span><span class="Identifier">&gt;</span>
-      <span class="Identifier">&lt;</span><span class="Statement">span</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">&quot;PreProc&quot;</span><span class="Identifier">&gt;</span>def<span class="Identifier">&lt;/</span><span class="Statement">span</span><span class="Identifier">&gt;</span> <span class="Identifier">&lt;</span><span class="Statement">span</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">&quot;Identifier&quot;</span><span class="Identifier">&gt;</span>foo<span class="Identifier">&lt;/</span><span class="Statement">span</span><span class="Identifier">&gt;</span>
-        <span class="Identifier">&lt;</span><span class="Statement">span</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">&quot;Statement&quot;</span><span class="Identifier">&gt;</span>return<span class="Identifier">&lt;/</span><span class="Statement">span</span><span class="Identifier">&gt;</span> bar = baz
-      <span class="Identifier">&lt;</span><span class="Statement">span</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">&quot;PreProc&quot;</span><span class="Identifier">&gt;</span>end<span class="Identifier">&lt;/</span><span class="Statement">span</span><span class="Identifier">&gt;</span>
-      <span class="Identifier">&lt;/</span><span class="Statement">pre</span><span class="Identifier">&gt;</span>
-    EOF
+<pre class='dot code syntax'>
+      <span class="Statement">digraph</span> <span class="Statement">{</span>
+        <span class="Identifier">A</span> <span class="Statement">-&gt;</span>
+    <span class="Identifier">EOF</span>
 </pre>
 <pre class='ruby code syntax'>
-    <span class="Comment">#! ))) html</span>
+    <span class="Comment">#! ))) dot</span>
+    <span class="Statement">lambda</span> { <span class="Type">Codnar</span>::<span class="Type">GraphViz</span>.to_html(diagram) }.should.raise
   end
 end
@@ -3623,8 +3747,8 @@ And here is the implementation:
 <p>
 <div class="named_with_containers chunk">
 <div class="chunk name">
-<a name="lib-codnar-gvim-rb">
-<span>lib/codnar/gvim.rb</span>
+<a name="lib-codnar-graphviz-rb">
+<span>lib/codnar/graphviz.rb</span>
 </a>
 </div>
 <div class="chunk html">
@@ -3640,14 +3764,14 @@ And here is the implementation:
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Syntax highlight using GVim.
+Generate diagrams using GraphViz.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-  <span class="PreProc">class</span> <span class="Type">GVim</span>
+  <span class="PreProc">class</span> <span class="Type">GraphViz</span>
 </pre>
     <table class='layout'>
@@ -3658,22 +3782,26 @@ Syntax highlight using GVim.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Convert a sequence of classified code lines to HTML using GVim syntax
-highlighting. The commands array allows configuring the way that GVim will
-format the output (see the <tt>cached_syntax_to_html</tt> method for
-details).
+Convert a string containing a GraphViz diagram into SVG suitable for
+embedding into the HTML documentation. We pre-process the diagram using M4
+to allow cutting down on the boilerplate (repeating the same styles in many
+nodes etc.). This should not be harmful for diagrams that do not use M4
+commands.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">lines_to_html</span>(lines, syntax, commands = [])
-      <span class="Statement">return</span> <span class="Type">Formatter</span>.merge_lines(lines, <span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span>) <span class="Statement">do</span> |<span class="Identifier">payload</span>|
-        <span class="Type">GVim</span>.cached_syntax_to_html(payload + <span class="Special">&quot;</span><span class="Special">\n</span><span class="Special">&quot;</span>, syntax, commands).chomp
-      <span class="Statement">end</span>
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">to_html</span>(diagram)
+      stdin, stdout, stderr = <span class="Type">Open3</span>.popen3(<span class="Special">&quot;</span><span class="Constant">m4 | dot -Tsvg</span><span class="Special">&quot;</span>)
+      write_diagram(stdin, diagram)
+      check_for_errors(stderr)
+      <span class="Statement">return</span> clean_output(stdout)
     <span class="PreProc">end</span>
+  <span class="Statement">protected</span>
 </pre>
     <table class='layout'>
 <tr>
@@ -3683,17 +3811,17 @@ details).
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-The cache used for speeding up recomputing the same syntax highlighting
-HTML.
+Send the diagram to the commands pipe.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-    <span class="Identifier">@cache</span> = <span class="Type">Cache</span>.new(<span class="Special">&quot;</span><span class="Constant">.gvim-cache</span><span class="Special">&quot;</span>) <span class="Statement">do</span> |<span class="Identifier">data</span>|
-      <span class="Type">GVim</span>.uncached_syntax_to_html(data.text, data.syntax, data.commands)
-    <span class="Statement">end</span>
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">write_diagram</span>(stdin, diagram)
+      stdin.write(diagram)
+      stdin.close
+    <span class="PreProc">end</span>
 </pre>
     <table class='layout'>
@@ -3704,16 +3832,17 @@ HTML.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Force recomputation of the syntax highlighting HTML, even if a cached
-version exists.
+Ensure we got no processing errors from either m4 or dot. If we did, raise
+them, and they will be handled by the formatter wrapping code.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">force_recompute=</span>(force_recompute)
-      <span class="Identifier">@cache</span>.force_recompute = force_recompute
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">check_for_errors</span>(stderr)
+      errors = stderr.read
+      <span class="Statement">raise</span> errors.sub(<span class="Special">/</span><span class="Constant">Error: &lt;stdin&gt;:</span><span class="Special">\d</span><span class="Special">+</span><span class="Constant">: </span><span class="Special">/</span>, <span class="Special">&quot;&quot;</span>) <span class="Statement">if</span> errors != <span class="Special">&quot;&quot;</span>
     <span class="PreProc">end</span>
 </pre>
@@ -3725,55 +3854,275 @@ version exists.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Highlight syntax of text using GVim. This uses the GVim standard CSS
-classes to mark keywords, identifiers, and so on. See the GVim
-documentation for details. The commands array allows configuring the way
-that GVim will format the output. For example:
-</p>
-<ul><li>
-<p>
-The command <tt>&quot;+:colorscheme &lt;name&gt;&quot;</tt> will override
-the default color scheme used.
-</p>
-</li><li>
-<p>
-The command <tt>&quot;+:let html_use_css=1&quot;</tt> will just annotate
-each HTML tag with a CSS class, instead of embedding some specific style
-directly into the tag. In this case the colorscheme and background are
-ignored; you will need to provide your own CSS stylesheet as part of the
-final woven document to style the marked-up words.
-</p>
-</li></ul>
-<p>
-Additional commands may be useful; GVim provides a full scripting
-environment so there is no theoretical limit to what can be done here.
-</p>
-<p>
-Since GVim is as slow as molasses to start up, we cache the results of
-highlighting the syntax of each code fragment in a directory called
-<tt>.gvim-cache</tt>, which can appear at the current working directory or
-in any of its parents.
+Clean the SVG we got to make it suitable for embedding in HTML.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">cached_syntax_to_html</span>(text, syntax, commands = [])
-      data = { <span class="Special">&quot;</span><span class="Constant">text</span><span class="Special">&quot;</span> =&gt; text, <span class="Special">&quot;</span><span class="Constant">syntax</span><span class="Special">&quot;</span> =&gt; syntax, <span class="Special">&quot;</span><span class="Constant">commands</span><span class="Special">&quot;</span> =&gt; commands }
-      <span class="Statement">return</span> <span class="Identifier">@cache</span>[data]
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">clean_output</span>(stdout)
+      <span class="Statement">return</span> stdout.read.sub(<span class="Special">/</span><span class="Special">.</span><span class="Special">*</span><span class="Constant">&lt;svg</span><span class="Special">/m</span>, <span class="Special">&quot;</span><span class="Constant">&lt;svg</span><span class="Special">&quot;</span>).gsub(<span class="Special">/</span><span class="Special">\r</span><span class="Special">/</span>, <span class="Special">&quot;&quot;</span>)
     <span class="PreProc">end</span>
+  end
+end
 </pre>
-    <table class='layout'>
-<tr>
-<td class='indentation'>
-<pre>    </pre>
-</td>
-<td class='html'>
-<div class='rdoc comment markup'>
+</div>
+</div>
+</p>
+<h4>Syntax highlighting using GVIM</h4>
 <p>
-Highlight syntax of text using GVim, without caching. This is <b>slow</b>
+If you have GVim istalled, it is possible to use it to generate syntax
+highlighting. This is a <em>slow</em> operation, as GVim was never meant to be used as
+a command-line tool. However, what it lacks in speed it compensates for in
+scope; almost any language you can think of has a GVim syntax highlighting
+definition. Here is a simple test that demonstrates using GVim for syntax
+highlighting:
+</p>
+<p>
+<div class="named_with_containers chunk">
+<div class="chunk name">
+<a name="test-gvim-highlight-syntax-rb">
+<span>test/gvim_highlight_syntax.rb</span>
+</a>
+</div>
+<div class="chunk html">
+<pre class='ruby code syntax'>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar</span><span class="Special">&quot;</span>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">test/spec</span><span class="Special">&quot;</span>
+</pre>
+<table class='layout'>
+<tr>
+<td class='indentation'>
+<pre></pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Test highlighting syntax using GVim.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+<span class="PreProc">class</span> <span class="Type">TestGVimHighlightSyntax</span> &lt; <span class="Type">Test</span>::<span class="Type">Unit</span>::<span class="Type">TestCase</span>
+  <span class="PreProc">def</span> <span class="Identifier">setup</span>
+    <span class="Type">Codnar</span>::<span class="Type">GVim</span>.force_recompute = <span class="Constant">true</span>
+  <span class="PreProc">end</span>
+  <span class="PreProc">def</span> <span class="Identifier">teardown</span>
+    <span class="Type">Codnar</span>::<span class="Type">GVim</span>.force_recompute = <span class="Constant">false</span>
+  <span class="PreProc">end</span>
+  <span class="PreProc">def</span> <span class="Identifier">test_ruby_no_css</span>
+    ruby = &lt;&lt;-<span class="Special">EOF</span>.unindent
+<span class="Constant">      def foo</span>
+<span class="Constant">        return bar = baz</span>
+<span class="Constant">      end</span>
+<span class="Constant">    </span><span class="Special">EOF</span>
+    <span class="Type">Codnar</span>::<span class="Type">GVim</span>.cached_syntax_to_html(ruby, <span class="Special">&quot;</span><span class="Constant">ruby</span><span class="Special">&quot;</span>).should == &lt;&lt;-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( html</span>
+</pre>
+<pre class='html code syntax'>
+      <span class="Identifier">&lt;</span><span class="Statement">div</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">'ruby code syntax'</span><span class="Identifier"> </span><span class="Type">bgcolor</span><span class="Identifier">=</span><span class="Constant">&quot;#ffffff&quot;</span><span class="Identifier"> </span><span class="Type">text</span><span class="Identifier">=</span><span class="Constant">&quot;#000000&quot;</span><span class="Identifier">&gt;</span>
+      <span class="Identifier">&lt;</span><span class="Statement">font</span><span class="Identifier"> </span><span class="Type">face</span><span class="Identifier">=</span><span class="Constant">&quot;monospace&quot;</span><span class="Identifier">&gt;</span>
+      <span class="Identifier">&lt;</span><span class="Statement">font</span><span class="Identifier"> </span><span class="Type">color</span><span class="Identifier">=</span><span class="Constant">&quot;#ff40ff&quot;</span><span class="Identifier">&gt;</span>def<span class="Identifier">&lt;/</span><span class="Statement">font</span><span class="Identifier">&gt;</span><span class="Special">&amp;nbsp;</span><span class="Identifier">&lt;</span><span class="Statement">font</span><span class="Identifier"> </span><span class="Type">color</span><span class="Identifier">=</span><span class="Constant">&quot;#00ffff&quot;</span><span class="Identifier">&gt;</span>foo<span class="Identifier">&lt;/</span><span class="Statement">font</span><span class="Identifier">&gt;</span><span class="Identifier">&lt;</span><span class="Statement">br</span><span class="Identifier"> /&gt;</span>
+      <span class="Special">&amp;nbsp;&amp;nbsp;</span><span class="Identifier">&lt;</span><span class="Statement">font</span><span class="Identifier"> </span><span class="Type">color</span><span class="Identifier">=</span><span class="Constant">&quot;#ffff00&quot;</span><span class="Identifier">&gt;</span>return<span class="Identifier">&lt;/</span><span class="Statement">font</span><span class="Identifier">&gt;</span><span class="Special">&amp;nbsp;</span>bar = baz<span class="Identifier">&lt;</span><span class="Statement">br</span><span class="Identifier"> /&gt;</span>
+      <span class="Identifier">&lt;</span><span class="Statement">font</span><span class="Identifier"> </span><span class="Type">color</span><span class="Identifier">=</span><span class="Constant">&quot;#ff40ff&quot;</span><span class="Identifier">&gt;</span>end<span class="Identifier">&lt;/</span><span class="Statement">font</span><span class="Identifier">&gt;</span><span class="Identifier">&lt;</span><span class="Statement">br</span><span class="Identifier"> /&gt;</span>
+      <span class="Identifier">&lt;/</span><span class="Statement">font</span><span class="Identifier">&gt;</span>
+      <span class="Identifier">&lt;/</span><span class="Statement">div</span><span class="Identifier">&gt;</span>
+    EOF
+</pre>
+<pre class='ruby code syntax'>
+    <span class="Comment">#! ))) html</span>
+  end
+  <span class="PreProc">def</span> <span class="Identifier">test_ruby_css</span>
+    ruby = &lt;&lt;-<span class="Special">EOF</span>.unindent
+<span class="Constant">      def foo</span>
+<span class="Constant">        return bar = baz</span>
+<span class="Constant">      end</span>
+<span class="Constant">    </span><span class="Special">EOF</span>
+    <span class="Type">Codnar</span>::<span class="Type">GVim</span>.cached_syntax_to_html(ruby, <span class="Special">&quot;</span><span class="Constant">ruby</span><span class="Special">&quot;</span>, [ <span class="Special">&quot;</span><span class="Constant">+:let html_use_css=1</span><span class="Special">&quot;</span> ]).should == &lt;&lt;-<span class="Special">EOF</span>.unindent <span class="Comment">#! ((( html</span>
+</pre>
+<pre class='html code syntax'>
+      <span class="Identifier">&lt;</span><span class="Statement">pre</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">'ruby code syntax'</span><span class="Identifier">&gt;</span>
+      <span class="Identifier">&lt;</span><span class="Statement">span</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">&quot;PreProc&quot;</span><span class="Identifier">&gt;</span>def<span class="Identifier">&lt;/</span><span class="Statement">span</span><span class="Identifier">&gt;</span> <span class="Identifier">&lt;</span><span class="Statement">span</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">&quot;Identifier&quot;</span><span class="Identifier">&gt;</span>foo<span class="Identifier">&lt;/</span><span class="Statement">span</span><span class="Identifier">&gt;</span>
+        <span class="Identifier">&lt;</span><span class="Statement">span</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">&quot;Statement&quot;</span><span class="Identifier">&gt;</span>return<span class="Identifier">&lt;/</span><span class="Statement">span</span><span class="Identifier">&gt;</span> bar = baz
+      <span class="Identifier">&lt;</span><span class="Statement">span</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">&quot;PreProc&quot;</span><span class="Identifier">&gt;</span>end<span class="Identifier">&lt;/</span><span class="Statement">span</span><span class="Identifier">&gt;</span>
+      <span class="Identifier">&lt;/</span><span class="Statement">pre</span><span class="Identifier">&gt;</span>
+    EOF
+</pre>
+<pre class='ruby code syntax'>
+    <span class="Comment">#! ))) html</span>
+  end
+end
+</pre>
+</div>
+</div>
+</p>
+<p>
+And here is the implementation:
+</p>
+<p>
+<div class="named_with_containers chunk">
+<div class="chunk name">
+<a name="lib-codnar-gvim-rb">
+<span>lib/codnar/gvim.rb</span>
+</a>
+</div>
+<div class="chunk html">
+<pre class='ruby code syntax'>
+<span class="PreProc">module</span> <span class="Type">Codnar</span>
+</pre>
+  <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>  </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Syntax highlight using GVim.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+  <span class="PreProc">class</span> <span class="Type">GVim</span>
+</pre>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Convert a sequence of classified code lines to HTML using GVim syntax
+highlighting. The commands array allows configuring the way that GVim will
+format the output (see the <tt>cached_syntax_to_html</tt> method for
+details).
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">lines_to_html</span>(lines, syntax, commands = [])
+      <span class="Statement">return</span> <span class="Type">Formatter</span>.merge_lines(lines, <span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span>) <span class="Statement">do</span> |<span class="Identifier">payload</span>|
+        <span class="Type">GVim</span>.cached_syntax_to_html(payload + <span class="Special">&quot;</span><span class="Special">\n</span><span class="Special">&quot;</span>, syntax, commands).chomp
+      <span class="Statement">end</span>
+    <span class="PreProc">end</span>
+</pre>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+The cache used for speeding up recomputing the same syntax highlighting
+HTML.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+    <span class="Identifier">@cache</span> = <span class="Type">Cache</span>.new(<span class="Special">&quot;</span><span class="Constant">.gvim-cache</span><span class="Special">&quot;</span>) <span class="Statement">do</span> |<span class="Identifier">data</span>|
+      <span class="Type">GVim</span>.uncached_syntax_to_html(data.text, data.syntax, data.commands)
+    <span class="Statement">end</span>
+</pre>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Force recomputation of the syntax highlighting HTML, even if a cached
+version exists.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">force_recompute=</span>(force_recompute)
+      <span class="Identifier">@cache</span>.force_recompute = force_recompute
+    <span class="PreProc">end</span>
+</pre>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Highlight syntax of text using GVim. This uses the GVim standard CSS
+classes to mark keywords, identifiers, and so on. See the GVim
+documentation for details. The commands array allows configuring the way
+that GVim will format the output. For example:
+</p>
+<ul><li>
+<p>
+The command <tt>&quot;+:colorscheme &lt;name&gt;&quot;</tt> will override
+the default color scheme used.
+</p>
+</li><li>
+<p>
+The command <tt>&quot;+:let html_use_css=1&quot;</tt> will just annotate
+each HTML tag with a CSS class, instead of embedding some specific style
+directly into the tag. In this case the colorscheme and background are
+ignored; you will need to provide your own CSS stylesheet as part of the
+final woven document to style the marked-up words.
+</p>
+</li></ul>
+<p>
+Additional commands may be useful; GVim provides a full scripting
+environment so there is no theoretical limit to what can be done here.
+</p>
+<p>
+Since GVim is as slow as molasses to start up, we cache the results of
+highlighting the syntax of each code fragment in a directory called
+<tt>.gvim-cache</tt>, which can appear at the current working directory or
+in any of its parents.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+    <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">cached_syntax_to_html</span>(text, syntax, commands = [])
+      data = { <span class="Special">&quot;</span><span class="Constant">text</span><span class="Special">&quot;</span> =&gt; text, <span class="Special">&quot;</span><span class="Constant">syntax</span><span class="Special">&quot;</span> =&gt; syntax, <span class="Special">&quot;</span><span class="Constant">commands</span><span class="Special">&quot;</span> =&gt; commands }
+      <span class="Statement">return</span> <span class="Identifier">@cache</span>[data]
+    <span class="PreProc">end</span>
+</pre>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Highlight syntax of text using GVim, without caching. This is <b>slow</b>
 (measured in seconds), due to GVim’s start-up tim. See the
 <tt>cached_syntax_to_html</tt> method for a faster variant and
 functionality details.
@@ -4619,7 +4968,7 @@ Test splitting code files.
       <span class="Identifier">&lt;</span><span class="Statement">td</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">'html'</span><span class="Identifier">&gt;</span>
       <span class="Identifier">&lt;</span><span class="Statement">div</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">'rdoc rdoc markup'</span><span class="Identifier">&gt;</span>
       <span class="Identifier">&lt;</span><span class="Statement">p</span><span class="Identifier">&gt;</span>
-      This is <span class="Identifier">&lt;</span><span class="Statement">b</span><span class="Identifier">&gt;</span><span class="htmlBold">rdoc</span><span class="Identifier">&lt;/</span><span class="Statement">b</span><span class="Identifier">&gt;</span>.
+      This is <span class="Identifier">&lt;</span><span class="Statement">strong</span><span class="Identifier">&gt;</span><span class="htmlBold">rdoc</span><span class="Identifier">&lt;/</span><span class="Statement">strong</span><span class="Identifier">&gt;</span>.
       <span class="Identifier">&lt;/</span><span class="Statement">p</span><span class="Identifier">&gt;</span>
       <span class="Identifier">&lt;/</span><span class="Statement">div</span><span class="Identifier">&gt;</span>
       <span class="Identifier">&lt;/</span><span class="Statement">td</span><span class="Identifier">&gt;</span>
@@ -4834,7 +5183,7 @@ Test “splitting” documentation files.
       <span class="Special">&quot;</span><span class="Constant">containers</span><span class="Special">&quot;</span> =&gt; [],
       <span class="Special">&quot;</span><span class="Constant">contained</span><span class="Special">&quot;</span> =&gt; [],
       <span class="Special">&quot;</span><span class="Constant">locations</span><span class="Special">&quot;</span> =&gt; [ { <span class="Special">&quot;</span><span class="Constant">file</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">rdoc.rdoc</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">line</span><span class="Special">&quot;</span> =&gt; <span class="Constant">1</span> } ],
-      <span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">&lt;div class='rdoc rdoc markup'&gt;</span><span class="Special">\n</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Constant">&lt;b&gt;foo&lt;/b&gt; bar</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Constant">&lt;/div&gt;</span><span class="Special">&quot;</span>
+      <span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">&lt;div class='rdoc rdoc markup'&gt;</span><span class="Special">\n</span><span class="Constant">&lt;p&gt;</span><span class="Special">\n</span><span class="Constant">&lt;strong&gt;foo&lt;/strong&gt; bar</span><span class="Special">\n</span><span class="Constant">&lt;/p&gt;</span><span class="Special">\n</span><span class="Constant">&lt;/div&gt;</span><span class="Special">&quot;</span>
     } ]
   <span class="PreProc">end</span>
@@ -4939,69 +5288,14 @@ Application.
 <pre class='ruby code syntax'>
   <span class="PreProc">module</span> <span class="Type">Configuration</span>
-</pre>
-<pre class='nested chunk'>
-    <a class='nested chunk' href='#documentation-splitting-configurations'>Documentation &quot;splitting&quot; configurations</a>
-</pre>
-<pre class='ruby code syntax'>
+    <span class="PreProc">include</span> <span class="Type">Documentation</span>
+    <span class="PreProc">include</span> <span class="Type">Code</span>
+    <span class="PreProc">include</span> <span class="Type">Comments</span>
+    <span class="PreProc">include</span> <span class="Type">Highlighting</span>
+  <span class="PreProc">end</span>
-</pre>
-<pre class='nested chunk'>
-    <a class='nested chunk' href='#source-code-lines-classification-configurations'>Source code lines classification configurations</a>
-</pre>
-<pre class='ruby code syntax'>
-</pre>
-<pre class='nested chunk'>
-    <a class='nested chunk' href='#nested-foreign-syntax-code-islands-configurations'>Nested foreign syntax code islands configurations</a>
-</pre>
-<pre class='ruby code syntax'>
-</pre>
-<pre class='nested chunk'>
-    <a class='nested chunk' href='#simple-comment-classification-configurations'>Simple comment classification configurations</a>
-</pre>
-<pre class='ruby code syntax'>
-</pre>
-<pre class='nested chunk'>
-    <a class='nested chunk' href='#complex-comment-classification-configurations'>Complex comment classification configurations</a>
-</pre>
-<pre class='ruby code syntax'>
-</pre>
-<pre class='nested chunk'>
-    <a class='nested chunk' href='#comment-formatting-configurations'>Comment formatting configurations</a>
-</pre>
-<pre class='ruby code syntax'>
-</pre>
-<pre class='nested chunk'>
-    <a class='nested chunk' href='#gvim-syntax-highlighting-formatting-configurations'>GVim syntax highlighting formatting configurations</a>
-</pre>
-<pre class='ruby code syntax'>
-</pre>
-<pre class='nested chunk'>
-    <a class='nested chunk' href='#coderay-syntax-highlighting-formatting-configurations'>CodeRay syntax highlighting formatting configurations</a>
-</pre>
-<pre class='ruby code syntax'>
-</pre>
-<pre class='nested chunk'>
-    <a class='nested chunk' href='#sunlight-syntax-highlighting-formatting-configurations'>Sunlight syntax highlighting formatting configurations</a>
-</pre>
-<pre class='ruby code syntax'>
-</pre>
-<pre class='nested chunk'>
-    <a class='nested chunk' href='#chunk-splitting-configurations'>Chunk splitting configurations</a>
-</pre>
-<pre class='ruby code syntax'>
-  end
-end
+end
 </pre>
 </div>
 </div>
@@ -5323,7 +5617,7 @@ Test the built-in split documentation configurations.
 <pre class='html code syntax'>
     <span class="Identifier">&lt;</span><span class="Statement">div</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">'rdoc doc markup'</span><span class="Identifier">&gt;</span>
     <span class="Identifier">&lt;</span><span class="Statement">p</span><span class="Identifier">&gt;</span>
-    This is a <span class="Identifier">&lt;</span><span class="Statement">b</span><span class="Identifier">&gt;</span><span class="htmlBold">marked-up</span><span class="Identifier">&lt;/</span><span class="Statement">b</span><span class="Identifier">&gt;</span> file.
+    This is a <span class="Identifier">&lt;</span><span class="Statement">strong</span><span class="Identifier">&gt;</span><span class="htmlBold">marked-up</span><span class="Identifier">&lt;/</span><span class="Statement">strong</span><span class="Identifier">&gt;</span> file.
     <span class="Identifier">&lt;/</span><span class="Statement">p</span><span class="Identifier">&gt;</span>
     <span class="Identifier">&lt;/</span><span class="Statement">div</span><span class="Identifier">&gt;</span>
   EOF
@@ -5380,18 +5674,39 @@ And here are the actual configurations:
 <p>
 <div class="named_with_containers chunk">
 <div class="chunk name">
-<a name="documentation-splitting-configurations">
-<span>Documentation &quot;splitting&quot; configurations</span>
+<a name="lib-codnar-configuration-documentation-rb">
+<span>lib/codnar/configuration/documentation.rb</span>
 </a>
 </div>
 <div class="chunk html">
 <pre class='ruby code syntax'>
+<span class="PreProc">module</span> <span class="Type">Codnar</span>
+  <span class="PreProc">module</span> <span class="Type">Configuration</span>
 </pre>
-<table class='layout'>
+    <table class='layout'>
 <tr>
 <td class='indentation'>
-<pre></pre>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Configurations for “splitting” documentation files.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+    <span class="PreProc">module</span> <span class="Type">Documentation</span>
+</pre>
+      <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>      </pre>
 </td>
 <td class='html'>
 <div class='rdoc comment markup'>
@@ -5410,25 +5725,25 @@ processing on the input. It isn’t the most useful configuration.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="Type">SPLIT_HTML_DOCUMENTATION</span> = {
-  <span class="Special">&quot;</span><span class="Constant">formatters</span><span class="Special">&quot;</span> =&gt; {
-    <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.cast_lines(lines, 'html')</span><span class="Special">&quot;</span>,
-  },
-  <span class="Special">&quot;</span><span class="Constant">syntax</span><span class="Special">&quot;</span> =&gt; {
-    <span class="Special">&quot;</span><span class="Constant">patterns</span><span class="Special">&quot;</span> =&gt; {
-      <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; { <span class="Special">&quot;</span><span class="Constant">regexp</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">^(.*)$</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">groups</span><span class="Special">&quot;</span> =&gt; [ <span class="Special">&quot;</span><span class="Constant">payload</span><span class="Special">&quot;</span> ] },
-    },
-    <span class="Special">&quot;</span><span class="Constant">states</span><span class="Special">&quot;</span> =&gt; {
-      <span class="Special">&quot;</span><span class="Constant">start</span><span class="Special">&quot;</span> =&gt; { <span class="Special">&quot;</span><span class="Constant">transitions</span><span class="Special">&quot;</span> =&gt; [ { <span class="Special">&quot;</span><span class="Constant">pattern</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> } ] },
-    },
-  },
-}
+      <span class="Type">SPLIT_HTML_DOCUMENTATION</span> = {
+        <span class="Special">&quot;</span><span class="Constant">formatters</span><span class="Special">&quot;</span> =&gt; {
+          <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.cast_lines(lines, 'html')</span><span class="Special">&quot;</span>,
+        },
+        <span class="Special">&quot;</span><span class="Constant">syntax</span><span class="Special">&quot;</span> =&gt; {
+          <span class="Special">&quot;</span><span class="Constant">patterns</span><span class="Special">&quot;</span> =&gt; {
+            <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; { <span class="Special">&quot;</span><span class="Constant">regexp</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">^(.*)$</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">groups</span><span class="Special">&quot;</span> =&gt; [ <span class="Special">&quot;</span><span class="Constant">payload</span><span class="Special">&quot;</span> ] },
+          },
+          <span class="Special">&quot;</span><span class="Constant">states</span><span class="Special">&quot;</span> =&gt; {
+            <span class="Special">&quot;</span><span class="Constant">start</span><span class="Special">&quot;</span> =&gt; { <span class="Special">&quot;</span><span class="Constant">transitions</span><span class="Special">&quot;</span> =&gt; [ { <span class="Special">&quot;</span><span class="Constant">pattern</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> } ] },
+          },
+        },
+      }
 </pre>
-<table class='layout'>
+      <table class='layout'>
 <tr>
 <td class='indentation'>
-<pre></pre>
+<pre>      </pre>
 </td>
 <td class='html'>
 <div class='rdoc comment markup'>
@@ -5441,17 +5756,17 @@ preserved by escaping it and wrapping it in an HTML pre element.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="Type">SPLIT_PRE_DOCUMENTATION</span> = <span class="Type">SPLIT_HTML_DOCUMENTATION</span>.deep_merge(
-  <span class="Special">&quot;</span><span class="Constant">formatters</span><span class="Special">&quot;</span> =&gt; {
-    <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.lines_to_pre_html(lines, :class =&gt; :doc)</span><span class="Special">&quot;</span>,
-  }
-)
+      <span class="Type">SPLIT_PRE_DOCUMENTATION</span> = <span class="Type">SPLIT_HTML_DOCUMENTATION</span>.deep_merge(
+        <span class="Special">&quot;</span><span class="Constant">formatters</span><span class="Special">&quot;</span> =&gt; {
+          <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.lines_to_pre_html(lines, :class =&gt; :doc)</span><span class="Special">&quot;</span>,
+        }
+      )
 </pre>
-<table class='layout'>
+      <table class='layout'>
 <tr>
 <td class='indentation'>
-<pre></pre>
+<pre>      </pre>
 </td>
 <td class='html'>
 <div class='rdoc comment markup'>
@@ -5463,18 +5778,18 @@ preserved by escaping it and wrapping it in an HTML pre element.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="Type">SPLIT_RDOC_DOCUMENTATION</span> = <span class="Type">SPLIT_HTML_DOCUMENTATION</span>.deep_merge(
-  <span class="Special">&quot;</span><span class="Constant">formatters</span><span class="Special">&quot;</span> =&gt; {
-    <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.markup_lines_to_html(lines, Codnar::RDoc, 'rdoc')</span><span class="Special">&quot;</span>,
-    <span class="Special">&quot;</span><span class="Constant">unindented_html</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">&quot;</span>,
-  }
-)
+      <span class="Type">SPLIT_RDOC_DOCUMENTATION</span> = <span class="Type">SPLIT_HTML_DOCUMENTATION</span>.deep_merge(
+        <span class="Special">&quot;</span><span class="Constant">formatters</span><span class="Special">&quot;</span> =&gt; {
+          <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.markup_lines_to_html(lines, Codnar::RDoc, 'rdoc')</span><span class="Special">&quot;</span>,
+          <span class="Special">&quot;</span><span class="Constant">unindented_html</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">&quot;</span>,
+        }
+      )
 </pre>
-<table class='layout'>
+      <table class='layout'>
 <tr>
 <td class='indentation'>
-<pre></pre>
+<pre>      </pre>
 </td>
 <td class='html'>
 <div class='rdoc comment markup'>
@@ -5486,18 +5801,18 @@ preserved by escaping it and wrapping it in an HTML pre element.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="Type">SPLIT_MARKDOWN_DOCUMENTATION</span> = <span class="Type">SPLIT_HTML_DOCUMENTATION</span>.deep_merge(
-  <span class="Special">&quot;</span><span class="Constant">formatters</span><span class="Special">&quot;</span> =&gt; {
-    <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.markup_lines_to_html(lines, Codnar::Markdown, 'markdown')</span><span class="Special">&quot;</span>,
-    <span class="Special">&quot;</span><span class="Constant">unindented_html</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">&quot;</span>,
-  }
-)
+      <span class="Type">SPLIT_MARKDOWN_DOCUMENTATION</span> = <span class="Type">SPLIT_HTML_DOCUMENTATION</span>.deep_merge(
+        <span class="Special">&quot;</span><span class="Constant">formatters</span><span class="Special">&quot;</span> =&gt; {
+          <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.markup_lines_to_html(lines, Codnar::Markdown, 'markdown')</span><span class="Special">&quot;</span>,
+          <span class="Special">&quot;</span><span class="Constant">unindented_html</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">&quot;</span>,
+        }
+      )
 </pre>
-<table class='layout'>
+      <table class='layout'>
 <tr>
 <td class='indentation'>
-<pre></pre>
+<pre>      </pre>
 </td>
 <td class='html'>
 <div class='rdoc comment markup'>
@@ -5509,30 +5824,82 @@ preserved by escaping it and wrapping it in an HTML pre element.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="Type">SPLIT_GRAPHVIZ_DOCUMENTATION</span> = <span class="Type">SPLIT_HTML_DOCUMENTATION</span>.deep_merge(
-  <span class="Special">&quot;</span><span class="Constant">formatters</span><span class="Special">&quot;</span> =&gt; {
-    <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.markup_lines_to_html(lines, Codnar::GraphViz, 'graphviz')</span><span class="Special">&quot;</span>,
-    <span class="Special">&quot;</span><span class="Constant">unindented_html</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">&quot;</span>,
-  }
-)
+      <span class="Type">SPLIT_GRAPHVIZ_DOCUMENTATION</span> = <span class="Type">SPLIT_HTML_DOCUMENTATION</span>.deep_merge(
+        <span class="Special">&quot;</span><span class="Constant">formatters</span><span class="Special">&quot;</span> =&gt; {
+          <span class="Special">&quot;</span><span class="Constant">doc</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.markup_lines_to_html(lines, Codnar::GraphViz, 'graphviz')</span><span class="Special">&quot;</span>,
+          <span class="Special">&quot;</span><span class="Constant">unindented_html</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">&quot;</span>,
+        }
+      )
+    end
+  end
+end
 </pre>
 </div>
-<div class="chunk containers">
-<span class="chunk containers header">Contained in:</span>
-<ul class="chunk containers">
-<li class="chunk container">
-<a class="chunk container" href="#lib-codnar-split-configurations-rb">lib/codnar/split_configurations.rb</a>
-</li>
-</ul>
-</div>
 </div>
 </p>
 <h4>Source code lines classification</h4>
 <p>
 Splitting source code files is a more complex affair, which does typically
-require combining several configurations. The basic configuration marks all
-lines as belonging to some code syntax, as a single chunk:
+require combining several configurations.
+</p>
+<p>
+<div class="named_with_containers chunk">
+<div class="chunk name">
+<a name="lib-codnar-configuration-code-rb">
+<span>lib/codnar/configuration/code.rb</span>
+</a>
+</div>
+<div class="chunk html">
+<pre class='ruby code syntax'>
+<span class="PreProc">module</span> <span class="Type">Codnar</span>
+  <span class="PreProc">module</span> <span class="Type">Configuration</span>
+</pre>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Configurations for splitting source code.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+    <span class="PreProc">module</span> <span class="Type">Code</span>
+</pre>
+<pre class='nested chunk'>
+      <a class='nested chunk' href='#source-code-lines-classification-configurations'>Source code lines classification configurations</a>
+</pre>
+<pre class='ruby code syntax'>
+</pre>
+<pre class='nested chunk'>
+      <a class='nested chunk' href='#nested-foreign-syntax-code-islands-configurations'>Nested foreign syntax code islands configurations</a>
+</pre>
+<pre class='ruby code syntax'>
+    end
+  end
+end
+</pre>
+</div>
+</div>
+</p>
+<p>
+The basic configuration marks all lines as belonging to some code syntax, as a
+single chunk:
 </p>
 <p>
 <div class="named_with_containers chunk">
@@ -5591,7 +5958,7 @@ configuration(s).
 <span class="chunk containers header">Contained in:</span>
 <ul class="chunk containers">
 <li class="chunk container">
-<a class="chunk container" href="#lib-codnar-split-configurations-rb">lib/codnar/split_configurations.rb</a>
+<a class="chunk container" href="#lib-codnar-configuration-code-rb">lib/codnar/configuration/code.rb</a>
 </li>
 </ul>
 </div>
@@ -5674,7 +6041,7 @@ nested code may not contain deeper nested code using a third syntax.
 <span class="chunk containers header">Contained in:</span>
 <ul class="chunk containers">
 <li class="chunk container">
-<a class="chunk container" href="#lib-codnar-split-configurations-rb">lib/codnar/split_configurations.rb</a>
+<a class="chunk container" href="#lib-codnar-configuration-code-rb">lib/codnar/configuration/code.rb</a>
 </li>
 </ul>
 </div>
@@ -5768,41 +6135,343 @@ Test combinations of the built-in split code configurations.
     <span class="Identifier">&lt;</span><span class="Statement">pre</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">'ruby code syntax'</span><span class="Identifier">&gt;</span>
 </pre>
 <pre class='ruby code syntax'>
-    &lt;span <span class="PreProc">class</span>=&quot;<span class="Type">Comment</span>&quot;&gt;<span class="Comment"># ))) html&lt;/span&gt;</span>
-    &lt;/pre&gt;
-  <span class="Type">EOF</span>
+    &lt;span <span class="PreProc">class</span>=&quot;<span class="Type">Comment</span>&quot;&gt;<span class="Comment"># ))) html&lt;/span&gt;</span>
+    &lt;/pre&gt;
+  <span class="Type">EOF</span>
+  <span class="PreProc">def</span> <span class="Identifier">test_island_code</span>
+    check_split_file(<span class="Type">ISLAND_CODE</span>, <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_SOURCE_CODE</span>.call(<span class="Special">&quot;</span><span class="Constant">ruby</span><span class="Special">&quot;</span>),
+                                  <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">FORMAT_CODE_GVIM_CSS</span>.call(<span class="Special">&quot;</span><span class="Constant">ruby</span><span class="Special">&quot;</span>),
+                                  <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_NESTED_CODE</span>.call(<span class="Special">&quot;</span><span class="Constant">ruby</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span>),
+                                  <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">FORMAT_CODE_GVIM_CSS</span>.call(<span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span>)) <span class="Statement">do</span> |<span class="Identifier">path</span>|
+      [ {
+        <span class="Special">&quot;</span><span class="Constant">name</span><span class="Special">&quot;</span> =&gt; path,
+        <span class="Special">&quot;</span><span class="Constant">locations</span><span class="Special">&quot;</span> =&gt; [ { <span class="Special">&quot;</span><span class="Constant">file</span><span class="Special">&quot;</span> =&gt; path, <span class="Special">&quot;</span><span class="Constant">line</span><span class="Special">&quot;</span> =&gt; <span class="Constant">1</span> } ],
+        <span class="Special">&quot;</span><span class="Constant">containers</span><span class="Special">&quot;</span> =&gt; [],
+        <span class="Special">&quot;</span><span class="Constant">contained</span><span class="Special">&quot;</span> =&gt; [],
+        <span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span> =&gt; <span class="Type">ISLAND_HTML</span>
+      } ]
+    <span class="Statement">end</span>
+  <span class="PreProc">end</span>
+<span class="PreProc">end</span>
+</pre>
+</div>
+</div>
+</p>
+<h4>Classifying comment lines</h4>
+<p>
+Classifying comment lines is the most complex part of splitting source code
+files, requiring the use of one or more configurations specific to the language
+used.
+</p>
+<p>
+<div class="named_with_containers chunk">
+<div class="chunk name">
+<a name="lib-codnar-configuration-comments-rb">
+<span>lib/codnar/configuration/comments.rb</span>
+</a>
+</div>
+<div class="chunk html">
+<pre class='ruby code syntax'>
+<span class="PreProc">module</span> <span class="Type">Codnar</span>
+  <span class="PreProc">module</span> <span class="Type">Configuration</span>
+</pre>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Configurations for splitting source code with comments.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+    <span class="PreProc">module</span> <span class="Type">Comments</span>
+</pre>
+<pre class='nested chunk'>
+      <a class='nested chunk' href='#simple-comment-classification-configurations'>Simple comment classification configurations</a>
+</pre>
+<pre class='ruby code syntax'>
+</pre>
+<pre class='nested chunk'>
+      <a class='nested chunk' href='#denoted-comment-classification-configurations'>Denoted comment classification configurations</a>
+</pre>
+<pre class='ruby code syntax'>
+</pre>
+<pre class='nested chunk'>
+      <a class='nested chunk' href='#delimited-comment-classification-configurations'>Delimited comment classification configurations</a>
+</pre>
+<pre class='ruby code syntax'>
+</pre>
+<pre class='nested chunk'>
+      <a class='nested chunk' href='#comment-formatting-configurations'>Comment formatting configurations</a>
+</pre>
+<pre class='ruby code syntax'>
+    end
+  end
+end
+</pre>
+</div>
+</div>
+</p>
+<h5>Simple comment classification</h5>
+<p>
+Many languages use a simple comment syntax, where some prefix indicates a
+comment that spans until the end of the line (e.g., shell <code>#</code> comments or C++
+<code>//</code> comments).
+</p>
+<p>
+<div class="named_with_containers chunk">
+<div class="chunk name">
+<a name="simple-comment-classification-configurations">
+<span>Simple comment classification configurations</span>
+</a>
+</div>
+<div class="chunk html">
+<pre class='ruby code syntax'>
+</pre>
+<table class='layout'>
+<tr>
+<td class='indentation'>
+<pre></pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Classify simple comment lines. It accepts a restricted format: each comment
+is expected to start with some exact prefix (e.g. “#” for shell style
+comments or “//” for C++ style comments). The following space, if any,
+is stripped from the payload. As a convenience, comment that starts with
+“!” is not taken to start a comment. This both protects the 1st line of
+shell scripts (“#!”), and also any other line you wish to avoid being
+treated as a comment.
+</p>
+<p>
+This configuration is typically complemented by an additional one
+specifying how to format the (stripped!) comments; by default they are just
+displayed as-is using an HTML <tt>pre</tt> element, which isn’t very
+useful.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+<span class="Type">CLASSIFY_SIMPLE_COMMENTS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span> |<span class="Identifier">prefix</span>|
+  <span class="Statement">return</span> <span class="Type">Comments</span>.simple_comments(prefix)
+<span class="Statement">end</span>
+</pre>
+<table class='layout'>
+<tr>
+<td class='indentation'>
+<pre></pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Classify simple shell (“#”) comment lines.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+<span class="Type">CLASSIFY_SHELL_COMMENTS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span>
+  <span class="Statement">return</span> <span class="Type">Comments</span>.simple_comments(<span class="Special">&quot;</span><span class="Constant">#</span><span class="Special">&quot;</span>)
+<span class="Statement">end</span>
+</pre>
+<table class='layout'>
+<tr>
+<td class='indentation'>
+<pre></pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Classify simple C++ (“//”) comment lines.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+<span class="Type">CLASSIFY_CPP_COMMENTS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span>
+  <span class="Statement">return</span> <span class="Type">Comments</span>.simple_comments(<span class="Special">&quot;</span><span class="Constant">//</span><span class="Special">&quot;</span>)
+<span class="Statement">end</span>
+</pre>
+<table class='layout'>
+<tr>
+<td class='indentation'>
+<pre></pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Configuration for classifying lines to comments and code based on a simple
+prefix (e.g. “#” for shell style comments or “//” for C++ style
+comments).
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+<span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">simple_comments</span>(prefix)
+  <span class="Statement">return</span> {
+    <span class="Special">&quot;</span><span class="Constant">syntax</span><span class="Special">&quot;</span> =&gt; {
+      <span class="Special">&quot;</span><span class="Constant">patterns</span><span class="Special">&quot;</span> =&gt; {
+        <span class="Special">&quot;</span><span class="Constant">comment_</span><span class="Special">#{</span>prefix<span class="Special">}</span><span class="Special">&quot;</span> =&gt; { <span class="Special">&quot;</span><span class="Constant">regexp</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">^(</span><span class="Special">\\</span><span class="Constant">s*)</span><span class="Special">#{</span>prefix<span class="Special">}</span><span class="Constant">(?!!)</span><span class="Special">\\</span><span class="Constant">s?(.*)$</span><span class="Special">&quot;</span> },
+      },
+      <span class="Special">&quot;</span><span class="Constant">states</span><span class="Special">&quot;</span> =&gt; {
+        <span class="Special">&quot;</span><span class="Constant">start</span><span class="Special">&quot;</span> =&gt; {
+          <span class="Special">&quot;</span><span class="Constant">transitions</span><span class="Special">&quot;</span> =&gt; [
+            { <span class="Special">&quot;</span><span class="Constant">pattern</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">comment_</span><span class="Special">#{</span>prefix<span class="Special">}</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">kind</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">comment</span><span class="Special">&quot;</span> },
+            []
+          ],
+        },
+      },
+    },
+  }
+<span class="PreProc">end</span>
+</pre>
+</div>
+<div class="chunk containers">
+<span class="chunk containers header">Contained in:</span>
+<ul class="chunk containers">
+<li class="chunk container">
+<a class="chunk container" href="#lib-codnar-configuration-comments-rb">lib/codnar/configuration/comments.rb</a>
+</li>
+</ul>
+</div>
+</div>
+</p>
+<p>
+Here is a simple test demonstrating using simple comment classifications:
+</p>
+<p>
+<div class="named_with_containers chunk">
+<div class="chunk name">
+<a name="test-split-simple-comment-configurations-rb">
+<span>test/split_simple_comment_configurations.rb</span>
+</a>
+</div>
+<div class="chunk html">
+<pre class='ruby code syntax'>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar</span><span class="Special">&quot;</span>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">olag/test</span><span class="Special">&quot;</span>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">test/spec</span><span class="Special">&quot;</span>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">test_with_configurations</span><span class="Special">&quot;</span>
+</pre>
+<table class='layout'>
+<tr>
+<td class='indentation'>
+<pre></pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Test built-in split simple comment configurations.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+<span class="PreProc">class</span> <span class="Type">TestSplitSimpleCommentsConfigurations</span> &lt; <span class="Type">Test</span>::<span class="Type">Unit</span>::<span class="Type">TestCase</span>
+  <span class="PreProc">include</span> <span class="Type">Test</span>::<span class="Type">WithConfigurations</span>
+  <span class="PreProc">include</span> <span class="Type">Test</span>::<span class="Type">WithErrors</span>
+  <span class="PreProc">include</span> <span class="Type">Test</span>::<span class="Type">WithTempfile</span>
+  <span class="PreProc">def</span> <span class="Identifier">test_custom_comments</span>
+    check_any_comment(<span class="Special">&quot;</span><span class="Constant">!</span><span class="Special">&quot;</span>, <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_SIMPLE_COMMENTS</span>.call(<span class="Special">&quot;</span><span class="Constant">!</span><span class="Special">&quot;</span>))
+  <span class="PreProc">end</span>
+  <span class="PreProc">def</span> <span class="Identifier">test_shell_comments</span>
+    check_any_comment(<span class="Special">&quot;</span><span class="Constant">#</span><span class="Special">&quot;</span>, <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_SHELL_COMMENTS</span>.call)
+  <span class="PreProc">end</span>
+  <span class="PreProc">def</span> <span class="Identifier">test_cpp_comments</span>
+    check_any_comment(<span class="Special">&quot;</span><span class="Constant">//</span><span class="Special">&quot;</span>, <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_CPP_COMMENTS</span>.call)
+  <span class="PreProc">end</span>
+<span class="Statement">protected</span>
+</pre>
+  <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>  </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+The “?” will be replaced by the simple comment prefix.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+  <span class="Type">ANY_COMMENT_CODE</span> = &lt;&lt;-<span class="Special">EOF</span>.unindent
+<span class="Constant">    ?</span>
+<span class="Constant">    ? Comment</span>
+<span class="Constant">    Code</span>
+<span class="Constant">    ?! Not comment</span>
+<span class="Constant">  </span><span class="Special">EOF</span>
-  <span class="PreProc">def</span> <span class="Identifier">test_island_code</span>
-    check_split_file(<span class="Type">ISLAND_CODE</span>, <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_SOURCE_CODE</span>.call(<span class="Special">&quot;</span><span class="Constant">ruby</span><span class="Special">&quot;</span>),
-                                  <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">FORMAT_CODE_GVIM_CSS</span>.call(<span class="Special">&quot;</span><span class="Constant">ruby</span><span class="Special">&quot;</span>),
-                                  <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_NESTED_CODE</span>.call(<span class="Special">&quot;</span><span class="Constant">ruby</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span>),
-                                  <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">FORMAT_CODE_GVIM_CSS</span>.call(<span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span>)) <span class="Statement">do</span> |<span class="Identifier">path</span>|
+  <span class="PreProc">def</span> <span class="Identifier">check_any_comment</span>(prefix, configuration)
+    check_split_file(<span class="Type">ANY_COMMENT_CODE</span>.gsub(<span class="Special">&quot;</span><span class="Constant">?</span><span class="Special">&quot;</span>, prefix),
+                     <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_SOURCE_CODE</span>.call(<span class="Special">&quot;</span><span class="Constant">any</span><span class="Special">&quot;</span>),
+                     <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">FORMAT_PRE_COMMENTS</span>,
+                     configuration) <span class="Statement">do</span> |<span class="Identifier">path</span>|
       [ {
         <span class="Special">&quot;</span><span class="Constant">name</span><span class="Special">&quot;</span> =&gt; path,
         <span class="Special">&quot;</span><span class="Constant">locations</span><span class="Special">&quot;</span> =&gt; [ { <span class="Special">&quot;</span><span class="Constant">file</span><span class="Special">&quot;</span> =&gt; path, <span class="Special">&quot;</span><span class="Constant">line</span><span class="Special">&quot;</span> =&gt; <span class="Constant">1</span> } ],
         <span class="Special">&quot;</span><span class="Constant">containers</span><span class="Special">&quot;</span> =&gt; [],
         <span class="Special">&quot;</span><span class="Constant">contained</span><span class="Special">&quot;</span> =&gt; [],
-        <span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span> =&gt; <span class="Type">ISLAND_HTML</span>
+        <span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">&lt;pre class='comment'&gt;</span><span class="Special">\n\n</span><span class="Constant">Comment</span><span class="Special">\n</span><span class="Constant">&lt;/pre&gt;</span><span class="Special">\n</span><span class="Constant">&lt;pre class='code'&gt;</span><span class="Special">\n</span><span class="Constant">Code</span><span class="Special">\n</span><span class="Special">#{</span>prefix<span class="Special">}</span><span class="Constant">! Not comment</span><span class="Special">\n</span><span class="Constant">&lt;/pre&gt;</span><span class="Special">&quot;</span>
       } ]
     <span class="Statement">end</span>
   <span class="PreProc">end</span>
-<span class="PreProc">end</span>
+end
 </pre>
 </div>
 </div>
 </p>
-<h4>Simple comment classification</h4>
+<h5>Denoted comment classification</h5>
 <p>
-Many languages use a simple comment syntax, where some prefix indicates a
-comment that spans until the end of the line (e.g., shell <code>#</code> comments or C++
-<code>//</code> comments).
+Sometimes some simple comments require special treatment if they are denoted by
+some leading prefix. For example, Haskell simple comments start with <code>--</code> but
+Haddock (documentation) comments start with <code>-- |</code>, <code>-- ^</code> etc.
 </p>
 <p>
 <div class="named_with_containers chunk">
 <div class="chunk name">
-<a name="simple-comment-classification-configurations">
-<span>Simple comment classification configurations</span>
+<a name="denoted-comment-classification-configurations">
+<span>Denoted comment classification configurations</span>
 </a>
 </div>
 <div class="chunk html">
@@ -5817,13 +6486,11 @@ comment that spans until the end of the line (e.g., shell <code>#</code> comment
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Classify simple comment lines. It accepts a restricted format: each comment
-is expected to start with some exact prefix (e.g. “#” for shell style
-comments or “//” for C++ style comments). The following space, if any,
-is stripped from the payload. As a convenience, comment that starts with
-“!” is not taken to start a comment. This both protects the 1st line of
-shell scripts (“#!”), and also any other line you wish to avoid being
-treated as a comment.
+Classify denoted comment lines. Denoted comments are similar to simple
+comments, except that the 1st simple comment line must start with a
+specific prefix (e.g., in haddock, comment lines start with ‘–’ but
+haddoc comments start with ‘– |’, ‘– ^’, etc.). The comment
+continues in additional simple comment lines.
 </p>
 <p>
 This configuration is typically complemented by an additional one
@@ -5836,8 +6503,8 @@ useful.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="Type">CLASSIFY_SIMPLE_COMMENTS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span> |<span class="Identifier">prefix</span>|
-  <span class="Statement">return</span> <span class="Type">Configuration</span>.simple_comments(prefix)
+<span class="Type">CLASSIFY_DENOTED_COMMENTS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span> |<span class="Identifier">start_prefix</span>, <span class="Identifier">continue_prefix</span>|
+  <span class="Statement">return</span> <span class="Type">Comments</span>.denoted_comments(start_prefix, continue_prefix)
 <span class="Statement">end</span>
 </pre>
@@ -5849,15 +6516,17 @@ useful.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Classify simple shell (“#”) comment lines.
+Classify denoted haddock (“–”) comment lines. Note that non-haddock
+comment lines are not captured; they would treated as code and handled by
+syntax highlighting, if any.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="Type">CLASSIFY_SHELL_COMMENTS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span>
-  <span class="Statement">return</span> <span class="Type">Configuration</span>.simple_comments(<span class="Special">&quot;</span><span class="Constant">#</span><span class="Special">&quot;</span>)
+<span class="Type">CLASSIFY_HADDOCK_COMMENTS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span>
+  <span class="Statement">return</span> <span class="Type">Comments</span>.denoted_comments(<span class="Special">&quot;</span><span class="Constant">-- [|^$]</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">--</span><span class="Special">&quot;</span>)
 <span class="Statement">end</span>
 </pre>
@@ -5869,52 +6538,58 @@ Classify simple shell (“#”) comment lines.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Classify simple C++ (“//”) comment lines.
+Configuration for classifying lines to comments and code based on a start
+comment prefix and continuation comment prefix (e.g., “– |” and
+“–” for haddock).
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="Type">CLASSIFY_CPP_COMMENTS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span>
-  <span class="Statement">return</span> <span class="Type">Configuration</span>.simple_comments(<span class="Special">&quot;</span><span class="Constant">//</span><span class="Special">&quot;</span>)
-<span class="Statement">end</span>
+<span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">denoted_comments</span>(start_prefix, continue_prefix)
 </pre>
-<table class='layout'>
+  <table class='layout'>
 <tr>
 <td class='indentation'>
-<pre></pre>
+<pre>  </pre>
 </td>
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Configuration for classifying lines to comments and code based on a simple
-prefix (e.g. “#” for shell style comments or “//” for C++ style
-comments).
+Ruby coverage somehow barfs if we inline this. Go figure.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">simple_comments</span>(prefix)
+  start_transition = {
+    <span class="Special">&quot;</span><span class="Constant">pattern</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">comment_start_</span><span class="Special">#{</span>start_prefix<span class="Special">}</span><span class="Special">&quot;</span>,
+    <span class="Special">&quot;</span><span class="Constant">next_state</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">comment_continue_</span><span class="Special">#{</span>continue_prefix<span class="Special">}</span><span class="Special">&quot;</span>,
+    <span class="Special">&quot;</span><span class="Constant">kind</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">comment</span><span class="Special">&quot;</span>
+  }
   <span class="Statement">return</span> {
     <span class="Special">&quot;</span><span class="Constant">syntax</span><span class="Special">&quot;</span> =&gt; {
       <span class="Special">&quot;</span><span class="Constant">patterns</span><span class="Special">&quot;</span> =&gt; {
-        <span class="Special">&quot;</span><span class="Constant">comment_</span><span class="Special">#{</span>prefix<span class="Special">}</span><span class="Special">&quot;</span> =&gt; { <span class="Special">&quot;</span><span class="Constant">regexp</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">^(</span><span class="Special">\\</span><span class="Constant">s*)</span><span class="Special">#{</span>prefix<span class="Special">}</span><span class="Constant">(?!!)</span><span class="Special">\\</span><span class="Constant">s?(.*)$</span><span class="Special">&quot;</span> },
+        <span class="Special">&quot;</span><span class="Constant">comment_start_</span><span class="Special">#{</span>start_prefix<span class="Special">}</span><span class="Special">&quot;</span> =&gt; { <span class="Special">&quot;</span><span class="Constant">regexp</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">^(</span><span class="Special">\\</span><span class="Constant">s*)</span><span class="Special">#{</span>start_prefix<span class="Special">}</span><span class="Special">\\</span><span class="Constant">s?(.*)$</span><span class="Special">&quot;</span> },
+        <span class="Special">&quot;</span><span class="Constant">comment_continue_</span><span class="Special">#{</span>continue_prefix<span class="Special">}</span><span class="Special">&quot;</span> =&gt; { <span class="Special">&quot;</span><span class="Constant">regexp</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">^(</span><span class="Special">\\</span><span class="Constant">s*)</span><span class="Special">#{</span>continue_prefix<span class="Special">}</span><span class="Special">\\</span><span class="Constant">s?(.*)$</span><span class="Special">&quot;</span> },
       },
       <span class="Special">&quot;</span><span class="Constant">states</span><span class="Special">&quot;</span> =&gt; {
         <span class="Special">&quot;</span><span class="Constant">start</span><span class="Special">&quot;</span> =&gt; {
-          <span class="Special">&quot;</span><span class="Constant">transitions</span><span class="Special">&quot;</span> =&gt; [
-            { <span class="Special">&quot;</span><span class="Constant">pattern</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">comment_</span><span class="Special">#{</span>prefix<span class="Special">}</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">kind</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">comment</span><span class="Special">&quot;</span> },
-            []
+          <span class="Special">&quot;</span><span class="Constant">transitions</span><span class="Special">&quot;</span> =&gt; [ start_transition, [] ],
+        },
+        <span class="Special">&quot;</span><span class="Constant">comment_continue_</span><span class="Special">#{</span>continue_prefix<span class="Special">}</span><span class="Special">&quot;</span> =&gt; {
+          <span class="Special">&quot;</span><span class="Constant">transitions</span><span class="Special">&quot;</span> =&gt; [ {
+              <span class="Special">&quot;</span><span class="Constant">pattern</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">comment_continue_</span><span class="Special">#{</span>continue_prefix<span class="Special">}</span><span class="Special">&quot;</span>,
+              <span class="Special">&quot;</span><span class="Constant">kind</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">comment</span><span class="Special">&quot;</span> },
+            { <span class="Special">&quot;</span><span class="Constant">next_state</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">start</span><span class="Special">&quot;</span> }
           ],
         },
       },
     },
   }
-<span class="PreProc">end</span>
+end
 </pre>
 </div>
@@ -5922,20 +6597,20 @@ comments).
 <span class="chunk containers header">Contained in:</span>
 <ul class="chunk containers">
 <li class="chunk container">
-<a class="chunk container" href="#lib-codnar-split-configurations-rb">lib/codnar/split_configurations.rb</a>
+<a class="chunk container" href="#lib-codnar-configuration-comments-rb">lib/codnar/configuration/comments.rb</a>
 </li>
 </ul>
 </div>
 </div>
 </p>
 <p>
-Here is a simple test demonstrating using simple comment classifications:
+Here is a simple test demonstrating using denoted comment classifications:
 </p>
 <p>
 <div class="named_with_containers chunk">
 <div class="chunk name">
-<a name="test-split-simple-comment-configurations-rb">
-<span>test/split_simple_comment_configurations.rb</span>
+<a name="test-split-denoted-comment-configurations-rb">
+<span>test/split_denoted_comment_configurations.rb</span>
 </a>
 </div>
 <div class="chunk html">
@@ -5954,29 +6629,25 @@ Here is a simple test demonstrating using simple comment classifications:
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Test built-in split simple comment configurations.
+Test built-in split denoted comment configurations.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="PreProc">class</span> <span class="Type">TestSplitSimpleCommentsConfigurations</span> &lt; <span class="Type">Test</span>::<span class="Type">Unit</span>::<span class="Type">TestCase</span>
+<span class="PreProc">class</span> <span class="Type">TestSplitDenotedCommentsConfigurations</span> &lt; <span class="Type">Test</span>::<span class="Type">Unit</span>::<span class="Type">TestCase</span>
   <span class="PreProc">include</span> <span class="Type">Test</span>::<span class="Type">WithConfigurations</span>
   <span class="PreProc">include</span> <span class="Type">Test</span>::<span class="Type">WithErrors</span>
   <span class="PreProc">include</span> <span class="Type">Test</span>::<span class="Type">WithTempfile</span>
   <span class="PreProc">def</span> <span class="Identifier">test_custom_comments</span>
-    check_any_comment(<span class="Special">&quot;</span><span class="Constant">!</span><span class="Special">&quot;</span>, <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_SIMPLE_COMMENTS</span>.call(<span class="Special">&quot;</span><span class="Constant">!</span><span class="Special">&quot;</span>))
+    check_any_comment(<span class="Special">&quot;</span><span class="Constant">// @</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">//</span><span class="Special">&quot;</span>, <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_DENOTED_COMMENTS</span>.call(<span class="Special">&quot;</span><span class="Constant">// @</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">//</span><span class="Special">&quot;</span>))
   <span class="PreProc">end</span>
-  <span class="PreProc">def</span> <span class="Identifier">test_shell_comments</span>
-    check_any_comment(<span class="Special">&quot;</span><span class="Constant">#</span><span class="Special">&quot;</span>, <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_SHELL_COMMENTS</span>.call)
-  <span class="PreProc">end</span>
-  <span class="PreProc">def</span> <span class="Identifier">test_cpp_comments</span>
-    check_any_comment(<span class="Special">&quot;</span><span class="Constant">//</span><span class="Special">&quot;</span>, <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_CPP_COMMENTS</span>.call)
+  <span class="PreProc">def</span> <span class="Identifier">test_haddoc_comments</span>
+    check_any_comment(<span class="Special">&quot;</span><span class="Constant">-- |</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">--</span><span class="Special">&quot;</span>, <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_HADDOCK_COMMENTS</span>.call)
   <span class="PreProc">end</span>
 <span class="Statement">protected</span>
@@ -5990,7 +6661,8 @@ Test built-in split simple comment configurations.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-The “?” will be replaced by the simple comment prefix.
+The “&lt;&lt;&lt;” will be replaced by the start comment prefix, and
+the “&gt;&gt;&gt;” will be replaced by the continue comment prefix.
 </p>
 </div>
 </td>
@@ -5998,35 +6670,67 @@ The “?” will be replaced by the simple comment prefix.
 </table>
 <pre class='ruby code syntax'>
   <span class="Type">ANY_COMMENT_CODE</span> = &lt;&lt;-<span class="Special">EOF</span>.unindent
-<span class="Constant">    ?</span>
-<span class="Constant">    ? Comment</span>
-<span class="Constant">    Code</span>
-<span class="Constant">    ?! Not comment</span>
+<span class="Constant">    &gt;&gt;&gt; Not start comment</span>
+<span class="Constant">    &lt;&lt;&lt; Start comment</span>
+<span class="Constant">    &gt;&gt;&gt; Continue comment</span>
+<span class="Constant">    Not a comment</span>
 <span class="Constant">  </span><span class="Special">EOF</span>
-  <span class="PreProc">def</span> <span class="Identifier">check_any_comment</span>(prefix, configuration)
-    check_split_file(<span class="Type">ANY_COMMENT_CODE</span>.gsub(<span class="Special">&quot;</span><span class="Constant">?</span><span class="Special">&quot;</span>, prefix),
-                     <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_SOURCE_CODE</span>.call(<span class="Special">&quot;</span><span class="Constant">any</span><span class="Special">&quot;</span>),
-                     <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">FORMAT_PRE_COMMENTS</span>,
-                     configuration) <span class="Statement">do</span> |<span class="Identifier">path</span>|
+</pre>
+  <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>  </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+The “&gt;&gt;&gt;” will be replaced by the continue comment prefix.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+  <span class="Type">ANY_COMMENT_HTML</span> = &lt;&lt;-<span class="Special">EOF</span>.unindent.chomp <span class="Comment"># ((( html</span>
+</pre>
+<pre class='html code syntax'>
+    <span class="Identifier">&lt;</span><span class="Statement">pre</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">'code'</span><span class="Identifier">&gt;</span>
+    <span class="Error">&gt;&gt;&gt;</span> Not start comment
+    <span class="Identifier">&lt;/</span><span class="Statement">pre</span><span class="Identifier">&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Statement">pre</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">'comment'</span><span class="Identifier">&gt;</span>
+    Start comment
+    Continue comment
+    <span class="Identifier">&lt;/</span><span class="Statement">pre</span><span class="Identifier">&gt;</span>
+    <span class="Identifier">&lt;</span><span class="Statement">pre</span><span class="Identifier"> </span><span class="Type">class</span><span class="Identifier">=</span><span class="Constant">'code'</span><span class="Identifier">&gt;</span>
+    Not a comment
+    <span class="Identifier">&lt;/</span><span class="Statement">pre</span><span class="Identifier">&gt;</span>
+  EOF
+  # )))
+  def check_any_comment(start_prefix, continue_prefix, configuration)
+    check_split_file(ANY_COMMENT_CODE.gsub(&quot;<span class="Identifier">&lt;</span><span class="Error">&lt;</span><span class="Identifier">&lt;</span><span class="Constant">&quot;, start_prefix).gsub(&quot;</span><span class="Identifier">&gt;</span><span class="Error">&gt;&gt;</span>&quot;, continue_prefix),
+                     Codnar::Configuration::CLASSIFY_SOURCE_CODE.call(&quot;any&quot;),
+                     Codnar::Configuration::FORMAT_PRE_COMMENTS,
+                     configuration) do |path|
       [ {
-        <span class="Special">&quot;</span><span class="Constant">name</span><span class="Special">&quot;</span> =&gt; path,
-        <span class="Special">&quot;</span><span class="Constant">locations</span><span class="Special">&quot;</span> =&gt; [ { <span class="Special">&quot;</span><span class="Constant">file</span><span class="Special">&quot;</span> =&gt; path, <span class="Special">&quot;</span><span class="Constant">line</span><span class="Special">&quot;</span> =&gt; <span class="Constant">1</span> } ],
-        <span class="Special">&quot;</span><span class="Constant">containers</span><span class="Special">&quot;</span> =&gt; [],
-        <span class="Special">&quot;</span><span class="Constant">contained</span><span class="Special">&quot;</span> =&gt; [],
-        <span class="Special">&quot;</span><span class="Constant">html</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">&lt;pre class='comment'&gt;</span><span class="Special">\n\n</span><span class="Constant">Comment</span><span class="Special">\n</span><span class="Constant">&lt;/pre&gt;</span><span class="Special">\n</span><span class="Constant">&lt;pre class='code'&gt;</span><span class="Special">\n</span><span class="Constant">Code</span><span class="Special">\n</span><span class="Special">#{</span>prefix<span class="Special">}</span><span class="Constant">! Not comment</span><span class="Special">\n</span><span class="Constant">&lt;/pre&gt;</span><span class="Special">&quot;</span>
+        &quot;name&quot; =<span class="Error">&gt;</span> path,
+        &quot;locations&quot; =<span class="Error">&gt;</span> [ { &quot;file&quot; =<span class="Error">&gt;</span> path, &quot;line&quot; =<span class="Error">&gt;</span> 1 } ],
+        &quot;containers&quot; =<span class="Error">&gt;</span> [],
+        &quot;contained&quot; =<span class="Error">&gt;</span> [],
+        &quot;html&quot; =<span class="Error">&gt;</span> ANY_COMMENT_HTML.gsub(&quot;<span class="Error">&gt;&gt;&gt;</span>&quot;, continue_prefix),
       } ]
-    <span class="Statement">end</span>
-  <span class="PreProc">end</span>
+    end
+  end
 end
 </pre>
 </div>
 </div>
 </p>
-<h4>Complex comment classification</h4>
+<h5>Delimited comment classification</h5>
 <p>
-Other languages use a complex multi-line comment syntax, where some prefix
+Other languages use a delimited multi-line comment syntax, where some prefix
 indicates the beginning of the comment, some suffix indicates the end, and by
 convention some prefix is expected for the inner comment lines (e.g., C's
 "<code>/*</code>", "<code>*</code>", "<code>*/</code>" comments or HTML's "<code>&lt;!--</code>", "<code>-</code>", "<code>--&gt;</code>" comments).
@@ -6034,8 +6738,8 @@ convention some prefix is expected for the inner comment lines (e.g., C's
 <p>
 <div class="named_with_containers chunk">
 <div class="chunk name">
-<a name="complex-comment-classification-configurations">
-<span>Complex comment classification configurations</span>
+<a name="delimited-comment-classification-configurations">
+<span>Delimited comment classification configurations</span>
 </a>
 </div>
 <div class="chunk html">
@@ -6050,7 +6754,7 @@ convention some prefix is expected for the inner comment lines (e.g., C's
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Classify complex comment lines. It accepts a restricted format: each
+Classify delimited comment lines. It accepts a restricted format: each
 comment is expected to start with some exact prefix (e.g. “/*” for C
 style comments or “&lt;!–” for HTML style comments). The following
 space, if any, is stripped from the payload. Following lines are also
@@ -6075,8 +6779,8 @@ useful.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="Type">CLASSIFY_COMPLEX_COMMENTS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span> |<span class="Identifier">prefix</span>, <span class="Identifier">inner</span>, <span class="Identifier">suffix</span>|
-  <span class="Statement">return</span> <span class="Type">Configuration</span>.complex_comments(prefix, inner, suffix)
+<span class="Type">CLASSIFY_DELIMITED_COMMENTS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span> |<span class="Identifier">prefix</span>, <span class="Identifier">inner</span>, <span class="Identifier">suffix</span>|
+  <span class="Statement">return</span> <span class="Type">Comments</span>.delimited_comments(prefix, inner, suffix)
 <span class="Statement">end</span>
 </pre>
@@ -6088,7 +6792,7 @@ useful.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Classify complex C (“/*”, “ *”, “ */”) style comments.
+Classify delimited C (“/*”, “ *”, “ */”) style comments.
 </p>
 </div>
 </td>
@@ -6113,7 +6817,7 @@ need to escape special characters such as “*”.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-  <span class="Statement">return</span> <span class="Type">Configuration</span>.complex_comments(<span class="Special">&quot;</span><span class="Constant">/</span><span class="Special">\\</span><span class="Constant">*</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> </span><span class="Special">\\</span><span class="Constant">*</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> </span><span class="Special">\\</span><span class="Constant">*/</span><span class="Special">&quot;</span>)
+  <span class="Statement">return</span> <span class="Type">Comments</span>.delimited_comments(<span class="Special">&quot;</span><span class="Constant">/</span><span class="Special">\\</span><span class="Constant">*</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> </span><span class="Special">\\</span><span class="Constant">*</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> </span><span class="Special">\\</span><span class="Constant">*/</span><span class="Special">&quot;</span>)
 end
 </pre>
@@ -6125,7 +6829,7 @@ end
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Classify complex HTML (“&lt;!–”, “ -”, “–&gt;”) style
+Classify delimited HTML (“&lt;!–”, “ -”, “–&gt;”) style
 comments.
 </p>
 </div>
@@ -6134,7 +6838,7 @@ comments.
 </table>
 <pre class='ruby code syntax'>
 <span class="Type">CLASSIFY_HTML_COMMENTS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span>
-  <span class="Statement">return</span> <span class="Type">Configuration</span>.complex_comments(<span class="Special">&quot;</span><span class="Constant">&lt;!--</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> -</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">--&gt;</span><span class="Special">&quot;</span>)
+  <span class="Statement">return</span> <span class="Type">Comments</span>.delimited_comments(<span class="Special">&quot;</span><span class="Constant">&lt;!--</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> -</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant">--&gt;</span><span class="Special">&quot;</span>)
 <span class="Statement">end</span>
 </pre>
@@ -6146,17 +6850,17 @@ comments.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Configuration for classifying lines to comments and code based on a complex
-start prefix, inner line prefix and final suffix (e.g., “/*”, “ *”,
-“ */” for C-style comments or “&lt;!–”, “ -”, “–&gt;”
-for HTML style comments).
+Configuration for classifying lines to comments and code based on a
+delimited start prefix, inner line prefix and final suffix (e.g., “/*”,
+“ *”, “ */” for C-style comments or “&lt;!–”, “ -”,
+“–&gt;” for HTML style comments).
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">complex_comments</span>(prefix, inner, suffix)
+<span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">delimited_comments</span>(prefix, inner, suffix)
   <span class="Statement">return</span> {
     <span class="Special">&quot;</span><span class="Constant">syntax</span><span class="Special">&quot;</span> =&gt; {
       <span class="Special">&quot;</span><span class="Constant">patterns</span><span class="Special">&quot;</span> =&gt; {
@@ -6196,20 +6900,20 @@ for HTML style comments).
 <span class="chunk containers header">Contained in:</span>
 <ul class="chunk containers">
 <li class="chunk container">
-<a class="chunk container" href="#lib-codnar-split-configurations-rb">lib/codnar/split_configurations.rb</a>
+<a class="chunk container" href="#lib-codnar-configuration-comments-rb">lib/codnar/configuration/comments.rb</a>
 </li>
 </ul>
 </div>
 </div>
 </p>
 <p>
-Here is a simple test demonstrating using complex comment classifications:
+Here is a simple test demonstrating using delimited comment classifications:
 </p>
 <p>
 <div class="named_with_containers chunk">
 <div class="chunk name">
-<a name="test-split-complex-comment-configurations-rb">
-<span>test/split_complex_comment_configurations.rb</span>
+<a name="test-split-delimited-comment-configurations-rb">
+<span>test/split_delimited_comment_configurations.rb</span>
 </a>
 </div>
 <div class="chunk html">
@@ -6228,14 +6932,14 @@ Here is a simple test demonstrating using complex comment classifications:
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-Test built-in split complex comment configurations.
+Test built-in split delimited comment configurations.
 </p>
 </div>
 </td>
 </tr>
 </table>
 <pre class='ruby code syntax'>
-<span class="PreProc">class</span> <span class="Type">TestSplitComplexCommentsConfigurations</span> &lt; <span class="Type">Test</span>::<span class="Type">Unit</span>::<span class="Type">TestCase</span>
+<span class="PreProc">class</span> <span class="Type">TestSplitDelimitedCommentsConfigurations</span> &lt; <span class="Type">Test</span>::<span class="Type">Unit</span>::<span class="Type">TestCase</span>
   <span class="PreProc">include</span> <span class="Type">Test</span>::<span class="Type">WithConfigurations</span>
   <span class="PreProc">include</span> <span class="Type">Test</span>::<span class="Type">WithErrors</span>
@@ -6259,7 +6963,7 @@ need to escape special characters such as “{” and “|”.
 </tr>
 </table>
 <pre class='ruby code syntax'>
-    check_any_comment([ <span class="Special">&quot;</span><span class="Constant">@{</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> |</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> }@</span><span class="Special">&quot;</span> ], <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_COMPLEX_COMMENTS</span>.call(<span class="Special">&quot;</span><span class="Constant">@</span><span class="Special">\\</span><span class="Constant">{</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> </span><span class="Special">\\</span><span class="Constant">|</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> </span><span class="Special">\\</span><span class="Constant">}@</span><span class="Special">&quot;</span>))
+    check_any_comment([ <span class="Special">&quot;</span><span class="Constant">@{</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> |</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> }@</span><span class="Special">&quot;</span> ], <span class="Type">Codnar</span>::<span class="Type">Configuration</span>::<span class="Type">CLASSIFY_DELIMITED_COMMENTS</span>.call(<span class="Special">&quot;</span><span class="Constant">@</span><span class="Special">\\</span><span class="Constant">{</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> </span><span class="Special">\\</span><span class="Constant">|</span><span class="Special">&quot;</span>, <span class="Special">&quot;</span><span class="Constant"> </span><span class="Special">\\</span><span class="Constant">}@</span><span class="Special">&quot;</span>))
   end
   <span class="PreProc">def</span> <span class="Identifier">test_c_comments</span>
@@ -6281,9 +6985,9 @@ need to escape special characters such as “{” and “|”.
 <td class='html'>
 <div class='rdoc comment markup'>
 <p>
-The “&lt;&lt;&lt;” will be replaced by the complex comment prefix, the
+The “&lt;&lt;&lt;” will be replaced by the start comment prefix, the
 “&lt;&gt;” will be replaced by the inner line comment prefix, and the
-“&gt;&gt;&gt;” will be replaced by the complex comment suffix.
+“&gt;&gt;&gt;” will be replaced by the end comment suffix.
 </p>
 </div>
 </td>
@@ -6291,12 +6995,12 @@ The “&lt;&lt;&lt;” will be replaced by the complex comment prefix, the
 </table>
 <pre class='ruby code syntax'>
   <span class="Type">ANY_COMMENT_CODE</span> = &lt;&lt;-<span class="Special">EOF</span>.unindent
-<span class="Constant">    /-- One-line comment --/</span>
+<span class="Constant">    &lt;&lt;&lt; One-line comment &gt;&gt;&gt;</span>
 <span class="Constant">    Code</span>
-<span class="Constant">    /--</span>
-<span class="Constant">     - Multi-line</span>
-<span class="Constant">     - comment.</span>
-<span class="Constant">    --/</span>
+<span class="Constant">    &lt;&lt;&lt;</span>
+<span class="Constant">    &lt;&gt; Multi-line</span>
+<span class="Constant">    &lt;&gt; comment.</span>
+<span class="Constant">    &gt;&gt;&gt;</span>
 <span class="Constant">  </span><span class="Special">EOF</span>
   <span class="Type">ANY_COMMENT_HTML</span> = &lt;&lt;-<span class="Special">EOF</span>.unindent.chomp <span class="Comment"># ((( html</span>
@@ -6319,21 +7023,21 @@ The “&lt;&lt;&lt;” will be replaced by the complex comment prefix, the
   def check_any_comment(patterns, configuration)
     prefix, inner, suffix = patterns
-    check_split_file(ANY_COMMENT_CODE.gsub(&quot;/--&quot;, prefix).gsub(&quot;--/&quot;, suffix).gsub(&quot; -&quot;, inner),
-                     Codnar::Configuration::CLASSIFY_SOURCE_CODE.call(&quot;any&quot;),
-                     Codnar::Configuration::FORMAT_PRE_COMMENTS,
-                     configuration) do |path|
-      [ {
-        &quot;name&quot; =<span class="Error">&gt;</span> path,
-        &quot;locations&quot; =<span class="Error">&gt;</span> [ { &quot;file&quot; =<span class="Error">&gt;</span> path, &quot;line&quot; =<span class="Error">&gt;</span> 1 } ],
-        &quot;containers&quot; =<span class="Error">&gt;</span> [],
-        &quot;contained&quot; =<span class="Error">&gt;</span> [],
-        &quot;html&quot; =<span class="Error">&gt;</span> ANY_COMMENT_HTML.gsub(&quot;/--&quot;, prefix).gsub(&quot;--/&quot;, suffix).gsub(&quot; -&quot;, inner),
-      } ]
-    end
-  end
+    check_split_file(ANY_COMMENT_CODE.gsub(&quot;<span class="Identifier">&lt;</span><span class="Error">&lt;</span><span class="Identifier">&lt;</span><span class="Constant">&quot;, prefix).gsub(&quot;</span><span class="Identifier">&gt;</span><span class="Error">&gt;&gt;</span>&quot;, suffix).gsub(&quot;<span class="Identifier">&lt;&gt;</span><span class="Constant">&quot;, inner),</span>
+<span class="Constant">                     Codnar::Configuration::CLASSIFY_SOURCE_CODE.call(&quot;</span><span class="Identifier">any</span><span class="Constant">&quot;),</span>
+<span class="Constant">                     Codnar::Configuration::FORMAT_PRE_COMMENTS,</span>
+<span class="Constant">                     configuration) do |path|</span>
+<span class="Constant">      [ {</span>
+<span class="Constant">        &quot;</span><span class="Type">name</span><span class="Constant">&quot; =&gt; path,</span>
+<span class="Constant">        &quot;</span><span class="Identifier">locations</span><span class="Constant">&quot; =&gt; [ { &quot;</span><span class="Identifier">file</span><span class="Constant">&quot; =&gt; path, &quot;</span><span class="Identifier">line</span><span class="Constant">&quot; =&gt; 1 } ],</span>
+<span class="Constant">        &quot;</span><span class="Identifier">containers</span><span class="Constant">&quot; =&gt; [],</span>
+<span class="Constant">        &quot;</span><span class="Identifier">contained</span><span class="Constant">&quot; =&gt; [],</span>
+<span class="Constant">        &quot;</span><span class="Identifier">html</span><span class="Constant">&quot; =&gt; ANY_COMMENT_HTML.gsub(&quot;</span><span class="Identifier">/--</span><span class="Constant">&quot;, prefix).gsub(&quot;</span><span class="Identifier">--/</span><span class="Constant">&quot;, suffix).gsub(&quot;</span><span class="Identifier"> -</span><span class="Constant">&quot;, inner),</span>
+<span class="Constant">      } ]</span>
+<span class="Constant">    end</span>
+<span class="Constant">  end</span>
-end
+<span class="Constant">end</span>
 </pre>
 </div>
 </div>
@@ -6425,13 +7129,37 @@ configuration that classifies some lines as <tt>comment</tt>.
   },
 }
+</pre>
+<table class='layout'>
+<tr>
+<td class='indentation'>
+<pre></pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Format comments that use the Haddock notation. Is used to complement a
+configuration that classifies some lines as <tt>comment</tt>.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+<span class="Type">FORMAT_HADDOCK_COMMENTS</span> = {
+  <span class="Special">&quot;</span><span class="Constant">formatters</span><span class="Special">&quot;</span> =&gt; {
+    <span class="Special">&quot;</span><span class="Constant">comment</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.markup_lines_to_html(lines, Haddock, 'haddock')</span><span class="Special">&quot;</span>,
+    <span class="Special">&quot;</span><span class="Constant">unindented_html</span><span class="Special">&quot;</span> =&gt; <span class="Special">&quot;</span><span class="Constant">Formatter.unindented_lines_to_html(lines)</span><span class="Special">&quot;</span>,
+  },
+}
 </pre>
 </div>
 <div class="chunk containers">
 <span class="chunk containers header">Contained in:</span>
 <ul class="chunk containers">
 <li class="chunk container">
-<a class="chunk container" href="#lib-codnar-split-configurations-rb">lib/codnar/split_configurations.rb</a>
+<a class="chunk container" href="#lib-codnar-configuration-comments-rb">lib/codnar/configuration/comments.rb</a>
 </li>
 </ul>
 </div>
@@ -6499,7 +7227,7 @@ Test built-in split comment formatting configurations.
 <span class="Constant">    &lt;td class='html'&gt;</span>
 <span class="Constant">    &lt;div class='rdoc comment markup'&gt;</span>
 <span class="Constant">    &lt;p&gt;</span>
-<span class="Constant">    Comment &lt;b&gt;text&lt;/b&gt;.</span>
+<span class="Constant">    Comment &lt;strong&gt;text&lt;/strong&gt;.</span>
 <span class="Constant">    &lt;/p&gt;</span>
 <span class="Constant">    &lt;/div&gt;</span>
 <span class="Constant">    &lt;/td&gt;</span>
@@ -6554,10 +7282,80 @@ Test built-in split comment formatting configurations.
 </div>
 </div>
 </p>
-<h4>Syntax highlighting using GVim</h4>
+<h4>Syntax highlighting</h4>
+<p>
+Highlighting the syntax of the source code embedded in the documentation
+improved readability. Codnar provides several ways to achieve this.
+</p>
+<p>
+<div class="named_with_containers chunk">
+<div class="chunk name">
+<a name="lib-codnar-configuration-highlighting-rb">
+<span>lib/codnar/configuration/highlighting.rb</span>
+</a>
+</div>
+<div class="chunk html">
+<pre class='ruby code syntax'>
+<span class="PreProc">module</span> <span class="Type">Codnar</span>
+  <span class="PreProc">module</span> <span class="Type">Configuration</span>
+</pre>
+    <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>    </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+Configurations for highlighting source code lines.
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+    <span class="PreProc">module</span> <span class="Type">Highlighting</span>
+</pre>
+<pre class='nested chunk'>
+      <a class='nested chunk' href='#gvim-syntax-highlighting-formatting-configurations'>GVim syntax highlighting formatting configurations</a>
+</pre>
+<pre class='ruby code syntax'>
+</pre>
+<pre class='nested chunk'>
+      <a class='nested chunk' href='#coderay-syntax-highlighting-formatting-configurations'>CodeRay syntax highlighting formatting configurations</a>
+</pre>
+<pre class='ruby code syntax'>
+</pre>
+<pre class='nested chunk'>
+      <a class='nested chunk' href='#sunlight-syntax-highlighting-formatting-configurations'>Sunlight syntax highlighting formatting configurations</a>
+</pre>
+<pre class='ruby code syntax'>
+</pre>
+<pre class='nested chunk'>
+      <a class='nested chunk' href='#chunk-splitting-configurations'>Chunk splitting configurations</a>
+</pre>
+<pre class='ruby code syntax'>
+    end
+  end
+end
+</pre>
+</div>
+</div>
+</p>
+<h5>Syntax highlighting using GVim</h5>
 <p>
-Supporting a specific programming language (other than dealing with comments)
-is very easy using GVim for syntax highlighting, as demonstrated here:
+Supporting almost any known programming language (other than dealing with
+comments) is very easy using GVim for syntax highlighting, as demonstrated
+here:
 </p>
 <p>
 <div class="named_with_containers chunk">
@@ -6588,7 +7386,7 @@ lines.
 </table>
 <pre class='ruby code syntax'>
 <span class="Type">FORMAT_CODE_GVIM_HTML</span> = <span class="Statement">lambda</span> <span class="Statement">do</span> |<span class="Identifier">syntax</span>|
-  <span class="Statement">return</span> <span class="Type">Configuration</span>.klass_code_format(<span class="Special">'</span><span class="Constant">GVim</span><span class="Special">'</span>, syntax, <span class="Special">&quot;</span><span class="Constant">[]</span><span class="Special">&quot;</span>)
+  <span class="Statement">return</span> <span class="Type">Highlighting</span>.klass_code_format(<span class="Special">'</span><span class="Constant">GVim</span><span class="Special">'</span>, syntax, <span class="Special">&quot;</span><span class="Constant">[]</span><span class="Special">&quot;</span>)
 <span class="Statement">end</span>
 </pre>
@@ -6610,7 +7408,7 @@ already classified the code lines.
 </table>
 <pre class='ruby code syntax'>
 <span class="Type">FORMAT_CODE_GVIM_CSS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span> |<span class="Identifier">syntax</span>|
-  <span class="Statement">return</span> <span class="Type">Configuration</span>.klass_code_format(<span class="Special">'</span><span class="Constant">GVim</span><span class="Special">'</span>, syntax, <span class="Special">&quot;</span><span class="Constant">[ '+:let html_use_css=1' ]</span><span class="Special">&quot;</span>)
+  <span class="Statement">return</span> <span class="Type">Highlighting</span>.klass_code_format(<span class="Special">'</span><span class="Constant">GVim</span><span class="Special">'</span>, syntax, <span class="Special">&quot;</span><span class="Constant">[ '+:let html_use_css=1' ]</span><span class="Special">&quot;</span>)
 <span class="Statement">end</span>
 </pre>
@@ -6643,7 +7441,7 @@ Return a configuration for highlighting a specific syntax using GVim.
 <span class="chunk containers header">Contained in:</span>
 <ul class="chunk containers">
 <li class="chunk container">
-<a class="chunk container" href="#lib-codnar-split-configurations-rb">lib/codnar/split_configurations.rb</a>
+<a class="chunk container" href="#lib-codnar-configuration-highlighting-rb">lib/codnar/configuration/highlighting.rb</a>
 </li>
 </ul>
 </div>
@@ -6688,7 +7486,7 @@ Colors for GVim classes
 </div>
 </div>
 </p>
-<h4>Syntax highlighting using CodeRay</h4>
+<h5>Syntax highlighting using CodeRay</h5>
 <p>
 For supported programming languages, you may choose to use CodeRay instead of GVim.
 </p>
@@ -6721,7 +7519,7 @@ lines.
 </table>
 <pre class='ruby code syntax'>
 <span class="Type">FORMAT_CODE_CODERAY_HTML</span> = <span class="Statement">lambda</span> <span class="Statement">do</span> |<span class="Identifier">syntax</span>|
-  <span class="Statement">return</span> <span class="Type">Configuration</span>.klass_code_format(<span class="Special">'</span><span class="Constant">CodeRay</span><span class="Special">'</span>, syntax, <span class="Special">&quot;</span><span class="Constant">{}</span><span class="Special">&quot;</span>)
+  <span class="Statement">return</span> <span class="Type">Highlighting</span>.klass_code_format(<span class="Special">'</span><span class="Constant">CodeRay</span><span class="Special">'</span>, syntax, <span class="Special">&quot;</span><span class="Constant">{}</span><span class="Special">&quot;</span>)
 <span class="Statement">end</span>
 </pre>
@@ -6743,7 +7541,7 @@ configuration already classified the code lines.
 </table>
 <pre class='ruby code syntax'>
 <span class="Type">FORMAT_CODE_CODERAY_CSS</span> = <span class="Statement">lambda</span> <span class="Statement">do</span> |<span class="Identifier">syntax</span>|
-  <span class="Statement">return</span> <span class="Type">Configuration</span>.klass_code_format(<span class="Special">'</span><span class="Constant">CodeRay</span><span class="Special">'</span>, syntax, <span class="Special">&quot;</span><span class="Constant">{ :css =&gt; :class }</span><span class="Special">&quot;</span>)
+  <span class="Statement">return</span> <span class="Type">Highlighting</span>.klass_code_format(<span class="Special">'</span><span class="Constant">CodeRay</span><span class="Special">'</span>, syntax, <span class="Special">&quot;</span><span class="Constant">{ :css =&gt; :class }</span><span class="Special">&quot;</span>)
 <span class="Statement">end</span>
 </pre>
@@ -6752,7 +7550,7 @@ configuration already classified the code lines.
 <span class="chunk containers header">Contained in:</span>
 <ul class="chunk containers">
 <li class="chunk container">
-<a class="chunk container" href="#lib-codnar-split-configurations-rb">lib/codnar/split_configurations.rb</a>
+<a class="chunk container" href="#lib-codnar-configuration-highlighting-rb">lib/codnar/configuration/highlighting.rb</a>
 </li>
 </ul>
 </div>
@@ -6916,7 +7714,7 @@ Extracted from CodeRay output
 </div>
 </div>
 </p>
-<h4>Syntax highlighting using Sunlight</h4>
+<h5>Syntax highlighting using Sunlight</h5>
 <p>
 For small projects in supported languages, you may choose to use Sunlight
 instead of GVim.
@@ -6951,7 +7749,7 @@ splitting the file.
 </table>
 <pre class='ruby code syntax'>
 <span class="Type">FORMAT_CODE_SUNLIGHT</span> = <span class="Statement">lambda</span> <span class="Statement">do</span> |<span class="Identifier">syntax</span>|
-  <span class="Statement">return</span> <span class="Type">Configuration</span>.sunlight_code_format(syntax)
+  <span class="Statement">return</span> <span class="Type">Highlighting</span>.sunlight_code_format(syntax)
 <span class="Statement">end</span>
 </pre>
@@ -6984,7 +7782,7 @@ Return a configuration for highlighting a specific syntax using Sunlight.
 <span class="chunk containers header">Contained in:</span>
 <ul class="chunk containers">
 <li class="chunk container">
-<a class="chunk container" href="#lib-codnar-split-configurations-rb">lib/codnar/split_configurations.rb</a>
+<a class="chunk container" href="#lib-codnar-configuration-highlighting-rb">lib/codnar/configuration/highlighting.rb</a>
 </li>
 </ul>
 </div>
@@ -7156,7 +7954,7 @@ designations. Assumes other configurations handle the actual content lines.
 <span class="chunk containers header">Contained in:</span>
 <ul class="chunk containers">
 <li class="chunk container">
-<a class="chunk container" href="#lib-codnar-split-configurations-rb">lib/codnar/split_configurations.rb</a>
+<a class="chunk container" href="#lib-codnar-configuration-highlighting-rb">lib/codnar/configuration/highlighting.rb</a>
 </li>
 </ul>
 </div>
@@ -7364,7 +8162,7 @@ Test combination of many built-in configurations.
 <span class="Constant">    &lt;td class='html'&gt;</span>
 <span class="Constant">    &lt;div class='rdoc comment markup'&gt;</span>
 <span class="Constant">    &lt;p&gt;</span>
-<span class="Constant">    Hello, &lt;b&gt;world&lt;/b&gt;!</span>
+<span class="Constant">    Hello, &lt;strong&gt;world&lt;/strong&gt;!</span>
 <span class="Constant">    &lt;/p&gt;</span>
 <span class="Constant">    &lt;/div&gt;</span>
 <span class="Constant">    &lt;/td&gt;</span>
@@ -9100,6 +9898,7 @@ convenient list of all of Codnar's parts and dependencies:
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">irb</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">open3</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">rdiscount</span><span class="Special">&quot;</span>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">rdoc</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">rdoc/markup/to_html</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">tempfile</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">yaml</span><span class="Special">&quot;</span>
@@ -9113,6 +9912,7 @@ convenient list of all of Codnar's parts and dependencies:
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/version</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/coderay</span><span class="Special">&quot;</span>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/haddock</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/hash_extensions</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/markdown</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/rdoc</span><span class="Special">&quot;</span>
@@ -9128,6 +9928,10 @@ convenient list of all of Codnar's parts and dependencies:
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/split</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/reader</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/scanner</span><span class="Special">&quot;</span>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/configuration/code</span><span class="Special">&quot;</span>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/configuration/comments</span><span class="Special">&quot;</span>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/configuration/documentation</span><span class="Special">&quot;</span>
+<span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/configuration/highlighting</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/split_configurations</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/splitter</span><span class="Special">&quot;</span>
 <span class="PreProc">require</span> <span class="Special">&quot;</span><span class="Constant">codnar/sunlight</span><span class="Special">&quot;</span>
@@ -9848,10 +10652,9 @@ Test running the Weave Codnar Application.
   <span class="PreProc">def</span> <span class="Identifier">test_run_weave_missing_file</span>
     write_fake_file(<span class="Special">&quot;</span><span class="Constant">root</span><span class="Special">&quot;</span>, <span class="Type">FILE_CHUNKS</span>.to_yaml)
     <span class="Type">Codnar</span>::<span class="Type">Application</span>.with_argv(<span class="Special">%w(</span><span class="Constant">-e stderr -o stdout root</span><span class="Special">)</span>) { <span class="Type">Codnar</span>::<span class="Type">Weave</span>.new(<span class="Constant">true</span>).run }.should == <span class="Constant">1</span>
-    double_message = <span class="Special">&quot;</span><span class="Constant">No such file or directory - </span><span class="Special">&quot;</span> * <span class="Constant">2</span> <span class="Comment"># Something weird in Ruby Exception.to_s</span>
-    <span class="Type">File</span>.read(<span class="Special">&quot;</span><span class="Constant">stdout</span><span class="Special">&quot;</span>).should == <span class="Special">&quot;</span><span class="Constant">Root</span><span class="Special">\n</span><span class="Constant">FILE: included.file EXCEPTION: </span><span class="Special">#{</span>double_message<span class="Special">}</span><span class="Special">\n</span><span class="Special">&quot;</span>
+    <span class="Type">File</span>.read(<span class="Special">&quot;</span><span class="Constant">stdout</span><span class="Special">&quot;</span>).should == <span class="Special">&quot;</span><span class="Constant">Root</span><span class="Special">\n</span><span class="Constant">FILE: included.file EXCEPTION: No such file or directory - included.file</span><span class="Special">\n</span><span class="Special">&quot;</span>
     <span class="Type">File</span>.read(<span class="Special">&quot;</span><span class="Constant">stderr</span><span class="Special">&quot;</span>).should \
-      == <span class="Special">&quot;</span><span class="Special">#{</span><span class="Identifier">$0</span><span class="Special">}</span><span class="Constant">: Reading file: included.file exception: </span><span class="Special">#{</span>double_message<span class="Special">}</span><span class="Constant"> in file: root at line: 1</span><span class="Special">\n</span><span class="Special">&quot;</span>
+      == <span class="Special">&quot;</span><span class="Special">#{</span><span class="Identifier">$0</span><span class="Special">}</span><span class="Constant">: Reading file: included.file exception: No such file or directory - included.file in file: root at line: 1</span><span class="Special">\n</span><span class="Special">&quot;</span>
   <span class="PreProc">end</span>
   <span class="PreProc">def</span> <span class="Identifier">test_run_weave_existing_file</span>
@@ -10447,6 +11250,27 @@ Actually create common Rake split tasks.
         ::<span class="Type">Rake</span>::<span class="Type">Task</span>.define_task(<span class="Constant">:clean</span> =&gt; <span class="Special">&quot;</span><span class="Constant">clean_codnar</span><span class="Special">&quot;</span>)
       <span class="PreProc">end</span>
+</pre>
+      <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>      </pre>
+</td>
+<td class='html'>
+<div class='rdoc comment markup'>
+<p>
+For some reason, <code>include ::Rake::DSL</code> doesn’t give us this
+and life is too short…
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='ruby code syntax'>
+      <span class="PreProc">def</span> <span class="Constant">self</span>.<span class="Identifier">desc</span>(description)
+        ::<span class="Type">Rake</span>.application.last_description = description
+      <span class="PreProc">end</span>
 </pre>
       <table class='layout'>
 <tr>
@@ -11040,7 +11864,23 @@ Create nested UL/LI lists for the table of content.
   <span class="Identifier">var</span> container;
   <span class="Identifier">var</span> indices = <span class="Identifier">[]</span>;
   <span class="Identifier">var</span> h_elements = all_h_elements();
-  <span class="Statement">for</span> (<span class="Identifier">var</span> e <span class="Statement">in</span> h_elements) <span class="Identifier">{</span>
+</pre>
+  <table class='layout'>
+<tr>
+<td class='indentation'>
+<pre>  </pre>
+</td>
+<td class='html'>
+<div class='markdown comment markup'>
+<p>
+Using "for (var e in h_elements)" is too sensitive to other libraries
+</p>
+</div>
+</td>
+</tr>
+</table>
+<pre class='javascript code syntax'>
+  <span class="Statement">for</span> (<span class="Identifier">var</span> e = 0; e &lt; h_elements.length; e++) <span class="Identifier">{</span>
     h = h_elements<span class="Identifier">[</span>e<span class="Identifier">]</span>;
     <span class="Identifier">var</span> level = h.tagName.substring(1, 2) - 1;
     container = pop_container(container, indices, level);
@@ -11450,7 +12290,8 @@ function contents_lists() {
   var container;
   var indices = [];
   var h_elements = all_h_elements();
-  for (var e in h_elements) {
+  /* Using "for (var e in h_elements)" is too sensitive to other libraries */
+  for (var e = 0; e < h_elements.length; e++) {
     h = h_elements[e];
     var level = h.tagName.substring(1, 2) - 1;
     container = pop_container(container, indices, level);