Extending RedCloth

[latex]\LaTeX{}[/latex] is the permier typesetting tool of the engineering and math world. It allows you to create beautifully typeset mathematical documents with a minimal learning curve. So why would you care about this on the web? Well for one, there really is no way to typset math in a browser. Sure there is <a href="http://www.w3.org/Math/">MathML</a> but that is supported by only a few browsers nativly, most will require a plugin (if even available). So how should one go about doing this, ensuring that the math formulas will be seen by the widest possible auidence? Use images! Every browser can render an image, so if we are able to take the LaTeX and render it as an image, we will be set. This is exactly the approach taked by <a href="http://www.mayer.dial.pipex.com/tex.htm">LatexRender</a>, a set of scripts for rendering LaTeX in <a href="http://www.php.net/">php</a> programs. Unfortunatly, as far as I know, there is not drop in solution for Ruby. However, there were a few projects that pointed me in the right direction. Most noteable was redsymbols <a href="http://redsymbol.net/software/l2p/">l2p</a> Perl script and the afformentioned LatexRender. I have already done the hard stuff for you and put it up on my GitHub <a href="http://github.com/mpetnuch">repository</a>. <pre><code class="multiline_code">$> git clone git://github.com/mpetnuch/latex-renderer.git vendor/plugins/latex_render</code></pre>You also need to make sure that you have the RedCloth Ruby Gem and a LaTeX package for the <a href="http://github.com/mpetnuch/latex-renderer/tree/master">Latex Render plugin</a> installed. Next we need to write our own custom RedCloth. I am going to call it Washcloth since it is cleaning up the site. Create a new file called washcloth.rb in your projects lib directory with the following contents: <pre><code class="multiline_code">class Washcloth < RedCloth LATEX_START_CODE = /\[latex\]/i LATEX_END_CODE = /\[\/latex\]/i LATEX_RE = /\[latex\](.*)\[\/latex\]/i RULES = [:block_textile_table, :block_textile_lists, :block_textile_prefix, :inline_textile_image, :inline_latex, :inline_textile_link, :inline_textile_code, :inline_textile_span, :glyphs_textile] def inline_latex( text ) # Don't do anything unless we have same number of start/end tags if text.scan(LATEX_START_CODE).size == text.scan(LATEX_END_CODE).size text.gsub!( LATEX_RE ) do |m| latex = LatexRenderer.new latex.formula = $1 begin filename = latex.process md5 = latex.md5hash # if the processing was successful we just display the rendered image sprintf '<img src="%s" alt="latex image" />', filename.gsub(/.*?\/images/, '/images') rescue => e sprintf('%s', latex.formula) end end end end def to_html super(*RULES) end end</code></pre>Let’s test it out. Fire up the console: <pre><code class="multiline_code">>> latex = '[latex]x^2 + y^2 = z^2[/latex]' => "[latex]x^2 + y^2 = z^2[/latex]" >> r = WashCloth.new latex => "[latex]x^2 + y^2 = z^2[/latex]" >> r.to_html => "<img src="/images/latex/image.png" />"</code></pre> So we see that our [latex]\LaTeX{}[/latex] is replaced with a link to a rendered image of the code. All that is left is to replace any instance of RedCloth in your program with WashCloth and it will automatically render the LaTeX in your views. What if you use something like Err the Blog’s <a href="http://errtheblog.com/posts/12-actsastextiled">acts_as_textiled</a>? You going to have to edit the plugins source and change RedCloth to WashCloth, but that’s it! So what have we accomplished? We can now render latex commands inline with our Textiled HTML. For instance, the following command: <pre> [latex] $$\Gamma(s) \zeta(s) = \int_0^{\infty} \frac{x^{s-1}e^{-x}}{1-e^{-x}}\,dx$$ [/latex] </pre>Will render as: [latex]$$\Gamma(s) \zeta(s) = \int_0^{\infty} \frac{x^{s-1}e^{-x}}{1-e^{-x}}\,dx$$[/latex]

2008-06-16T03:37:49Z

