rote 0.3.2 → 0.3.2.2

data/lib/rote/filters.rb

@@ -3,7 +3,7 @@
 # (c)2005, 2006 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: filters.rb 128 2005-12-12 02:45:24 +0000 (Mon, 12 Dec 2005) roscopeco $
+# $Id: filters.rb 156 2006-01-05 01:13:43 +0000 (Thu, 05 Jan 2006) roscopeco $
 #++
 
 # Everyone requires this, we need to get it loaded first.

data/lib/rote/filters/base.rb

@@ -3,7 +3,7 @@
 # (c)2005 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: base.rb 144 2005-12-14 19:17:21 +0000 (Wed, 14 Dec 2005) roscopeco $
+# $Id: base.rb 135 2005-12-12 15:01:07 +0000 (Mon, 12 Dec 2005) roscopeco $
 #++
 module Rote
   module Filters

data/lib/rote/filters/rdoc.rb

@@ -3,7 +3,7 @@
 # (c)2005 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: rdoc.rb 128 2005-12-12 02:45:24 +0000 (Mon, 12 Dec 2005) roscopeco $
+# $Id: rdoc.rb 119 2005-12-11 02:18:37 +0000 (Sun, 11 Dec 2005) roscopeco $
 #++
 
 require 'rdoc/markup/simple_markup'

data/lib/rote/filters/redcloth.rb

@@ -3,7 +3,7 @@
 # (c)2005, 2006 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: redcloth.rb 128 2005-12-12 02:45:24 +0000 (Mon, 12 Dec 2005) roscopeco $
+# $Id: redcloth.rb 155 2006-01-05 00:50:32 +0000 (Thu, 05 Jan 2006) roscopeco $
 #++
 
 require 'redcloth'

data/lib/rote/filters/syntax.rb

@@ -3,7 +3,7 @@
 # (c)2005 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: syntax.rb 144 2005-12-14 19:17:21 +0000 (Wed, 14 Dec 2005) roscopeco $
+# $Id: syntax.rb 170 2006-01-11 23:38:51 +0000 (Wed, 11 Jan 2006) roscopeco $
 #++
   
 require 'syntax'
@@ -14,24 +14,38 @@ module Rote
   module Filters
     
     #####
-    ## Page filter that supports syntax highlighting for Ruby code
-    ## via the +Syntax+ library. Code is expected to be in the 
-    ## following format:
+    ## Page filter that supports syntax highlighting for Ruby code,
+    ## XML and YAML via the (extensible) Syntax (http://syntax.rubyforge.org/)
+    ## library. Code is expected to be enclosed by the +code+ macro:
     ##
     ##   #:code#ruby#
     ##     def amethod(arg)
     ##       puts arg
     ##     end
     ##   #:code#
-    ##  
+    ##
+    ## Where the macro argument may be 'ruby', 'xml', 'yaml', or a
+    ## custom identifier registered (with Syntax) for a custom highlighter.
+    ## 
+    ## The macro output will resemble:
+    ##
+    ##   <pre class='#{lang}'><code class=#{lang}'>
+    ##     ...
+    ##   </code></pre>
+    ##
+    ## Syntax uses <span> tags for highlighting, with CSS classes used to apply
+    ## formatting. See http://syntax.rubyforge.org/chapter-2.html for a list
+    ## of recognised classes.
+    ##
     class Syntax < MacroFilter
       def initialize(macro_re = MACRO_RE)
         super([],macro_re)
       end      
       
+      # Implementation of the +code+ macro.
       def macro_code(lang,body,raw)
         converter = ::Syntax::Convertors::HTML.for_syntax(lang)
-        "<pre class='#{lang}'><code>#{converter.convert(body,false)}</code></pre>"
+        "<pre class='#{lang}'><code class='#{lang}'>#{converter.convert(body,false)}</code></pre>"
       end      
     end      
   end 

data/lib/rote/filters/tidy.rb

@@ -3,7 +3,7 @@
 # (c)2005 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: tidy.rb 128 2005-12-12 02:45:24 +0000 (Mon, 12 Dec 2005) roscopeco $
+# $Id: tidy.rb 125 2005-12-12 02:27:41 +0000 (Mon, 12 Dec 2005) roscopeco $
 #++
 
 module Rote

data/lib/rote/filters/toc.rb

@@ -3,7 +3,7 @@
 # (c)2005 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: toc.rb 128 2005-12-12 02:45:24 +0000 (Mon, 12 Dec 2005) roscopeco $
+# $Id: toc.rb 170 2006-01-11 23:38:51 +0000 (Wed, 11 Jan 2006) roscopeco $
 #++
 
 module Rote
@@ -57,7 +57,8 @@ module Rote
       #   <%= links.join(" - ") %>
       #
       # *Note* that this isn't populated until after
