Changeset 80

Timestamp:

10/03/2006 15:57:42 (2 years ago)

Author:

why

Message:

• README: updated all rdoc and package docs to 0.5 and its conventions.
  

Location:

trunk

Files:

• CHANGELOG (modified) (1 diff)
• README (modified) (6 diffs)
• Rakefile (modified) (1 diff)
• lib/markaby.rb (modified) (1 diff)
• lib/markaby/builder.rb (modified) (3 diffs)
• lib/markaby/tags.rb (modified) (4 diffs)

trunk/CHANGELOG

@@ +1 @@
+= 0.5
+=== 03 October, 2006
+
+* XHTML Validation built in.  So, if you have an invalid tag: error.  Invalid attribute: error.
+  And two identical IDs in the same document: error.  Optional, of course.  But handy!
+* New Markaby::Fragment class adds much flexibility.  If it discovers you are using a tag as a string,
+  the tag is removed from the stream.  (<tt>div { strong("Real") + " Giraffes" }</tt>)
+* The prevailing rule now is: if you want it escaped, pass it to a block.  If not, pass it as an arg.
+* Again, escaped: <tt>h1("Me & You Have a Giraffe")</tt>
+* And, not escaped: <tt>h1 { "<a href='/'>Home</a>" }</tt>
+* Less method_missing, meaning: faster calls all around.  Tag methods generated based on doctype.
+* The <tt>html</tt> method doesn't write the doctype tags and meta tags.  You must use <tt>xhtml_transitional</tt> or <tt>xhtml_strict</tt> methods to do that.
+* The <tt>img</tt> method doesn't try to inject an empty alt tag and a zero border.  No more of that.
+
 = 0.3
 === 02nd February, 2006

trunk/README

@@ -74 +74 @@
 module where it won't mix with anything.
 
-= A Note About Rails Helpers
-
-When used in Rails templates, the Rails helper object is passed into 
-Markaby::Builder.  When you call helper methods inside Markaby, the output
-from those methods will be output to the stream.  This is incredibly
-handy, since most Rails helpers output HTML tags.
-
-  head do
-    javascript_include_tag 'prototype'
-    autodiscovery_link_tag
-  end
-
-However, some methods are designed to give back a String which you can use
-elsewhere.  Call the <tt>@helpers</tt> object with the method and you'll get
-the String back and nothing will be output.
-
-  p "Total is: #{@helper.number_to_human_size @file_bytes}"
-
-Conversely, you may call instance variables from your controller by using
-a method and its value will be returned, nothing will be output.
-
-  # Inside imaginary ProductController
-  def list
-    @products = Product.find :all
-  end
-
-  # Inside app/views/product/list.mab
-  products.each do |product|
-    p product.title
-  end
-
-= A Quick Tour
+= The Six Steps of Markaby
 
 If you dive right into Markaby, it'll probably make good sense, but you're
-likely to run into a few kinks.  Keep these pointers in mind and everything
-will be fine.
-
-== Element Classes
+likely to run into a few kinks.  Why not review these six steps and commit
+them memory so you can really *know* what you're doing?
+
+== 1. Element Classes
 
 Element classes may be added by hooking methods onto container elements:
@@ -129 +98 @@
   </div>
 
-== Element IDs
+== 2. Element IDs
 
 IDs may be added by the use of bang methods:
@@ -147 +116 @@
   </div>
 
-== Markaby assumes XHTML 1.0 Transitional 
-
-Output defaults to XHTML 1.0 Transitional. To do XHTML 1.0 Strict,
-try this:
+== 3. Validate Your XHTML 1.0 Output 
+
+If you'd like Markaby to help you assemble valid XHTML documents,
+you can use the <tt>xhtml_transitional</tt> or <tt>xhtml_strict</tt>
+methods in place of the normal <tt>html</tt> tag.
 
   xhtml_strict do
