wbzyl-rack-codehighlighter 0.2.2 → 0.2.4

data/README.markdown

@@ -1,98 +1,96 @@
 # Rack::Codehighlighter middleware
 
-*Rack::Codehighlighter* provides a thin wrapper over 
-a bunch of code highlighters to make their usage as generic possible.
+
+## What?
+
+The *rack-codehighlighter* gem provides a thin wrapper over 
+a bunch of code highlighters to make their usage as generic possible:
 
 * ultraviolet
 * coderay
 * syntax
 * prettify
-* censor (a fake highlighter used in example below)
-
-Install the gem with:
-
-    sudo gem install wbzyl-rack-codehighlighter -s http://gems.github.com
-
+* censor (a fake highlighter used in the example below)
 
-The middleware looks for code blocks to be highlighted in HTML produced by
-application. For each block found it calls requested highlighter.
-Below we ask *coderay* to highlight all `pre` elements:
-
-    use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/
 
-The middleware uses the *pattern* to learn what language the code block
-contains, for example
+## How it works?
 
-    <pre>:::ruby
-    puts "hello world"
-    </pre>
+*Rack::Codehighlighter* looks for code blocks to be highlighted in the HTML
+produced by your application. For each block found it calls requested
+highlighter.
 
-Plain description what the *pattern* says: 
-If the element contents begins with three colons, the text following
-the colons, up to the end of line, identifies the language. The text
-matched by the pattern is removed from the code block before
-processing.
 
-The above example could be shortened to:
+## Installing and Usage
 
-    use Rack::Codehighlighter, :coderay
+Install the gem with:
 
-because the default options values are used.
+    sudo gem install wbzyl-rack-codehighlighter -s http://gems.github.com
 
-Normalization: 
+### Using *rack-codehighlighter* with a Rails application
 
-* Highlighted code is always wrapped with `pre` element
-  with attributes appropriate for codehighlighter used.
-* Language names are taken from Ultraviolet.
+In order to use, include the following code in a Rails application
+`config/environment.rb` file:
 
+    require 'coderay'               # get one of supported highlighters 
+    require 'rack/codehighlighter'
+    
+    Rails::Initializer.run do |config|  
+      config.gem 'coderay'
+      config.gem 'wbzyl-rack-codehighlighter'
+        
+      config.middleware.use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/
+    end  
 
-## Using with Rack application
+### Using *rack-codehighlighter* with a Rack application
 
-*Rack::Codehighlighter* can be used with any Rack application, for example with
-a **Sinatra** application. If your application includes a rackup file or
-uses *Rack::Builder* to construct the application pipeline, simply
-require and use as follows:
+The *rack-codehighlighter* gem can be used with any Rack application,
+for example with a **Sinatra** application. If your application
+includes a rackup file or uses *Rack::Builder* to construct the
+application pipeline, simply require and use as follows:
 
-    gem 'coderay' # get one of supported highlighters 
-    require 'coderay'
-     
+    gem 'coderay'       # get one of supported highlighters 
+    require 'coderay'   
+           
     gem 'wbzyl-rack-codehighlighter'
     require 'rack/codehighlighter'
      
-    use Rack::Codehighlighter, :coderay
+    use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/
     run app
 
-Remember to include in the layout an appropriate stylesheet 
-(look into `examples/public/stylesheets` directory 
-for sample stylesheets).
 
+## *Rack::Codehighlighter* by an example
 
-## Using with Rails
+Below we ask *Rack::Codehighlighter* to look for code blocks into all
+`pre` *element*s:
 
-In order to use include the following in a Rails application
-`config/environment.rb` file:
+    use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/
 
-    require 'coderay' # get one of supported highlighters 
-      
-    require 'rack/codehighlighter'
-    
-    Rails::Initializer.run do |config|  
-      config.gem 'coderay'
-      config.gem 'wbzyl-rack-codehighlighter'
-        
-      config.middleware.use Rack::Codehighlighter, :coderay
-    end  
+and use the `/\A:::(\w+)\s*\n/` *pattern* to learn what language 
+the code block contains. 
 
-Check the Rack configuration:
+For example:
 
-    rake middleware
+    <pre>:::ruby
+    puts "hello world"
+    </pre>
+
+Informal description of the *pattern*: if the element contents begins
+with three colons, word characters following these colons up to
+optional spaces followed by end of line, name the language.  
 
-Remember to include in the layout an appropriate stylesheet 
-(look into `examples/public/stylesheets` directory 
-for sample stylesheets).
+Language names are taken from the *ultraviolet* gem, see below for
+the list.
 
+The matched element is removed, and the code block is passed to *coderay*
+highlighter for processing. 
 
-## Configuration examples
+The highlighted code returned by the *coderay* highlighter is
+wrapped with `pre` element with attributes appropriate for the
+codehighlighter used.
+
+### More examples
+
+In examples displayed below, the default value of each option is used.
 
 Coderay:
 