-      # the filter is run.
+      # the filter is run. The @links array will usually
+      # be used in layout.
       attr_reader :headings
       alias :links :headings
       

data/lib/rote/format.rb

@@ -3,7 +3,7 @@
 # (c)2005 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: format.rb 128 2005-12-12 02:45:24 +0000 (Mon, 12 Dec 2005) roscopeco $
+# $Id: format.rb 120 2005-12-11 06:05:48 +0000 (Sun, 11 Dec 2005) roscopeco $
 #++
 
 Dir[File.join(File.dirname(__FILE__), 'format/*.rb')].each { |f| require f }

data/lib/rote/format/html.rb

@@ -3,7 +3,7 @@
 # (c)2005 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: html.rb 128 2005-12-12 02:45:24 +0000 (Mon, 12 Dec 2005) roscopeco $
+# $Id: html.rb 113 2005-12-09 01:28:21 +0000 (Fri, 09 Dec 2005) roscopeco $
 #++
 require 'erb'
 

data/lib/rote/page.rb

@@ -3,35 +3,115 @@
 # (c)2005, 2006 Ross Bamford (and contributors)
 #
 # See 'rote.rb' or LICENSE for licence information.
-# $Id: page.rb 143 2005-12-14 19:01:05 +0000 (Wed, 14 Dec 2005) roscopeco $
+# $Id: page.rb 170 2006-01-11 23:38:51 +0000 (Wed, 11 Jan 2006) roscopeco $
 #++
 
 require 'erb'
 require 'rote/cache'
+require 'rote/filters'
 
 module Rote
   STRIP_SLASHES = /^\/?(.*?)\/?$/
   FILE_EXT = /\..*$/
   
   #####
-  ## A +Page+ object represents an individual template source file, taking
-  ## input from that file and (optionally) some ruby code, and producing 
-  ## rendered (or 'merged') output as a +String+. All user-supplied code
-  ## (COMMON.rb or page code, for example) is executed in the binding
-  ## of an instance of this class. 
+  ## A +Page+ object represents an individual page in the final 
+  ## documentation set, bringing together a source template, 
+  ## optional _page_ _code_ (in Ruby) obtained from 
+  ## various sources (see below), and an optional layout template
+  ## (with it's own code) to produce rendered output as a +String+. 
+  ## Specifically, Page provides the following capabilities:
   ##
-  ## When a page is created, ruby source will be sought alongside the 
-  ## file, with same basename and an '.rb' extension. If found it will
-  ## run through +instance_eval+. That source can call methods
-  ## and set any instance variables, for use later in the template.
-  ## Such variables or methods may also be defined in a COMMON.rb file
-  ## in or above the page's directory, in code associated with the 
-  ## +layout+ applied to a page, or (less often) in a block supplied to
-  ## +new+.
+  ## * Read _template_ _files_ containing ERB code and render them
+  ##   to create output.
+  ## * Locate and evaluate all _common_ _and_ _page_ _code_ in the binding
+  ##   of the Page instance itself.
+  ## * Apply _layout_ to rendered content using multiple render
+  ##   passes.
+  ## * Apply user-supplied _filters_ to the output to allow 
+  ##   transformations and additional processing. 
+  ##
+  ## In normal use the instantiation and initialization of Pages
+  ## will be handled internally by Rote. From the user point of 
+  ## view most interaction with Rote from user code takes place
+  ## via the instance methods of this class.
+  ##
+  ## == Template lookup and evaluation
+  ##
+  ## Each +Page+ instance is provided at instantiation with base paths
+  ## from which it should resolve both template and layout files when
+  ## required. Usually these paths are supplied by the Rake task 
+  ## configuration. The attributes that provide information on template
+  ## and layout paths (e.g. +template_name+, +base_layout_name+, and
+  ## so on) give those paths relative to the +base_path+ and +layout_path+
+  ## as appropriate.
+  ##
+  ## === Common, page and layout code evaluation
+  ## 
+  ## Code applied to a given page is found and evaluated in the following
+  ## order:
+  ##
+  ## * A block supplied to the <%= section_link 'extension mappings', 'extension mapping' %>
+  ##   that matched this page (if any).
+  ## * Any COMMON.rb files from the filesystem root down to this directory.
+  ## * This page's ruby code, _basename_.rb.
+  ## * In the template itself (via ERB).
+  ## 
+  ## When a +Page+ instance is created, Rote looks for these, and if found evaluates
+  ## them, in order, in the +Page+ instance binding.
+  ## 
+  ## Additionally, when layout is used the following evaluation takes place 
+  ## *after rendering the template text* and can be used to make variables 
+  ## available for the layout pass(es), and apply nested layout:
+  ## 
+  ## * This layout's ruby code, _layout_basename_.rb.
+  ## * In the layout itself (again, with ERB).
+  ##
+  ## As mentioned, +Page+ instances serve as the context for page code 
+  ## execution - All user-supplied code (COMMON.rb, page and layout code, and
+  ## ERB in the templates themselves) is executed in the binding of an instance
+  ## of this class.
+  ##
+  ## == Layout
+  ##
+  ## All pages support layout, which allow common template to be applied across
+  ## several pages. This is handled via multiple render passes, with each layout
+  ## responsible for including the previously rendered content (via ERB).
+  ##
+  ## Layout templates include the content rendered by the page (or previous layout,
+  ## see below) render pass using the instance variable @content_for_layout. 
+  ## This should be a familar pattern for those familiar with the Rails framework.
+  ##
+  ## To apply layout to a page, the +layout+ method should be called, passing
+  ## in the base-name (with extension if different from the page template).
+  ## When issued from common or page code, multiple calls to this method will
+  ## override any previous setting. It may be called again from layout code,
+  ## however, in which case the output of the currently-rendering layout will
+  ## be passed (via the @content_to_layout instance variable) to the specified
+  ## layout. In this way, Rote allows layouts to be nested to any level.
+  ##
+  ## == Filtering
+  ##
+  ## The +page_filter+ and +post_filter+ methods allow _filters_ to be applied
+  ## to a page. Filters can be used to support any kind of textual transformation,
+  ## macro expansion (page filters), or post-render processing (post filters).
+  ## Rote includes a number of filters as standard, supporting plain-text markup,
+  ## syntax highlighting, HTMLTidy postprocessing, and more.
+  ##
+  ## See +Rote::Filters+ for details of standard filters and their individual use.
+  ##
+  ## Filters are written in Ruby, and Rote provides base-classes from which filters
+  ## can be derived with just a few lines of code (See Rote::Filters::TextFilter
+  ## and Rote::Filters::MacroFilter). Additionally, the page and post filter
+  ## methods allow text filters to be created from a supplied block.
+  ##
+  ## == Rendering
+  ##
+  ## Rendering occurs only once for a given page object, when the +render+ method 
+  ## is first called. Once a page has been rendered, the instance it is frozen
+  ## to prevent further modification, and the rendered output is cached. Future
+  ## calls to +render+ will return the cached output.
   ##
