Support and use Sunlight syntax highlighting.

Author: orenbenkiki

ChangeLog

@@ -1,3 +1,7 @@
+2011-04-16	Oren Ben-Kiki <[email protected]>
+
+	* Support and use Sunlight syntax highlighting.
+
 2011-04-12	Oren Ben-Kiki <[email protected]>
 
 	* Add chunk visibility control.

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Oren Ben-Kiki
+Copyright (c) 2010-2011 Oren Ben-Kiki
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

Rakefile

@@ -150,9 +150,9 @@ end
 def ruby_configurations(*additional_configurations)
   return [
     "classify_source_code:ruby",
-    "format_code_gvim_css:ruby",
+    "format_code_sunlight:ruby",
     "classify_nested_code:ruby:html",
-    "format_code_gvim_css:html",
+    "format_code_sunlight:html",
     "classify_shell_comments",
     "format_rdoc_comments"
   ] + additional_configurations
@@ -161,7 +161,7 @@ end
 def javascript_configurations
   return [
     "classify_source_code:javascript",
-    "format_code_gvim_css:javascript",
+    "format_code_sunlight:javascript",
     "classify_c_comments",
     "format_markdown_comments"
   ]
@@ -170,7 +170,7 @@ end
 def css_configurations
   return [
     "classify_source_code:css",
-    "format_code_gvim_css:css",
+    "format_code_sunlight:css",
     "classify_c_comments",
     "format_markdown_comments"
   ]

doc/contents.js

