webgen 0.5.0 → 0.5.1

data/doc/contentprocessor/sass.page

@@ -0,0 +1,32 @@
+---
+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]!
+The short name of the processor is `sass`!
+
+> 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

@@ -1,61 +1,73 @@
 ---
 title: Webgen::ContentProcessor::Tags
 ---
+## Description
 
-> TODO: This needs to be redone!
-{.exclamation}
+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. The short name of the processor is `tags`!
 
-### webgen Tags
+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
 
-TODO: remove this whole section since it depends on the processing pipeline??? or add a special
-section explaining the processing pipeline. ev. move this to the docu for the tags processor. or
-still better move this to its own reference section since this is a special webgen construct
+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.
 
-Tags are used to generate content. During processing of a file in WebPage Format so called 'tags'
-are replaced with dynamic content. For example, the menu you can see to the left was generated by a
-tag. This makes it easier to add or remove menu items. If the menu was not generated, you would have
-to change every file which uses the menu.
+For information on how to create such a tag classes have a look at the API documentation of the
+class Webgen::Tag::Base.
 
-#### Usage
 
-Tags are defined by a special markup code. A tag has the following structure:
+## Syntax for webgen Tags  {#syntax}
 
-    \{tagname: {parameters}}
+webgen tags are defined using a special markup construct which consists of the tag name, a parameter
+part and a body part.
 
-Every time a tag is found in a file, the registered plugin for the tag is called. The plugin returns
-a string which is put into the output file instead of the tag. The output a tag plugin can produce
-ranges from something simple to something complex. For example, the Tag/Meta plugin copies any
-additional meta information specified in the file verbatim into the correct place in the output
-file. And in contrast, the Tag/Menu plugin generates a whole menu tree.
+A tag can be specified in one of the following ways:
 
-If you want to use the markup code used for tags, you need to escape the tag with a backslash, like
-this:
+*   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: {parameters}}
+         \{tagname:}
 
-#### Parameters
+*   If a plugin has only one mandatory parameter, there is a short-cut syntax for specifying its
+    value.
 
-A tag can have zero or more parameters some of which are mandatory. You can see the supported
-parameters (and if they are mandatory) for each tag on the tag's plugin page. The default mandatory
-parameter can be specified in a special way, see the examples below. The format used for parsing the
-parameters is YAML.
+         \{tagname: value}
 
-Here some examples with tags and parameters:
+*   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.
 
