gettalong-webgen 0.5.4.20080929

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
+{.exclamation}
+
+[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,22 @@
+---
+title: Webgen::Tag::Langbar
+used_options:
+  - tag.langbar.separator
+  - tag.langbar.show_own_lang
+  - tag.langbar.show_single_lang
+---
+## Description
+
+This tag is used to display a list of links to translations of the page.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{langbar:}</td>
+  <td>{langbar:}</td>
+</tr>
+</table>

data/doc/tag/menu.page

@@ -0,0 +1,92 @@
+---
+title: Webgen::Tag::Menu
+used_options:
+  - tag.menu.used_nodes
+  - tag.menu.start_level
+  - tag.menu.min_levels
+  - tag.menu.max_levels
+  - tag.menu.show_current_subtree_only
+---
+## Description
+
+The menu tag builds a seemingly simple menu using HTML lists. However, it is very flexible due to
+its many options that let you decide every detail of the menu.
+
+> The menu is constructed using HTML lists with `ul` and `li` tags.  However, the menu normally
+> looks better if no discs are shown for the menu items (using the CSS directive `list-style-type:
+> none`).
+{.information}
+
+It uses the meta information `in_menu` and `sort_info` to determine which nodes should be in the
+menu and how they should be ordered. A separate menu tree is then created from all nodes for each
+language.
+
+By setting the option `tag.menu.used_nodes` to `fragments`, the menu tag can also be used for
+generating an in-page content menu of all the header sections.
+
+> When using the option value `files` for `tag.menu.used_nodes`, all nodes which are only in the
+> menu because they have fragment nodes beneath them are not included in the menu.
+{.exclamation}
+
+The rendered menu consists of `ul` and `li` tags and the links (or `span` elements) to the menu
+entries . The `li` tags have special CSS classes set for styling. These CSS class names are as
+follows:
+
+* `webgen-menu-levelNUMBER`: Set on all menu items and can be used to style specific menu levels
+  only. `NUMBER` is replaced with the actual menu level, so the first level menu entries will get a
+  `webgen-menu-level1` class.
+* `webgen-menu-submenu`: Set if the menu item contains sub menu items.
+* `webgen-menu-submenu-inhierarchy`: Set if the menu item contains sub menu items and it is in the
+  sub tree of the rendered node.
+* `webgen-menu-item-selected`: Set if the menu item corresponds to the rendered node.
+
+## "Static" Menus
+
+It is also possible to define a "static" menu or to augment the dynamic menu with static entries by
+using virtual files. They can be used to structure the menu the way you like it. This way it is also
+possible to add one page under two different headings:
+
+    features.en.html:
+      in_menu: true
+      title: Features
+      url: index.en.html#features
+
+    newdir:
+      sort_info: 2
+
+    newdir/new.en.html:
+      sort_info: 1
+      in_menu: true
+      url: ../features.en.html
+
+There is no need to specify `in_menu` for `newdir` since a page under the directory is in the
+menu. Also be aware that you need to set the language explicitly if a file should only appear in the
+menu for a specific language. Otherwise it appears in every menu. The `url` specifies the file that
+should be shown when clicked on the generated link.
+
+A completely "static" menu can be generated by only using virtual directories and files and not
+setting `in_menu` for any other node.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{menu: }</td>
+  <td>{menu:}</td>
+</tr>
+<tr>
+  <td>\{menu: {used_nodes: all}}</td>
+  <td>{menu: {used_nodes: all}}</td>
+</tr>
+<tr>
+  <td>\{menu: {used_nodes: files}}</td>
+  <td>{menu: {used_nodes: files}}</td>
+</tr>
+<tr>
+  <td>\{menu: {used_nodes: fragments}}</td>
+  <td>{menu: {used_nodes: fragments}}</td>
+</tr>
+</table>

data/doc/tag/metainfo.page

@@ -0,0 +1,29 @@
+---
+title: Webgen::Tag::Metainfo
+---
+## Description
+
+The meta tag is used to copy meta information verbatim. It is used as fallback when no other tag
+class for a specific tag name could not be found. For example, if you define a meta information with
+the key `revision`, you can put the tag `\{revision:}` into a block of a page file and the value
+gets substituted automatically.
+
+An every day usage example for the meta tag would be including the title of a page in the
+`head`-section of a HTML template or specifying the language of the HTML file by using the
+`\{lang:}` tag.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{title: }</td>
+  <td>{title:}</td>
+</tr>
+<tr>
+  <td>\{lang: }</td>
+  <td>{lang:}</td>
+</tr>
+</table>