-  ## Rendering happens only once for a given page object, when the 
-  ## +render+ method is first called. Once a page has been rendered
-  ## it is frozen.
   class Page  
   
     class << self
@@ -39,7 +119,7 @@ module Rote
       # This does not check that the source exists - use the +ruby_filename+
       # instance method to get the actual filename (if any) of source
       # associated with a given page instance.
-      def page_ruby_filename(template_fn)
+      def page_ruby_filename(template_fn) # :nodoc:
         fn = nil
         if (template_fn) 
           if (fn = template_fn.dup) =~ FILE_EXT
@@ -52,7 +132,7 @@ module Rote
       end
       
       # Find all COMMON.rb files from given dir up to FS root.
-      def resolve_common_rubys(dir, arr = [])
+      def resolve_common_rubys(dir, arr = []) # :nodoc:
         # defer to parent dir first
         parent = File.expand_path(File.join(dir, '..'))
         resolve_common_rubys(parent,arr) unless parent == dir # at root    
@@ -72,24 +152,36 @@ module Rote
     # and operates only on the innermost layout.
     attr_reader :layout_text    # Deprecated vv0.3.2 v-0.4    
     
-    # The names from which this page's template and layout (if any) 
-    # are read, relative to the +base_path+.
-    attr_reader :template_name, :layout_names
+    # The basename from which this page's template was read, 
+    # relative to the +base_path+.
+    attr_reader :template_name
+    
+    attr_reader :layout_names   # :nodoc:    
     
-    # Convenience accessor for the first queued layout. This is the
-    # innermost layout, usually specified by the page itself.
-    def layout_name; layout_names.first; end   
+    # The filename of the innermost layout, usually specified by the page
+    # itself, relative to the +layout_path+. This method should not be used 
+    # from COMMON.rb since its behaviour is undefined until all page code is
+    # evaluated and the final base_layout is known.
+    def base_layout_name; layout_names.first; end       
+    alias :layout_name :base_layout_name    # Compat alias, please migrate  vv0.3.3 v-0.4
     
-    # The base paths for this page's template and layout. These point
-    # to the directories configured in the Rake tasks.
-    attr_reader :base_path, :layout_path
+    # The base path for template resolution.
+    attr_reader :base_path
     
-    # The array of page filters (applied to this page output *before* 
-    # layout is applied) and post filters (three gueses). 
-    # You can use +append_page_filter+ and +append_post_filter+ to add 
-    # new filters, which gives implicit block => Filters::Proc conversion 
+    # The base path for layout resolution
+    attr_reader :layout_path
+    
+    # The array of page filters (applied to this page during the first render 
+    # pass, *before* layout is applied). You can use +page_filter+ to 
+    # add new page filters, which gives implicit block => Filters::TextFilter conversion 
+    # and checks for nil.
+    attr_reader :page_filters
+
+    # The array of post filters (applied to this page output *after* 
+    # layout is applied). You can use +post_filter+ to add 
+    # new post filters, which gives implicit block => Filters::TextFilter conversion 
     # and checks for nil.
