README.markdown in wbzyl-rack-codehighlighter-0.2.1 vs README.markdown in wbzyl-rack-codehighlighter-0.2.2
- old
+ new
@@ -5,130 +5,57 @@
* ultraviolet
* coderay
* syntax
* prettify
-* censor
+* censor (a fake highlighter used in example below)
Install the gem with:
sudo gem install wbzyl-rack-codehighlighter -s http://gems.github.com
-The middleware reads HTML produced by an application, where it looks
-for code blocks to highlight. Below we ask *coderay* to
-highlight all `pre` elements:
+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
+The middleware uses the *pattern* to learn what language the code block
contains, for example
<pre>:::ruby
puts "hello world"
</pre>
-Plain description what the pattern says:
+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:
use Rack::Codehighlighter, :coderay
-because the default values for options are used.
+because the default options values are used.
Normalization:
-* highlighted code is always wrapped with `pre` element
- with attributes appropriate for codehighlighter used. (2
-* language names are taken from Ultraviolet
+* Highlighted code is always wrapped with `pre` element
+ with attributes appropriate for codehighlighter used.
+* Language names are taken from Ultraviolet.
-## A simple example with inline template
-
- # example.rb
-
- require 'rubygems'
-
- 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:
-
- ruby example.rb
-
-The results are accessible from `http://localhost:4567`.
-
-
-## Why using middleware for code highlighting is awesome?
-
-In pre-Rack applications era possible approaches were:
-
-* pure javascript; cons code must be html-escaped
-* 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.
-
-
## 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:
- # get one of supported highlighters
- gem 'coderay'
+ gem 'coderay' # get one of supported highlighters
require 'coderay'
gem 'wbzyl-rack-codehighlighter'
require 'rack/codehighlighter'
@@ -143,12 +70,11 @@
## Using with Rails
In order to use include the following in a Rails application
`config/environment.rb` file:
- # get one of supported highlighters
- require 'coderay'
+ require 'coderay' # get one of supported highlighters
require 'rack/codehighlighter'
Rails::Initializer.run do |config|
config.gem 'coderay'
@@ -197,11 +123,85 @@
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:
- use Rack::Codehighlighter, :coderay, :markdown => true
+ use Rack::Codehighlighter, :coderay, :markdown => true,
:element => "pre>code", :pattern => /\A:::(\w+)\s*\n/, :logging => false
+
+## A simple example with inline template
+
+ # example.rb
+
+ require 'rubygems'
+
+ 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:
+
+ 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 `<`. 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),