7 <a href="http://whytheluckystiff.net/ruby/redcloth/">RedCloth</a> is Ruby’s Textile module. Textile is a lightweight markup language originally developed by Dean Allen that allows a user to create well-formed styled XHTML. This site employes the RedCloth Textile module through the <a href="http://errtheblog.com/posts/12-actsastextiled">acts_as_textiled</a> plugin. The nice thing about RedCloth is it is faily easy to extend the markup which it recognies. In this tutorial, I am going to show you how to render [latex]\LaTeX{}[/latex] in your site by extending RedCloth. extending-redcloth Extending RedCloth

2008-12-01T00:15:21Z

48 As with the LaTeX problem, I wanted something that could integrate with what I was alreadying using. Parsing the entire text twice was just not an option. RedCloth was already identifying the <code>pre</code> and <code>code</code> blocks because it doesn’t textilse those. I just had to figure out how to intercept and then stylize them. I came across <a href="http://rpheath.com/">Ryan Heath’s blog</a> and his code snippits instantly caught my eye. I shot him an email and asked him what he was using to preform the syntax highlighting. Turned out he was using the Ruby Syntax <a href="http://syntax.rubyforge.org/">gem</a>. Apparently, he tried out <a href="http://ultraviolet.rubyforge.org/">UltraViolet</a>, but couldn’t get it to run on his hosts’ server. I think the UltraViolet gem was overkill for what I wanted to accomplish and that the Syntax gem was just what I needed — simple and fast. Now that I found the tool sytlizing code, I needed to intercept the <code>code</code> blocks from RedCloth. After a little bit of fishing around in the RedCloth <a href="http://redcloth.rubyforge.org/">documentation</a>, I found the function I needed to override: rip_offtags. Before we can begin though, we have to install the Sytax gem. Preform the following on the command line: <pre><code class="multiline_code">> sudo gem install syntax</code></pre>The syntax gem contains a function called <code>convert</code> which takes code and tranforms into HTML with each token of the code put into spans. It is very simple to use. The following is taken directly from its docs: <pre><code class="multiline_code">require 'syntax/convertors/html' convertor = Syntax::Convertors::HTML.for_syntax "ruby" html = convertor.convert( File.read( "program.rb" ) ) puts html</code></pre>From the above, you can see that once we are able to intercept the code blocks from RedCloth, we just pass it onto the <code>convert</code> function and we are done. We are now ready to edit the washcloth.rb file we created when making the LaTeX extension. Add the following to the very begining of the file (before the class tag): <pre><code class="multiline_code">require 'syntax/convertors/html' # for the syntax gem</code></pre>Next we need to copy the existing rip_offtags defintion from redcloth.rb. <pre><code class="multiline_code"># File lib/redcloth.rb, line 1009 OFFTAGS = /(code|pre|kbd|notextile)/ OFFTAG_MATCH = /(?:(<\/#{ OFFTAGS }>)|(<#{ OFFTAGS }[^>]*>))(.*?)(?=<\/?#{ OFFTAGS }|\Z)/mi def rip_offtags( text ) if text =~ /<.*>/ # strip and encode pre content codepre, used_offtags = 0, {} text.gsub!( OFFTAG_MATCH ) do |line| if $3 offtag, aftertag = $4, $5 codepre += 1 used_offtags[offtag] = true if codepre - used_offtags.length > 0 htmlesc( line, :NoQuotes ) unless used_offtags['notextile'] @pre_list.last << line line = "" else # this is the part that we're interested in htmlesc( aftertag, :NoQuotes ) if aftertag and not used_offtags['notextile'] line = "<redpre##{ @pre_list.length }>" @pre_list << "#{ $3 }#{ aftertag }" end elsif $1 and codepre > 0 if codepre - used_offtags.length > 0 htmlesc( line, :NoQuotes ) unless used_offtags['notextile'] @pre_list.last << line line = "" end codepre -= 1 unless codepre.zero? used_offtags = {} if codepre.zero? end line end end text end</code></pre>The code that were need to change is the following: <pre><code class="multiline_code">htmlesc( aftertag, :NoQuotes ) if aftertag and not used_offtags['notextile'] line = "<redpre##{ @pre_list.length }>" @pre_list << "#{ $3 }#{ aftertag }"</code></pre>The local variable, <code>aftertag</code>, contains the unformatted code that we are interested in. What is happening in that block, is RedCloth is passing it off to another function which escapes special characters. Since the syntax gem will do that for us we can use it’s convert function as a drop in replacement. Chage the above code to the following: <pre><code class="multiline_code">if aftertag and not used_offtags['notextile'] convertor = Syntax::Convertors::HTML.for_syntax "ruby" aftertag = convertor.convert(aftertag, false) end line = "<redpre##{ @pre_list.length }>" @pre_list << "#{ $3 }#{ aftertag }"</code></pre>Notice that my call to convert has a second parameter set to <code>false</code>. This is because we already have <code>pre</code> and <code>code</code> tags that RedCloth is going to insert back in for us. Setting the second paramter to <code>false</code> tells convert to not add in <code>pre</code> tags. The only thing left to do is write some custom CSS to tell the browser how we want to style our tokens. <a href="/stylesheets/code.css">Here</a> is a good starting point. Just edit the colors to fit the scheme you have for your own site! <h4>Update:</h4> There is a bug in the current implementation. For instance if you have a <code>pre</code> tag inside your <code>code</code> block, RedCloth will break it out and deal with it separately which then breaks your highlighting. Once solution would be to create <code>[code]</code> blocks like we did for LaTeX rendering, but I am not sure if I like that way. Have to think about this. If you have any good ideas, let me know and post it in the comments!

