webgen 0.5.8 → 0.5.9

data/Rakefile

@@ -59,9 +59,9 @@ Webgen::WebgenTask.new('htmldoc') do |site|
     prefix = "webgen-website-bundle-"
     config['resources'].select {|name, data| name =~ /^#{prefix}style/}.each do |name, data|
       config['sources'] <<
-        ["/website_styles/#{name.sub(prefix, '')}", "Webgen::Source::FileSystem", 'misc', 'style.page']
+        ["/website_styles/#{name.sub(prefix, '')}/", "Webgen::Source::FileSystem", 'misc', 'style.page']
       config['sources'] <<
-        ["/website_styles/#{name.sub(prefix, '')}", 'Webgen::Source::Resource', name, '/src/**', '/src']
+        ["/website_styles/#{name.sub(prefix, '')}/", 'Webgen::Source::Resource', name, '/src/**', '/src/']
     end
     config['output'] = ['Webgen::Output::FileSystem', 'htmldoc']
   end
@@ -171,8 +171,7 @@ EOF
       s.add_development_dependency('haml', '>= 2.0.9')
       s.add_development_dependency('builder', '>= 2.1.0')
       s.add_development_dependency('rdoc', '>= 2.4.2')
-      s.add_development_dependency('coderay', '>= 0.7.4.214')
-      s.add_development_dependency('feedtools', '>= 0.2.29')
+      s.add_development_dependency('coderay', '>= 0.8.312')
       s.add_development_dependency('erubis', '>= 2.6.2')
       s.add_development_dependency('rdiscount', '>= 1.2.9')
       s.add_development_dependency('archive-tar-minitar', '>= 0.5.2')
@@ -279,9 +278,9 @@ The official version is called 'webgen' and can be installed via
       prefix = "webgen-website-bundle-"
       config['resources'].select {|name, data| name =~ /^#{prefix}style/}.each do |name, data|
         config['sources'] <<
-          ["/documentation/website_styles/#{name.sub(prefix, '')}", "Webgen::Source::FileSystem", '../misc', 'style.page']
+          ["/documentation/website_styles/#{name.sub(prefix, '')}/", "Webgen::Source::FileSystem", '../misc', 'style.page']
         config['sources'] <<
-          ["/documentation/website_styles/#{name.sub(prefix, '')}", 'Webgen::Source::Resource', name, '/src/**', '/src']
+          ["/documentation/website_styles/#{name.sub(prefix, '')}/", 'Webgen::Source::Resource', name, '/src/**', '/src/']
       end
     end
   end

data/THANKS

@@ -16,3 +16,4 @@ Thanks for donations to:
 * Andrew Pietsch
 * Mateusz Szczap
 * Michael Franzl
+* Roger Pack

data/VERSION

@@ -1 +1 @@
-0.5.8
+0.5.9

data/bin/webgen

@@ -6,7 +6,7 @@ require 'webgen/cli'
 begin
   Webgen::CLI::CommandParser.new.parse
 rescue
-  puts 'An error has occurred:   ' + $!.message
+  puts "An error has occurred:\n  " + $!.message
   puts $!.backtrace if $DEBUG
   exit(-1)
 end

data/data/webgen/passive_sources/stylesheets/coderay-default.css

@@ -0,0 +1,129 @@
+/* This file has been generated with the coderay_stylesheet binary from the coderay gem. */
+/* Copyright by Kornelius Kalnbach, licensed under LGPL - see coderay.rubychan.de */ 
+
+.CodeRay {
+  background-color: #f8f8f8;
+  border: 1px solid silver;
+  font-family: 'Courier New', 'Terminal', monospace;
+  color: #000;
+}
+.CodeRay pre { margin: 0px }
+
+div.CodeRay { }
+
+span.CodeRay { white-space: pre; border: 0px; padding: 2px }
+
+table.CodeRay { border-collapse: collapse; width: 100%; padding: 2px }
+table.CodeRay td { padding: 2px 4px; vertical-align: top }
+
+.CodeRay .line_numbers, .CodeRay .no {
+  background-color: #def;
+  color: gray;
+  text-align: right;
+}
+.CodeRay .line_numbers tt { font-weight: bold }
+.CodeRay .no { padding: 0px 4px }
+.CodeRay .code { width: 100% }
+
+ol.CodeRay { font-size: 10pt }
+ol.CodeRay li { white-space: pre }
+
+.CodeRay .code pre { overflow: auto }
+
+.CodeRay .debug { color:white ! important; background:blue ! important; }
+
+.CodeRay .af { color:#00C }
+.CodeRay .an { color:#007 }
+.CodeRay .at { color:#f08 }
+.CodeRay .av { color:#700 }
+.CodeRay .aw { color:#C00 }
+.CodeRay .bi { color:#509; font-weight:bold }
+.CodeRay .c  { color:#888; }
+
+.CodeRay .ch { color:#04D }
+.CodeRay .ch .k { color:#04D }
+.CodeRay .ch .dl { color:#039 }
+
+.CodeRay .cl { color:#B06; font-weight:bold }
+.CodeRay .co { color:#036; font-weight:bold }
+.CodeRay .cr { color:#0A0 }
+.CodeRay .cv { color:#369 }
+.CodeRay .df { color:#099; font-weight:bold }
+.CodeRay .di { color:#088; font-weight:bold }
+.CodeRay .dl { color:black }
+.CodeRay .do { color:#970 }
+.CodeRay .dt { color:#34b }
+.CodeRay .ds { color:#D42; font-weight:bold }
+.CodeRay .e  { color:#666; font-weight:bold }
+.CodeRay .en { color:#800; font-weight:bold }
+.CodeRay .er { color:#F00; background-color:#FAA }
+.CodeRay .ex { color:#F00; font-weight:bold }
+.CodeRay .fl { color:#60E; font-weight:bold }
+.CodeRay .fu { color:#06B; font-weight:bold }
+.CodeRay .gv { color:#d70; font-weight:bold }
+.CodeRay .hx { color:#058; font-weight:bold }
+.CodeRay .i  { color:#00D; font-weight:bold }
+.CodeRay .ic { color:#B44; font-weight:bold }
+
+.CodeRay .il { background: #eee; color: black }
+.CodeRay .il .il { background: #ddd }
+.CodeRay .il .il .il { background: #ccc }
+.CodeRay .il .idl { font-weight: bold; color: #777 }
+
+.CodeRay .im { color:#f00; }
+.CodeRay .in { color:#B2B; font-weight:bold }
+.CodeRay .iv { color:#33B }
+.CodeRay .la { color:#970; font-weight:bold }
+.CodeRay .lv { color:#963 }
+.CodeRay .oc { color:#40E; font-weight:bold }
+.CodeRay .of { color:#000; font-weight:bold }
+.CodeRay .op { }
+.CodeRay .pc { color:#038; font-weight:bold }
+.CodeRay .pd { color:#369; font-weight:bold }
+.CodeRay .pp { color:#579; }
+.CodeRay .ps { color:#00C; font-weight: bold; }
+.CodeRay .pt { color:#349; font-weight:bold }
+.CodeRay .r, .kw  { color:#080; font-weight:bold }
+
+.CodeRay .ke { color: #808; }
+.CodeRay .ke .dl { color: #606; }
+.CodeRay .ke .ch { color: #80f; }
+.CodeRay .vl { color: #088; }
+
+.CodeRay .rx { background-color:#fff0ff }
+.CodeRay .rx .k { color:#808 }
+.CodeRay .rx .dl { color:#404 }
+.CodeRay .rx .mod { color:#C2C }
+.CodeRay .rx .fu  { color:#404; font-weight: bold }
+
+.CodeRay .s { background-color:#fff0f0; color: #D20; }
+.CodeRay .s .s { background-color:#ffe0e0 }
+.CodeRay .s .s  .s { background-color:#ffd0d0 }
+.CodeRay .s .k { }
+.CodeRay .s .ch { color: #b0b; }
+.CodeRay .s .dl { color: #710; }
+
+.CodeRay .sh { background-color:#f0fff0; color:#2B2 }
+.CodeRay .sh .k { }
+.CodeRay .sh .dl { color:#161 }
+
+.CodeRay .sy { color:#A60 }
+.CodeRay .sy .k { color:#A60 }
+.CodeRay .sy .dl { color:#630 }
+
+.CodeRay .ta { color:#070 }
+.CodeRay .tf { color:#070; font-weight:bold }
+.CodeRay .ts { color:#D70; font-weight:bold }
+.CodeRay .ty { color:#339; font-weight:bold }
+.CodeRay .v  { color:#036 }
+.CodeRay .xt { color:#444 }
+
+.CodeRay .ins { background: #afa; }
+.CodeRay .del { background: #faa; }
+.CodeRay .chg { color: #aaf; background: #007; }
+.CodeRay .head { color: #f8f; background: #505 }
+
+.CodeRay .ins .ins { color: #080; font-weight:bold }
+.CodeRay .del .del { color: #800; font-weight:bold }
+.CodeRay .chg .chg { color: #66f; }
+.CodeRay .head .head { color: #f4f; }

data/data/webgen/passive_sources/templates/atom_feed.template

@@ -0,0 +1,38 @@
+---
+template: ~
+--- pipeline:erb
+<?xml version="1.0" encoding="utf-8" ?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+  <title type="html"><%= h(context.node['title']) %></title>
+  <subtitle type="html"><%= h(context.node['description']) %></subtitle>
+  <author>
+    <name><%= h(context.node['author']) %></name>
+    <uri><%= h(context.node['author_url']) %></uri>
+  </author>
+
+  <link href="<%= context.node.feed_link %>" rel="alternate" />
+  <generator uri="http://webgen.rubyforge.org/documentation/sourcehandler/feed.html" version="<%= Webgen::VERSION %>">
+    webgen - Webgen::SourceHandler::Feed
+  </generator>
+  <updated><%= Time.now.xmlschema %></updated>
+  <id><%= context.node.feed_link %></id>
+
+  <% context.node.feed_entries.each do |entry| %>
+  <entry>
+    <title type="html"><%= h(entry['title']) %></title>
+    <% if entry['author'] %>
+    <author>
+      <name><%= h(entry['author']) %></name>
+      <uri><%= h(entry['author_url']) %></uri>
+    </author>
+    <% end %>
+    <link href="<%= Webgen::Node.url(File.join(context.node['site_url'], entry.path), false) %>" rel="alternate" />
+    <id><%= Webgen::Node.url(File.join(context.node['site_url'], entry.path), false) %></id>
+    <updated><%= entry['modified_at'].xmlschema %></updated>
+    <% if entry['created_at'].kind_of?(Time) %>
+    <published><%= entry['created_at'].xmlschema %></published>
+    <% end %>
+    <content type="html"><%= h(context.node.entry_content(entry)) %></content>
+  </entry>
+  <% end %>
+</feed>

data/data/webgen/passive_sources/templates/rss_feed.template

@@ -0,0 +1,28 @@
+---
+template: ~
+--- pipeline:erb
+<?xml version="1.0" encoding="utf-8" ?>
+<rss version="2.0">
+  <channel>
+    <title><%= h(context.node['title']) %></title>
+    <link><%= context.node.feed_link %>"</link>
+    <description><%= h(context.node['description']) %></description>
+    <pubDate><%= Time.now.rfc822 %></pubDate>
+    <lastBuildDate><%= Time.now.rfc822 %></lastBuildDate>
+    <generator>webgen - Webgen::SourceHandler::Feed</generator>
+
+    <% context.node.feed_entries.each do |entry| %>
+    <item>
+      <title><%= h(entry['title']) %></title>
+      <link><%= Webgen::Node.url(File.join(context.node['site_url'], entry.path), false) %></link>
+      <description><%= h(context.node.entry_content(entry)) %></description>
+      <pubDate><%= entry['modified_at'].rfc822 %></pubDate>
+      <guid isPermaLink="true"><%= Webgen::Node.url(File.join(context.node['site_url'], entry.path), false) %></guid>
+    </item>
+    <% end %>
+
+  </channel>
+</rss>
+
+
+

data/data/webgen/passive_sources/templates/sitemap.template

@@ -0,0 +1,21 @@
+---
+template: ~
+--- pipeline:erb
+<?xml version="1.0" encoding="utf-8" ?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<%
+context.node.alcns.each do |alcn|
+  item = context.node.tree[alcn]
+%>
+  <url>
+    <loc><%= URI.escape(File.join(context.node['site_url'], item.path)) %></loc>
+    <lastmod><%= item['modified_at'].iso8601 %></lastmod>
+    <changefreq><%= item['change_freq'] || context.node['default_change_freq'] %></changefreq>
+    <% if priority = item['priority'] || context.node['default_priority'] %>
+    <priority><%= priority %></priority>
+    <% end %>
+  </url>
+<%
+end
+%>
+</urlset>

data/data/webgen/resources.yaml

@@ -1,3 +1,4 @@
-website_skeleton:    webgen-website-skeleton
+website_skeleton:        webgen-website-skeleton
 website_bundles/style/*: webgen-website-bundle-style-$basename
 website_bundles/default: webgen-website-bundle-default
+passive_sources:         webgen-passive-sources

data/data/webgen/website_skeleton/Rakefile

@@ -31,7 +31,11 @@ task :auto_webgen do
     # you may need to adjust the glob so that all your sources are included
     paths = Dir['src/**/*'].sort
     if old_paths != paths || paths.any? {|p| File.mtime(p) > time}
-      Rake::Task['webgen'].execute({})
+      begin
+        Rake::Task['webgen'].execute({})
+      rescue Webgen::Error => e
+        puts e.message
+      end
     end
     time = Time.now
     old_paths = paths

data/doc/contentprocessor/builder.page

@@ -48,11 +48,11 @@ Following is a complete example which shows how to use this extension in a page
 a custom XML document (the `content` block has to be valid Ruby!):
 
     ---
-    output_path_style: [:parent, :cnbase, ['.', :lang], '.xml']
+    output_path_style: [:parent, :basename, ['.', :lang], '.xml']
     title: Person Object
     template: ~
     --- pipeline:builder
-    xml.persons(:path => context.node.absolute_lcn) do |p|
+    xml.persons(:path => context.node.alcn) do |p|
       p.person do |b|
         b.firstname('Thomas')
         b.lastname('Leitner')

data/doc/contentprocessor/erb.page

@@ -8,7 +8,7 @@ a look at its documentation by executing `ri ERB` or the [ruby documentation
 site](http://www.ruby-doc.org/)!
 
 You can use the special object `context` in your ERB code which provides the whole rendering context
-and the following useful methods:
+and, for example, the following useful methods:
 
 * `website`: Provides access to the `Webgen::Website` object which can be used to access all aspects
   of the currently rendered website.
@@ -22,6 +22,9 @@ and the following useful methods:
 * `dest_node`: The node in which the result gets inserted. Should be used for calculating relative
   paths.
 
+For a complete list of supported methods have a look at the API documentation for
+[Webgen::Context](../rdoc/Webgen/Context.html).
+
 Here is a small usage example. The following put in a page file
 
     Counting 5 items dynamically:
@@ -53,5 +56,5 @@ 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!
+> ERB code with `<notextile>` tags!
 {.important}

data/doc/contentprocessor/erubis.page

@@ -25,9 +25,9 @@ following configuration options:
 
 * `contentprocessor.erubis.use_pi`: Use processing instructions instead of ERB like
   instructions. Normally you use statements like `<%% result = some_method_call(opts) %>` or `<%%=
-  context.content_node.absolute_lcn %>` in your content. When setting this option to `true`, you can
+  context.content_node.alcn %>` in your content. When setting this option to `true`, you can
   use XML processing instructions instead, like this: `<?rb result = some_method_call(opts) ?>` or
-  `@{context.content_node.absolute_lcn}@`.
+  `@{context.content_node.alcn}@`.
 
 * `contentprocessor.erubis.options`: This is hash which is passed to the Erubis interpreter and
   which can be used to set additional options.

data/doc/contentprocessor/head.page

@@ -0,0 +1,21 @@
+---
+title: Webgen::ContentProcessor::Head
+---
+## Description
+
+This processor inserts before the end of the HTML head section links to used javascript and css
+files, inline javascript and css content and general meta tags. This functionality can be used, for
+example, by webgen tags to add needed javascript or css fragments on a page-per-page basis.
+
+It can also be used to insert arbitrary meta tags on a page-per-page basis. This can be done by
+setting the meta information named [`meta`]({relocatable: ../reference_metainfo.html#meta}) on a
+page file.
+
+This content processor should be used on template files since its output is only useful in the head
+section of an HTML file. And it should be the last content processor in the pipeline because
+otherwise not all needed information is available! There is no need for a special markup since the
+HTML head end tag is unique in a HTML element and therefore the insertion place can easily be found.
+
+Developers wanting to use the functionality of this content processor should have a look at its [API
+documentation](../rdoc/Webgen/ContentProcessor/Head.html).
+

data/doc/contentprocessor/tidy.page

@@ -0,0 +1,14 @@
+---
+title: Webgen::ContentProcessor::Tidy
+---
+## Description
+
+This content processor uses the [`tidy`][1] program to convert the input into valid (X)HTML. It
+supports a vast amount of options for specifying how the input should be processed. These options
+can be set throught the configuration option [`contentprocessor.tidy.options`]({relocatable:
+../reference_configuration.html#contentprocessortidyoptions}).
+
+The options `-q` and `-f FILE` are always set because they are needed internally and should
+therefore not be set through `contentprocessor.tidy.options`!
+
+[1]: http://tidy.sf.net

data/doc/extensions.page

@@ -6,7 +6,7 @@ title: Extensions
 Following is a listing of all available extensions:
 
 <%
-pattern = /#{File.join(context.node.parent.absolute_lcn, '/')}(contentprocessor|output|source|sourcehandler|tag|)\/.*html$/
+pattern = /#{File.join(context.node.parent.alcn, '/')}(contentprocessor|output|source|sourcehandler|tag|)\/.*html$/
 context.node.tree.node_access[:alcn].select {|alcn, n| alcn =~ pattern}.sort.each do |alcn, n|
 next if n.is_fragment?
 %>

data/doc/faq.page

@@ -124,14 +124,14 @@ You have several options of varying granularity:
 
       default_meta_info:
         :all:
-          output_path_style: [:parent, :cnbase, [., :lang], :ext]
+          output_path_style: [:parent, :basename, [., :lang], :ext]
 
 * Set the meta information `output_path_style` for a specific source handler to only change the
   output paths of this source handler (the page source handler in the following example):
 
       default_meta_info:
         Page:
-          output_path_style: [:parent, :cnbase, [., :lang], :ext]
+          output_path_style: [:parent, :basename, [., :lang], :ext]
 
 * Add the meta information `output_path_style` to a single file via, for example, a meta information
   backing file.

data/doc/manual.page

@@ -38,11 +38,12 @@ Following is a short overview of the available commands:
 
 *   `apply [-f] (BUNDLE_NAME|BUNDLE_URL)`
 
-    The argument may either be a valid bundle name or an URL to a bundle archive (a (gzipped) tar
-    archive). The command applies the bundle to the given webgen website. The files that will be
-    written to website directory are shown and the user is asked to confirm that the shown files
-    should indeed be written (and sometimes overwritten). If the `-f` option is used, the files are
-    always written.
+    The argument may either be a valid bundle name or an URL (in this case you will need to have all
+    dependencies for [Source::TarArchive]({relocatable: source/tararchive.html}) installed) to a
+    bundle archive (a (gzipped) tar archive). The command applies the bundle to the given webgen
+    website. The files that will be written to website directory are shown and the user is asked to
+    confirm that the shown files should indeed be written (and sometimes overwritten). If the `-f`
+    option is used, the files are always written.
 
     You can get the full list of available bundle names by running `webgen help apply`!
 
@@ -253,9 +254,32 @@ feeling of what files are handled by webgen.
 ## Source Paths Naming Convention {#source-naming}
 
 webgen assumes that the paths provided by the sources follow a special naming convention sothat meta
-information can be extracted correctly from the path name:
+information can be extracted correctly from the path names. There are three different cases
+depending on the type of path (the individual parts of a path are explained below):
 
-    [sort_info.]basename[.lang].extension
+*   The path specifies a directory. It must end with a slash character and must not contain any hash
+    characters. A directory path has to follow the scheme:
+
+        /parent_path/basename/
+
+*   The path specifies a file. It must not end with a slash character and must not contain any hash
+    characters. A file path has to follow the scheme:
+
+        /parent_path/[sort_info.]basename[.lang][.extension]
+
+*   The path specifies a fragment (e.g. part of a file). It must contain exactly one hash character
+    and it has to follow the scheme (where `/parent_path` needs to be a file path):
+
+        /parent_path#basename
+
+Following is the explanation of the parts of the path names:
+
+*   `/parent_path`
+
+    This part specifies the path of the parent of this path and is used internally to create a
+    hierarchy of paths. Although the leading slash is explicitly written here, it is part of the
+    parent path, i.e. each parent path begins with a slash. Also note that the parent path will end
+    with a slash if it is a directory!
 
 *   `sort_info`
 
@@ -265,53 +289,85 @@ information can be extracted correctly from the path name:
 *   `basename`
 
     This part is used on the one hand to generate the `title` meta information (but with `_` and `-`
-    replaced by spaces). And on the other hand, the canonical name is derived from it. `basename`
-    must not contain any dots, spaces or any character from the following list: ``; / ? * : ` & = +
-    $ ,``. If you do use one of them webgen may not work correctly!
+    replaced by spaces). And on the other hand, the [canonical name]({relocatable: '#source-cn'}) is
+    derived from it. `basename` must not contain any dots, spaces or any character from the
+    following list: ``; ? * : ` & = + $ ,``. If you do use one of them, webgen may not work
+    correctly!
 
-    > If two paths have the same `basename` and `extension` part, they should define the same
+    > If two file 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
+    > language version of the content.
     {.important}
 
 *   `lang`
 
     This part is optional and has to be an [ISO-639-1/2](http://www.loc.gov/standards/iso639-2/)
-    language identifier (two or three characters (a-z) long). If not specified, it is assumed that
-    the path is language independent (for example, images are normally not specific for a specific
-    language). However, this behaviour may be different for some source handler classes (for
-    example, all paths handled by SourceHandler::Page are assigned the default language if none is
-    set).
+    language identifier (two or three characters (a-z) long). It can only be specified if an
+    extension is also specified. If the file path should not have an extension, then just add a
+    trailing dot, e.g. `/dir/file.de.` - the trailing dot is ignored by webgen.
+
+    If the language part is not specified, it is assumed that the path is language independent (for
+    example, images are normally not specific for a specific language). However, this behaviour may
+    be different for some source handler classes (for example, all paths handled by
+    SourceHandler::Page are assigned the default language if none is set).
 
     If the language identifier can't be matched to a valid language, it is assumed that this part
     isn't actually a language identifier but a part of the extension. This also means that in the
     special case where the first part of an extension is also a valid language identifier, the first
-    part is interpreted as language identifier and not as part of the extension.
+    part is interpreted as language identifier and not as part of the extension!
 
 *   `extension`
 
     The file extension can be anything and can include dots.
 
-Following are some examples of source path names:
+Following are some examples of source path names (the acn and alcn parts are explained
+[below]({relocatable: '#source-cn'})):
 
-|Path name                 | Parsed meta information
-|--------------------------|------------------------------------------------
-|`name.png`                | title: Name, language: none, sort\_info: 0, basename: name, cn: name.png
-|`name.de.png`             | title: Name, language: de, sort\_info: 0, basename: name, cn: name.png
-|`01.name_of-file.eo.page` | title: Name of file, language: eo, sort\_info: 1, basename: name_of-file, cn: name_of-file.page
-|`name.tar.bz2`            | title: Name, language: none, sort\_info: 0, basename: name, cn: name.tar.bz2
-|`name.de.tar.bz2`         | title: Name, language: de, sort\_info: 0, basename: name, cn: name.tar.bz2
+| Path                       | Basename     | Language | `title`      | `sort_info` | acn                    | alcn                    |
+|----------------------------|--------------|----------|--------------|-------------|------------------------|-------------------------|
+| `/directory/`              | directory    | -none-   | Directory    |      -none- | `/directory/`          | `/directory/`           |
+| `/image.png`               | image        | -none-   | Image        |           0 | `/image.png`           | `/image.png`            |
+| `/image.de.png`            | image        | de       | Image        |           0 | `/image.png`           | `/image.de.png`         |
+| `/01.name_of-file.eo.page` | name_of-file | eo       | Name of file |           1 | `/name_of-file.page`   | `/name_of-file.eo.page` |
+| `/archive.tar.bz2`         | archive      | -none-   | Archive      |           0 | `/archive.tar.bz2`     | `/archive.tar.bz2`      |
+| `/archive.de.tar.bz2`      | archive      | de       | Archive      |           0 | `/archive.tar.bz2`     | `/archive.de.tar.bz2`   |
+| `/manual.html#sources`     | manual       | -none-   | Manual       |      -none- | `/manual.html#sources` | `/manual.html#sources`  |
+{#source-path-example-table style="border: 1px solid black; width: 100%"}
 
-Notice: The first two and the last two examples define the same content for two different languages
-(or more exactly: the first one is unlocalized and the second one localized to German) as they have
-the same canonical name.
+Notice: The first two file path and the last two file path examples define the same content for two
+different languages (or more exactly: the first one is unlocalized in both cases and the second one
+localized to German) as they have the same canonical name.
 
 
-## Canonical Name of a File ### {#source-cn}
+## Canonical Name (CN) of a File ### {#source-cn}
 
 webgen provides the functionality to define the same content in more than one language, ie. to
 localize content. This is achieved with the _canonical name_ of a path, short CN.
 
+The canonical name as well as all the other variants (\[absolute] \[localized] canonical name, all
+described below) are created directly from the source paths sothat one can easily derive the
+canonical name onself. Here are some examples:
+
+| Source path           | CN         | ACN                | LCN           | ALCN                  |
+|-----------------------|------------|--------------------|---------------|-----------------------|
+| `/images/test/`       | `test/`    | `/images/test/`    | `test/`       | `/images/test/`       |
+| `/images/logo.png`    | `logo.png` | `/images/logo.png` | `logo.png`    | `/images/logo.png`    |
+| `/images/logo.de.png` | `logo.png` | `/images/logo.png` | `logo.de.png` | `/images/logo.de.png` |
+| `/test.de.html#frag`  | `#frag`    | `/test.html#frag`  | `#frag`       | `/test.de.html#frag`  |
+{#cn-example-table style="border: 1px solid black; width: 100%"}
+
+What one can immediately see is that if a source path is unlocalized, the CN is the same as the LCN
+and the ACN is the same as the ALCN. This is always true for directory and fragment paths since they
+are always unlocalized! The first example shows a directory path - note the trailing slash! And the
+last example shows a fragment path - note the difference in the ACN and the ALCN! Another
+good-to-know fact is that an LCN is unique within its hierarchy level and that an ALCN is globally
+unique!
+
+> Source handlers can change some parts of a source path. For example, the page source handler
+> changes the extension from `page` to `html`. This has to be taken into account when specifying
+> canonical names! These changes are documented on the documentation pages for the source handlers!
+{.information}
+
 When multiple paths share the same canonical name, webgen assumes that they have the same content
 but in different languages. It is also possible to specify a _language independent_ path (i.e. one
 without a language) which is used as a fallback. Therefore when a path should be resolved using a
@@ -344,7 +400,7 @@ specified language is ignored as it is assumed that the user really only wants t
 specified language!
 
 Continuing the above example, this means that `images/my.de.jpg` is always returned when one
-specifies `images/my.de.jpg` in any of the index page files, e.g. in `index.fr.page`.
+specifies `images/my.de.jpg` in any of the index page files, e.g. even in `index.fr.page`.
 
 Both canonical and localized canonical names can be absolute (ACN and ALCN) which is done by using
 the full path starting with a slash. This is especially useful when you don't exactly know in which
@@ -353,7 +409,9 @@ hierarchy level a certain canoncial name gets evaluated.
 Everything said above also means that all paths are not resolved using their real source or output
 names but using the (localized) canonical name! So when specifying paths for extensions, for example
 when using the [relocatable tag]({relocatable: tag/relocatable.html}), you always have to use the
-(absolute) (localized) canonical names. This is different from previous webgen versions!
+(absolute) (localized) canonical names. This is different from previous webgen versions! However, it
+allows for using a naming scheme based on the source paths to be used independently from the output
+paths and therefore the output paths may change but no changes in the files themselves are needed.
 
 
 ## Output Path Name Construction ### {#source-output}
@@ -370,7 +428,7 @@ information key is an array which can have the following values:
 * strings (for inserting arbitrary text into output names)
 * arrays (for grouping values - only interesting for the language part)
 * symbols for inserting special values:
-  * `:cnbase`: The basename of the path.
+  * `:basename`: The basename of the path.
   * `:parent`: The parent path.
   * `:lang`: The language.
   * `:ext`: The file extension including the leading dot.
@@ -384,7 +442,7 @@ information key is an array which can have the following values:
 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/`):
 
-*   `output_path_style=[:parent, :cnbase, [., :lang], :ext]` (the default)
+*   `output_path_style=[:parent, :basename, [., :lang], :ext]` (the default)
 
     *   `index.jpg` --> `/img/index.jpg`
 
@@ -405,13 +463,13 @@ the default language and that the path is under a directory called `/img/`):
 
         Since `de` is not the default language, the language part is always used!
 
-*   `output_path_style=[:parent, :cnbase, :ext, ., :lang]`
+*   `output_path_style=[:parent, :basename, :ext, ., :lang]`
 
     *   `index.jpg` --> `/img/index.jpg.`
 
         Be aware of the trailing dot since the `:lang` value is not defined in a sub array!
 
-*   `output_path_style=[:parent, :year, /, :month, /, :cnbase, [., :lang], :ext]`
+*   `output_path_style=[:parent, :year, /, :month, /, :basename, [., :lang], :ext]`
 
     *   `index.jpg` --> `/img/2008/09/index.jpg`
 
@@ -537,14 +595,21 @@ There are several types of extensions:
     Webgen Page Format. It is not specified how they have to process the content but this type of
     extension can basically be divided into two groups:
 
-    * Markup processors: Processors like Maruku or RedCloth belong to this group and they convert
-      markup text that is easy to read and write to a more structure format like HTML. This allows
-      you to write an HTML page without knowing HTML.
+    * Text content processors: These processors are used to process textual content like files in
+      Webgen Page Format. This group can furthe be divided:
+
+        * Markup processors: Processors like Maruku or RedCloth belong to this group and they
+          convert markup text that is easy to read and write to a more structure format like HTML.
+          This allows you to write an HTML page without knowing HTML.
+
+        * String replacers: These processors normally process special strings and substitute them
+          with other content. For example, the `erb` processors replaces delimited strings
+          interpreted as Ruby code with the interpreted value. Another example would be webgen's
+          `tags` processor which replaces strings like `\{relocatable: ../index.html}` with a
+          processed value.
 
-    * String replacers: These processors normally process special strings and substitute them with
-      other content. For example, the `erb` processors replaces delimited strings interpreted as
-      Ruby code with the interpreted value. Another example would be webgen's `tags` processor which
-      replaces strings like `\{relocatable: ../index.html}` with a processed value.
+    * Binary content processors: These processors are used to process binary data. For example, one
+      might want to process an image to produce a thumbnailed version of it.
 
 *   **Source Handler**: These extensions are used for handling source paths. They read the content of
     a path and produce one or more nodes (the internal representation of an output path, see [source