webgen 0.5.2 → 0.5.3

data/doc/reference_metainfo.page

@@ -11,8 +11,26 @@ follows the same pattern:
 * Then the paths for which this item is valid are listed.
 * And at last follows a detailed description.
 
+
 {:miref: .meta-information-ref}
 
+### author
+
+{:miref}
+* String: `Thomas Leitner`
+* Any
+
+Sets the author of the path. This information is used, for example, by Webgen::SourceHandler::Feed.
+
+### author\_url
+
+{:miref}
+* String: `http://webgen.rubyforge.org`
+* Any where `author` is also set
+
+Sets the homepage of the author of the path. This information is used, for example, by
+Webgen::SourceHandler::Feed and normally only when `author` is also set.
+
 ### blocks
 
 {:miref}
@@ -23,6 +41,34 @@ Specifies the default names and additional options for the blocks. The special k
 to set default options for all blocks. Specific options for (or the name of) a block can be set by
 using the block index as key (numbering starts from one).
 
+### change\_freq
+
+{:miref}
+* String: `hourly`
+* Any
+
+Sets the change frequency of the page. This information is used, for example, by the sitemap source
+handler. You can use the following values for this key: `hourly, daily, weekly, monthly, yearly,
+never`.
+
+### created\_at
+
+{:miref}
+* Time: `2008-08-14 10:25:34 +02:00`
+* Any
+
+Sets the time when the path was created. This information cannot automatically be derived for paths
+provided by Webgen::Source::FileSystem, so this has to be set manually.
+
+### draft
+
+{:miref}
+* Boolean: `true`
+* Any
+
+If this meta information is set on a path, no node will be created from it. This is useful to add
+content to a website which should only be used later on.
+
 ### fragments\_in\_menu
 
 {:miref}
@@ -47,6 +93,15 @@ Sets the directory index path for the directory overriding the default value.
 
 Specifies if the path should appear in menus.
 
+### kind
+
+{:miref}
+* String: `page`
+* Any
+
+Specifies the kind of the path. Some source handlers define a default value for this meta
+information for nodes created by them.
+
 ### lang
 
 {:miref}
@@ -65,15 +120,26 @@ meta information needs to be set before a node gets created.
 Specifies additional attribute-value pairs (in form of a Hash) that should be added to a link to the
 path.
 
+### modified\_at
+
+{:miref}
+* Time: `2008-08-14 10:25:34 +02:00`
+* Any
+
+Sets the time when the path was last modified. This information is automatically set for paths
+provided by Webgen::Source::FileSystem but can be overridden by setting it manually. If not set to a
+valid time, the time when webgen is executed is used for this meta information.
+
 ### no\_output
 
 {:miref}
 * Boolean: `true`
 * Any
 
-Specifies whether an output path for this node gets written or not.
+Specifies whether an output path for the node should be written or not. This differs from `draft`
+that a node for the path gets created nonetheless.
 
-### omit_index_path
+### omit\_index\_path
 
 {:miref}
 * Boolean: `false`
@@ -97,6 +163,15 @@ in a sub-array, the whole sub-array is omitted, if the configuration option
 > only useful, for example, in the `paths` block of a meta information backing file.
 {.exclamation}
 
+### priority
+
+{:miref}
+* Float: `0.5`
+* Any
+
+Specifies the priority of this file in respect to all the other files of the website. This
+information is used, for example, by the sitemap source handler.
+
 ### routed\_title
 
 {:miref}

data/doc/sourcehandler/feed.page

