gettalong-webgen 0.5.4.20080929

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
+{.exclamation}
+
+[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/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
+{.exclamation}
+
+
+## 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
+{.exclamation}
+
+[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
+{.exclamation}
+
+[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
+{.exclamation}
+
+
+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
+{.exclamation}
+
+
+## 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}}`.

data/doc/extensions.metainfo

@@ -0,0 +1,29 @@
+contentprocessor/:
+  index_path: ~
+
+contentprocessor/*:
+  template: ../contentprocessor.template
+
+sourcehandler/:
+  index_path: ~
+
+sourcehandler/*:
+  template: ../sourcehandler.template
+
+tag/:
+  index_path: ~
+
+tag/*:
+  template: ../tag.template
+
+source/:
+  index_path: ~
+
+source/*:
+  template: ../extensions.template
+
+output/:
+  index_path: ~
+
+output/*:
+  template: ../extensions.template

data/doc/extensions.page

@@ -0,0 +1,16 @@
+---
+title: Extensions
+---
+# Extension Listing
+
+Following is a listing of all available extensions:
+
+<%
+pattern = /#{File.join(node.parent.absolute_lcn, '/')}(contentprocessor|output|source|sourcehandler|tag|)\//
+context.content_node.tree.node_access[:alcn].select {|alcn, n| alcn =~ pattern}.sort.each do |alcn, n|
+next if n.is_fragment?
+%>
+* <%= dest_node.link_to(n) %>
+<%
+end
+%>

data/doc/extensions.template

@@ -0,0 +1,17 @@
+--- pipeline:erb,tags,maruku,blocks
+[Back]({relocatable: extensions.html}) to the extension listing.
+{.backlink}
+
+# {title:}
+
+<% if (context[:chain][1] || context[:chain][0]).node_info[:page].blocks.has_key?('summary') %>
+## Summary
+
+<webgen:block name='summary' />
+
+<% end %>
+
+<webgen:block name='content' />
+
+[Back]({relocatable: extensions.html}) to the extension listing.
+{.backlink}

data/doc/faq.page

@@ -0,0 +1,214 @@
+---
+title: FAQ
+---
+# General Questions
+
+*   **webgen fails with an error after upgrading to a newer version - what to do?**
+
+    Delete the cache file and try again. The structure of the cache may not be valid anymore after a
+    version update. So it is always good to delete the cache after installing a new webgen version.
+
+*   **Why can I specify multiple blocks in a page/template file?**
+
+    This allows you to provide different content parts for one page. For example, image you have a
+    layout with a sidebar and you want to have page specific sidebar contents. The easiest way to
+    achieve that is to add a `sidebar` block to the page files that provide a page specific sidebar
+    content and conditionally include the `sidebar` block in your `default.template`, like this:
+
+        <%% if node.node_info[:page].blocks.has_key?('sidebar') %>
+          \<webgen:block name='sidebar' />
+        <%% end %>
+
+*   **What do I have to do to use the extensions?**
+
+    Nothing! Extensions are initialized and used automatically when needed. So, for example, if you
+    add a `my.feed` file to your website, the `Webgen::SourceHandler::Feed` extension gets
+    automatically used. The same is true for all types of extensions (source handler, content
+    processors, tags, ...).
+
+*   **Is there any way to add comments to my webgen website?**
+
+    Surely! There are several comment engines out there, however, the following two look very
+    promising:
+
+    * [JS-Kit](http://js-kit.com/comments/)
+    * [DISQUS](http://disqus.com)
+
+# How to ...
+
+This section provides quick answers and links to more information for the most commonly asked
+questions.
+
+### ... create a website?
+
+Use the `webgen` command to create the needed directories
+
+    webgen create -t project -s andreas07 my_site
+
+This will create a webgen website in the directory `my_site` using the specified template and style.
+
+### ... set configuration options?
+
+You can set any configuration options via the configuration file called `config.yaml`. For example,
+say you want to set the option `website.link_to_current_page` to `true`, then you would add the
+following to the configuration file:
+
+    website.link_to_current_page: true
+
+There is a second possibility for webgen tags: you can set the options directly in the tag
+definition, like this:
+
+    \{menu: {start_level: 2, min_levels: 3}}
+
+And if you want to have complete control over the configuration options, you can use the file
+`ext/init.rb`. For example, the following specifies that all page files should be in the menu by
+default:
+
+    config = Webgen::WebsiteAccess.website.config
+    config['sourcehandler.default_meta_info']['Webgen::SourceHandler::Page']['in_menu'] = true
+
+### ... change the default language?
+
+To use, for example, German as the default language, put the following into the configuration file:
+
+    website.lang: de
+
+The value needs to be a valid ISO-639-1/2 language code.
+
+### ... use a different processing pipeline for page files?
+
+If you want to change the processing pipeline (ie. how a page file get rendered), you need to add
+the following to your configuration file:
+
+    default_processing_pipeline:
+      Page: erb,tags,textile,blocks
+
+The `default_processing_pipeline` key is a special key which allows to directly set the processing
+pipeline (instead of going through all the meta information).
+
+If you just want to change the pipeline for one block, you can do it like this:
+
+    --- pipeline:erb,tags,textile,blocks
+    This is the content of the block
+
+### ... set the default meta information for files created by a specific source handler?
+
+Use the configuration file! For example, to change the meta information `in-menu` sothat it defaults
+to `true` for all page files use the following in your configuration file:
+
+    default_meta_info:
+      Page:
+        inMenu: true
+
+The key `default_meta_info` is a special key in the configuration file which allows to update the
+default meta information for a source handler and not to substitute it.
+
+### ... ignore files in the source directory?
+
+This can be done using the `sourcehandler.ignore` configuration options. For example, to ignore all
+files starting with `core`, you would put the following in the configuration file:
+
+    sourcehandler.ignore: [**/core*]
+
+The value of this option has to be an array of path patterns. Be aware that this overwrites the
+default setting.
+
+### ... change the output name style?
+
+You have several options of varying granularity:
+
+* Set the meta information `output_path_style` for all source handlers:
+
+      default_meta_info:
+        :all:
+          output_path_style: [:parent, :cnbase, [., :lang], :ext]
+
+* Set the meta information `output_path_style` for a specific source handler to only change the
+  output paths of this source handler (the page source handler in the following example):
+
+      default_meta_info:
+        Page:
+          output_path_style: [:parent, :cnbase, [., :lang], :ext]
+
+* Add the meta information `output_path_style` to a single file via, for example, a meta information
+  backing file.
+
+### ... modify the template chain?
+
+To stop the template chain at a specific template or even at the page file itself, specify a
+null template in the meta information, like this:
+
+    template: ~
+
+To nest templates, you just need to specify the template, in which this template/page file should be
+nested, in the meta information:
+
+    template: my_special.template
+
+Be aware that if no `template` meta information is specified for a page or template file, the
+template handler automatically searches for a default template in the directory and the parent
+directories of the file!
+
+### ... localize a directory name?
+
+Just set the `routed_title` meta information on the correct localized directory index files.
+
+### ... provide additional attributes on links to a file?
+
+You can specify additional attributes for a link to a file by using the `link_attrs` meta
+information. Take the following page file:
+
+    ---
+    title: Tutorial
+    in_menu: true
+    link_attrs:
+      title: This is a rather large tutorial
+      accesskey: D
+      tabindex: 5
+    ---
+    Yippieh, this is my tutorial!
+
+When a link to this page is created, the specified attributes get additionally set on the link!
+
+### ... add page specific sidebar content?
+
+There are many ways to accomplish this, I will show only one way here using blocks. Add the
+following to the sidebar part in your `default.template` (ensure that you haven't disabled `erb` in
+the processing pipeline):
+
+    <%% if node.node_info[:page].blocks.has_key?('sidebar') %>
+      \<webgen:block name='sidebar' />
+    <%% end %>
+
+This will include the contents of the block `sidebar` in the sidebar if such a block exists for a
+page. You can then add a sidebar block to each page file which needs it. Following is such a sample
+page file:
+
+    This is the main content block
+    --- name:sidebar
+    This is the sidebar block and everything in here goes to the sidebar!
+
+### ... create XML output?
+
+This can be achieved manually (by removing any markup processor in the processing pipeline of the
+page file and then directly creating the XML elements) or by changing the processing pipeline to
+include content processor `builder` which provides an easy way of programmatically creating an XML
+compliant file. More information on this can be found on the documentation page of
+Webgen::ContentProcessor::Builder!
+
+### ... create a static menu?
+
+You can use virtual nodes to define virtually any menu structure you like, including things like
+having menu entries that point to the same page and links to external pages.
+
+### ... use short menu title?
+
+You can use a special of the meta information `link_attrs` to achieve that. Just use the following
+in the meta information block of the page file for which you want a short menu title:
+
+    link_attrs:
+      :link_text: Short title
+
+> Be aware that this changes not only how the page appears in a menu but also how it appears in
+> breadcrumb trails and other links generated by webgen.
+{.exclamation}