webgen 0.5.6 → 0.5.7

data/data/webgen/webgui/controller/main.rb

@@ -1,3 +1,5 @@
+# -*- encoding: utf-8 -*-
+
 require 'stringio'
 require 'webgen/website'
 require 'webgen/websitemanager'

data/data/webgen/website_skeleton/ext/init.rb

@@ -4,3 +4,7 @@
 # allows you to add your own extensions to webgen or to modify webgen's core!
 #
 # If you don't need this feature you can savely delete this file and the directory in which it is!
+#
+# The +config+ variable below can be used to access the Webgen::Configuration object for the current
+# website.
+config = Webgen::WebsiteAccess.website.config

data/doc/contentprocessor/blocks.page

@@ -8,20 +8,32 @@ templates to define the place where the actual page content should be.
 
 The general syntax is as follows:
 
-    <webgen:block name='BLOCK_NAME' chain='(L)CN;(L)CN;...' />
+    <webgen:block name='BLOCK_NAME' chain='(L)CN;(L)CN;...' node='first' notfound='ignore' />
 
-So it is basically an XML tag with two attributes, `name` and `chain`. The `name` attribute
-specifies the name of the block that should be rendered in place of the block tag. The next node in
-the used node chain needs to have a block that is named so, otherwise an error is thrown (if there
-is only one node left in the node chain that node is used). The block is rendered according to its
-render pipeline and then inserted.
+So it is basically an XML tag with the mandatory attribute `name` and the optional attributes
+`chain`, `node` and `notfound`:
 
-The optional attribute `chain` specifies the node chain that should be used for rendering the
-block. Its value needs to be a list of (localized) canonical names of nodes separated by semicolons
-that should be used as node chain. If this attribute is not specified the default node chain is
-used.
+* The `name` attribute is the only mandatory attribute and it specifies the name of the block that
+  should be rendered in place of the block tag. The next node in the used node chain (if there is
+  only one node left in the node chain that node is used) needs to have a block that has such a name
+  (this behaviour can be changed with the `node` attribute), otherwise an error is raised. The
+  block is rendered according to its render pipeline and then inserted.
 
-This is more easily explained with examples. Assume we have a `default.template` file, a
+* The optional attribute `chain` specifies the node chain that should be used for rendering the
+  block. Its value needs to be a list of (localized) canonical names of nodes separated by
+  semicolons that should be used as node chain. If this attribute is not specified the default node
+  chain is used.
+
+* The optional attribute `node` specifies which node in the node chain should be used. If this
+  attribute is not specified, the next node in the node chain is used. If it is specified with the
+  value `first`, then the node chain is traversed till a node is found that has a block with the
+  specified name. If no such node is in the node chain, an error is raised.
+
+* If the optional attribute `notfound` has a value of `ignore`, all errors that can occur are
+  ignored. This is especially useful when used in templates to include blocks that may not be
+  defined in all page files.
+
+All this is more easily explained with examples. Assume that we have a `default.template` file, a
 `page.template` file and a `my.page` file with the following contents:
 
 The `default.template` file:
@@ -32,6 +44,10 @@ The `default.template` file:
     after default 1
     <webgen:block name='content' chain='page.template;my.html' />
     after default 2
+    <webgen:block name='optional' chain='page.template;my.html' node='first' />
+    after default 3
+    <webgen:block name='invalid' notfound='ignore' />
+    after default 4
 
 The `page.template` file:
 
@@ -44,18 +60,28 @@ And the `my.page` file:
 
     --- name:content pipeline:
     The content of the page file.
+    --- name:optional pipeline:
+    Optional content.
 
 When `my.page` gets rendered to `my.html`, the node chain looks like this by default:
 
-    default.template ---> my.page
+    default.template ---> my.html
 
 The first webgen block tag just inserts the rendered block named `content` of `my.page`. The second
 block tag uses a custom node chain. Therefore the block named `content` of `page.template` gets
 rendered using the node chain:
 
-    page.template ---> my.page
+    page.template ---> my.html
 
-and then inserted. Summing up the above, the rendered file `my.html` will then look like this:
+and then inserted. The third block tag uses the same custom node chain but for a block named
+`optional`. This block does not exist in `page.template` but it does exist in `my.page`. Since the
+`node` attribute is set to `first`, the first node `page.template` in the node chain is ignored and
+the block is found in `my.page` (if the `node` attribute is not specified, an error will be raised).
+
+The fourth block tag specifies a block name that does not occur in `my.page`. However, since the
+optional attribute `notfound` is set to `ignore`, this error is ignored.
+
+Summing up the above, the rendered file `my.html` will then look like this:
 
     before default 1
     The content of the page file.
@@ -64,3 +90,7 @@ and then inserted. Summing up the above, the rendered file `my.html` will then l
     The content of the page file.
     after page 1
     after default 2
+    Optional content.
+    after default 3
+
+    after default 4

data/doc/contentprocessor/builder.page

@@ -12,7 +12,7 @@ erb.html}).
 > to do this is via Rubygems:
 >
 >     gem install builder
-{.exclamation}
+{.warning}
 
 
 ## Examples

