README.markdown in wbzyl-rack-codehighlighter-0.2.2 vs README.markdown in wbzyl-rack-codehighlighter-0.2.4

- old
+ new

@@ -1,101 +1,99 @@ # 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) +* censor (a fake highlighter used in the example below) -Install the gem with: - sudo gem install wbzyl-rack-codehighlighter -s http://gems.github.com +## How it works? +*Rack::Codehighlighter* looks for code blocks to be highlighted in the HTML +produced by your application. For each block found it calls requested +highlighter. -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/ +## Installing and Usage -The middleware uses the *pattern* to learn what language the code block -contains, for example +Install the gem with: - <pre>:::ruby - puts "hello world" - </pre> + sudo gem install wbzyl-rack-codehighlighter -s http://gems.github.com -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. +### Using *rack-codehighlighter* with a Rails application -The above example could be shortened to: +In order to use, include the following code in a Rails application +`config/environment.rb` file: - use Rack::Codehighlighter, :coderay + 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 -because the default options values are used. +### Using *rack-codehighlighter* with a Rack application -Normalization: +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: -* Highlighted code is always wrapped with `pre` element - with attributes appropriate for codehighlighter used. -* Language names are taken from Ultraviolet. - - -## Using with 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: - - 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> -Remember to include in the layout an appropriate stylesheet -(look into `examples/public/stylesheets` directory -for sample stylesheets). +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. +Language names are taken from the *ultraviolet* gem, see below for +the list. -## Configuration examples +The matched element is removed, and the code block is passed to *coderay* +highlighter for processing. +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: use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/, :logging => false @@ -117,108 +115,70 @@ 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' use Rack::Codehighlighter, :censor, :reason => '[[--difficult code removed--]]' get "/" do erb :hello end __END__ - @@ hello <h3>Fibonacci numbers in Ruby</h3> - <pre>:::ruby def fib(n) if n < 2 1 else fib(n-2) + fib(n-1) end 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*: * xml * ruby - ### [Coderay](http://coderay.rubychan.de/) Languages supported by *Coderay*: * C, CSS @@ -241,14 +201,14 @@ 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: sudo gem install ultraviolet @@ -286,5 +246,68 @@ sweave, swig * tcl, template\_toolkit, tex, tex\_math, textile, tsv, twiki, txt2tags * 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)