gettalong-webgen 0.5.4.20080929

data/doc/tag/relocatable.page

@@ -0,0 +1,38 @@
+---
+title: Webgen::Tag::Relocatable
+used_options:
+  - tag.relocatable.path
+---
+## Description
+
+This tag ensures that the relative path to the specified path is always correct. 
+
+When the tag is used, it changes the directory part of the supplied path name to a relative path to
+the destination and is most often used in template files. A relocatable tag looks like this:
+`\{relocatable: default.css}`. If this was put into a template and the template was used by a file
+in a subdirectory, then the `relocatable` tag would put `../default.css` into the output file; thus
+ensuring that the relative path to file is valid.
+
+> You can only use the `relocatable` tag with paths that are handled by webgen. If you want to
+> handle paths that are not normally handled by webgen, create a virtual path for them.
+{.exclamation}
+
+If the specified path is an absolute URL (like `http://webgen.rubyforge.org`), it will just return
+it. And if you specify an URL fragment, this fragment has to exist. If you don't want to resolve a
+fragment, just don't specify it in the tag but afterwards!
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{relocatable: /default.css}</td>
+  <td>{relocatable: /default.css}</td>
+</tr>
+<tr>
+  <td>\{relocatable: ../}</td>
+  <td>{relocatable: ../}</td>
+</tr>
+</table>

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,139 @@
+---
+title: Upgrading from 0.4.x
+---
+# Upgrading
+
+Here are step-by-step instructions on how to update your webgen website from 0.4.x to 0.5.x:
+
+* **Update the configuration file `config.yaml`**
+
+  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 instead of Textile. 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.
+
+  * Name changes: All configuration options now use underscores to separate word parts instead of
+    camelCase.
+  * Syntax changes: The configuration options are not specific to a certain extension anymore. You
+    now need the full configuration option name to specify it. So instead of
+
+        Tag/Menu:
+          maxLevels: 4
+
+    you now use
+
+        tag.menu.max_levels: 4
+
+* **Convert your `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}).
+
+* **Update meta information names and values**
+
+  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
+
+  Also be aware that the syntax of some meta information keys has changed. For example, all meta
+  information keys that took a source path name, e.g. `index_path`, now take an localized canonical
+  name.
+
+  You need to change the names/value in all places where meta information can be specified:
+
+  * `metainfo` files
+  * `virtual` files
+  * page and template files
+
+* **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 are primarily page and template files. The main change in the format was a different use
+  of the block start 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.
+
+  So you need to look for `\{block: content}` tags (where `content` is just a place holder for the
+  name of the block that should be included) and replace them with `<webgen:block name='content'
+  />`.
+
+* **Update tag names and parameters**
+
+  Since the names of the configuration options changed (from using camelCase to using under\_scores)
+  and some tags have different options, you need to change all tag parameters. You may also need to
+  convert old tag names to new ones (same reason: camelCase to under\_score), for example,
+  `includeFile` is now `include_file`.
+
+* **Update your ERB code**
+
+  If you have any ERB code in your template or page files you will most certainly have to adapt them
+  to the new [API]({relocatable: api.html}). One thing that has been used often is the check if a
+  page file has a certain block:
+
+      <%% if node.node_info[:page_data].blocks.has_key?('NAME') %>
+      ...
+      <%% end %>
+
+  This needs to be changed into the following:
+
+      <%% if context.content_node.node_info[:page].blocks.has_key?('NAME') %>
+      ...
+      <%% end %>
+
+* **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!
+
+* **Running webgen on the converted website**
+
+  You now can run webgen 0.5.x on the converted website. This helps in ironing out the remaining
+  errors, for example:
+
+  * If you have forgotten to change a block start line, you will get an application error and the
+    name of the file where the error occured.
+
+  * If you have overlooked changing a tag parameter, you will find `ERROR` and `WARN` lines in the
+    log output showing you what still needs to be changed.
+
+* **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), resource, wikilink
+  * misc: smiley replacer, html validators
+  * CLI commands: check, show, use
+
+  If you need any of those you have to wait till they are implemented or port them on your on.

data/doc/webgen_page_format.page

@@ -0,0 +1,128 @@
+---
+title: Webgen Page Format
+---
+## Webgen Page Format
+
+The Webgen Page Format is a custom format designed primarily for page and template files. It
+consists of an optional meta information block and one or more blocks of data; it is very simple and
+easy to use.
+
+## Structure
+
+A file using the Webgen Page Format consists of one or more blocks which are the smallest units
+recongnized. Blocks are separated from each other through a line containing three dashes. This is
+illustrated in the following examples which are all valid files in WebPage Format:
+
+Example 1:
+
+    Here is a block!
+
+Example 2:
+
+    This is one block of the file
+    ---
+    This is another block.
+
+Example 3:
+
+    Block 1
+    --- name:block2
+    Block 2
+    --- name:block3
+    Block 3...
+
+If you want to use three dashes in a block but you don't want to end the block, you have to escape
+them with a backslash character, like this:
+
+    Block 1
+    \---
+    still Block 1
+    --- name:block2
+    Block 2
+
+All of the above examples show one kind of block, the content block. However, there may also be
+another type of block: the meta information block. Following is a short description of both kinds,
+starting with the meta information block.
+
+
+### Meta Information Block
+
+Each file in Webgen Page Format can have zero or one meta information blocks. This block is
+specified at the beginning of the file. To tell the parser that the first block is the meta
+information block and not a content block, you have to start the file with three dashes:
+
+    ---
+    title: The title set by Meta info
+    ---
+    This is the content of the file
+
+The above defines a meta information block and a content block. The meta information block has to be
+in YAML format and should contain key-value pairs of meta information. [YAML](http://www.yaml.org)
+is a simple markup language designed for ease of use and although you define structured data with
+it, it feels like just writing a plain text document.
+
+
+### Content Blocks
+
+A content block is used to provide content in a specific format. Each file in Webgen Page Format
+needs to have at least one content block which may be empty. However, it can have as many content
+blocks as necessary. Each content block needs to have a unique name and additional options can also
+be set.
+
+The name uniquely identifies a content block and is used to access it. The only option used by
+webgen is the `pipeline` option which specifies the processing pipeline for the block. The
+processing pipeline is used for rendering the block by using the specified content processors in the
+specified order. There are many different content processors available - have a look at the
+[extensions page]({relocatable: extensions.html}) for an overview.
+
+There are also defaults for the name and the options of a block but they can be overwritten. You can
+use one of two ways to do this:
+
+* you either specify the name and additional options of the block on the starting line with the
+  three dashes
+
+* or you use the special meta information `block` to define the names and options of one or all
+  blocks.
+
+The following example uses the first technique to override the name and/or the `pipeline` option:
+
+    1. content block of the file
+    --- name:sidebar pipeline:maruku,tags
+    2. content block of the file
+    --- name:other
+    3. content block of the file
+
+The first block has no identifieres set (there is no line with three dashes and the identifieres).
+Therefore the default value for the name is used: `content`. The second block is named `sidebar` and
+uses the processing pipeline `maruku,tags`. As you can see, the name of a block as well as
+additional options are specified by stating the key (e.g. `name` or `pipeline`) followed by a colon
+and the value. Multiple options are separated via one or more spaces. The value of a block option is
+parsed with YAML. For example, when specifying `use_something:true` the value `true` is
+automatically converted from the string `true` to the boolean `true`.
+
+> Only the first block gets the default name of `content`. The second and following blocks have
+> numbered names like `block2`, `block3` and so on.
+{.information}
+
+You can also set the name and additional options of the content blocks by using the special `blocks`
+meta information. It is a hash using the index of a block (or the special value `default`) as key
+and the options as values. The above example can therefore also be written like this:
+
+    ---
+    blocks: \{2: {name: sidebar, pipeline: maruku,tags}, 3: {name: other}}
+    ---
+    1. content block of the file
+    ---
+    2. content block of the file
+    ---
+    3. content block of the file
+
+When selecting a value for the name of a block or an option, the following precedence is used (from
+low to high):
+
+* global defaults set via the `default` key of the meta information `blocks`
+* block defaults set via the meta information `blocks`
+* the `--- line` options
+
+As stated above, the "option" `name` is special insofar that when it is not set, an automatic name
+gets generated.

data/lib/webgen/blackboard.rb

@@ -0,0 +1,73 @@
+module Webgen
+
+  # A blackboard object provides two features for inter-object communication:
+  #
+  # * services: An object can add a service to the blackboard which can be called by any other
+  #             object by just specifing the service name. Therefore it is easy to change the
+  #             underlying implementation of the service and there are no hard dependencies on
+  #             specific class or method names.
+  #
+  # * listeners: Objects may register themselves for specific messsage names and get notified when
+  #              such a message gets dispatched.
+  class Blackboard
+
+    # Create a new Blackboard object.
+    def initialize
+      @listener = {}
+      @services = {}
+    end
+
+    # Add the +callable_object+ or the given block as listener for the messages +msg_names+ (one
+    # message name or an array of message names).
+    def add_listener(msg_names = nil, callable_object = nil, &block)
+      callable_object = callable_object || block
+      if !callable_object.nil?
+        raise ArgumentError, "The listener needs to respond to 'call'" unless callable_object.respond_to?(:call)
+        [msg_names].flatten.compact.each {|name| (@listener[name] ||= []) << callable_object}
+      else
+        raise ArgumentError, "You have to provide a callback object or a block"
+      end
+    end
+
+    # Remove the given object from the dispatcher queues of the message names specified in
+    # +msg_names+.
+    def del_listener(msg_names, callable_object)
+      [msg_names].flatten.each {|name| @listener[name].delete(callable_object) if @listener[name]}
+    end
+
+    # Dispatch the message +msg_name+ to all listeners for this message, passing the given
+    # arguments.
+    def dispatch_msg(msg_name, *args)
+      return unless @listener[msg_name]
+      @listener[msg_name].each {|obj| obj.call(*args)}
+    end
+
+    # Add a service named +service_name+ provided by the +callable_object+ or a block to the
+    # blackboard.
+    def add_service(service_name, callable_object = nil, &block)
+      callable_object = callable_object || block
+      if @services.has_key?(service_name)
+        raise "The service name '#{service_name}' is already taken"
+      else
+        raise ArgumentError, "An object providing a service needs to respond to 'call'" unless callable_object.respond_to?(:call)
+        @services[service_name] = callable_object
+      end
+    end
+
+    # Delete the service +service_name+.
+    def del_service(service_name)
+      @services.delete(service_name)
+    end
+
+    # Invoke the service called +service_name+ with the given arguments.
+    def invoke(service_name, *args, &block)
+      if @services.has_key?(service_name)
+        @services[service_name].call(*args, &block)
+      else
+        raise ArgumentError, "No such service named '#{service_name}' available"
+      end
+    end
+
+  end
+
+end

data/lib/webgen/cache.rb

@@ -0,0 +1,85 @@
+require 'set'
+require 'facets/kernel/constant'
+
+module Webgen
+
+  # A cache object provides access to various caches to speed up rendering of a website.
+  #
+  # permanent:: The permanent cache should be used for data that should be available between webgen
+  #             runs.
+  #
+  # volatile:: The volatile cache is used for data that can easily be regenerated but might be
+  #            expensive to do so. This cache is not stored between webgen runs.
+  #
+  # standard:: The standard cache saves data between webgen runs and returns the cached data (not
+  #            the newly set data) if it is available. This is useful, for example, to store file
+  #            modifcation times and check if a file has been changed between runs.
+  #
+  # The standard cache should be accessed through the <tt>[]</tt> method which returns the correct
+  # value and the <tt>[]=</tt> method should be used for setting the new value. However, if you
+  # really need to access a particular value of the old or new standard cache, you can use the
+  # accessors +old_data+ and +new_data+.
+  class Cache
+
+    # The permanent cache hash.
+    attr_reader :permanent
+
+    # The volatile cache hash.
+    attr_reader :volatile
+
+    # The cache data stored in the previous webgen run.
+    attr_reader :old_data
+
+    # The cache data stored in the current webgen run.
+    attr_reader :new_data
+
+    # Create a new cache object.
+    def initialize()
+      @old_data = {}
+      @new_data = {}
+      @volatile = {}
+      @permanent = {:classes => []}
+    end
+
+    # Return the cached data (or, if it is not available, the new data) identified by +key+ from the
+    # standard cache.
+    def [](key)
+      if @old_data.has_key?(key)
+        @old_data[key]
+      else
+        @new_data[key]
+      end
+    end
+
+    # Store +value+ identified by +key+ in the standard cache.
+    def []=(key, value)
+      @new_data[key] = value
+    end
+
+    # Restore the caches from +data+ and recreate all cached instances (see #instance).
+    def restore(data)
+      @old_data, @permanent = *data
+      @permanent[:classes].each {|klass| instance(klass)}
+    end
+
+    # Return all caches that should be available between webgen runs.
+    def dump
+      [@old_data.merge(@new_data), @permanent]
+    end
+
+    # Reset the volatile cache.
+    def reset_volatile_cache
+      @volatile = {:classes => @volatile[:classes]}
+    end
+
+    # Return the unique instance of the class +name+. This method should be used when it is
+    # essential that webgen uses only one object of a class or when an object should automatically
+    # be recreated upon cache restoration (see #restore).
+    def instance(name)
+      @permanent[:classes] << name unless @permanent[:classes].include?(name)
+      (@volatile[:classes] ||= {})[name] ||= constant(name).new
+    end
+
+  end
+
+end