mirror of
https://github.com/haml/haml.git
synced 2022-11-09 12:33:31 -05:00
Use YARD's new capabilities to render the FAQ as Markdown.
This commit is contained in:
Nathan Weizenbaum
parent
02f4a21483
commit
06c1b3dd35
4 changed files with 153 additions and 140 deletions
5
.yardopts
Normal file
5
.yardopts
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
--readme README.md
|
||||
--markup markdown
|
||||
--markup-provider maruku
|
||||
--protected
|
||||
--no-highlight
|
||||
138
FAQ
138
FAQ
|
|
@ -1,138 +0,0 @@
|
|||
= 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>
</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
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
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].
|
||||
142
FAQ.md
Normal file
142
FAQ.md
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
# Frequently Asked Questions
|
||||
|
||||
## Haml
|
||||
|
||||
### How do I put a punctuation mark after an element, like "`I like <strong>cake</strong>!`"?
|
||||
{#q-punctuation}
|
||||
|
||||
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?
|
||||
{#q-preserve}
|
||||
|
||||
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 (`
`),
|
||||
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 [`:preserve`](Haml.html#preserve-option) option.
|
||||
For example,
|
||||
|
||||
%p
|
||||
%textarea= "Foo\nBar"
|
||||
|
||||
will be compiled to
|
||||
|
||||
<p>
|
||||
<textarea>Foo
Bar</textarea>
|
||||
</p>
|
||||
|
||||
However, if a helper is generating the tag,
|
||||
Haml can't detect that and so you'll have to call {Haml::Helpers#find_and_preserve} yourself.
|
||||
You can also use `~`, which is the same as `=`
|
||||
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
Bar</textarea></p>
|
||||
|
||||
### How do I make my long lines of Ruby code look nicer in my Haml document?
|
||||
{#q-multiline}
|
||||
|
||||
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 `|` (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 `.html.erb` files | rendering Haml files as plain text | rendering Haml files as blank pages)?
|
||||
{#q-blank-page}
|
||||
|
||||
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?
|
||||
{#q-ruby-code}
|
||||
|
||||
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).
|
||||
8
Rakefile
8
Rakefile
|
|
@ -142,9 +142,13 @@ begin
|
|||
files.exclude('lib/haml/template/*.rb')
|
||||
files.exclude('lib/haml/helpers/action_view_mods.rb')
|
||||
t.files = files.to_a
|
||||
|
||||
t.options << '-r' << 'README.md' << '-m' << 'markdown' << '--protected' << '--no-highlight'
|
||||
t.options += FileList.new('yard/*.rb').to_a.map {|f| ['-e', f]}.flatten
|
||||
t.options << '--files' << FileList.new('*') do |list|
|
||||
list.exclude(/(^|[^.a-z])[a-z]+/)
|
||||
list.exclude('README.md')
|
||||
list.exclude('REVISION')
|
||||
list.exclude('TODO')
|
||||
end.to_a.join(',')
|
||||
end
|
||||
|
||||
task :doc => :yardoc
|
||||
|
|
|
|||
Loading…
Reference in a new issue