@@ -0,0 +1,82 @@
+---
+title: Webgen::SourceHandler::Feed
+---
+## Description
+
+This source handler automatically generates an atom or RSS feed for a set of files from a file in
+[Webgen Page Format]({relocatable: ../webgen_page_format.html}) (the format which is also used for
+page files).
+
+The following meta information keys are supported:
+
+*   `entries` (MANDATORY)
+
+    A LCN pattern (or an array of LCN patterns) which specify the page files that should be
+    used. Other matched files are excluded from the list.
+
+*   `number_of_entries` (OPTIONAL)
+
+    The number of entries that should be included in the feed. Defaults to 10.
+
+*   `atom` (OPTIONAL)
+
+    An atom feed is generated if this key is set to `true`. Defaults to `true`.
+
+*   `rss` (OPTIONAL)
+
+    A RSS feed is generated if this key is set to `true`. Defaults to `true`.
+
+*   `site_url` (MANDATORY)
+
+    The base url of the website for which the feed is generated.
+
+*   `author` (MANDATORY)
+
+    Specifies the author of the feed.
+
+*   `author_url` (OPTIONAL)
+
+    Specifies the URL of the homepage of the author.
+
+*   `title` (MANDATORY)
+
+    The title of the feed.
+
+*   `description` (OPTIONAL)
+
+    A short description of the feed.
+
+*   `created_at` (OPTIONAL)
+
+    The time at which this feed was created. Defaults to the current time if not set.
+
+*   `icon` (OPTIONAL)
+
+    The absolute localized canonical name of the feed's icon image.
+
+The following meta information keys of page files are used if they are specified:
+
+*   `created_at`
+
+    The time at which the page file was created, used as the publication time.
+
+*   `modified_at`
+
+    The time at which the page file was last modified, used as the time at which this feed entry was
+    updated.
+
+*   `title`
+
+    The title of the page file, used as title of the feed entry.
+
+*   `author`
+
+    The name of the author of the page file, used as the author of the feed entry.
+
+*   `author_url`
+
+    The URL of the homepage of the author. Only used if the `author` meta information is also set.
+
+The default implementation supports the generation of atom and RSS feeds. You can override the
+default generation mechanism by adding an `atom_template` and/or `rss_template` block in the feed
+file which are then used to generate the atom or the RSS feed respectively.

data/doc/sourcehandler/metainfo.page

@@ -11,8 +11,9 @@ This source handler provides the ability to set meta information for any path. I
   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!
+  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

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
+{.exclamation}
+
+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/tag.template

