thewoolleyman-webgen 0.5.8.20090419

data/doc/contentprocessor/erb.page

@@ -0,0 +1,59 @@
+---
+title: Webgen::ContentProcessor::Erb
+---
+## Description
+
+This processer uses ERB (embedded Ruby) to process content. For detailed information about ERB have
+a look at its documentation by executing `ri ERB` or the [ruby documentation
+site](http://www.ruby-doc.org/)!
+
+You can use the following special objects in your ERB code:
+
+* `website`: Provides access to the `Webgen::Website` object which can be used to access all aspects
+  of the currently rendered website.
+
+* `context`: This object provides the whole rendering context, the following objects are just for
+  backwards compatibility.
+
+* `ref_node` (or `context.ref_node`): The reference node which is the source of the ERB code that is
+  executed. Should be used, for example, for resolving paths.
+
+* `node` (or `context.content_node`): The node that gets currently rendered. Should be used for
+  retrieving meta information.
+
+* `dest_node` (or `context.dest_node`): The node in which the result gets inserted. Should be used
+  for calculating relative paths.
+
+Here is a small usage example. The following put in a page file
+
+    Counting 5 items dynamically:
+    <%% for i in 1..5 %>
+      * item <%%= i %>
+    <%% end %>
+
+    Outputting all meta information:
+    <%% node.meta_info.each do |k,v| %>
+      * <%%= k %> = <%%= v %>
+    <%% end %>
+
+... will give the result:
+
+    Counting 5 items dynamically:
+    <% for i in 1..5 %>
+      * item <%= i %>
+    <% end %>
+
+    Outputting all meta information:
+    <% node.meta_info.each do |k,v| %>
+      * <%= k %> = <%= v %>
+    <% end %>
+
+The second line shows the first form of the ERB tags which executes Ruby code but does not output
+anything: it just starts a `for` loop. On the third line the second form of ERB tags is used to
+output the result of the Ruby code (note the equation sign!). And the fourth line completes the
+`for` loop by adding the needed `end` keyword.
+
+> You may need to ensure that the ERB start and end tags are not processed by the content
+> processor. For example, when using the RedCloth content processor, you may need to surround the
+> ERB code with `<textile>` tags!
+{.important}

data/doc/contentprocessor/erubis.page

@@ -0,0 +1,46 @@
+---
+title: Webgen::ContentProcessor::Erubis
+---
+## Description
+
+This processor uses the [Erubis][1] library to process embedded Ruby statements. Erubis is quite a
+bit faster than the standard ERB library that is shipped with Ruby and provides many other useful
+options.
+
+> This extension is only available if you have installed the [erubis][1] library. The preferred
+> way to do this is via Rubygems:
+>
+>     gem install erubis
+{.warning}
+
+[1]: http://www.kuwata-lab.com/erubis/ "Erubis Homepage"
+
+You can use some special objects provided by webgen in your embedded Ruby code. These are the same
+objects that are available to the `erb` processor, have a look at its [documentation
+page]({relocatable: erb.html}).
+
+The default mode of Erubis works like ERB. So everyting said on the [erb page]({relocatable:
+erb.html}) is also true for Erubis. However, you can customize how this processor works by using the
+following configuration options:
+
+* `contentprocessor.erubis.use_pi`: Use processing instructions instead of ERB like
+  instructions. Normally you use statements like `<%% result = some_method_call(opts) %>` or `<%%=
+  context.content_node.absolute_lcn %>` in your content. When setting this option to `true`, you can
+  use XML processing instructions instead, like this: `<?rb result = some_method_call(opts) ?>` or
+  `@{context.content_node.absolute_lcn}@`.
+
+* `contentprocessor.erubis.options`: This is hash which is passed to the Erubis interpreter and
+  which can be used to set additional options.
+
+For more information on the additional options or on how to use the processing instructions mode of
+Erubis, have a look at the [Erubis User Guide](http://www.kuwata-lab.com/erubis/users-guide.html)!
+
+You can also use block options to modify the behavior of Erubis. The block option `erubis_use_pi` is
+used instead of the configuration option `contentprocessor.erubis.use_pi` and all other block
+options starting with `erubis_` are added the options hash that is passed to the Erubis
+interpreter. For example, the following page tells the Erubis interpreter to use the processing
+instructions mode and to trim spaces:
+
+    --- erubis_use_pi:true erubis_trim:true
+    Here are the numbers from 1 to 5:
+    <?rb for i in [1,2,3,4,5] ?>@{i}@<?rb end ?>

data/doc/contentprocessor/fragments.page

@@ -0,0 +1,25 @@
+---
+title: Webgen::ContentProcessor::Fragments
+---
+## Description
+
+This processor generates nested fragment nodes from all headers `h1` to `h6` which have an `id`
+attribute set.
+
+> This is only done for the block named `content` or if no block is associated with the given render
+> context! This is to ensure that fragment nodes are not created from multiple block of one page
+> file. So this content processor has no effect when used in the pipeline of blocks except if the
+> block is named `content`.
+{.warning}
+
+The default markup language Maruku automatically generates an `id` attribute for all headers. If you
+use another markup language or plain old HTML, you might need to set the `id` attributes by hand.
+
+> The reason why only header tags with an `id` attribute are used is that only those can be
+> referenced and linked to later.
+{.information}
+
+The generated fragment nodes can be used like any other node. So you can link to them and use them
+in a menu. Concerning the menu, there is a setting for the `tag.menu.used_nodes` option called
+`fragments` which only uses the fragment node of the current page to generate a menu. This allows to
+generate a nice overview of the page.

data/doc/contentprocessor/haml.page

@@ -0,0 +1,47 @@
+---
+title: Webgen::ContentProcessor::Haml
+---
+## Description
+
+This processor converts the content, which is assumed to be in the Haml markup language, to valid
+XHTML by using the Haml library. For detailed information about Haml have a look at the [Haml
+Homepage][1]!
+
+You can use some special objects provided by webgen in your Haml markup. These are the same objects
+that are available to the `erb` processor, have a look at its [documentation page]({relocatable:
+erb.html}).
+
+> This extension is only available if you have installed the [haml][1] library. The preferred way to
+> do this is via Rubygems:
+>
+>     gem install haml
+{.warning}
+
+
+## Example
+
+Here is a short sample of a text in Haml markup:
+
+    %h1#myid This a h1 header
+
+    %p
+      You can just write
+      %b your
+      paragraphs here and
+      %a{:href => 'http://someurl.com'} link
+      them below. This is a
+      %strong nice
+      format!
+
+    %blockquote.information
+      Citations are easy too.
+      Really. And you can assign them attributes.
+
+    %ul
+      %li Lists
+      %li aren't
+      %li difficult
+      %li either.
+
+
+[1]: http://haml.hamptoncatlin.com/

data/doc/contentprocessor/maruku.page

@@ -0,0 +1,41 @@
+---
+title: Webgen::ContentProcessor::Maruku
+---
+## Description
+
+This processor converts the content, which is assumed to be in Markdown markup, to HTML by using the
+Maruku library. Maruku is a Markdown processor which supports a superset of Markdown, including
+support for assigning ids and classes to every element, support for Markdown inside HTML elements
+and footnotes.
+
+For detailed information about Maruku have a look at the [Maruku Homepage][1]. There you will find
+information about the general Markdown syntax as well as information about the extras added by
+Maruku.
+
+> Maruku is the default markup content processor for webgen as its markup syntax is easy to learn
+> and nice to look at. Give it a try!
+{.info}
+
+Example
+-------
+
+Here is a short sample of a text in Markdown+Extras markup:
+
+    # This a h1 header    {#myid}
+
+    You can just write *your* paragraphs here and
+    [link][1] them below. This is **nice** format!
+
+    > Citations are easy too.
+    > Really. And you can assign them attributes.
+    {.information}
+
+    * Lists
+    * aren't
+    * difficult
+    * either.
+
+    [1]: http://someurl.com
+
+
+[1]: http://maruku.rubyforge.org/

data/doc/contentprocessor/rdiscount.page

@@ -0,0 +1,37 @@
+---
+title: Webgen::ContentProcessor::RDiscount
+---
+## Description
+
+This processor converts the content, which is assumed to be in Markdown markup, to HTML by using the
+RDiscount library. This library is based on the C based discount library which provides very fast
+Markdown processing. However, this processor does not support advanced features like the [Maruku
+Markdown processor]({relocatable: maruku.html}) does.
+
+> This extension is only available if you have installed the [rdiscount][1] library. The preferred
+> way to do this is via Rubygems:
+>
+>     gem install rdiscount
+{.warning}
+
+[1]: http://github.com/rtomayko/rdiscount
+
+Example
+-------
+
+Here is a short sample of a text in Markdown markup:
+
+    # This a h1 header
+
+    You can just write *your* paragraphs here and
+    [link][1] them below. This is **nice** format!
+
+    > Citations are easy too.
+    > Really. And you can assign them attributes.
+
+    * Lists
+    * aren't
+    * difficult
+    * either.
+
+    [1]: http://someurl.com

data/doc/contentprocessor/rdoc.page

@@ -0,0 +1,36 @@
+---
+title: Webgen::ContentProcessor::RDoc
+---
+## Description
+
+This content processors converts content written in RDoc markup (the default documentation format
+for Ruby source files, [reference][1]) to HTML.
+
+> This extension needs the [new RDoc implementation][2] and is not compatible with the
+> implementation included in the Ruby distribution. The preferred way to install the new
+> implementation is via Rubygems:
+>
+>     gem install rdoc
+{.warning}
+
+[1]: http://rdoc.rubyforge.org/rdoc/ "RDoc Reference"
+[2]: http://rubyforge.org/projects/rdoc/ "New RDoc implementation"
+
+## Example
+
+Here is a short sample of a text in RDoc markup:
+
+    = This a h1 header
+
+    You can just write *your* paragraphs here and <a href="http://someurl.com">link</a> them below.
+    This is also a _nice_ format!
+
+    <blockquote class='information>
+    Citations are easy too.
+    Really. And you can assign them attributes.
+    </blockquote>
+
+    * Lists
+    * aren't
+    * difficult
+    * either.

data/doc/contentprocessor/redcloth.page

@@ -0,0 +1,39 @@
+---
+title: Webgen::ContentProcessor::RedCloth
+---
+## Description
+
+This processor converts the content, which is assumed to be in Textile markup, to HTML by using the
+RedCloth library. For detailed information about Textile have a look at the [Textile Reference][1]!
+
+> This extension is only available if you have installed the [redcloth][2] library. The preferred
+> way to do this is via Rubygems:
+>
+>     gem install RedCloth
+{.warning}
+
+
+Example
+-------
+
+Here is a short sample of a text in Textile markup:
+
+    h1(#myid). This a h1 header
+
+    You can just write *your* paragraphs here and
+    "link":http://someurl.com them below. This is also a
+    **nice** format!
+
+    <blockquote class='information>
+    Citations are easy too.
+    Really. And you can assign them attributes.
+    </blockquote>
+
+    * Lists
+    * aren't
+    * difficult
+    * either.
+
+
+[1]: http://hobix.com/textile/
+[2]: http://whytheluckystiff.net/ruby/redcloth/

data/doc/contentprocessor/sass.page

@@ -0,0 +1,31 @@
+---
+title: Webgen::ContentProcessor::Sass
+---
+## Description
+
+This processor converts the content, which is assumed to be in the Sass meta language, to valid CSS
+using the Haml library. For detailed information about Sass have a look at the [Haml Homepage][1]!
+
+> This extension is only available if you have installed the [haml][1] library. The preferred way to
+> do this is via Rubygems:
+>
+>     gem install haml
+{.warning}
+
+
+## Example
+
+Here is a short sample of a text in the Sass meta language:
+
+    #main
+      :width 90%
+      p
+        :border-style solid
+        :border-color #00f
+        a
+          :font-weight bold
+        a:hover
+          :text-decoration underline
+
+
+[1]: http://haml.hamptoncatlin.com/

data/doc/contentprocessor/tags.page

@@ -0,0 +1,73 @@
+---
+title: Webgen::ContentProcessor::Tags
+---
+## Description
+
+This processor provides an easy method for adding dynamic content to web pages. It uses so called
+webgen tags to replace special markup constructs with dynamic content. This system allows webgen to
+generate menus and breadcrumb trails, include files and much more. webgen already comes with many
+tags that handle simple things, like including a file, to advanced things, like generating a
+menu.
+
+Each webgen tag is defined using a unique name and handled by a tag class. A tag can have zero or
+more parameters some of which are mandatory. Tag parameters map directly to configuration options,
+so you can temporarily (for the rendering of the tag) override some configuration options. Since
+normally only the special configuration options for the tag itself are used, a shorter form can be
+used for them: just remove the tag class name part (without the `Webgen::` prefix) from the
+configuration option. For example, the relocatable tag handled by Webgen::Tag::Relocatable specifies
+the configuration option `tag.relocatable.path` and the short name for it (when used as parameter
+for the relocatable tag, not when used for other tags) is therefore just `path`. The supported
+parameters (and if they are mandatory) are listed for each tag on its documentation page. The
+default mandatory parameter can be specified in a special way, see the following section. When spe
+
+When content is parsed and a webgen tag is encountered, the registered class for this tag is
+called. If no class for a tag exists there are two possibilities: if a default tag class exists,
+then this default class is called. Otherwise an error is raised.
+
+For information on how to create such a tag classes have a look at the API documentation of the
+class Webgen::Tag::Base.
+
+
+## Syntax for webgen Tags  {#syntax}
+
+webgen tags are defined using a special markup construct which consists of the tag name, a parameter
+part and a body part.
+
+A tag can be specified in one of the following ways:
+
+*   The simplest form of a webgen tag just consists of the tag name itself. This form can only be used
+    if the tag does not have any mandatory parameters.
+
+         \{tagname:}
+
+*   If a plugin has only one mandatory parameter, there is a short-cut syntax for specifying its
+    value.
+
+         \{tagname: value}
+
+*   If a plugin has more than one mandatory parameter or if some default parameter values should be
+    overwritten, one needs to use the following general form.
+
+         \{tagname: {option: value, other_option: other_value}}
+
+    > The parameters defined using this syntax are actually specified using a hash in YAML
+    > markup. So you can use any valid YAML construct in the YAML hash definition.
+    {.information}
+
+*   Additionally, you can use a body part with any of the above forms. To specify that the tag has a
+    body part, just use two colons instead of one after the tag name and don't forget the closing
+    tag.
+
+         \{tagname::}Here comes the body{tagname}
+
+    Although you can always specify a body part, only some tags actually use it - the documentation
+    for each tag states if the body part is used or not.
+
+Sometimes you need to specify something which looks like a webgen tag but should not be processed
+like one. In such cases, you need to escape the tag with a backslash, like this:
+
+    \\\{tagname: {key:value}}
+
+Another solution to this is to specify a general prefix for all webgen tags using the configuration
+option `contentprocessor.tags.prefix`. Let's imagine that you set the prefix to `webgen:`; then this
+content processor will only process webgen tags of the form `\{webgen:tagname: {key: value}}`.