Skip to content

Commit

Permalink
Move the options documentation to a more prominent place.
Browse files Browse the repository at this point in the history
  • Loading branch information
@nex3
nex3 committed Jun 19, 2009
1 parent 0b8fb17 commit 3847bea
Show file tree
Hide file tree
Showing 2 changed files with 174 additions and 174 deletions.
132 changes: 66 additions & 66 deletions doc-src/HAML_REFERENCE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,72 @@ and using {Haml::Engine} like so:
engine = Haml::Engine.new("%p Haml code!")
engine.render #=> "<p>Haml code!</p>\n"

### Options

Options can be set by setting the {Haml::Template#options Haml::Template.options} hash
in `environment.rb` in Rails...

Haml::Template.options[:format] = :html5

...or by setting the `Merb::Plugin.config[:haml]` hash in `init.rb` in Merb...

Merb::Plugin.config[:haml][:format] = :html5

...or by passing an options hash to {Haml::Engine#initialize}.
Available options are:

{#format-option} `:format`
: Determines the output format. The default is `:xhtml`.
Other options are `:html4` and `:html5`, which are
identical to `:xhtml` except there are no self-closing tags,
the XML prolog is ignored and correct DOCTYPEs are generated.

{#escape_html-option} `:escape_html`
: Sets whether or not to escape HTML-sensitive characters in script.
If this is true, `=` behaves like `&=`;
otherwise, it behaves like `!=`.
Note that if this is set, `!=` should be used for yielding to subtemplates
and rendering partials.
Defaults to false.

{#suppress_eval-option} `:suppress_eval`
: Whether or not attribute hashes and Ruby scripts
designated by `=` or `~` should be
evaluated. If this is `true`, said scripts are
rendered as empty strings. Defaults to `false`.

{#attr_wrapper-option} `:attr_wrapper`
: The character that should wrap element attributes.
This defaults to `'` (an apostrophe). Characters
of this type within the attributes will be escaped
(e.g. by replacing them with `&apos;`) if
the character is an apostrophe or a quotation mark.

{#filename-option} `:filename`
: The name of the Haml file being parsed.
This is only used as information when exceptions are raised.
This is automatically assigned when working through ActionView,
so it's really only useful for the user to assign
when dealing with Haml programatically.

{#line-option} `:line`
: The line offset of the Haml template being parsed.
This is useful for inline templates,
similar to the last argument to `Kernel#eval`.

{#autoclose-option} `:autoclose`
: A list of tag names that should be automatically self-closed
if they have no content.
Defaults to `['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']`.

{#preserve-option} `:preserve`
: A list of tag names that should automatically have their newlines preserved
using the {Haml::Helpers#preserve} helper.
This means that any content given on the same line as the tag will be preserved.
For example, `%textarea= "Foo\nBar"` compiles to `<textarea>Foo&#x000A;Bar</textarea>`.
Defaults to `['textarea', 'pre']`.
See also [Whitespace Preservation](#whitespace_preservation).

## Plain Text

A substantial portion of any HTML document is its content,
Expand Down Expand Up @@ -988,69 +1054,3 @@ for doing stuff like preserving whitespace,
creating nicely indented output for user-defined helpers,
and other useful things.
The helpers are all documented in the {Haml::Helpers} and {Haml::Helpers::ActionViewExtensions} modules.

## Haml Options

Options can be set by setting the {Haml::Template#options Haml::Template.options} hash
in `environment.rb` in Rails...

Haml::Template.options[:format] = :html5

...or by setting the `Merb::Plugin.config[:haml]` hash in `init.rb` in Merb...

Merb::Plugin.config[:haml][:format] = :html5

...or by passing an options hash to {Haml::Engine#initialize}.
Available options are:

{#format-option} `:format`
: Determines the output format. The default is `:xhtml`.
Other options are `:html4` and `:html5`, which are
identical to `:xhtml` except there are no self-closing tags,
the XML prolog is ignored and correct DOCTYPEs are generated.

{#escape_html-option} `:escape_html`
: Sets whether or not to escape HTML-sensitive characters in script.
If this is true, `=` behaves like `&=`;
otherwise, it behaves like `!=`.
Note that if this is set, `!=` should be used for yielding to subtemplates
and rendering partials.
Defaults to false.

{#suppress_eval-option} `:suppress_eval`
: Whether or not attribute hashes and Ruby scripts
designated by `=` or `~` should be
evaluated. If this is `true`, said scripts are
rendered as empty strings. Defaults to `false`.

{#attr_wrapper-option} `:attr_wrapper`
: The character that should wrap element attributes.
This defaults to `'` (an apostrophe). Characters
of this type within the attributes will be escaped
(e.g. by replacing them with `&apos;`) if
the character is an apostrophe or a quotation mark.

{#filename-option} `:filename`
: The name of the Haml file being parsed.
This is only used as information when exceptions are raised.
This is automatically assigned when working through ActionView,
so it's really only useful for the user to assign
when dealing with Haml programatically.

{#line-option} `:line`
: The line offset of the Haml template being parsed.
This is useful for inline templates,
similar to the last argument to `Kernel#eval`.

{#autoclose-option} `:autoclose`
: A list of tag names that should be automatically self-closed
if they have no content.
Defaults to `['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']`.

{#preserve-option} `:preserve`
: A list of tag names that should automatically have their newlines preserved
using the {Haml::Helpers#preserve} helper.
This means that any content given on the same line as the tag will be preserved.
For example, `%textarea= "Foo\nBar"` compiles to `<textarea>Foo&#x000A;Bar</textarea>`.
Defaults to `['textarea', 'pre']`.
See also [Whitespace Preservation](#whitespace_preservation).
216 changes: 108 additions & 108 deletions doc-src/SASS_REFERENCE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,114 @@ and using Sass::Engine like so:
engine = Sass::Engine.new("#main\n :background-color #0000ff")
engine.render #=> "#main { background-color: #0000ff; }\n"

### Options

Options can be set by setting the {Sass::Plugin#options Sass::Plugin.options} hash
in `environment.rb` in Rails...

Sass::Plugin.options[:style] = :compact

...or by setting the `Merb::Plugin.config[:sass]` hash in `init.rb` in Merb...

Merb::Plugin.config[:sass][:style] = :compact

...or by passing an options hash to {Sass::Engine#initialize}.
Available options are:

{#style-option} `:style`
: Sets the style of the CSS output.
See the section on Output Style, above.

{#attribute_syntax-option} `:attribute_syntax`
: Forces the document to use one syntax for attributes.
If the correct syntax isn't used, an error is thrown.
`:normal` forces the use of a colon
before the attribute name.
For example: `:color #0f3`
or `:width = !main_width`.
`:alternate` forces the use of a colon or equals sign
after the attribute name.
For example: `color: #0f3`
or `width = !main_width`.
By default, either syntax is valid.

{#cache-option} `cache`
: Whether parsed Sass files should be cached,
allowing greater speed. Defaults to true.

{#never_update-option} `:never_update`
: Whether the CSS files should never be updated,
even if the template file changes.
Setting this to true may give small performance gains.
It always defaults to false.
Only has meaning within Ruby on Rails or Merb.

{#always_update-option} `:always_update`
: Whether the CSS files should be updated every
time a controller is accessed,
as opposed to only when the template has been modified.
Defaults to false.
Only has meaning within Ruby on Rails or Merb.

{#always_check-option} `:always_check`
: Whether a Sass template should be checked for updates every
time a controller is accessed,
as opposed to only when the Rails server starts.
If a Sass template has been updated,
it will be recompiled and will overwrite the corresponding CSS file.
Defaults to false in production mode, true otherwise.
Only has meaning within Ruby on Rails or Merb.

{#full_exception-option} `:full_exception`
: Whether an error in the Sass code
should cause Sass to provide a detailed description.
If set to true, the specific error will be displayed
along with a line number and source snippet.
Otherwise, a simple uninformative error message will be displayed.
Defaults to false in production mode, true otherwise.
Only has meaning within Ruby on Rails or Merb.

{#template-location-option} `:template_location`
: A path to the root sass template directory for you application.
If a hash, `:css_location` is ignored and this option designates
both a mapping between input and output directories.
May also be given a list of 2-element lists, instead of a hash.
Defaults to `RAILS_ROOT + "/public/stylesheets/sass"`
or `MERB_ROOT + "/public/stylesheets/sass"`.
Only has meaning within Ruby on Rails or Merb.
This will be derived from the `:css_location` path list if not provided
by appending a folder of "sass" to each corresponding css location.

{#css-location-option} `:css_location`
: The path where CSS output should be written to.
This option is ignored when `:template_location` is a Hash.
Defaults to `RAILS_ROOT + "/public/stylesheets"`
or `MERB_ROOT + "/public/stylesheets"`.
Only has meaning within Ruby on Rails or Merb.

{#cache_location-option} `:cache_location`
: The path where the cached `sassc` files should be written to.
Defaults to `RAILS_ROOT + "/tmp/sass-cache"`,
or `MERB_ROOT + "/tmp/sass-cache"`,
or just `"./.sass-cache"`.

{#filename-option} `:filename`
: The filename of the file being rendered.
This is used solely for reporting errors,
and is automatically set when using Rails or Merb.

{#load_paths-option} `:load_paths`
: An array of filesystem paths which should be searched
for Sass templates imported with the "@import" directive.
This defaults to the working directory and, in Rails or Merb,
whatever `:template_location` is.

{#line_numbers-option} `:line_numbers`
: When set to true, causes the line number and file
where a selector is defined to be emitted into the compiled CSS
as a comment. Useful for debugging especially when using imports
and mixins.

## CSS Rules

Rules in flat CSS have two elements:
Expand Down Expand Up @@ -968,111 +1076,3 @@ It's not meant to be human-readable.
For example:

#main{color:#fff;background-color:#000}#main p{width:10em}.huge{font-size:10em;font-weight:bold;text-decoration:underline}

## Sass Options

Options can be set by setting the {Sass::Plugin#options Sass::Plugin.options} hash
in `environment.rb` in Rails...

Sass::Plugin.options[:style] = :compact

...or by setting the `Merb::Plugin.config[:sass]` hash in `init.rb` in Merb...

Merb::Plugin.config[:sass][:style] = :compact

...or by passing an options hash to {Sass::Engine#initialize}.
Available options are:

{#style-option} `:style`
: Sets the style of the CSS output.
See the section on Output Style, above.

{#attribute_syntax-option} `:attribute_syntax`
: Forces the document to use one syntax for attributes.
If the correct syntax isn't used, an error is thrown.
`:normal` forces the use of a colon
before the attribute name.
For example: `:color #0f3`
or `:width = !main_width`.
`:alternate` forces the use of a colon or equals sign
after the attribute name.
For example: `color: #0f3`
or `width = !main_width`.
By default, either syntax is valid.

{#cache-option} `cache`
: Whether parsed Sass files should be cached,
allowing greater speed. Defaults to true.

{#never_update-option} `:never_update`
: Whether the CSS files should never be updated,
even if the template file changes.
Setting this to true may give small performance gains.
It always defaults to false.
Only has meaning within Ruby on Rails or Merb.

{#always_update-option} `:always_update`
: Whether the CSS files should be updated every
time a controller is accessed,
as opposed to only when the template has been modified.
Defaults to false.
Only has meaning within Ruby on Rails or Merb.

{#always_check-option} `:always_check`
: Whether a Sass template should be checked for updates every
time a controller is accessed,
as opposed to only when the Rails server starts.
If a Sass template has been updated,
it will be recompiled and will overwrite the corresponding CSS file.
Defaults to false in production mode, true otherwise.
Only has meaning within Ruby on Rails or Merb.

{#full_exception-option} `:full_exception`
: Whether an error in the Sass code
should cause Sass to provide a detailed description.
If set to true, the specific error will be displayed
along with a line number and source snippet.
Otherwise, a simple uninformative error message will be displayed.
Defaults to false in production mode, true otherwise.
Only has meaning within Ruby on Rails or Merb.

{#template-location-option} `:template_location`
: A path to the root sass template directory for you application.
If a hash, `:css_location` is ignored and this option designates
both a mapping between input and output directories.
May also be given a list of 2-element lists, instead of a hash.
Defaults to `RAILS_ROOT + "/public/stylesheets/sass"`
or `MERB_ROOT + "/public/stylesheets/sass"`.
Only has meaning within Ruby on Rails or Merb.
This will be derived from the `:css_location` path list if not provided
by appending a folder of "sass" to each corresponding css location.

{#css-location-option} `:css_location`
: The path where CSS output should be written to.
This option is ignored when `:template_location` is a Hash.
Defaults to `RAILS_ROOT + "/public/stylesheets"`
or `MERB_ROOT + "/public/stylesheets"`.
Only has meaning within Ruby on Rails or Merb.

{#cache_location-option} `:cache_location`
: The path where the cached `sassc` files should be written to.
Defaults to `RAILS_ROOT + "/tmp/sass-cache"`,
or `MERB_ROOT + "/tmp/sass-cache"`,
or just `"./.sass-cache"`.

{#filename-option} `:filename`
: The filename of the file being rendered.
This is used solely for reporting errors,
and is automatically set when using Rails or Merb.

{#load_paths-option} `:load_paths`
: An array of filesystem paths which should be searched
for Sass templates imported with the "@import" directive.
This defaults to the working directory and, in Rails or Merb,
whatever `:template_location` is.

{#line_numbers-option} `:line_numbers`
: When set to true, causes the line number and file
where a selector is defined to be emitted into the compiled CSS
as a comment. Useful for debugging especially when using imports
and mixins.

0 comments on commit 3847bea

Please sign in to comment.