2008-06-18T00:59:03Z

8 After I implemented LaTeX rendering into my views, I was quite satisfied with how it came out. LaTeX can now be effortless inserted into a field that is textile enabled with very good results. But then I began to look at the code snippits and I realized how ugly they look when compared to the rest of the site. I did a quick web search for ways to incorporate syntax highlighting in Rails applications, but I wasn’t really satisfied with what I found. Then the solution smacked me in the face. Just extend RedCloth! syntax-highlighting-with-redcloth Syntax Highlighting with RedCloth

2008-12-01T01:14:52Z

54 According to A List Apart’s Derek Powazek’s <a href="http://alistapart.com/articles/wheream">article</a>, the hallmarks of a good navigation system lets the user know the three basic things: where they are, where they have been, and where they can go. While there are many methods to achieve this, I decided to go the <a href="http://en.wikipedia.org/wiki/Breadcrumb_%28navigation%29">breadcrumb</a> route. While breadcrumbs are great, there is no easy was to make them with Rails. The problem is that the breadcrumb trail may span across more than one controller. So how do you model the relationships? Use ActsAsNestedSet. The ActsAsNestedSet plugin allows you to have tree like relationships and retrieve the entire tree with just one SQL query. First we need to get the plugin: <pre><code class="multiline_code">git clone git://github.com/chris/better_nested_set.git</code></pre>and create our menu model: <pre><code class="multiline_code">class Menu < ActiveRecord::Base acts_as_nested_set after_save :move_to_proposed_parent def proposed_parent_id @proposed_parent_id end def proposed_parent_id=(parent) @proposed_parent_id = parent end private # After the menu is saved, we move it to the correct location # If the proposed parent is nil, or doesn't exist then move it to the end of the list. # If the proposed parent has children - move it to the right of the last child # If the proposed parent has no children, move it directly under the parent def move_to_proposed_parent unless proposed_parent_id.to_s == parent_id.to_s new_parent = self.class.find_by_id(proposed_parent_id) if new_parent.nil? self.move_to_right_of(self.class.roots.last) else unless new_parent.children.last.nil? self.move_to_right_of(new_parent.children.last) else self.move_to_child_of(new_parent) end end end end end</code></pre>and finally our migration for the table that will contain our data. Note, in our migration we need to make sure that we create the base menus for whatever model we plan on listing. In this example I create a base menu for the models <code>home</code>, <code>post</code>, and <code>topics</code>. My migration file looks like this. <pre><code class="multiline_code">class CreateMenus < ActiveRecord::Migration def self.up create_table :menus, :force => true do |t| t.string :name, :controller, :action t.references :menuable, :polymorphic => true t.integer :parent_id t.integer :lft, :rgt, :null => false t.integer :lock_version, :default => 0 end add_index :menus, ["name", "parent_id"], :name => "index_menu_on_name_and_parent_id", :unique => false # add base menus home = Menu.create :name => 'Home', :controller => 'home', :action => 'index' posts = Menu.create :name => 'Posts', :controller => 'posts', :action => 'index', :proposed_parent_id => home topics = Menu.create :name => 'Topics', :controller => 'topics', :action => 'index', :proposed_parent_id => posts def self.down drop_table :menus end end</code></pre>The <code>menu</code> model has pseudo column, <code>proposed_parent_id</code>. This allows us to use an <code>after_save</code> callback, which automatically creates the new menu item as a child of the correct parent. If <code>proposed_parent_id</code> is blank, then the new menu item will become a root menu. Now that we have the menu table set up, we need to update our models so that it populates the menu table with the newly created information. In each model that you wish to associate a menu item with add the following (I am assuming the model named Topic): <pre><code class="multiline_code">has_one :menu, :as => :menuable, :dependent => :destroy after_create :create_menu private def create_menu parent_menu = Menu.find( :first, :conditions => ['controller = ? and action = ?', 'topics', 'index'] ) new_menu = Menu.new( :name => self.name.titleize, :controller => 'topics', :action => 'show', :proposed_parent_id => parent_menu ) self.menu = new_menu end</code></pre>Now depending upon how static this model is, you might want to create an <code>after_code</code> callback that would update the menu name if, for instance, the topic name is a mutable attribute. After you have everything to you liking, it’s time to migrate your database: <pre><code class="multiline_code">rake db:migrate</code></pre>Next we create a helper method so that we can access the current menu. We are exploting the fact that Rails sets for us the name of the current controller and action via the global <code>controller</code> variable. We are then able to set the correct submenu page (if appropriate) if we are passed an <code>id</code> as well. <pre><code class="multiline_code">module MenuHelper def current_menu id = params[:id] unless id.nil? Menu.find(:first, :conditions => [ 'controller = ? and action = ? and menuable_id = ?', controller.controller_name, controller.action_name, id ] ) else Menu.find(:first, :conditions => [ 'controller = ? and action = ?', controller.controller_name, controller.action_name ] ) end end end</code></pre>With that setup, all that is left is for us to create the view to see our navigation. This is were we get to see the power of <code>ActsAsNestedSet</code>. In order to retrieve all of the root menus (in our case the children of Home) you create the following loop: <pre><code class="multiline_code">Menu.root.children.each do |menu| # Do something special with the current selected menu unless menu == current_menu.self_and_ancestors[1] .... # Standard formatting for the rest else .... end end</code></pre>Notice that I use NestedSet’s <code>self_and_ancestors</code> method on the <code>current_menu</code>, but instead of checking the first item in the array I am actually checking the second. The reason for this is that is <code>home</code> is the parent of every item (according to how I setup my menus) and is therefore the first item in the array. If, on the other hand, you decide that you want your Posts, About, etc… to be the topic level menus along with home you would use <code>self_and_ancestors.first</code> instead. Now to retrieve the breadcrumbs we do something quite similar. Again we use NestedSet’s <code>anestor</code> method to get all the breadcrumbs. Notice however, that we do not use <code>self_and_ancestors</code> because we want to treat the current menu differently, for example, we want to provide links to all the ancestors. But since we are viewing the current page there is no reason to link to it. Also, notice that we omit breadcrumbs if were are at the home page. This we done as a suggestion from <a href="http://www.alistapart.com">A List Apart</a>, but the choice is up to you. <pre><code class="multiline_code"># Don't display breadcrumbs if we are in the home menu unless current_menu.root? current_menu.ancestors.each do |menu| ... end # Do something with current_menu ... end</code></pre>All that is left is for you to decide on how you want to style your menus. <a href="http://www.webdesignpractices.com">Web Design Practices</a> presents a good overview of some <a href="http://www.webdesignpractices.com/navigation/breadcrumb.html">more popular setups</a>.

2008-06-26T02:54:44Z

9 Deciding upon a navigation system is probably one of the most important choices in website design. The navigation system can make or break a sites usability. Because of the importance a good navigation system plays, I choose to ignore the many available Rails menu plugins and roll out my own so that it would work exactly as I needed it. In this tutorial, I will detail how to use the Rails plugin <a href="http://github.com/rails/acts_as_nested_set/tree/master">acts_as_nested_set</a> to create your own dynamic navigation system. creating-a-navigation-system-with-rails Creating a Navigation System with Rails

2009-03-06T17:11:41Z