webby 0.8.2 → 0.8.3

data/examples/webby/content/index.txt

@@ -9,9 +9,7 @@ Webby works by combining the contents of a *page* with a *layout* to produce HTM
 
 Install Webby and try it out!
 
-<pre>
-sudo gem install -y webby
-</pre>
+  sudo gem install webby
 
 h2. Features
 
@@ -29,13 +27,11 @@ h2. But Wait! There's More!
 
 Webby has a great _autobuild_ feature that continuously generates HTML whenever the *pages* or *layouts* change. The HTML is served up via "heel":http://copiousfreetime.rubyforge.org/heel/, a static file webserver based on mongrel. Whenever you change a page, you can immediately see those changes without having to run any commands.
 
-<pre>
-$ rake autobuild
-heel --root output --daemonize
-[10:21:26]  INFO: starting autobuild (Ctrl-C to stop)
-[10:21:26]  INFO: creating output/index.html
-[10:22:57]  INFO: creating output/index.html
-</pre>
+  $ rake autobuild
+  heel --root output --daemonize
+  [10:21:26]  INFO: starting autobuild (Ctrl-C to stop)
+  [10:21:26]  INFO: creating output/index.html
+  [10:22:57]  INFO: creating output/index.html
 
 Webby is not limited to producing HTML. By no means! Do you ever get tired of repeating the same color code *#D3C4A2* in your CSS files? Webby can help. Need some customized JavaScript for your website. Webby can help. Anytime you find yourself repeating the same bit of text over and over, then you should be using Webby.
 

data/examples/webby/content/manual/index.txt

@@ -188,7 +188,7 @@ The following attributes are defined for each page in the content folder. These
 
 h4. Page Filters
 
-Filters operate on the content of a page by transforming the text of the content section according to the rules of the individual filter. Some filters transform simplified markup into true HTML syntax; examples of these are the Textile filter and the Markdown filter. Other filters create images from text in the page (Graphviz filter) or apply syntax highlighting to the text (CodeRay filter). All the filters are discussed in detail in the "Filters":#filters section of this document.
+Filters operate on the content of a page by transforming the text of the content section according to the rules of the individual filter. Some filters transform simplified markup into true HTML syntax; examples of these are the Textile filter and the Markdown filter. Other filters will rewrite URLs (basepath filter) or clean up the generated HTML (tidy filter). All the filters are discussed in detail in the "Filters":#filters section of this document.
 
 h3. Layouts
 
@@ -248,17 +248,20 @@ The title of this page is "<%= @page.title" %>".
 The title of this page is "<%= @page.title %>".
 </pre>
 
-p(column span-2). *Usage*:
-
-p(column span-13). Include "erb" in the filter list of the page or layout that contains ERB formatting.
-
-p(column span-2). *Options*:
-
-p(column span-13). none
+<div class="label">Usage</div>
+<div class="desc">
+Include "erb" in the filter list of the page or layout that contains ERB formatting.
+</div>
 
-p(column span-2). *Require*:
+<div class="label">Options</div>
+<div class="desc">
+none
+</div>
 
-p(column span-13). none
+<div class="label">Require</div>
+<div class="desc">
+none
+</div>
 
 h3. Textile
 
@@ -268,17 +271,20 @@ A complete textile reference is beyond the scope of this document. Please refer
 
 The textile filter will operate on all the contents of a page or layout. Given that fact, it should be one of the last filters applied to the page. You can prevent a section of the page from being processed by the textile filter by surrounding it with <code><notextile>&lt;notextile&gt;...&lt;/notextile&gt;</notextile></code> tags.
 
-p(column span-2). *Usage*:
-
-p(column span-13). Include "textile" in the filter list of the page or layout that contains Textile formatting
-
-p(column span-2). *Options*:
-
-p(column span-13). none
+<div class="label">Usage</div>
+<div class="desc">
+Include "textile" in the filter list of the page or layout that contains Textile formatting
+</div>
 
