thewoolleyman-webgen 0.5.8.20090419

data/doc/sourcehandler/metainfo.page

@@ -0,0 +1,41 @@
+---
+title: Webgen::SourceHandler::Metainfo
+---
+## Description
+
+This source handler provides the ability to set meta information for any path. It uses files in
+[Webgen Page Format]({relocatable: ../webgen_page_format.html}) which can have two special blocks:
+
+* `paths`: This block specifies meta information for paths and therefore this meta information is
+  applied before a node for a path is created. This can be used, for example, to change the output
+  path style. When specifying patterns, remember that the patterns are matched against paths!
+
+* `alcn`: This block specifies meta information for nodes and this meta information is applied
+  directly after a node has been created. When specifying patterns, remember that the patterns are
+  matched against absolute localized canonical names! So you always need to take the language part
+  into account, ie. `/index.html` won't match but `/index.en.html`.
+
+When no name is specified in the meta information file, the first block is assumed to be the `paths`
+block and the second block is assumed to be the `alcn` block. The format of the two blocks is the
+same: they need to be in YAML format and provide a hash with path patterns as keys and the
+to-be-assigned meta information as values. This is best showed in an example:
+
+    --- name:paths
+    /**/index.page:
+      output_path_style: [:parent, :cnbase, :ext, [., :lang]]
+
+    mypic.jpg:
+      in_menu: true
+    --- name:alcn
+    **/index.en.html:
+      in_menu: true
+
+All paths named `index.page` are assigned a new output path style. This has to be done in the
+`paths` block because otherwise it would have no effect. And the file `mypic.jpg` will show up in
+the menu. Notice, that the first form is specified as an absolute path pattern and the second
+not. If this meta information file lies in the root directory there is no difference between those
+two approaches. However, when it lies in a sub directory, the first form is still absolute but the
+second form is taken relative to the directory in which the meta information file is in.
+
+And last but not least, all nodes with a localized canonical name of `index.en.html` will show up in
+the menu (again, notice that the pattern is relative).

data/doc/sourcehandler/page.page

@@ -0,0 +1,14 @@
+---
+title: Webgen::SourceHandler::Page
+---
+## Description
+
+This source handler uses page files which are used to specify the actual content for the
+website. These files are written using [Webgen Page Format]({relocatable:
+../webgen_page_format.html}). Therefore they contain the content for the web page and, optionally,
+meta information.
+
+*In contrast* to other handled files, page files can never be unlocalized! If they have no language
+set, the default language specified using the configuration option `website.lang` is used. This
+means that for the default language set to English and a source path named `index.page`, the
+language meta information is automatically set to English.

data/doc/sourcehandler/sitemap.page