@@ -119,24 +117,25 @@ Censor:
     use Rack::Codehighlighter, :censor, :reason => "[[--  ugly code removed  --]]",
       :element => "pre", :pattern => /\A:::(\w+)\s*\n/, :logging => false
 
-In the above examples, the default value of each option is used.
 
-All highlighters use `pre` element to wrap highlighted code.
-In Markdown, Maruku and RDiscount templates code is wrapped with `pre>code`.
-To remove an extra nesting the `:markdown` option should be used:
+In Markdown, Maruku and RDiscount templates, after converting to HTML,
+code is wrapped with `pre>code`.  To remove this extra one level of
+nesting the `:markdown` option should be used:
 
     use Rack::Codehighlighter, :coderay, :markdown => true,
       :element => "pre>code", :pattern => /\A:::(\w+)\s*\n/, :logging => false
 
-## A simple example with inline template
+Check the `examples` directory for working examples.
+
+## Try it!
+
+Simple Copy & Paste example. Implemented in Sinatra and uses inline template.
 
     # example.rb
 
     require 'rubygems'
-      
-    gem 'sinatra', '>=0.9.0'
+    gem 'sinatra', '>=0.9.0' 
     require 'sinatra'
-
     gem 'wbzyl-rack-codehighlighter', '>=0.2.0'
     require 'rack/codehighlighter'
     
@@ -147,10 +146,8 @@ To remove an extra nesting the `:markdown` option should be used:
     end
     
     __END__
-    
     @@ hello
     <h3>Fibonacci numbers in Ruby</h3>
-    
     <pre>:::ruby
     def fib(n)
       if n < 2
@@ -161,54 +158,18 @@ To remove an extra nesting the `:markdown` option should be used:
     end
     </pre>
 
-Run the above example with:
+Run the example with:
 
     ruby example.rb
 
 The results are accessible from `http://localhost:4567`.
 
 