@@ -8,14 +8,13 @@ The following tag names are registered for this tag class:
       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 (see [configuration option reference]({relocatable:
-reference_configuration.html}) for detailed information on the 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 %>` <%= temp ? '(' + temp + ')' : '' %>
+%>* [`<%= option %>`]({relocatable: reference_configuration.html#<%= option.tr('.', '') %>}) <%= temp ? '(' + temp + ')' : '' %>
 <%
   temp = nil
 end

data/doc/tag/breadcrumbtrail.page

@@ -2,8 +2,9 @@
 title: Webgen::Tag::BreadcrumbTrail
 used_options:
   - tag.breadcrumbtrail.separator
-  - tag.breadcrumbtrail.omit_last
   - tag.breadcrumbtrail.omit_index_path
+  - tag.breadcrumbtrail.start_level
+  - tag.breadcrumbtrail.end_level
 ---
 ## Description
 
@@ -11,6 +12,9 @@ The breadcrumb trail tag is used for displaying the hierarchy of the current pag
 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">
@@ -26,7 +30,11 @@ setting the meta information `omit_index_path` accordingly.
   <td>{breadcrumb_trail: {separator: " HELLO "}}</td>
 </tr>
 <tr>
-  <td>\{breadcrumb_trail: {omit_last: true}}</td>
-  <td>{breadcrumb_trail: {omit_last: true}}</td>
+  <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/menu.page

@@ -28,16 +28,18 @@ generating an in-page content menu of all the header sections.
 > 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 to the menu entries as well as a
-surrounding `div` tag. The `li` tags have special CSS classes set for styling. These CSS class names
-are as follows:
+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

data/doc/tag/sitemap.page

@@ -0,0 +1,31 @@
+---
+title: Webgen::Tag::Sitemap
+used_options:
+  - common.sitemap.honor_in_menu
+  - common.sitemap.any_lang
+  - common.sitemap.used_kinds
+---
+## Description
+
+This tag is used to display a site map of the current website. The used nodes can be customized by
+setting the above mentioned configuration options accordingly.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{sitemap: }</td>
+  <td>{sitemap: }</td>
+</tr>
+<tr>
+  <td>\{sitemap: {honor_in_menu: true}}</td>
+  <td>{sitemap: {honor_in_menu: true}}</td>
+</tr>
+<tr>
+  <td>\{sitemap: {honor_in_menu: true, used_kinds: []}}</td>
+  <td>{sitemap: {honor_in_menu: true, used_kinds: []}}</td>
+</tr>
+</table>

data/doc/upgrading.page

@@ -0,0 +1,67 @@
+---
+title: Upgrading from 0.4.x
+---
+# Upgrading
+
+Here are some helpers to make upgrading a webgen website from 0.4.x to 0.5.x more easy:
+
+* **Files in [Webgen Page Format]({relocatable: webgen_page_format.html})**: Since the format of
+  these files changed a little bit you may need to adapt all your files that use it, that is
+  primarily page and template files. The main change in the format was a different use of the block
+  separator line. Whereas before you would write
+
+      --- content, textile
+
+  for specifying the name of the block and its processor, you now can specify any number of
+  options. Two options are currently used by webgen: `name` and `pipeline`. So you could change the
+  name and the processing pipeline of a block by using a block start line like:
+
+      --- name:other pipeline:tags,maruku,blocks
+
+* **Block inclusion in template/page files**: The way how named blocks are included has
+  changed. This feature is now provided by the content processor [blocks]({relocatable:
+  contentprocessor/blocks.html}) instead of the tag `block`. This allows you to specify the point in
+  the processing pipeline when a block should be included. So you definitely need to update your
+  `default.template` file as well as any other page/template file where you used the `block` tag.
+
+* **Meta information names**: The names of some meta information keys have been changed. Meta
+  information names are not specified in camelCase anymore but with under\_scores. You can find a
+  complete list of supported meta information names in the [meta information
+  reference]({relocatable: reference_metainfo.html}). The most notable changes are:
+
+  * directoryName → routed\_title
+  * inMenu → in\_menu
+  * indexFile → index\_path
+  * omitIndexPath → omit\_index\_path
+  * outputNameStyle → output\_path\_style
+  * orderInfo → sort\_info
+
+* **website\_dir/metainfo.yaml**: This file is not supported anymore since webgen 0.5.x uses a more
+  flexible way for specifying meta information and virtual paths. You need to migrate its data to
+  `metainfo` and `virtual` files in the source directory. Have a look at the documentation of the
+  [metainfo source handler]({relocatable: sourcehandler/metainfo.html}) and the [virtual source
+  handler]({relocatable: sourcehandler/virtual.html}).
+
+* **Configuration file syntax**: The configuration file syntax as well as the names of the
+  configuration options and some defaults changed. For example, the default processing pipeline now
+  uses Maruku (a Markdown converter) as markup language processor. You can find an overview over all
+  available configuration options in the [configuration option reference]({relocatable:
+  reference_configuration.html}). Also have a look at the [configuration file
+  documentation]({relocatable: manual.html#website-configfile}) for more information on the syntax
+  of this file and the available helpers.
+
+* **Extensions development**: Since the complete core of webgen has changed you need to rewrite all
+  your plugins for the 0.5.x series. Howver, webgen has complete [API documentation]({relocatable:
+  api.html}) now which provides you with all needed information as well as examples on how to
+  implement source handlers, tags, content processors, ... If you still have any questions, don't
+  hesitate to contact me or write a mail to the mailing list!
+
+* **Not Implement Yet**: There are several features of the 0.4.x series which are currently not
+  implemented in the 0.5.x series:
+
+  * source handlers: gallery, sipttra
+  * tags: customvar (won't be ported), download, htmlmetainfo, news (won't be ported, superceded
+    by blogging support), wikilink
+  * misc: smiley replacer, html validators
+
+  If you need any of those you have to wait till they are implemented or port them on your on.

data/lib/webgen/cli/utils.rb

@@ -1,8 +1,8 @@
 require 'facets/ansicode'
 require 'rbconfig'
 
-Console::ANSICode.define_ansicolor_method(:lred, '1;31')
-Console::ANSICode.define_ansicolor_method(:lblue, '1;34')
+ANSICode.define_ansicolor_method(:lred, '1;31')
+ANSICode.define_ansicolor_method(:lblue, '1;34')
 
 module Webgen::CLI
 
@@ -18,8 +18,8 @@ module Webgen::CLI
 
     # Used for dynamically formatting the text (setting color, bold face, ...).
     def self.method_missing(id, text = nil)
-      if USE_ANSI_COLORS && Console::ANSICode.respond_to?(id)
-        Console::ANSICode.send(id, text.to_s)
+      if USE_ANSI_COLORS && ANSICode.respond_to?(id)
+        ANSICode.send(id, text.to_s)
       else
         text.to_s
       end