-    attr_reader :page_filters, :post_filters   
+    attr_reader :post_filters   
     
     # Reads the template, and evaluates the global and page scripts, if 
     # available, using the current binding. You may define any instance
@@ -102,7 +194,7 @@ module Rote
     #
     # If a block is supplied, it is executed _before_ the global / page
     # code. This will be the block supplied by the file-extension mapping.
-    def initialize(template_name, pages_dir = '.', layout_dir = pages_dir, &blk) 
+    def initialize(template_name, pages_dir = '.', layout_dir = pages_dir) 
       @template_text = nil
       @template_name = nil
       @layout_names = []
@@ -122,14 +214,15 @@ module Rote
       tfn = template_name
       read_template(tfn)
       
-      blk[self] if blk
+      # Yield to the (extension mapping) block
+      yield self if block_given?
       
       # Eval COMMON.rb's
       eval_common_rubys
       
       # get script filenames, and eval them if found
       tfn = ruby_filename # nil if no file      
-      instance_eval(File.read(tfn),tfn) if tfn      
+      instance_eval(File.read(tfn),tfn) if tfn         
     end
             
     # Returns the full filename of this Page's template. This is obtained by
@@ -140,9 +233,10 @@ module Rote
     
     # Returns the full filename of the first queued layout. This is
     # the innermost layout, usually specified by the page itself.
-    def layout_filename
+    def base_layout_filename
       layout_fn(layout_name)
     end
+    alias :layout_filename :base_layout_filename    # Compat alias, please migrate  vv0.3.3 v-0.4
     
     # Returns the full filename of this Page's ruby source. If no source is
     # found for this page (not including common source) this returns +nil+.
@@ -160,7 +254,7 @@ module Rote
         page_filters << filter
       else
         if block
-          page_filters << Filters::Proc.new(block)
+          page_filters << Filters::TextFilter.new(&block)
         end
       end
     end    
@@ -172,7 +266,7 @@ module Rote
         post_filters << filter
       else
         if block
-          post_filters << Filters::Proc.new(block)
+          post_filters << Filters::TextFilter.new(&block)
         end
       end
     end    
@@ -186,17 +280,19 @@ module Rote
     
     alias :to_s :render
     
-    # Adds the specified layout to those that will be rendered. The specified
+    # Sets the page's base-layout as specified, or applies _nested_ _layout_ 
+    # if called during a layout render pass. The specified
     # basename should be the name of the layout file relative to the 
-    # +layout_dir+, with no extension.
+    # +layout_path+. If the layout has the same extension as the page source
+    # template, it may be omitted.
     #
     # *The* *layout* *is* *not* *read* *by* *this* *method*. It, and 
     # it's source, are loaded only at rendering time. This prevents
     # multiple calls by various scoped COMMON code, for example, from
     # making a mess in the Page binding.
     #
-    # This can only be called before the first call to +render+. After 
-    # that the instance is frozen.
+    # This can only be called before the first call to +render+ returns it's
+    # result. After that the Page instance is frozen.
     def layout(basename)
       if basename
         self.layout_names << "#{basename}#{@layout_defext if File.extname(basename).empty?}"
@@ -267,6 +363,16 @@ module Rote
         @content_for_layout = render_page_filters( erb.result(binding) )
       end
       
+      # FIXME: Quick fix for incorrect COMMON.rb layout nesting.
+      # All we do here is reset the layout to be the last layout
+      # added. 
+      #
+      # If it turns out that the ability to nest from COMMON/page
+      # really is useless, we should remove the layout queue entirely,
+      # and then just have the render layout loop run until
+      # layout at end == layout at start.
+      @layout_names = [@layout_names.last] unless layout_names.empty?
+      
       # Do layout _after_ page eval. As we go through this, the layouts
       # we load may add to the end of the layout names array, so nested
       # layout is supported by just chasing the end of the array until
@@ -299,7 +405,7 @@ module Rote
       @result 
     end
         
-    def inherit_common    # inherit_common is implicit now    vv0.2.99  v-0.5
+    def inherit_common    # inherit_common is implicit now    vv0.2.99  v-0.4
       warn "Warning: inherit_common is deprecated (inheritance is now implicit)"
     end
         

data/lib/rote/project/README

@@ -44,6 +44,6 @@ WHAT NEXT?
   + Start Rote in monitor mode, and have your changes rendered as
     you work:
 
-        (rote|rake) monitor
+        (rote|rake) doc_monitor