data/doc/contentprocessor/erb.page

@@ -53,4 +53,4 @@ output the result of the Ruby code (note the equation sign!). And the fourth lin
 > You may need to ensure that the ERB start and end tags are not processed by the content
 > processor. For example, when using the RedCloth content processor, you may need to surround the
 > ERB code with `<textile>` tags!
-{.exclamation}
+{.important}

data/doc/contentprocessor/erubis.page

@@ -11,7 +11,7 @@ options.
 > way to do this is via Rubygems:
 >
 >     gem install erubis
-{.exclamation}
+{.warning}
 
 [1]: http://www.kuwata-lab.com/erubis/ "Erubis Homepage"
 

data/doc/contentprocessor/fragments.page

@@ -10,7 +10,7 @@ attribute set.
 > context! This is to ensure that fragment nodes are not created from multiple block of one page
 > file. So this content processor has no effect when used in the pipeline of blocks except if the
 > block is named `content`.
-{.exclamation}
+{.warning}
 
 The default markup language Maruku automatically generates an `id` attribute for all headers. If you
 use another markup language or plain old HTML, you might need to set the `id` attributes by hand.

data/doc/contentprocessor/haml.page

@@ -15,7 +15,7 @@ erb.html}).
 > do this is via Rubygems:
 >
 >     gem install haml
-{.exclamation}
+{.warning}
 
 
 ## Example

data/doc/contentprocessor/rdiscount.page

@@ -12,7 +12,7 @@ Markdown processor]({relocatable: maruku.html}) does.
 > way to do this is via Rubygems:
 >
 >     gem install rdiscount
-{.exclamation}
+{.warning}
 
 [1]: http://github.com/rtomayko/rdiscount
 

data/doc/contentprocessor/rdoc.page

@@ -11,7 +11,7 @@ for Ruby source files, [reference][1]) to HTML.
 > implementation is via Rubygems:
 >
 >     gem install rdoc
-{.exclamation}
+{.warning}
 
 [1]: http://rdoc.rubyforge.org/rdoc/ "RDoc Reference"
 [2]: http://rubyforge.org/projects/rdoc/ "New RDoc implementation"

data/doc/contentprocessor/redcloth.page