-p(column span-2). *Require*:
+<div class="label">Options</div>
+<div class="desc">
+none
+</div>
 
-p(column span-13). The @RedCloth@ gem must be installed on your system in order to use the textile filter.
+<div class="label">Require</div>
+<div class="desc">
+The *RedCloth* gem must be installed on your system in order to use the textile filter.
+</div>
 
 fn1(fn){clear:both}. Please don't ask. Why is very smart, he wrote the Ruby code that handles Textile markup, and the code is very solid. Enjoy the benefits of his work.
 
@@ -290,17 +296,20 @@ bq. The overriding design goal for Markdown's formatting syntax is to make it as
 
 The markdown filter will operate on all the contents of a page or layout. Given that fact, it should be one of the last filters applied to the page.
 
-p(column span-2). *Usage*:
-
-p(column span-13). Include "markdown" in the filter list of the page or layout that contains Markdown formatting.
-
-p(column span-2). *Options*:
-
-p(column span-13). none
+<div class="label">Usage</div>
+<div class="desc">
+Include "markdown" in the filter list of the page or layout that contains Markdown formatting.
+</div>
 
-p(column span-2). *Require*:
+<div class="label">Options</div>
+<div class="desc">
+none
+</div>
 
-p(column span-13). The @BlueCloth@ gem must be installed on your system in order to use the markdown filter.
+<div class="label">Require</div>
+<div class="desc">
+The *BlueCloth* gem must be installed on your system in order to use the markdown filter.
+</div>
 
 h3. HAML & SASS
 
@@ -310,95 +319,38 @@ bq. "HAML":http://haml.hamptoncatlin.com/docs/haml and "SASS":http://haml.hampto
 
 Both the haml and the sass filter will operate on all the contents of a page or layout. Given that fact, these should be one of the last filters applied to the page.
 
-p(column span-2). *Usage*:
-
-p(column span-13). Include "haml" in the filter list of the page or layout that contains HAML  formatting. Include "sass" in the filter list of the page that contains SASS formatting (this should be a CSS page).
-
-p(column span-2). *Options*:
-
-p(column span-13). Options are passed to the haml filter by setting the "haml_options" in the page meta-data  --  the hash of options defined under the "haml_options" attribute will be passed to the haml filter engine when it is run. Please refer to the HAML documentation for the list of available options.
-
-p(column span-13 prepend-2). Options are passed to the sass filter by setting the "sass_options" in the page meta-data  --  the hash of options defined under the "sass_options" attribute will be passed to the sass filter engine when it is run. Please refer to the SASS documentation for the list of available options.
-
-p(column span-2). *Require*:
-
-p(column span-13). The @haml@ gem must be installed on your system in order to use the haml filter or the sass filter.
-
-h3. CodeRay
-
-"CodeRay":http://coderay.rubychan.de/ is a Ruby library that provides syntax highlighting for various types of source code. The coderay filter takes a portion of the page contents and runs it through the CodeRay syntax highlighter, and pretty, colored XHTML is inserted into the page. The end result is that you can embed code into a page, and the coderay filter will convert that code into valid XHTML.
-
-Unlike the filters mentioned thus far, the coderay filter does not operate on the entire contents of a page. Only text between <code><notextile>&lt;coderay&gt;...&lt;/coderay&gt;</notextile></code> tags will be run through the coderay filter. The XHTML inserted into the page is contained in a @div@ element styled with a @CodeRay@ class.
-
-The coderay filter is controlled by setting attributes on the coderay tags in the content of the page. These attributes tell the CodeRay engine the language being parsed, to show line numbers, where to start numbering etc.
-
-<pre>
-<notextile>&lt;coderay lang="ruby" line_numbers="inline"&gt;
-class Object
-  def returning( r )
-    yield r if block_given?
-    r
-  end
-end
-&lt;/coderay&gt;</notextile>
-</pre>
-
-<% coderay :lang => "ruby", :line_numbers => "inline" do %>
-class Object
-  def returning( r )
-    yield r if block_given?
-    r
-  end
-end
-<% end %>
-
-p(column span-2). *Usage*:
-
-p(column span-13). Include "coderay" in the filter list of the page or layout that contains Markdown formatting. You will also need to link to the coderay stylesheet in any page containing coderay markup.
+<div class="label">Usage</div>
+<div class="desc">
+Include "haml" in the filter list of the page or layout that contains HAML  formatting. Include "sass" in the filter list of the page that contains SASS formatting (this should be a CSS page).
+</div>
 