@@ -0,0 +1,46 @@
+---
+title: Webgen::SourceHandler::Sitemap
+---
+## Description
+
+This source handler automatically generates a sitemap based on the specification of
+[sitemaps.org](http://sitemaps.org) from a file in [Webgen Page Format]({relocatable:
+../webgen_page_format.html}).
+
+> This extension can only be used if you have installed the [builder](http://builder.rubyforge.org)
+> library. The preferred way to do this is via Rubygems:
+>
+>     gem install builder
+{.warning}
+
+The following meta information keys are supported:
+
+*   `site_url` (MANDATORY)
+
+    The base url of the website for which the sitemap is generated.
+
+*   `default_change_freq` (OPTIONAL)
+
+    The default change frequency of a file.
+
+*   `default_priority` (OPTIONAL)
+
+    The default priority of a file.
+
+You can also specify all common sitemap configuration options to customize the output of the source
+handler.
+
+The following meta information keys of files are used if they are specified:
+
+*   `modified_at`
+
+    The time at which the file was last modified, used as the time at which this feed entry was
+    updated.
+
+*   `change_freq`
+
+    The change frequency of the the file.
+
+*   `priority`
+
+    The priority of the file in respect to the other files.

data/doc/sourcehandler/template.page

@@ -0,0 +1,45 @@
+---
+title: Webgen::SourceHandler::Template
+---
+## Description
+
+The template handler processes the templates files. Templates, as the name already implies, normally
+specify the layout and the overall "picture" of a web page that is defined using a page file. These
+files are in [Webgen Page Format]({relocatable: ../webgen_page_format.html}) (the format which is
+also used for page files).
+
+The configuration option `sourcehandler.template.default_template` specifies the name of the default
+template which is used when no explicit template is set via the meta information `template`. webgen
+assumes that the default template is in the same directory as the page file. However, if it can not
+be found there, the parent directory is searched for it and so on. If a default template isn't found
+in the root directory, no template is used at all. This means that when you create a default
+template in the root directory, it is used as template for all page files that have no explicit
+template set.
+
+webgen also uses the concept of a template chain to support multiple templates for one page
+file. For example, assume that
+
+* the page file `index.page` has set the `template` meta information to `special.template`,
+* the template `special.template` has no `template` meta information set and
+* the page file `other.page` also has no `template` meta information set.
+
+The template chain for `index.page` would look like this
+
+    default.template <-- special.template <-- index.page
+
+whereas the template chain for `other.page` would look like this
+
+    default.template <-- index.page
+
+The first case also means that the `special.template` is nested in the `default.template`. This
+makes it possible, for example, to create a general website layout and then to create a special
+image gallery layout which uses the general one.
+
+To stop the template handler from further searching for a template, you explicitly need to set a
+null template for the page or template file:
+
+    template: ~
+
+This is useful if you want to have a different `default.template` in a sub directory which should
+provide a different look-and-feel for this subtree as the `default.template` in the root of the
+website.

data/doc/sourcehandler/virtual.page

@@ -0,0 +1,49 @@
+---
+title: Webgen::SourceHandler::Virtual
+---
+## Description
+
+This source handler uses files in [Webgen Page Format]({relocatable: ../webgen_page_format.html})
+which are used to specify virtual paths. Virtual paths don't really exist as source paths but are
+useful nonetheless. For example, they allow to include links to external content in automatically
+generated menus. They are never written out since they define no real content!
+
+The `content` block of the source path is used and its content needs to be a hash in YAML
+format. The keys are relative or absolute source paths names and the values meta information for
+them. Any meta information can be set on a virtual path but one meta information key is special:
+`url`. This meta information specifies, relative to the directory in which the source file is in,
+the output path for the virtual node. If no `url` meta information is specified, the source path
+itself is used as output path.
+
+Following is a sample virtual source files with explanations afterwards:
+
+    \--- !omap
+    - /documentation/:
+
+    - /documentation/index.html:
+        routed_title: Documentation
+
+    - download_and_installation.html:
+        in_menu: true
+        sort_info: 25
+        url: index.html#download__installation
+
+    - /documentation/api.html:
+        title: API Reference
+        url: http://myhost.com/api
+
+> The example does not use a normal hash but an ordered YAML map. This ensures that the virtual
+> nodes are created in the order they appear in the file.
+{.information}
+
+The first entry specifies that a directory `/documentation` should be created. The virtual file
+handler recognizes this because the given path ends in a slash!. Then a virtual index file for the
+virtual directory is created. This would be done, for example, when the documentation directory is
+created by an external program.
+
+The third entry specifies a virtual file that should in the menu and should have a certain sort
+information. When this virtual file is referenced, the path given by the `url` key is returned. This
+example shows how to make a single link to a fragment appear in automatically generated menus.
+
+And the fourth entry specifies another virtual file whose output path is an URL pointing to
+`http://myhost.com/api`.

data/doc/tag.template

@@ -0,0 +1,25 @@
+---
+template: extensions.template
+--- name:summary pipeline:erb,tags,maruku,blocks
+
+The following tag names are registered for this tag class:
+<%= context.website.config['contentprocessor.tags.map'].
+      select {|k,v| v == context.content_node['title']}.
+      map {|k,v| '`' + (k.kind_of?(Symbol) ? k.inspect : k.to_s) + '`'}.join(', ') %>
+
+<% if context.content_node['used_options'] %>
+This tag uses the following options:
+
+<%
+for option in context.content_node['used_options']
+  temp = 'mandatory' if !context.website.config.meta_info[option][:mandatory].nil?
+  temp += ' default' if context.website.config.meta_info[option][:mandatory] == 'default'
+%>* [`<%= option %>`]({relocatable: reference_configuration.html#<%= option.tr('.', '') %>}) <%= temp ? '(' + temp + ')' : '' %>
+<%
+  temp = nil
+end
+ %>
+
+<% end %>
+--- name:content
+<webgen:block name='content' />

data/doc/tag/breadcrumbtrail.page

@@ -0,0 +1,40 @@
+---
+title: Webgen::Tag::BreadcrumbTrail
+used_options:
+  - tag.breadcrumbtrail.separator
+  - tag.breadcrumbtrail.omit_index_path
+  - tag.breadcrumbtrail.start_level
+  - tag.breadcrumbtrail.end_level
+---
+## Description
+
+The breadcrumb trail tag is used for displaying the hierarchy of the current page. The behavior of
+the `tag.breadcrumbtrail.omit_index_path` option can be overridden for individual index paths by
+setting the meta information `omit_index_path` accordingly.
+
+The amount of levels shown can be customized by using the options `tag.breadcrumbtrail.start_level`
+and `tag.breadcrumbtrail.end_level`, see the examples below.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{breadcrumb_trail:}</td>
+  <td>{breadcrumb_trail:}</td>
+</tr>
+<tr>
+  <td>\{breadcrumb_trail: {separator: " HELLO "}}</td>
+  <td>{breadcrumb_trail: {separator: " HELLO "}}</td>
+</tr>
+<tr>
+  <td>\{breadcrumb_trail: {end_level: -2}}</td>
+  <td>{breadcrumb_trail: {end_level: -2}}</td>
+</tr>
+<tr>
+  <td>\{breadcrumb_trail: {start_level: 1}}</td>
+  <td>{breadcrumb_trail: {start_level: 1}}</td>
+</tr>
+</table>

data/doc/tag/coderay.page

@@ -0,0 +1,49 @@
+---
+title: Webgen::Tag::Coderay
+used_options:
+  - tag.coderay.lang
+  - tag.coderay.process_body
+  - tag.coderay.wrap
+  - tag.coderay.line_numbers
+  - tag.coderay.line_number_start
+  - tag.coderay.bold_every
+  - tag.coderay.tab_width
+---
+## Description
+
+This tag applies syntax highlighting to its body by using the [coderay][1] library which can be used
+to highlight many different languages (see `tag.coderay.lang` documentation). The body of the tag
+specifies what should be highlighted.
+
+> It is easy to include and highlight an entire file by combining this tag with the `include_file` tag:
+>
+>     \{coderay:: ruby}{include_file: test.rb}{coderay}
+{.information}
+
+> This extension is only available if you have installed the [coderay][1] library. The preferred
+> way to do this is via Rubygems:
+>
+>     gem install coderay
+{.warning}
+
+[1]: http://coderay.rubychan.de/ "The Coderay homepage"
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{coderay:: {lang: ruby, bold_every: 2}}{include_file: lib/webgen/version.rb}{coderay}</td>
+  <% if File.exists?(File.join(context.website.directory, 'lib/webgen/version.rb')) %>
+  <td>{coderay:: {lang: ruby, bold_every: 2}}{include_file: lib/webgen/version.rb}{coderay}</td>
+  <% else %>
+  <td>{coderay:: {lang: ruby, bold_every: 2}}{include_file: ../lib/webgen/version.rb}{coderay}</td>
+  <% end %>
+</tr>
+<tr>
+  <td>\{coderay:: {lang: ruby, wrap: span}}puts 5+5{coderay}</td>
+  <td><code>{coderay:: {lang: ruby, wrap: span}}puts 5+5{coderay}</code></td>
+</tr>
+</table>

data/doc/tag/date.page

@@ -0,0 +1,31 @@
+---
+title: Webgen::Tag::Date
+used_options:
+  - tag.date.format
+---
+## Description
+
+The date tag is used to display the current time in a specific format (the format of Ruby's inbuilt
+method [Time#strftime][1]). Have a look a the examples below to see some possible outputs.
+
+[1]: http://www.ruby-doc.org/core/classes/Time.html
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{date:}</td>
+  <td>{date:}</td>
+</tr>
+<tr>
+  <td>\{date: {format: '%A, %Y-%m-%d'}}</td>
+  <td>{date: {format: '%A, %Y-%m-%d'}}</td>
+</tr>
+<tr>
+  <td>\{date: {format: %x - %X}}</td>
+  <td>{date: {format: %x - %X}}</td>
+</tr>
+</table>

data/doc/tag/executecommand.page

@@ -0,0 +1,26 @@
+---
+title: Webgen::Tag::ExecuteCommand
+used_options:
+  - tag.executecommand.command
+  - tag.executecommand.process_output
+  - tag.executecommand.escape_html
+---
+## Description
+
+The execute command tag is used to include the output from a shell command.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{execute_cmd: uname -p}</td>
+  <td><pre>{execute_cmd: uname -p}</pre></td>
+</tr>
+<tr>
+  <td>\{execute_cmd: {command: 'ruby -v'}}</td>
+  <td><pre>{execute_cmd: {command: 'ruby -v'}}</pre></td>
+</tr>
+</table>

data/doc/tag/includefile.page

@@ -0,0 +1,32 @@
+---
+title: Webgen::Tag::IncludeFile
+used_options:
+  - tag.includefile.filename
+  - tag.includefile.process_output
+  - tag.includefile.escape_html
+---
+## Description
+
+The include file tag is used to include the content of a file. The filename needs to be specified
+relative to the website directory or an absolute filename.
+
+> By surrounding the include file tag with a syntax highlighting tag it is possible to highlight the
+> contents of a file.
+{.information}
+
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{include_file: {filename: AUTHORS, process_output: false}}</td>
+  <% if File.exists?(File.join(context.website.directory, 'AUTHORS')) %>
+  <td><pre>{include_file: {filename: AUTHORS, process_output: false}}</pre></td>
+  <% else %>
+  <td><pre>{include_file: {filename: ../AUTHORS, process_output: false}}</pre></td>
+  <% end %>
+</tr>
+</table>

data/doc/tag/langbar.page

@@ -0,0 +1,44 @@
+---
+title: Webgen::Tag::Langbar
+used_options:
+  - tag.langbar.separator
+  - tag.langbar.show_own_lang
+  - tag.langbar.show_single_lang
+  - tag.langbar.lang_names
+---
+## Description
+
+This tag is used to display a list of links to translations of the page. The text that is displayed
+can be set via the configuration option `tag.langbar.lang_names` (if not set, the language code is
+shown).
+
+The option `tag.langbar.process_output` is useful in conjunction with `tag.langbar.lang_names` to
+display language flags. For example, you can use the following entries in `config.yaml`:
+
+    tag.langbar.lang_names:
+      en: |
+        <img src="\{relocatable: img/flag_english.gif}" alt="English flag"/> English
+      de: |
+        <img src="\{relocatable: img/flag_german.gif}" alt="German flag"/> Deutsch
+
+    tag.langbar.process_output: true
+
+This assumes that the `langbar` tag is *only* used in `src/default.template` and the flag images are
+under `src/img/` (otherwise the `relocatable` tag can correctly find the paths). To work around
+this, you could specify the `lang_names` directly in the `langbar` tag.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{langbar:}</td>
+  <td>{langbar:}</td>
+</tr>
+<tr>
+  <td>\{langbar: {lang_names: {en: Englisch}}}</td>
+  <td>{langbar: {lang_names: {en: Englisch}}}</td>
+</tr>
+</table>