@@ -29,29 +29,32 @@ function contents_header() {
 function contents_lists() {
   var container;
   var indices = [];
-  foreach_h_element(function (h, level) {
+  var h_elements = all_h_elements();
+  for (var e in h_elements) {
+    h = h_elements[e];
+    var level = h.tagName.substring(1, 2) - 1;
     container = pop_container(container, indices, level);
     container = push_container(container, indices, level);
     var id = indices.join(".");
     container.appendChild(list_element(id, h));
     h.insertBefore(header_anchor(id), h.firstChild);
-  });
+  }
   return pop_container(container, indices, 1);
 }
 
 /*
- * Apply a lambda to all H elements in the DOM. We skip the single H1 element;
+ * Get a list of all H elements in the DOM. We skip the single H1 element;
  * otherwise it would just have the index "1" which would be prefixed to all
  * other headers.
  */
-function foreach_h_element(lambda) {
+function all_h_elements() {
   var elements = document.getElementsByTagName("*");
+  var h_elements = [];
   for (var e in elements) {
     var h = elements[e];
-    if (!/^h[2-9]$/i.test(h.tagName)) continue;
-    var level = h.tagName.substring(1, 2) - 1;
-    lambda(h, level);
+    if (/^h[2-9]$/i.test(h.tagName)) h_elements.push(h);
   }
+  return h_elements;
 }
 
 /*

doc/control_chunks.js

@@ -1,44 +1,44 @@
-/*
- * Quick-and-dirty JS for inserting a "+"/"-" control for chunk visibility next
- * to each chunk's name. By default, all chunks are hidden.
- */
-function inject_chunk_controls() {
-  var name_div;
-  foreach_chunk_elements(function(div) {
-    name_div = div;
-  }, function(html_div) {
-    var control_span = document.createElement("span");
-    var hide = function() {
-      control_span.innerHTML = "+";
-      html_div.style.display = "none";
-    }
-    var show = function() {
-      control_span.innerHTML = "–"; // Vertical bar.
-      html_div.style.display = "block";
-    }
-    name_div.onclick = function() {
-      html_div.style.display == "block" ? hide() : show();
-    }
-    hide(); // Initializes html_div.style.display
-    control_span.className = "control chunk";
-    name_div.insertBefore(control_span, name_div.firstChild);
-  })
-}
-
-/*
- * Loop on all DIV elements that contain a chunk name, or that contain chunk
- * HTML. Assumes that they come in pairs - name first, HTML second.
- */
-function foreach_chunk_elements(name_lambda, html_lambda) {
-  var div_elements = document.getElementsByTagName("div");
-  for (var e in div_elements) {
-    var div = div_elements[e];
-    classes = " " + div.className + " ";
-    if (!/ chunk /.test(classes)) continue;
-    if (/ name /.test(classes)) name_lambda(div);
-    if (/ html /.test(classes)) html_lambda(div);
-  }
-}
-
-/* Only invoke it after all helper functions are defined. */
-inject_chunk_controls();
+/*
+ * Quick-and-dirty JS for inserting a "+"/"-" control for chunk visibility next
+ * to each chunk's name. By default, all chunks are hidden.
+ */
+function inject_chunk_controls() {
+  var name_div;
+  foreach_chunk_elements(function(div) {
+    name_div = div;
+  }, function(html_div) {
+    var control_span = document.createElement("span");
+    var hide = function() {
+      control_span.innerHTML = "+";
+      html_div.style.display = "none";
+    }
+    var show = function() {
+      control_span.innerHTML = "–"; // Vertical bar.
+      html_div.style.display = "block";
+    }
+    name_div.onclick = function() {
+      html_div.style.display == "block" ? hide() : show();
+    }
+    hide(); // Initializes html_div.style.display
+    control_span.className = "control chunk";
+    name_div.insertBefore(control_span, name_div.firstChild);
+  })
+}
+
+/*
+ * Loop on all DIV elements that contain a chunk name, or that contain chunk
+ * HTML. Assumes that they come in pairs - name first, HTML second.
+ */
+function foreach_chunk_elements(name_lambda, html_lambda) {
+  var div_elements = document.getElementsByTagName("div");
+  for (var e in div_elements) {
+    var div = div_elements[e];
+    classes = " " + div.className + " ";
+    if (!/ chunk /.test(classes)) continue;
+    if (/ name /.test(classes)) name_lambda(div);
+    if (/ html /.test(classes)) html_lambda(div);
+  }
+}
+
+/* Only invoke it after all helper functions are defined. */
+inject_chunk_controls();

doc/root.html

@@ -4,9 +4,10 @@
 <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
 <title>Code narrator - an inverse literate programming tool.</title>
 <style type="text/css">
-<embed src="doc/reset.css" type="x-codnar/file"/>
-<embed src="doc/base.css" type="x-codnar/file"/>
+<embed src="yui/reset.css" type="x-codnar/file"/>
+<embed src="yui/base.css" type="x-codnar/file"/>
 <embed src="doc/style.css" type="x-codnar/file"/>
+<embed src="sunlight/default.css" type="x-codnar/file"/>
 </style>
 </head>
 <body>
@@ -17,6 +18,12 @@
 <script type="text/javascript">
 <embed src="doc/contents.js" type="x-codnar/file"/>
 <embed src="doc/control_chunks.js" type="x-codnar/file"/>
+<embed src="sunlight/min.js" type="x-codnar/file"/>
+<embed src="sunlight/css-min.js" type="x-codnar/file"/>
+<embed src="sunlight/javascript-min.js" type="x-codnar/file"/>
+<embed src="sunlight/ruby-min.js" type="x-codnar/file"/>
+Sunlight.globalOptions.lineNumbers = false;
+Sunlight.highlightAll();
 </script>
 </body>
 </html>

doc/story.markdown

@@ -147,10 +147,11 @@ narrative. Then, when you write the new code itself, it should be easy to
 connect it to the narrative at the appropriate point.
 
 In the case of Code Narrator itself, the number of (raw) lines in the code
-itself is ~1800 lines, the number of test lines is ~1600 lines, while the
-number of narrative documentation lines is ~800 lines. Given narrative
-documentation are easier to write than system (or test) code, this indicates
-maintaining a narrative is not an unreasonable burden for a well-tested project.
+library itself is ~2100 lines, the number of test code lines is ~2200 lines,
+and the number of narrative documentation lines is only ~900 lines. Given
+narrative documentation are easier to write than system (or test) code, this
+indicates maintaining a narrative is not an unreasonable burden for a
+well-tested project.
 
 ### Code Narrator ###
 

doc/style.css

@@ -72,35 +72,23 @@ table.layout td.html {
   background-color: Beige;
 }
 
-span.Constant {
-  color: Crimson;
-}
-span.Identifier {
-  color: Teal;
-}
-span.PreProc {
-  color: Indigo;
-}
-span.Special {
-  color: Navy;
-}
-span.Statement {
-  color: Maroon;
-}
-span.Type {
-  color: Green;
-}
-span.Comment {
-  color: Purple;
-}
+/* Colors for GVim classes */
+
+span.Constant   { color: Crimson; }
+span.Identifier { color: Teal; }
+span.PreProc    { color: Indigo; }
+span.Special    { color: Navy; }
+span.Statement  { color: Maroon; }
+span.Type       { color: Green; }
+span.Comment    { color: Purple; }
 
 /* Fonts */
 
 body {
   font-family: Sans-Serif;
 }
 pre {
-  font-family: Consolas, Monospace;
+  font-family: Consolas, Inconsolata, Monaco, "Courier New", Monospace;
 }
 div.chunk.name {
   font-weight: bold;

doc/system.markdown

@@ -243,12 +243,33 @@ 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:
 
-[[test/highlight_syntax.rb|named_chunk_with_containers]]
+[[test/gvim_highlight_syntax.rb|named_chunk_with_containers]]
 
 And here is the implementation:
 
 [[lib/codnar/gvim.rb|named_chunk_with_containers]]
 
+#### Syntax highlighting using Sunlight ####
+
+[Sunlight](http://sunlightjs.com/) offers a different approach for syntax
+highlighting. Instead of pre-processing the code to generate highlighted HTML
+while splitting, it provides Javascript files that examine the textual code in
+the DOM and convert it to highlighted HTML in the browser. This takes virtually
+no time when splitting the code, but requires recomputing highlighting for all
+the code chunks every time the HTML file is loaded. This can be pretty slow,
+especially if using a browser with a slow Javascript engine, like IE. However,
+given how slow GVIM is, this is a reasonable trade-off, at least for small
+projects. Since Sunlight is a new project, it doesn't offer the extensive
+coverage of different programming languages supported by GVIM.
+
+Here is a simple test that demonstrates using Sunlight for syntax highlighting:
+
+[[test/sunlight_highlight_syntax.rb|named_chunk_with_containers]]
+
+And here is the implementation:
+
+[[lib/codnar/sunlight.rb|named_chunk_with_containers]]
+
 ### Putting it all together ###
 
 Now that we have all the separate pieces of functionality for splitting source
@@ -282,8 +303,7 @@ are also supported for code comments. Here is a simple test that demonstrates
 The splitting mechanism defined above is pretty generic. To apply it to a
 specific system requires providing the appropriate configuration. The system
 provides a few specific built-in configurations which may be useful "out of the
-box". Currently, these built-in configurations are focused on documenting Ruby
-code and GVim.
+box".
 
 If one is willing to give up altogether on syntax highlighting and comment
 formatting, the system would be applicable as-is to any programming language.
@@ -393,16 +413,27 @@ Here is a simple test demonstrating formatting comment contents:
 
 [[test/format_comment_configurations.rb|named_chunk_with_containers]]
 
-#### Syntax highlighting ####
+#### Syntax highlighting using GVim ####
 
 Supporting a specific programming language (other than dealing with comments)
 is very easy using GVim for syntax highlighting, as demonstrated here:
 
-[[Syntax highlighting formatting configurations|named_chunk_with_containers]]
+[[GVim syntax highlighting formatting configurations|named_chunk_with_containers]]
+
+Here is a simple test demonstrating highlighting code syntax using `gvim`:
 
-Here is a simple test demonstrating highlighting code syntax:
+[[test/format_code_gvim_configurations.rb|named_chunk_with_containers]]
 
-[[test/format_code_configurations.rb|named_chunk_with_containers]]
+#### Syntax highlighting using Sunlight ####
+
+For small projects in languages supported by Sunlight, you may choose to use
+it instead of GVIM
+
+[[Sunlight syntax highlighting formatting configurations|named_chunk_with_containers]]
+
+Here is a simple test demonstrating highlighting code syntax using Sunlight:
+
+[[test/format_code_sunlight_configurations.rb|named_chunk_with_containers]]
 
 #### Chunk splitting ####
 
@@ -673,23 +704,22 @@ iunjecting a table of content into the generated HTML.
 
 [[doc/contents.js|named_chunk_with_containers]]
 
-### CSS files ###
+### CSS style ###
 
 To avoid dealing with the different default styles used by different browsers,
-we employ the YUI CSS [reset](http://developer.yahoo.com/yui/reset/) file:
+we employ the YUI CSS [reset](http://developer.yahoo.com/yui/reset/) and
+[base](http://developer.yahoo.com/yui/base/) files. Resetting and restoring the
+default CSS styles is inelegant, but it is the only current way to get a
+consistent presentation of HTML. Once this is out of the way, we apply styles
+specific to our HTML. Some of these override the default styles established by
+the base CSS file above. We do this instead of directly tweaking the base CSS
+file, to allow easy upgrade to new versions if/when YUI release any.
 
-[[doc/reset.css|named_chunk_with_containers]]
-
-This requires us to restore the default look and feel of the standard HTML
-elements, using the YUI [base](http://developer.yahoo.com/yui/base/) CSS style
-file. Resetting and restoring the default CSS styles is inelegant, but it is
-the only current way to get a consistent presentation of HTML.
-
-[[doc/base.css|named_chunk_with_containers]]
+[[doc/style.css|named_chunk_with_containers]]
 
-Finally, we can apply styles specific to our HTML. Some of these override the
-default styles established by the base CSS file above. We do this instead of
-directly tweaking the base CSS file, to allow easy upgrade to new versions
-if/when YUI release any.
+### Using Sunlight ###
 
-[[doc/style.css|named_chunk_with_containers]]
+When using Sunlight for syntax highlighting, we also need to include some CSS
+and Javascript files to convert the classified `pre` elements into properly
+marked-up HTML. We also need to invoke this Javascript code (a one-line
+operations). See the last few lines of the `doc/root.html` file for details.

lib/codnar.rb

@@ -26,6 +26,7 @@
 require "codnar/reader"
 require "codnar/scanner"
 require "codnar/splitter"
+require "codnar/sunlight"
 require "codnar/weave"
 require "codnar/weaver"
 require "codnar/writer"