-p(column span-2). *Options*:
+<div class="label">Options</div>
+<div class="desc">
 
-p(column span-13). The full list of "coderay options":/rdoc/classes/Webby/Filters/CodeRay.html can be found in the source documentation.
+Options are passed to the haml filter by setting the "haml_options" in the page meta-data  --  the hash of options defined under the "haml_options" attribute will be passed to the haml filter engine when it is run. Please refer to the HAML documentation for the list of available options.
 
-p(column span-2). *Require*:
+p(last). Options are passed to the sass filter by setting the "sass_options" in the page meta-data  --  the hash of options defined under the "sass_options" attribute will be passed to the sass filter engine when it is run. Please refer to the SASS documentation for the list of available options.
 
-p(column span-13). The @coderay@ gem must be installed on your system in order to use the coderay filter. Be sure to include the coderay stylesheet in your layout.
+</div>
 
-h3(#graphviz). Graphviz
+<div class="label">Require</div>
+<div class="desc">
+The @haml@ gem must be installed on your system in order to use the haml filter or the sass filter.
+</div>
 
-"Graphviz":http://www.graphviz.org/ is open source graph visualization software. Graph visualization is a way of representing structural information as diagrams of abstract graphs and networks. The Graphviz layout programs take descriptions of graphs in a simple text language, and make diagrams in several useful formats. The graphviz filter allows you to embed Graphviz scripts into a page and generate an image in the page.
+h3. Outline
 
-The graphviz filter does not operate on the entire contents of a page. Only text between <code><notextile>&lt;graphviz&gt;...&lt;/graphviz&gt;</notextile></code> tags will be run through the graphviz filter. The resulting image will be inserted into the page using a standard @img@ tag. If the Graphviz script contains references to URLs, then an image map will also be generated and inserted into the page. This results in an image with clickable regions.
+The Outline filter is used to insert outline numbering into HTML heading tags (h1, h2, h3, etc.) and to generate a table of contents based on the heading tags. The table of contents is inserted into the page at the location of the @<toc />@ tag. If there is no @<toc />@ tag, then a table of contents will not be created but outline numbering will still take place.
 
-The graphviz filter is controlled by setting attributes on the graphviz tags in the content of the page. These attributes tell the Graphviz renderer where to store the generated image, the type of image to create, etc.
+If a table of contents is desired without outline numbers being inserted into the heading tags, this can be specified in the attibutes of the @<toc />@ tag itself.
 
 <pre>
-<notextile>&lt;graphviz path="images" alt="hello world graph"&gt;
-digraph hello_world {
-  rankdir = LR;
-  Hello -> World;
-}
-&lt;/graphviz&gt;</notextile>
+<toc numbering="off" />
 </pre>
 
-<% graphviz :path => "images", :alt => "hello world graph" do %>
-digraph hello_world {
-  rankdir = LR;
-  Hello -> World;
-}
-<% end %>
-
-p(column span-2). *Usage*:
-
-p(column span-13). Include "graphviz" in the filter list of the page or layout that contains Graphviz scripts.
-
-p(column span-2). *Options*:
-
-p(column span-13). The full list of "graphviz options":/rdoc/classes/Webby/Filters/Graphviz.html can be found in the source documentation.
+This will generate a table of contents, but not insert outline numbering into the heading tags. The full list of "TOC attributes":/rdoc/classes/Webby/Filters/Outline.html can be found in the source documentation.
 
-p(column span-2). *Require*:
-
-p(column span-13). The Graphviz application must be installed on your system, and the Graphviz executables must be available on the path.
+The Outline filter will only work on valid HTML or XHTML pages. Therefore it should be used after any markup langauge filters (textile, markdown, etc.).
 
 h3. BasePath
 
@@ -406,26 +358,31 @@ The basepath filter is used to rewrite the base path location for all URLs in a
 
 The basepath filter only works on HTML/XHTML text, and therefore, it should be one of the last (if not the last) filter applied to your content. It is recommended to only include the basepath filter in your layout(s). The basepath filter should appear before the tidy filter.
 
-p(column span-2). *Usage*:
+<div class="label">Usage</div>
+<div class="desc">
 
-p(column span-13){margin-bottom:0}. Include "basepath" in the filter list of your layout(s). Specify the new base path to use either as a command line argument or as an option configured in the _Rakefile_. The base path specified on the command line takes precedence over the base path specified in the Rakefile.
+Include "basepath" in the filter list of your layout(s). Specify the new base path to use either as a command line argument or as an option configured in the _Rakefile_. The base path specified on the command line takes precedence over the base path specified in the Rakefile.
 
-<pre class="option">
+<pre style="margin-bottom:0">
 $ rake rebuild BASE='http://your.website.com/path/to/your/site'
 </pre>
+</div>
 
-p(column span-2). *Options*:
+<div class="label">Options</div>
+<div class="desc">
 
-p(column span-13){margin-bottom:0}. Options can be passed to the basepath filter by specifying them in the project _Rakefile_.
+Options can be passed to the basepath filter by specifying them in the project _Rakefile_.
 
-<pre class="option">
+<pre style="margin-bottom:0">
 SITE.xpaths << '/html/body//img[@usemap]'
 SITE.base = 'http://webby.rubyforge.org'
 </pre>
+</div>
 
-p(column span-2). *Require*:
-
-p(column span-13). none
+<div class="label">Require</div>
+<div class="desc">
+none
+</div>
 
 h3(#tidy). Tidy
 
@@ -435,21 +392,25 @@ bq. When editing HTML it's easy to make mistakes. Wouldn't it be nice if there w
 
 The tidy program only works on HTML/XHTML text, and therefore, tidy should be one of the last (if not the last) filter applied to your content. It is recommended to only include the tidy filter in your layout(s).
 
-p(column span-2). *Usage*:
-
-p(column span-13). Include "tidy" as the last item in the filter list of your layout(s).
+<div class="label">Usage</div>
+<div class="desc">
+Include "tidy" as the last item in the filter list of your layout(s).
+</div>
 
-p(column span-2). *Options*:
+<div class="label">Options</div>
+<div class="desc">
 
-p(column span-13){margin-bottom:0}. Options can be passed to the tidy program by specifying them in the project _Rakefile_. These are the command line options that will be passed to the tidy program when it is run.
+Options can be passed to the tidy program by specifying them in the project _Rakefile_. These are the command line options that will be passed to the tidy program when it is run.
 
-<pre class="option">
+<pre style="margin-bottom:0">
 SITE.tidy_options = '-indent -wrap 80'
 </pre>
+</div>
 
-p(column span-2). *Require*:
-
-p(column span-13). The HTML Tidy application must be installed on your system, and the @tidy@ executable must be available on the path.
+<div class="label">Require</div>
+<div class="desc">
+The HTML Tidy application must be installed on your system, and the @tidy@ executable must be available on the path.
+</div>
 
 h2. Using Rake
 

data/examples/webby/content/reference/index.txt

@@ -5,6 +5,9 @@ filter:
   - erb
   - textile
   - outline
+content_for_head: |
+ <link rel="stylesheet" href="/css/coderay.css" type="text/css" media="screen, projection" />
+ <link rel="stylesheet" href="/css/uv/twilight.css" type="text/css" media="screen, projection" />
 ---
 <div class="toc push-1">
 
@@ -26,32 +29,174 @@ h3. Attributes
 
 Attributes are defined in the meta-data section of pages and layouts.
 
-table(reference).
-| *destination* | Defines the path in the output directory where the rendered page should be stored. |
-| *dirty* | The dirty flag is used to determine whether the page should rendered or not. Normally this is automatically determined by the filter engine, but it can be overridden by setting this attribute. If the dirty flag is set to _true_ then the page will always be rendered. If the dirty flag is set to _false_ then the page will never be rendered. |
-| *extension* | Defines the extension that will be appended to the filename of the rendered page in the output folder. The extension is determined by looking at the following:
+<div class="label">destination</div>
+<div class="desc">
+Defines the path in the output directory where the rendered page should be stored.
+</div>
+
+<div class="label">dirty</div>
+<div class="desc">
+The dirty flag is used to determine whether the page should rendered or not. Normally this is automatically determined by the filter engine, but it can be overridden by setting this attribute. If the dirty flag is set to _true_ then the page will always be rendered. If the dirty flag is set to _false_ then the page will never be rendered.
+</div> 
+
+<div class="label">extension</div>
+<div class="desc">
+Defines the extension that will be appended to the filename of the rendered page in the output folder. The extension is determined by looking at the following:
+
 * the meta-data of the current page for an @extension@ attribute
 * the meta-data of layout file of the current page for an @extension@ attribute
-* the extension of this page file in the _content_ folder |
-| *filter* | Defines the list of filters that will be applied to the contents of this page. If left blank, then the default filter will be applied to the page contents. |
-| *layout* | Defines the layout that the page contents will be rendered into. The default layout will be used if this attribute is not defined. The value of @nil@ should be specified if the page should not be rendered into any layout. |
+* the extension of this page file in the _content_ folder
+
+</div>
+
+<div class="label">filter</div>
+<div class="desc">
+Defines the list of filters that will be applied to the contents of this page. If left blank, then the default filter will be applied to the page contents.
+</div>
+
+<div class="label">layout</div>
+<div class="desc">
+Defines the layout that the page contents will be rendered into. The default layout will be used if this attribute is not defined. The value of @nil@ should be specified if the page should not be rendered into any layout.
+</div>
 
 The following attributes are defined for each page in the content folder. These attributes cannot be changed in the page's meta-data section. However, they are available to the ERB filter when rendering the contents of a page.
 
-table(reference).
-| *path* | The full path to the file in the _content_ folder |
-| *dir* | The relative directory in the output folder where the page will be rendered |
-| *filename* | The name of the file in the _content_ folder excluding any path information |
-| *ext* | The extension of the file in the _content_ folder |
-| *mtime* | The modification time of the file in the _content_ folder |
-| *number* | Reserved variable used for multi-page content |
-| *url* | A URL suitable for creating a link to the page |
-| *render* | Returns the contents of the page as rendered by the Webby filter engine |
+<div class="label">path</div>
+<div class="desc">
+The full path to the file in the _content_ folder
+</div>
+
+<div class="label">dir</div>
+<div class="desc">
+The relative directory in the output folder where the page will be rendered
+</div>
+
+<div class="label">filename </div>
+<div class="desc">
+The name of the file in the _content_ folder excluding any path information and extension
+</div>
+
+<div class="label">ext</div>
+<div class="desc">
+The extension of the file in the _content_ folder
+</div>
+
+<div class="label">mtime</div>
+<div class="desc">
+The modification time of the file in the _content_ folder
+</div>
+
+<div class="label">number</div>
+<div class="desc">
+Reserved variable used for multi-page content
+</div>
+
+<div class="label">url</div>
+<div class="desc">
+A URL suitable for creating a link to the page
+</div>
+
+<div class="label">render</div>
+<div class="desc">
+Returns the contents of the page as rendered by the Webby filter engine
+</div>
 
 h3. Filters
 
 h3. ERB Variables & Methods
 
+h4. coderay
+
+The coderay method is used to generate syntax highlighting on a block of code. You will need to have the coderay gem installed on your system, and you will need to include the coderay CSS stylesheet in your pages for the syntax highlighting markup to take effect.
+
+The full list of "coderay options":/rdoc/classes/Webby/Helpers/CodeRayHelper.html can be found in the source documentation.
+
+<pre>
+<%% coderay :lang => 'ruby', :line_numbers => 'inline' do -%>
+class Object
+  def returning( r )
+    yield r if block_given?
+    r
+  end
+end
+<%% end -%>
+</pre>
+
+<% coderay :lang => "ruby", :line_numbers => "inline" do -%>
+class Object
+  def returning( r )
+    yield r if block_given?
+    r
+  end
+end
+<% end -%>
+
+
+h4. graphviz
+
+The graphviz method is used to convert a DOT script into an image and insert the image into the page. If the DOT script contains URL references, then an image map will also be generated. The resulting image will then have "clickable" regions that link to the URLs specified.
+
+"Graphviz":http://www.graphviz.org/ needs to be installed on your system in order to use the graphviz method. The full list of "graphviz options":/rdoc/classes/Webby/Helpers/GraphvizHelper.html can be found in the source documentation.
+
+<pre>
+<%% graphviz :path => 'images', :alt => 'hello world graph' do -%>
+digraph hello_world {
+  rankdir = LR;
+  Hello -> World;
+}
+<%% end -%>
+</pre>
+
+<% graphviz :path => "images", :alt => "hello world graph" do -%>
+digraph hello_world {
+  rankdir = LR;
+  Hello -> World;
+}
+<% end -%>
+
+
+h4. tex2img
+
+The tex2img method is used to convert a LaTeX script into an image and insert the image into the page. "LaTeX":http://www.latex-project.org/ and "ImageMagick":http://www.imagemagick.org/script/index.php need to be instaled on your system in order to use the tex2img maethod.
+
+The full list of "tex2img options":/rdoc/classes/Webby/Helpers/TexImgHelper.html can be found in the source documentation.
+
+<pre>
+<%% tex2img 'wave_eq', :path => 'images', :alt => 'wave equation' do -%>
+$\psi_{tot}(x,-t_0,r) = \frac{1}{(2\pi)^2} \int\!\!\!\int
+\tilde\Psi_{tot}\left(k_x,\frac{c}{2}\sqrt{k_x^2 + k_r^2},r=0\right)$
+<%% end -%>
+</pre>
+
+<% tex2img 'wave_eq', :path => 'images', :alt => 'wave equation' do -%>
+$\psi_{tot}(x,-t_0,r) = \frac{1}{(2\pi)^2} \int\!\!\!\int
+\tilde\Psi_{tot}\left(k_x,\frac{c}{2}\sqrt{k_x^2 + k_r^2},r=0\right)$
+<% end -%>
+
+
+h4. uv
+
+The uv method is used to generate syntax highlighting on a block of code. You will need to have the "Ultraviolet":http://ultraviolet.rubyforge.org/ gem installed on your system, and you will need to include the desired CSS stylesheet in your pages for the syntax highlighting markup to take effect.
+
+The full list of "ultraviolet options":/rdoc/classes/Webby/Helpers/UltraVioletHelper.html can be found in the source documentation.
+
+<pre>
+<%% uv :lang => "ruby", :line_numbers => true do -%>
+# Initializer for the class.
+def initialize( string )
+  @str = string
+end
+<%% end -%>
+</pre>
+
+<% uv :lang => "ruby", :line_numbers => true, :theme => 'twilight' do -%>
+# Initializer for the class.
+def initialize( string )
+  @str = string
+end
+<% end -%>
+
+
 h3. Rake Tasks
 
 h3. Site Defaults