-    # innerds
-  end
-
-== Markaby prevents invalid HTML
-
-Since Markaby knows which doctype you're using, it checks a big
+    head { ... }
+    body { ... }
+  end
+
+This will add the XML instruction and the doctype tag to your document.
+Also, a character set meta tag will be placed inside your <tt>head</tt>
+tag.
+
+Now, since Markaby knows which doctype you're using, it checks a big
 list of valid tags and attributes before printing anything.
 
@@ -166 +139 @@
   InvalidHtmlError: no such attribute `styl'
 
-== Auto-stringification
+Markaby will also make sure you don't use the same element ID twice!
+
+== 4. Escape or No Escape?
+
+Markaby uses a simple convention for escaping stuff: if a string
+is an argument, it gets escaped.  If the string is in a block, it
+doesn't.
+
+This is handy if you're using something like RedCloth or
+RDoc inside an element.  Pass the string back through the block
+and it'll skip out of escaping.
+
+  div.comment { RedCloth.new(str).to_html }
+
+But, if we have some raw text that needs escaping, pass it in
+as an argument:
+
+  div.comment raw_str
+
+One caveat: if you have other tags inside a block, the string
+passed back will be ignored.
+
+  div.comment {
+    div.author "_why"
+    div.says "Torpedoooooes!"
+    "<div>Silence.</div>"
+  }
+
+The final div above won't appear in the output.  You can't mix
+tag modes like that, friend.
+
+== 5. Auto-stringification
 
 If you end up using any of your Markaby "tags" as a string, the
@@ -192 +196 @@
     join( " | " )
 
-== The <tt>tag!</tt> Method
+== 6. The <tt>tag!</tt> Method
 
 If you need to force a tag at any time, call <tt>tag!</tt> with the
@@ -204 +208 @@
   end
 
+= A Note About Rails Helpers
+
+When used in Rails templates, the Rails helper object is passed into 
+Markaby::Builder.  When you call helper methods inside Markaby, the output
+from those methods will be output to the stream.  This is incredibly
+handy, since most Rails helpers output HTML tags.
+
+  head do
+    javascript_include_tag 'prototype'
+    autodiscovery_link_tag
+  end
+
+However, some methods are designed to give back a String which you can use
+elsewhere.  That's okay!  Every method returns a Fragment object, which can
+be used as a string.
+
+  p { "Total is: #{number_to_human_size @file_bytes}" }
+
+Also see the Quick Tour above, specifically the stuff about auto-stringification.
+
+If for any reason you have trouble with fragments, you can just
+call the <tt>@helpers</tt> object with the method and you'll get
+the String back and nothing will be output.
+
+  p { "Total is: #{@helper.number_to_human_size @file_bytes}" }
+
+Conversely, you may call instance variables from your controller by using
+a method and its value will be returned, nothing will be output.
+
+  # Inside imaginary ProductController
+  def list
+    @products = Product.find :all
+  end
+
+  # Inside app/views/product/list.mab
+  products.each do |product|
+    p product.title
+  end
+
 = Credits
 

trunk/Rakefile

@@ -9 +9 @@
 
 REV = File.read(".svn/entries")[/committed-rev="(\d+)"/, 1] rescue nil
-VERS = ENV['VERSION'] || "0.4" + (REV ? ".#{REV}" : "")
+VERS = ENV['VERSION'] || "0.5" + (REV ? ".#{REV}" : "")
 
 task :default => [:package]

trunk/lib/markaby.rb

@@ -20 +20 @@
 #   proper templating language.
 module Markaby
-  VERSION = '0.4'
+  VERSION = '0.5'
 
   class InvalidXhtmlError < Exception; end

trunk/lib/markaby/builder.rb

@@ -162 +162 @@
     end
 
-    # Create XML markup based on the name of the method +sym+. This method is never 
-    # invoked directly, but is called for each markup method in the markup block.
-    #
-    # This method is also used to intercept calls to helper methods and instance
+    # This method is used to intercept calls to helper methods and instance
     # variables.  Here is the order of interception:
     #
-    # * If +sym+ is a recognized HTML tag, the tag is output
-    #   or a CssProxy is returned if no arguments are given.
-    # * If +sym+ appears to be a self-closing tag, its block
-    #   is ignored, thus outputting a valid self-closing tag.
+    # * If +sym+ is a helper method, the helper method is called
+    #   and output to the stream.
+    # * If +sym+ is a Builder::XmlMarkup method, it is passed on to the builder object.
     # * If +sym+ is also the name of an instance variable, the
     #   value of the instance variable is returned.
-    # * If +sym+ is a helper method, the helper method is called
-    #   and output to the stream.
-    # * Otherwise, +sym+ and its arguments are passed to tag!
+    # * If +sym+ has come this far and no +tagset+ is found, +sym+ and its arguments are passed to tag!
+    # * If a tagset is found, though, +NoMethodError+ is raised.
+    #
+    # method_missing used to be the lynchpin in Markaby, but it's no longer used to handle
+    # HTML tags.  See html_tag for that.
     def method_missing(sym, *args, &block)
       if @helpers.respond_to?(sym, true) && !self.class.ignored_helpers.include?(sym)
         r = @helpers.send(sym, *args, &block)
-        if @output_helpers
+        if @output_helpers and r.respond_to? :to_str
           fragment { @builder << r }
         else
@@ -196 +194 @@
     end
 
+    # Every HTML tag method goes through an html_tag call.  So, calling <tt>div</tt> is equivalent
+    # to calling <tt>html_tag(:div)</tt>.  All HTML tags in Markaby's list are given generated wrappers
+    # for this method.
+    #
+    # If the @auto_validation setting is on, this method will check for many common mistakes which
+    # could lead to invalid XHTML.
     def html_tag(sym, *args, &block)
       if @auto_validation and @tagset.self_closing.include?(sym) and block
@@ -263 +267 @@
   end
 
+  # Every tag method in Markaby returns a Fragment.  If any method gets called on the Fragment,
+  # the tag is removed from the Markaby stream and given back as a string.  Usually the fragment
+  # is never used, though, and the stream stays intact.
+  #
+  # For a more practical explanation, check out the README.
   class Fragment < ::Builder::BlankSlate
     def initialize(s, a, b)

trunk/lib/markaby/tags.rb

@@ -7 +7 @@
   # Common sets of attributes.
   AttrCore = [:id, :class, :style, :title]
-  AttrI18n = [:lang, :'xml:lang', :dir]
+  AttrI18n = [:lang, 'xml:lang'.intern, :dir]
   AttrEvents = [:onclick, :ondblclick, :onmousedown, :onmouseup, :onmouseover, :onmousemove, 
       :onmouseout, :onkeypress, :onkeydown, :onkeyup]
@@ -26 +26 @@
       :title => AttrI18n + [:id],
       :base => [:href, :id],
-      :meta => AttrI18n + [:id, :http, :name, :content, :scheme, :'http-equiv'],
+      :meta => AttrI18n + [:id, :http, :name, :content, :scheme, 'http-equiv'.intern],
       :link => Attrs + [:charset, :href, :hreflang, :type, :rel, :rev, :media],
-      :style => AttrI18n + [:id, :type, :media, :title, :'xml:space'],
-      :script => [:id, :charset, :type, :src, :defer, :'xml:space'],
+      :style => AttrI18n + [:id, :type, :media, :title, 'xml:space'.intern],
+      :script => [:id, :charset, :type, :src, :defer, 'xml:space'.intern],
       :noscript => Attrs,
       :body => Attrs + [:onload, :onunload],
@@ -42 +42 @@
       :address => Attrs,
       :hr => Attrs,
-      :pre => Attrs + [:'xml:space'],
+      :pre => Attrs + ['xml:space'.intern],
       :blockquote => Attrs + [:cite],
       :ins => Attrs + [:cite, :datetime],
@@ -48 +48 @@
       :a => Attrs + AttrFocus + [:charset, :type, :name, :href, :hreflang, :rel, :rev, :shape, :coords],
       :span => Attrs,
-      :bdo => AttrCore + AttrEvents + [:lang, :'xml:lang', :dir],
+      :bdo => AttrCore + AttrEvents + [:lang, 'xml:lang'.intern, :dir],
       :br => AttrCore,
       :em => Attrs,