-<table class="examples">
-<tr>
-  <th>Usage</th><th>Output</th>
-</tr>
-<tr>
-  <td>`\{tagname: }`</td>
-  <td>No parameters specified</td>
-</tr>
-<tr>
-  <td>`\{tagname: test.html}`</td>
-  <td>The default mandatory parameter is set to `test.html`. This form can only be used if there is only one mandatory parameter</td>
-</tr>
-<tr>
-  <td>`\{tagname: {param1: value1, param2: value2}}`</td>
-  <td>Two parameters (param1 and param2) specified</td>
-</tr>
-</table>
+         \{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

@@ -2,10 +2,21 @@
 title: Extensions
 in_menu: true
 ---
+# webgen Extensions
 
-> TODO: This needs to be filled with real docu.
-{.exclamation}
+webgen comes with many extensions that allow for rapid creation of static websites. The variety of
+the extensions allows you to use your tools of choice, for example, your preferred markup
+language. And if your choice is not available, you can write the extension for it yourself or make a
+feature request!
 
-# webgen Extensions
+Here is a list of all extensions:
 
-webgen comes with many extensions. Below is a list of all 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/reference_configuration.page

@@ -234,16 +234,237 @@ These options are not normally set in the configuration file but given directly
 respective tag classes. Therefore, all examples in this section show the use of these options in
 files in Webgen Page Format.
 
-*   ### `tag.relocatable.path`
+*   ### `tag.breadcrumbtrail.separator`
 
-    The default mandatory configuration option for Tag::Relocatable that specifies the path that
-    should be made relocatable.
+    Specifies the string that should be used as separator between indivdual parts of the breadcrumb
+    trail.
 
-    * Syntax: `PATH` where `PATH` is a (localized) canonical name.
+    * Syntax: `SEPARATOR` where `SEPARATOR` is a string (special HTML characters need to be properly
+      escaped)
 
     * Examples:
 
-          <a href="\{relocatable: ../features.html}">Some Path</a>
+          Breadcrumb trail with different separator: \{breadcrumb_trail: {separator: ' --- '}}
+
+
+*   ### `tag.breadcrumbtrail.omit_last`
+
+    Specifies that the last part of the breadcrumb trail should be omitted. If
+    `tag.breadcrumbtrail.omit_index_path` is also set to `true` and the last part is an index path,
+    only the index path is omitted (and not the parent of the index node too)!
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          Breadcrumb trail with last part omitted: \{breadcrumb_trail: {omit_last: true}}
+
+
+*   ### `tag.breadcrumbtrail.omit_index_path`
+
+    Specifies that the last part of the breadcrumb trail should be omitted if it is an index path.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          Breadcrumb trail with index path omitted: \{breadcrumb_trail: {omit_index_path: true}}
+
+
+*   ### `tag.coderay.lang`
+
+    Specifies the language that should be used for syntax highlighting.
+
+    * Syntax: `LANG` where `LANG` is one of <%= (require 'coderay'; CodeRay::Scanners.list.map {|n| '`' + n + '`'}.join(', ')) %>.
+
+    * Examples:
+
+          highlighting some ruby code \{coderay:: ruby}puts 5 + 5{coderay}
+
+
+*   ### `tag.coderay.process_body`
+
+    Specifies whether the body of the tag should be processed by the tags content processor first.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          wrapping in a span: \{coderay:: {lang: ruby, process_body: false}}puts 5 + 5{coderay}
+
+
+*   ### `tag.coderay.wrap`
+
+    Specifies in which HTML element the highlighted code should be wrapped.
+
+    * Syntax: `WRAP` where `WRAP` is either `div` or `span`
+
+    * Examples:
+
+          wrapping in a span: \{coderay:: {lang: ruby, wrap: span}}puts 5 + 5{coderay}
+
+
+*   ### `tag.coderay.line_numbers`
+
+    Specifies whether line numbers should be shown.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          not showing line numbers: \{coderay:: {lang: ruby, line_numbers: false}}puts 5 + 5{coderay}
+
+
+*   ### `tag.coderay.line_number_start`
+
+    Specifies the line number that should be used for the first line.
+
+    * Syntax: `NUMBER` where `NUMBER` is an integer value.
+
+    * Examples:
+
+          starting with line 4: \{coderay:: {lang: ruby, line_number_start: 4}}puts 5 + 5{coderay}
+
+
+*   ### `tag.coderay.bold_every`
+
+    Specifies the interval at which the line numbers should appear bold.
+
+    * Syntax: `NUMBER` where `NUMBER` is an integer value.
+
+    * Examples:
+
+          every other line bold: \{coderay:: {lang: ruby, bold_every: 2}}puts 5 + 5{coderay}
+
+
+*   ### `tag.coderay.tab_width`
+
+    Specifies the number of spaces that should be used to replace tabulator characters.
+
+    * Syntax: `NUMBER` where `NUMBER` is an integer value.
+
+    * Examples:
+
+          tabulator == 4 spaces: \{coderay:: {lang: ruby, tab_width: 4}}puts 5 + 5{coderay}
+
+
+*   ### `tag.date.format`
+
+    Specifies the format that should be used for formatting the current date. The format string
+    needs to be in a format supported by Ruby's method
+    [Time#strftime](http://www.ruby-doc.org/core/classes/Time.html).
+
+    * Syntax: `FORMAT` where `FORMAT` is a string.
+
+    * Examples:
+
+          very short date format: \{date: {format: '%Y-%m-%d'}}
+
+
+*   ### `tag.executecommand.command`
+
+    Specifies the command that should be executed. This option is the default mandatory option for
+    Webgen::Tag::ExecuteCommand.
+
+    * Syntax: `COMMAND` where `COMMAND` is the to-be-executed command.
+
+    * Examples:
+
+          executing a simple command \{exeucte_cmd: echo hallo}
+
+
+*   ### `tag.executecommand.process_output`
+
+    Specifies whether the output of the executed command should be further processed by the tags
+    content processor.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          executing command without further processing \{execute_cmd: {command: 'echo hallo', process_output: false}}
+
+
+*   ### `tag.executecommand.escape_html`
+
+    Specifies whether special HTML characters in the output of the executed command should be escaped.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          executing command, output not escaped \{execute_cmd: {command: 'echo hallo', escape_html: false}}
+
+
+*   ### `tag.includefile.filename`
+
+    Specifies the name of the file that should be included. The filename needs to be relative to the
+    website directory or an absolute path. This option is the default mandatory option for
+    Webgen::Tag::IncludeFile.
+
+    * Syntax: `FILENAME` where `FILENAME` is the name of a file
+
+    * Examples:
+
+          including a file \{include_file: my_file.txt}
+
+
+*   ### `tag.includefile.process_output`
+
+    Specifies whether the content of the file should be further processed by the tags content
+    processor.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          including a file without further processing \{include_file: {filename: my_file.txt, process_output: false}}
+
+
+*   ### `tag.includefile.escape_html`
+
+    Specifies whether special HTML characters in the content of the file should be escaped.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          including a file without escaping \{include_file: {filename: my_file.txt, escape_html: false}}
+
+
+*   ### `tag.langbar.separator`
+
+    Specifies the string that should be used as separator between the individual language parts.
+
+    * Syntax: `SEPARATOR` where `SEPARATOR` is a string (special HTML characters need to be properly
+      escaped)
+
+    * Examples:
+
+          Langbar with another separator: \{langbar: {separator: ' --- '}}
+
+
+*   ### `tag.langbar.show_own_lang`
+
+    Specifies whether the link to the language of the current page should be displayed.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          Langbar with current page's lang not shown: \{langbar: {show_own_lang: false}}
+
+
+*   ### `tag.langbar.show_single_lang`
+
+    Specifies whether the list should be displayed even if there are no translations of the page
+    (i.e. when there is only one page).
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          Langbar with single language not shown: \{langbar: {show_single_lang: false}}
 
 
 *   ### `tag.menu.used_nodes`
@@ -308,6 +529,22 @@ files in Webgen Page Format.
 
           Showing all subtrees: \{menu: {show_current_subtree_only: false}}
 
+
+*   ### `tag.relocatable.path`
+
+    The default mandatory configuration option for Tag::Relocatable that specifies the path that
+    should be made relocatable. This option is the default mandatory option for
+    Webgen::Tag::Relocatable.
+
+    * Syntax: `PATH` where `PATH` is a (localized) canonical name.
+
+    * Examples:
+
+          <a href="\{relocatable: ../features.html}">Some Path</a>
+
+
+
+
 ---
 
 ## Miscelleanous Configuration Options