-## Why using middleware for code highlighting is awesome?
-
-In each piece of code inserted into html we must change:
-`<` to `&lt;`. This is annoying thing.
-Each(? prettify, dp-) pure javascript highlighter has this defect.
-
-In pre-Rack applications era possible approaches were:
-
-* gems;  conection to methods responsible for code highlighting
-  is obtrusive, i.e. via plugin + additional markup
-
-Analyze packages mentioned at the *The Ruby Toolbox* page:
-[Syntax Highlighting](http://ruby-toolbox.com/categories/syntax_highlighting.html)
-
-Links:
-
-    http://carboni.ca/projects/harsh/  
-      unless HAML is used
-    http://redclothcoderay.rubyforge.org/  
-    http://github.com/augustl/redcloth-with-coderay
-      how to use with Rails
-      does't degrade to html: new source tag
-    http://github.com/arya/tm_syntax_highlighting/
-      how to connect to rails/sinatra?
-
-[*Ruby tips from me, your idol*](http://www.binarylogic.com/2009/04/19/ruby-tips-from-me-your-idol):
-I can not tell you how much time I’ve wasted trying to add in some
-cool feature into rails. I would dig into the rails internals,
-override methods, do all kinds of tricky stuff. I thought I was
-awesome. A month later rails comes out with some cool new feature, I
-update rails and everything explodes.
-
-Conclusion: highlighting via plugins is doomed to explode sooner or later.
-
-
 ## Supported highlighters
 
 These currently include: *Syntax* (fast), *Coderay* (very fast), 
 *Ultraviolet* (slow, but highlights almost any language).
 
-
 ### [Syntax](http://syntax.rubyforge.org/)
 
 Languages supported by *Syntax*: 
@@ -216,7 +177,6 @@ Languages supported by *Syntax*:
 * xml
 * ruby
 
-
 ### [Coderay](http://coderay.rubychan.de/)
 
 Languages supported by *Coderay*:
@@ -243,10 +203,10 @@ The *ultraviolet* gem needs oniguruma regexp library.
 
 On Fedora install the library with:
 
-    sudo yum install oniguruma
+    sudo yum install oniguruma oniguruma-devel
 
-For installation instruction from sources, see
-[Carbonica](http://carboni.ca/projects/harsh/)
+For installation instruction of the *oniguruma* library from sources,
+see [Carbonica](http://carboni.ca/projects/harsh/)
 
 Now, install the gem:
 
@@ -288,3 +248,66 @@ Ultraviolet supports almost any language:
 * vectorscript
 * xhtml\_1.0, xml, xml\_strict, xsl
 * yaml, yui\_javascript
+
+
+## Why? TODO
+
+Currently, almost everything what I write is rendered by Ruby on Rails
+and Sinatra applications. To improve the readability of the text, I
+want the code fragments to be colored. So extending Rails and Sinatra
+frameworks with syntax highlighting is a must.
+
+The problem is to how syntax highlighting features are hooked into
+these frameworks.
+
+Look at the current practice. To this end, analyze the top three tools
+listed on *The Ruby Toolbox* in category 
+[Syntax Highlighting](http://ruby-toolbox.com/categories/syntax_highlighting.html).
+
+[tm_syntax_highlighting](http://github.com/arya/tm_syntax_highlighting/) (plugin):
+
+    code(some_ruby_code, :theme => "twilight", :lang => "ruby", :line_numbers => true)
+
+[harsh](http://carboni.ca/projects/harsh/) (plugin):
+
+    <% harsh :theme => :dawn do %>    |    <% harsh %Q{ some_ruby_code }, :theme => :dawn %>
+      some_ruby_code                  |
+    <% end %>                         |
+
+[Redcloth with CodeRay](http://github.com/augustl/redcloth-with-coderay) (gem):
+
+    <source:ruby> some_ruby_code </source> 
+
+Overdone: highlighting engine/library/framework.
+Different solutions for each one framework are needed.
+Different output: include.
+
+With Rack based application we can simplifiy thingst by adding to the
+application pipeline..
+
+[*Ruby tips from me, your idol*](http://www.binarylogic.com/2009/04/19/ruby-tips-from-me-your-idol):
+I can not tell you how much time I’ve wasted trying to add in some
+cool feature into rails. I would dig into the rails internals,
+override methods, do all kinds of tricky stuff. I thought I was
+awesome. A month later rails comes out with some cool new feature, I
+update rails and everything explodes.
+
+Conclusion: highlighting via plugins is doomed to explode sooner or later.
+
+
+*Rack::Codehighlighter* provides a thin wrapper over 
+a bunch of code highlighters to make their usage as generic possible.
+
+Uniform/define own..
+
+In each piece of code inserted into html we must change:
+`<` to `&lt;`. This is annoying thing.
+Each(? prettify, dp-) pure javascript highlighter has this defect.
+
+In pre-Rack applications era possible approaches were:
+
+* gems;  connection to methods responsible for code highlighting
+  is obtrusive, i.e. via plugin + additional markup
+
+Analyze packages mentioned at the *The Ruby Toolbox* page:
+[Syntax Highlighting](http://ruby-toolbox.com/categories/syntax_highlighting.html)

data/TODO

@@ -1,13 +1,9 @@
+[15.06.2009]
 
-[1.05.2009, done] 
-  Add support for code-prettify:
-
-    * [source code](http://code.google.com/p/google-code-prettify/)
-      [example](http://google-code-prettify.googlecode.com/svn/trunk/README.html)
+  Compare: http://freelancing-god.github.com/ts/en/
+  Description of thinking-sphinx gem.
 
-   
-    * see http://tomayko.com/writings/javascript-prettification
-      (support for jQuery, new pallette)
+[1.05.2009, done] 
 
     * example:
       <pre class="prettyprint lang-html">
@@ -17,6 +13,3 @@
       "java", "js", "m", "mxml", "perl", "pl", "pm", "py", "rb", "sh",
       "xhtml", "xml", "xsl".
       </pre>
-
-[1.05.2009] 
-  Add support for unobtrustive Code Highlighter By Dan Webb 11/2005

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:patch: 2
-:major: 0
 :minor: 2
+:patch: 4
+:major: 0

data/examples/check.rb

@@ -0,0 +1,16 @@
+require 'rubygems'
+
+require 'coderay'
+require 'uv'
+require 'syntax/convertors/html'
+
+str = "def hitch; end"
+
+puts "---- Syntax ----"
+puts Syntax::Convertors::HTML.for_syntax('ruby').convert(str)
+
+puts "---- Coderay ----"
+puts CodeRay.encoder(:html).encode(str, 'ruby')
+
+puts "---- Ultraviolet ----"
+puts Uv.parse(str, 'xhtml', 'ruby_experimental', false, 'dawn')

data/lib/rack/codehighlighter.rb

@@ -1,7 +1,4 @@
-gem 'rack'
 require 'rack/utils'
-
-gem 'hpricot', '>=0.8.1'
 require 'hpricot'
 
 module Rack

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: wbzyl-rack-codehighlighter
 version: !ruby/object:Gem::Version 
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors: 
 - Wlodek Bzyl
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-07 00:00:00 -07:00
+date: 2009-07-26 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -57,6 +57,7 @@ files:
 - TODO
 - VERSION.yml
 - examples/app.rb
+- examples/check.rb
 - examples/config.ru
 - examples/public/javascripts/lang-css.js
 - examples/public/javascripts/lang-hs.js
@@ -113,4 +114,5 @@ signing_key:
 specification_version: 3
 summary: Rack Middleware for Code Highlighting.
 test_files: 
+- examples/check.rb
 - examples/app.rb