@@ -10,7 +10,7 @@ RedCloth library. For detailed information about Textile have a look at the [Tex
 > way to do this is via Rubygems:
 >
 >     gem install RedCloth
-{.exclamation}
+{.warning}
 
 
 Example

data/doc/contentprocessor/sass.page

@@ -10,7 +10,7 @@ using the Haml library. For detailed information about Sass have a look at the [
 > do this is via Rubygems:
 >
 >     gem install haml
-{.exclamation}
+{.warning}
 
 
 ## Example

data/doc/faq.page

@@ -177,7 +177,7 @@ following to the sidebar part in your `default.template` (ensure that you haven'
 the processing pipeline):
 
     <%% if node.node_info[:page].blocks.has_key?('sidebar') %>
-      \<webgen:block name='sidebar' />
+      <webgen:block name='sidebar' />
     <%% end %>
 
 This will include the contents of the block `sidebar` in the sidebar if such a block exists for a
@@ -188,6 +188,11 @@ page file:
     --- name:sidebar
     This is the sidebar block and everything in here goes to the sidebar!
 
+You can avoid using the ERB processor if you use the following syntax (available from version 0.5.7
+upwards):
+
+    <webgen:block name='sidebar' node='first' notfound='ignore' />
+
 ### ... create XML output?
 
 This can be achieved manually (by removing any markup processor in the processing pipeline of the
@@ -211,4 +216,4 @@ in the meta information block of the page file for which you want a short menu t
 
 > Be aware that this changes not only how the page appears in a menu but also how it appears in
 > breadcrumb trails and other links generated by webgen.
-{.exclamation}
+{.important}

data/doc/manual.page

@@ -19,7 +19,8 @@ The executable for webgen is called... webgen ;-) It uses a command style syntax
 possible commands run `webgen help`.
 
 The main command is the `render` command which does the actual website generation. This command uses
-the current working directory as website directory if none was specified via the gloabl `-d` option.
+either the environment variable `WEBGEN_WEBSITE` (if it is set and non-empty) or the current working
+directory as website directory if none was specified via the gloabl `-d` option.
 
 You can invoke a command by specifying its name after the executable name. Also counting the
 executable `webgen` as a command, the options for a command are specified directly after the command
@@ -250,7 +251,7 @@ information can be extracted correctly from the path name:
     > If two paths have the same `basename` and `extension` part, they should define the same
     > content but for different languages. This allows webgen to automatically deliver the right
     > language version of the content
-    {.information}
+    {.important}
 
 *   `lang`
 
@@ -297,7 +298,7 @@ language, it is first tried to get the path in the requested language. If this i
 (ie. no such localization exists), the unlocalized path is returned if it exists.
 
 > Directories and fragments are never localized, only files are!
-{.exclamation}
+{.important}
 
 It is also possible to use the _localized canonical name_ of a path to resolve it. The localized
 canonical name is the same as the canonical name but with a language code inserted before the
@@ -330,9 +331,9 @@ information key is an array which can have the following values:
   * `:year`, `:month`, `:day`: The creation year, month and day, respectively, of the source path.
     An error is raised if the needed meta information `created_at` is not set on the path.
 
-> The contructed output path must always be an absolute one, ie. it has to start at the root of the
+> The constructed output path must always be an absolute one, ie. it has to start at the root of the
 > output directory. Therefore, the `:parent` part should always be included!
-{.information}
+{.important}
 
 Following are some examples of output path names for given source path names (assuming that `en` is
 the default language and that the path is under a directory called `/img/`):

data/doc/reference_metainfo.page

@@ -171,7 +171,7 @@ at the [output path creation section]({relocatable: manual.html#source-output})
 
 > This meta information has to be set BEFORE a node gets created. Setting this value is therefore
 > only useful, for example, in the `paths` block of a meta information backing file.
-{.exclamation}
+{.important}
 
 ### priority
 

data/doc/sourcehandler/feed.page

@@ -7,6 +7,12 @@ This source handler automatically generates an atom or RSS feed for a set of fil
 [Webgen Page Format]({relocatable: ../webgen_page_format.html}) (the format which is also used for
 page files).
 
+> This extension is only available if you have installed the [feedtools][1] library. The preferred
+> way to do this is via Rubygems:
+>
+>     gem install feedtools
+{.warning}
+
 The following meta information keys are supported:
 
 *   `entries` (MANDATORY)
@@ -94,4 +100,6 @@ The following meta information keys of page files are used if they are specified
 
 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.
+file which are then used to generate the atom or the RSS feed respectively.
+
+[1]: http://sporkmonger.com/projects/feedtools

data/doc/sourcehandler/sitemap.page

@@ -11,7 +11,7 @@ This source handler automatically generates a sitemap based on the specification
 > library. The preferred way to do this is via Rubygems:
 >
 >     gem install builder
-{.exclamation}
+{.warning}
 
 The following meta information keys are supported:
 

data/doc/tag/coderay.page

@@ -24,7 +24,7 @@ specifies what should be highlighted.
 > way to do this is via Rubygems:
 >
 >     gem install coderay
-{.exclamation}
+{.warning}
 
 [1]: http://coderay.rubychan.de/ "The Coderay homepage"
 

data/doc/tag/langbar.page

@@ -12,6 +12,21 @@ This tag is used to display a list of links to translations of the page. The tex
 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">

data/doc/tag/menu.page

@@ -27,7 +27,7 @@ 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}
+{.important}
 
 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

data/doc/tag/relocatable.page

@@ -5,7 +5,7 @@ used_options:
 ---
 ## Description
 
-This tag ensures that the relative path to the specified path is always correct. 
+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:
@@ -15,7 +15,7 @@ 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}
+{.important}
 
 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

data/lib/webgen/blackboard.rb

@@ -1,14 +1,19 @@
+# -*- encoding: utf-8 -*-
+
 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.
+  #   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.
+  #   such a message gets dispatched.
+  #
+  # For a list of all available services and messages have a look at the main Webgen documentation
+  # page.
   class Blackboard
 
     # Create a new Blackboard object.

data/lib/webgen/cache.rb

@@ -1,3 +1,5 @@
+# -*- encoding: utf-8 -*-
+
 require 'set'
 require 'facets/kernel/constant'
 

data/lib/webgen/cli.rb

@@ -1,3 +1,5 @@
+# -*- encoding: utf-8 -*-
+
 require 'cmdparse'
 require 'webgen/website'
 require 'webgen/version'
@@ -77,9 +79,12 @@ module Webgen
       # The log level. Default: <tt>Logger::WARN</tt>
       attr_reader :log_level
 
+      # Create a new CommandParser class. The default webgen website (if not specified via the
+      # <tt>-d</tt> option) is taken from the environment variable +WEBGEN_WEBSITE+ or, if it is not
+      # set or empty, the current working directory.
       def initialize # :nodoc:
         super(true)
-        @directory = Dir.pwd
+        @directory = (ENV['WEBGEN_WEBSITE'].to_s.empty? ? Dir.pwd : ENV['WEBGEN_WEBSITE'])
         @verbosity = :normal
         @log_level = ::Logger::WARN
         @log_filter = nil

data/lib/webgen/cli/create_command.rb

@@ -1,3 +1,5 @@
+# -*- encoding: utf-8 -*-
+
 require 'webgen/cli'
 require 'webgen/websitemanager'
 

data/lib/webgen/cli/run_command.rb

@@ -1,3 +1,5 @@
+# -*- encoding: utf-8 -*-
+
 require 'webgen/cli'
 
 module Webgen::CLI

data/lib/webgen/cli/utils.rb

@@ -1,3 +1,5 @@
+# -*- encoding: utf-8 -*-
+
 require 'facets/ansicode'
 require 'rbconfig'
 

data/lib/webgen/cli/webgui_command.rb

@@ -1,3 +1,5 @@
+# -*- encoding: utf-8 -*-
+
 require 'webgen/cli'
 
 module Webgen::CLI