merbjedi-haml 2.1.0

data/FAQ

@@ -0,0 +1,138 @@
+= Frequently Asked Questions
+
+== Haml
+
+=== How do I put a punctuation mark after an element, like "<tt>I like <strong>cake</strong>!</tt>"?
+
+Expressing the structure of a document
+and expressing inline formatting are two very different problems.
+Haml is mostly designed for structure,
+so the best way to deal with formatting is to leave it to other languages
+that are designed for it.
+You could use Textile:
+
+  %p
+    :textile
+      I like *cake*!
+
+or Markdown:
+
+  %p
+    :markdown
+      I like **cake**!
+
+or plain old XHTML:
+
+  %p I like <strong>cake</strong>!
+
+If you're inserting something that's generated by a helper, like a link,
+then it's even easier:
+
+  %p== I like #{link_to 'chocolate', 'http://franschocolates.com'}!
+
+=== How do I stop Haml from indenting the contents of my +pre+ and +textarea+ tags?
+
+Because Haml automatically indents the HTML source code,
+the contents of whitespace-sensitive tags like +pre+ and +textarea+
+can get screwed up.
+The solution is to replace the newlines inside these tags
+with HTML newline entities (<tt>&#x000A;</tt>),
+which Haml does using the Haml::Helpers#preserve and Haml::Helpers#find_and_preserve helpers.
+
+Normally, Haml will do this for you automatically
+when you're using a tag that needs it
+(this can be customized using the <tt>:preserve</tt> option;
+see the Options section of the {Haml reference}(../classes/Haml.html)).
+For example,
+
+  %p
+    %textarea= "Foo\nBar"
+
+will be compiled to
+
+  <p>
+    <textarea>Foo&#x000A;Bar</textarea>
+  </p>
+
+However, if a helper is generating the tag,
+Haml can't detect that and so you'll have to call +find_and_preserve+ yourself.
+You can also use <tt>~</tt>, which is the same as <tt>=</tt>
+except that it automatically runs +find_and_preserve+ on its input.
+For example:
+
+  %p= find_and_preserve "<textarea>Foo\nBar</textarea>"
+
+is the same as
+
+  %p~ "<textarea>Foo\nBar</textarea>"
+
+and renders
+
+  <p><textarea>Foo&#x000A;Bar</textarea></p>
+
+=== How do I make my long lines of Ruby code look nicer in my Haml document?
+
+Put them in a helper or your model.
+
+Haml purposefully makes it annoying to put lots of Ruby code into your templates,
+because lots of code doesn't belong in the view.
+If you take that huge +link_to_remote+ call
+and move it to a +update_sidebar_link+ helper,
+it'll make your view both easier to read and more semantic.
+
+If you absolutely must put lots of code in your template,
+Haml offers a somewhat awkward multiline-continuation tool.
+Put a <tt>|</tt> (pipe character) at the end of each line you want to be merged into one
+(including the last line!).
+For example:
+
+  %p= @this.is(way.too.much). |
+      code("and I should").   |
+      really_move.it.into(    |
+        :a => @helper)        |
+
+=== I have Haml installed. Why is Rails (only looking for <tt>.html.erb</tt> files | rendering Haml files as plain text | rendering Haml files as blank pages)?
+
+There are several reasons these things might be happening.
+First of all, make sure vendor/plugins/haml really exists
+and has an init.rb file in there.
+Then try restarting Mongrel or WEBrick or whatever you might be using.
+
+Finally, if none of these work,
+chances are you've got some localization plugin like Globalize installed.
+Such plugins often don't play nicely with Haml.
+Luckily, there's usually an easy fix.
+For Globalize, just edit globalize/lib/globalize/rails/action_view.rb
+and change
+
+  @@re_extension = /\.(rjs|rhtml|rxml)$/
+
+to
+
+  @@re_extension = /\.(rjs|rhtml|rxml|erb|builder|haml)$/
+
+For other plugins, a little searching will probably turn up a way to fix them as well.
+
+== Sass
+
+=== Can I use a variable from my controller in my Sass file?
+
+No. Sass files aren't views.
+They're compiled once into static CSS files,
+then left along until they're changed and need to be compiled again.
+Not only don't you want to be running a full request cycle
+every time someone requests a stylesheet,
+but it's not a great idea to put much logic in there anyway
+due to how browsers handle them.
+
+If you really need some sort of dynamic CSS,
+the best thing to do is put only the snippet you need to dynamically set
+in the +head+ of your HTML document.
+
+== You still haven't answered my question!
+
+Sorry! Try looking at the Haml or Sass references,
+in the doucmentation for the haml and Sass modules, respectively.
+If you can't find an answer there,
+feel free to ask in #haml on irc.freenode.net
+or send an email to the {mailing list}[http://groups.google.com/group/haml?hl=en].

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2008 Hampton Catlin
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,332 @@
+= Haml and Sass
+
+Haml and Sass are templating engines
+for the two most common types of documents on the web:
+HTML and CSS, respectively.
+They are designed to make it both easier and more pleasant
+to code HTML and CSS documents,
+by eliminating redundancy,
+reflecting the underlying structure that the document represents,
+and providing elegant, easily understandable, and powerful syntax.
+
+== Using
+
+There are several ways to use Haml and Sass.
+They can be used as a plugin for Rails or Merb,
+or embedded on their own in other applications.
+The first step of all of these is to install the Haml gem:
+
+  gem install haml
+
+To install Haml and Sass as a Rails plugin,
+just run <tt>haml --rails path/to/rails/app</tt>
+and both Haml and Sass will be installed.
+Views with the <tt>.haml</tt> (or <tt>.html.haml</tt> for edge)
+extension will automatically use Haml.
+Sass is a little more complicated;
+<tt>.sass</tt> files should be placed in public/stylesheets/sass,
+where they'll be automatically compiled
+to corresponding CSS files in public/stylesheets when needed
+(the Sass template directory is customizable...
+see the Sass module docs for details).
+
+For Merb, <tt>.html.haml</tt> views will work without any further modification.
+To enable Sass, you also need to add a dependency.
+To do so, just add
+
+  dependency "merb-haml"
+
+to config/dependencies.rb (or config/init.rb in a flat/very flat Merb application).
+Then it'll work just like it does in Rails.
+
+To use Haml and Sass programatically,
+check out the RDocs for the Haml and Sass modules.
+
+== Formatting
+
+=== Haml
+
+The most basic element of Haml
+is a shorthand for creating HTML tags:
+
+  %tagname{ :attr1 => 'value1', :attr2 => 'value2' } Contents
+
+No end-tag is needed; Haml handles that automatically.
+Adding <tt>class</tt> and <tt>id</tt> attributes is even easier.
+Haml uses the same syntax as the CSS that styles the document:
+
+  %tagname#id.class
+
+In fact, when you're using the <tt><div></tt> tag,
+it becomes <em>even easier</em>.
+Because <tt><div></tt> is such a common element,
+a tag without a name defaults to a div. So
+
+  #foo Hello!
+
+becomes
+
+  <div id='foo'>Hello!</div>
+
+Haml uses indentation
+to bring the individual elements to represent the HTML structure.
+A tag's children are indented beneath than the parent tag.
+Again, a closing tag is automatically added.
+For example:
+
+  %ul
+    %li Salt
+    %li Pepper
+
+becomes:
+
+  <ul>
+    <li>Salt</li>
+    <li>Pepper</li>
+  </ul>
+
+You can also put plain text as a child of an element:
+
+  %p
+    Hello,
+    World!
+
+It's even possible to embed Ruby code into Haml documents.
+An equals sign, <tt>=</tt>, will output the result of the code.
+A hyphen, <tt>-</tt>, will run the code but not output the result.
+You can even use control statements
+like <tt>if</tt> and <tt>while</tt>:
+
+  %p
+    Date/Time:
+    - now = DateTime.now
+    %strong= now
+    - if now > DateTime.parse("December 31, 2006")
+      = "Happy new " + "year!"
+
+Haml provides far more tools than those presented here.
+Check out the reference documentation in the Haml module.
+
+=== Sass
+
+At its most basic,
+Sass is just another way of writing CSS.
+Although it's very much like normal CSS,
+the basic syntax offers a few helpful features:
+tabulation indicates the attributes in a rule,
+rather than non-DRY brackets;
+and newlines indicate the end of an attribute,
+rather than a semicolon.
+For example:
+
+  #main
+    :background-color #f00
+    :width 98%
+
+becomes:
+
+  #main {
+    background-color: #f00;
+    width: 98% }
+
+However, Sass provides much more than a way to make CSS look nice.
+In CSS, it's important to have accurate selectors,
+so your styles don't just apply to everything.
+However, in order to do this,
+you need to use nested element selectors.
+These get very ugly very quickly.
+I'm sure everyone's had to write something like
+"#main .sidebar .top p h1 a",
+followed by
+"#main .sidebar .top p h1 a:visited" and
+"#main .sidebar .top p h1 a:hover".
+Well, Sass gets rid of that.
+Like Haml, it uses indentation to indicate the structure of the document.
+So, what was:
+
+  #main {
+    width: 90%;
+  }
+  #main p {
+    border-style: solid;
+    border-width: 1px;
+    border-color: #00f;
+  }
+  #main p a {
+    text-decoration: none;
+    font-weight: bold;
+  }
+  #main p a:hover {
+    text-decoration: underline;
+  }
+
+becomes:
+
+  #main
+    :width 90%
+    p
+      :border-style solid
+      :border-width 1px
+      :border-color #00f
+      a
+        :text-decoration none
+        :font-weight bold
+      a:hover
+        :text-decoration underline
+
+Pretty nice, no? Well, it gets better.
+One of the main complaints against CSS is that it doesn't allow variables.
+What if have a color or a width you re-use all the time?
+In CSS, you just have to re-type it each time,
+which is a nightmare when you decide to change it later.
+Not so for Sass!
+You can use the "!" character to set variables.
+Then, if you put "=" after your attribute name,
+you can set it to a variable.
+For example:
+
+  !note_bg= #55aaff
+
+  #main
+    :width 70%
+    .note
+      :background-color= !note_bg
+    p
+      :width 5em
+      :background-color= !note_bg
+
+becomes:
+
+  #main {
+    width: 70%; }
+    #main .note {
+      background-color: #55aaff; }
+    #main p {
+      width: 5em;
+      background-color: #55aaff; }
+
+You can even do simple arithmetic operations with variables,
+adding numbers and even colors together:
+
+  !main_bg= #46ar12
+  !main_width= 40em
+
+  #main
+    :background-color= !main_bg
+    :width= !main_width
+    .sidebar
+      :background-color= !main_bg + #333333
+      :width= !main_width - 25em
+
+becomes:
+
+  #main {
+    background-color: #46a312;
+    width: 40em; }
+    #main .sidebar {
+      background-color: #79d645;
+      width: 15em; }
+
+Taking the idea of variables a bit further are mixins.
+These let you group whole swathes of CSS attributes into a single
+directive and then include those anywhere you want:
+
+  =blue-border
+    :border
+      :color blue
+      :width 2px
+      :style dotted
+
+  .comment
+    +blue-border
+    :padding 2px
+    :margin 10px 0
+
+  .reply
+    +blue-border
+
+becomes:
+
+  .comment {
+    border-color: blue;
+    border-width: 2px;
+    border-style: dotted;
+    padding: 2px;
+    margin: 10px 0;
+  }
+
+  .reply {
+    border-color: blue;
+    border-width: 2px;
+    border-style: dotted;
+  }
+
+A comprehensive list of features is in
+the documentation for the Sass module.
+
+== Indentation
+
+Indentation can be made up of one or more tabs or spaces.
+However, indentation must be consistent within a given document.
+Hard tabs and spaces can't be mixed,
+and the same number of tabs or spaces must be used throughout.
+
+== Executables
+
+The Haml gem includes several executables that are useful
+for dealing with Haml and Sass from the command line.
+
+=== +haml+
+
+The +haml+ executable transforms a source Haml file into HTML.
+See <tt>haml --help</tt> for further information and options.
+
+=== +sass+
+
+The +sass+ executable transforms a source Sass file into CSS.
+See <tt>sass --help</tt> for further information and options.
+
+=== <tt>html2haml</tt>
+
+The <tt>html2haml</tt> executable attempts to transform HTML,
+optionally with ERB markup, into Haml code.
+Since HTML is so variable, this transformation is not always perfect;
+it's a good idea to have a human check the output of this tool.
+See <tt>html2haml --help</tt> for further information and options.
+
+=== <tt>css2sass</tt>
+
+The <tt>css2sass</tt> executable attempts to transform CSS into Sass code.
+This transformation attempts to use Sass nesting where possible.
+See <tt>css2sass --help</tt> for further information and options.
+
+== Authors
+
+Haml and Sass are designed by Hampton Catlin (hcatlin) and he is the author
+of the original implementation. However, Hampton doesn't even know his way
+around the code anymore and mostly just concentrates on the language issues.
+Hampton lives in Toronto, Ontario (though he's an American by birth) and
+is a partner at Unspace Interactive.
+
+Nathan Weizenbaum is the primary maintainer and architect of the "modern" Ruby
+implementation of Haml. His hard work has kept the project alive by endlessly
+answering forum posts, fixing bugs, refactoring, finding speed improvements,
+writing documentation, implementing new features, and getting Hampton
+coffee (a fitting task for a boy-genius). Nathan lives in Seattle, Washington and
+while not being a student at University of Washington he consults for
+Unspace Interactive and Microsoft.
+
+Chris Eppstein is a core contributor to Sass and the creator of Compass, the first
+Sass-based framework. Chris focuses on making Sass more powerful, easy to use, and
+on ways to speed its adoption through the web development community. Chris lives in
+San Jose, CA with his wife and daughter. He is the Software Architect for Caring.com,
+a website devoted to the 34 Million caregivers whose parents are sick or elderly,
+that uses Haml and Sass.
+
+If you use this software, you must pay Hampton a compliment. And
+buy Nathan some jelly beans. Maybe pet a kitten. Yeah. Pet that kitty.
+
+Some of the work on Haml was supported by Unspace Interactive.
+
+Beyond that, the implementation is licensed under the MIT License.
+Ok, fine, I guess that means compliments aren't *required*.