RubyGems - webgen - Versions diffs - 0.5.5 → 0.5.6 - Mend

webgen 0.5.5 → 0.5.6

Files changed (101) hide show

data/ChangeLog +3662 -0
data/Rakefile +8 -1
data/VERSION +1 -1
data/data/webgen/website_styles/1024px/src/default.template +1 -1
data/data/webgen/website_styles/andreas00/src/default.template +1 -1
data/data/webgen/website_styles/andreas01/src/default.template +2 -1
data/data/webgen/website_styles/andreas03/src/default.template +1 -1
data/data/webgen/website_styles/andreas04/src/default.template +1 -1
data/data/webgen/website_styles/andreas05/src/default.template +1 -1
data/data/webgen/website_styles/andreas06/src/default.template +1 -1
data/data/webgen/website_styles/andreas07/src/default.template +1 -1
data/data/webgen/website_styles/andreas08/src/default.template +1 -1
data/data/webgen/website_styles/andreas09/src/default.template +1 -1
data/data/webgen/website_styles/simple/src/default.template +1 -1
data/doc/contentprocessor/fragments.page +25 -0
data/doc/extensions.page +1 -1
data/doc/manual.page +33 -15
data/doc/reference_configuration.page +339 -62
data/doc/reference_metainfo.page +11 -2
data/doc/sourcehandler/feed.page +19 -4
data/doc/sourcehandler/page.page +0 -16
data/doc/tag/langbar.page +8 -1
data/doc/tag/link.page +44 -0
data/doc/tag/tikz.page +158 -0
data/lib/webgen/cli.rb +4 -4
data/lib/webgen/common/sitemap.rb +2 -3
data/lib/webgen/configuration.rb +3 -1
data/lib/webgen/contentprocessor.rb +1 -0
data/lib/webgen/contentprocessor/blocks.rb +0 -2
data/lib/webgen/contentprocessor/context.rb +0 -3
data/lib/webgen/contentprocessor/erubis.rb +0 -2
data/lib/webgen/contentprocessor/fragments.rb +23 -0
data/lib/webgen/default_config.rb +15 -2
data/lib/webgen/languages.rb +9 -0
data/lib/webgen/logger.rb +18 -1
data/lib/webgen/node.rb +50 -25
data/lib/webgen/page.rb +26 -16
data/lib/webgen/path.rb +20 -10
data/lib/webgen/sourcehandler.rb +85 -69
data/lib/webgen/sourcehandler/base.rb +38 -15
data/lib/webgen/sourcehandler/copy.rb +2 -2
data/lib/webgen/sourcehandler/directory.rb +16 -13
data/lib/webgen/sourcehandler/feed.rb +6 -12
data/lib/webgen/sourcehandler/fragment.rb +6 -11
data/lib/webgen/sourcehandler/memory.rb +41 -0
data/lib/webgen/sourcehandler/metainfo.rb +21 -21
data/lib/webgen/sourcehandler/page.rb +7 -27
data/lib/webgen/sourcehandler/sitemap.rb +0 -2
data/lib/webgen/sourcehandler/template.rb +0 -4
data/lib/webgen/sourcehandler/virtual.rb +18 -18
data/lib/webgen/tag.rb +2 -0
data/lib/webgen/tag/breadcrumbtrail.rb +1 -4
data/lib/webgen/tag/coderay.rb +0 -3
data/lib/webgen/tag/date.rb +0 -2
data/lib/webgen/tag/executecommand.rb +1 -2
data/lib/webgen/tag/includefile.rb +1 -3
data/lib/webgen/tag/langbar.rb +2 -5
data/lib/webgen/tag/link.rb +23 -0
data/lib/webgen/tag/menu.rb +1 -4
data/lib/webgen/tag/metainfo.rb +0 -2
data/lib/webgen/tag/relocatable.rb +2 -3
data/lib/webgen/tag/sitemap.rb +0 -3
data/lib/webgen/tag/tikz.rb +117 -0
data/lib/webgen/tree.rb +11 -6
data/lib/webgen/version.rb +1 -1
data/lib/webgen/website.rb +2 -1
data/test/test_cli.rb +14 -0
data/test/test_common_sitemap.rb +4 -4
data/test/test_contentprocessor_context.rb +1 -1
data/test/test_contentprocessor_fragments.rb +40 -0
data/test/test_contentprocessor_redcloth.rb +1 -0
data/test/test_contentprocessor_tags.rb +1 -1
data/test/test_languages.rb +12 -0
data/test/test_logger.rb +19 -0
data/test/test_node.rb +35 -15
data/test/test_output_filesystem.rb +1 -1
data/test/test_page.rb +15 -6
data/test/test_path.rb +37 -5
data/test/test_source_filesystem.rb +1 -1
data/test/test_source_stacked.rb +1 -1
data/test/test_sourcehandler_base.rb +30 -1
data/test/test_sourcehandler_copy.rb +1 -1
data/test/test_sourcehandler_directory.rb +16 -1
data/test/test_sourcehandler_feed.rb +9 -8
data/test/test_sourcehandler_fragment.rb +1 -1
data/test/test_sourcehandler_memory.rb +42 -0
data/test/test_sourcehandler_metainfo.rb +23 -21
data/test/test_sourcehandler_page.rb +5 -12
data/test/test_sourcehandler_template.rb +1 -1
data/test/test_sourcehandler_virtual.rb +2 -2
data/test/test_tag_base.rb +0 -1
data/test/test_tag_breadcrumbtrail.rb +4 -4
data/test/test_tag_includefile.rb +3 -3
data/test/test_tag_langbar.rb +12 -7
data/test/test_tag_link.rb +61 -0
data/test/test_tag_menu.rb +7 -7
data/test/test_tag_metainfo.rb +1 -1
data/test/test_tag_relocatable.rb +1 -1
data/test/test_tag_tikz.rb +66 -0
data/test/test_tree.rb +8 -9
metadata +15 -2

data/Rakefile CHANGED

@@ -98,6 +98,7 @@ EOF
                             'Rakefile',
                             'setup.rb',
                             'VERSION',
+                            'ChangeLog',
                             'AUTHORS',
                             'THANKS',
                             'COPYING',
@@ -120,6 +121,12 @@ EOF
     File.open('VERSION', 'w+') {|file| file.write(Webgen::VERSION + "\n")}
   end
+  CLOBBER << 'ChangeLog'
+  file 'ChangeLog' do
+    puts "Generating ChangeLog file"
+    `git log --name-only > ChangeLog`
+  end
   Rake::PackageTask.new('webgen', Webgen::VERSION) do |pkg|
     pkg.need_tar = true
     pkg.need_zip = true
@@ -194,7 +201,7 @@ EOF
     task :gemspec do
       spec.version = Webgen::VERSION + '.' + Time.now.strftime('%Y%m%d')
       spec.summary = 'webgen beta build, not supported!!!'
-      spec.files = spec.files.reject {|f| f == 'VERSION'}
+      spec.files = spec.files.reject {|f| f == 'VERSION' || f == 'ChangeLog'}
       spec.post_install_message = "

data/VERSION CHANGED

	@@ -1 +1 @@
1	- 0.5.5
1	+ 0.5.6

data/data/webgen/website_styles/1024px/src/default.template CHANGED

@@ -35,7 +35,7 @@
         <p>Write a short presentation of yourself or the site right here!</p>
         <h2>Pages:</h2>
-        <div id="menu">{menu: {max_levels: 2}}</div>
+        <div id="menu">{menu: {max_levels: 2, used_nodes: files}}</div>
         <h2>Site news:</h2>
         <p><strong>09.09.2009</strong><br />

data/data/webgen/website_styles/andreas00/src/default.template CHANGED

@@ -20,7 +20,7 @@
       <div id="avmenu">
         <h2 class="hide">Site menu:</h2>
-        {menu: }
+        {menu: {used_nodes: files}}
         <div class="announce">
           <h2>Latest news:</h2>

data/data/webgen/website_styles/andreas01/src/default.template CHANGED

@@ -1,3 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="{lang:}">
@@ -24,7 +25,7 @@
       <div id="leftside">
         <h2 class="hide">Menu:</h2>
-        <div id="menu">{menu: }</div>
+        <div id="menu">{menu: {used_nodes: files}}</div>
         <div class="announce">
           <h2>Latest news:</h2>

data/data/webgen/website_styles/andreas03/src/default.template CHANGED

@@ -37,7 +37,7 @@
       <div id="sidebar">
         <h2 class="sidelink menuheader"><a id="sitemenu"></a>Menu:</h2>
-        <div id="menu">{menu: {max_levels: 1}}</div>
+        <div id="menu">{menu: {max_levels: 1, used_nodes: files}}</div>
         <a class="hide" href="#top" accesskey="1">Top of page</a>
         <h3>Regular links</h3>

data/data/webgen/website_styles/andreas04/src/default.template CHANGED

@@ -19,7 +19,7 @@
       </div>
       <div id="menu">
-        {menu: {max_levels: 1}}
+        {menu: {max_levels: 1, used_nodes: files}}
       </div>
       <div id="content">

data/data/webgen/website_styles/andreas05/src/default.template CHANGED

@@ -17,7 +17,7 @@
       <div id="sidebar">
         <h2>Site menu</h2>
-        <div id="menu">{menu: {max_levels: 1}}</div>
+        <div id="menu">{menu: {max_levels: 1, used_nodes: files}}</div>
         <p class="sidenote">
           Links:<br />

data/data/webgen/website_styles/andreas06/src/default.template CHANGED

@@ -23,7 +23,7 @@
       </div>
       <div id="nav">
-        {menu: {max_levels: 1}}
+        {menu: {max_levels: 1, used_nodes: files}}
         <p class="hide"><a href="#top">Back to top</a></p>
       </div>

data/data/webgen/website_styles/andreas07/src/default.template CHANGED

@@ -20,7 +20,7 @@
       <h2>your website slogan</h2>
       <div id="menu">
-        {menu: {max_levels: 1}}
+        {menu: {max_levels: 1, used_nodes: files}}
       </div>
       <h3>Links:</h3>

data/data/webgen/website_styles/andreas08/src/default.template CHANGED

@@ -19,7 +19,7 @@
       </div>
       <div id="navigation">
-        {menu: {max_levels: 1}}
+        {menu: {max_levels: 1, used_nodes: files}}
       </div>
       <div id="content">

data/data/webgen/website_styles/andreas09/src/default.template CHANGED

@@ -20,7 +20,7 @@
       </div>
       <div id="mainmenu">
-        {menu: {max_levels: 1}}
+        {menu: {max_levels: 1, used_nodes: files}}
       </div>
       <div id="wrap">

data/data/webgen/website_styles/simple/src/default.template CHANGED

@@ -22,7 +22,7 @@
     </div>
     <div id="menu">
-      {menu: }
+      {menu: {used_nodes: files}}
     </div>
     <div id="body">

data/doc/contentprocessor/fragments.page ADDED

@@ -0,0 +1,25 @@
+---
+title: Webgen::ContentProcessor::Fragments
+---
+## Description
+This processor generates nested fragment nodes from all headers `h1` to `h6` which have an `id`
+attribute set.
+> This is only done for the block named `content` or if no block is associated with the given render
+> 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}
+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.
+> The reason why only header tags with an `id` attribute are used is that only those can be
+> referenced and linked to later.
+{.information}
+The generated fragment nodes can be used like any other node. So you can link to them and use them
+in a menu. Concerning the menu, there is a setting for the `tag.menu.used_nodes` option called
+`fragments` which only uses the fragment node of the current page to generate a menu. This allows to
+generate a nice overview of the page.

data/doc/extensions.page CHANGED

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

data/doc/manual.page CHANGED

@@ -429,21 +429,6 @@ As you might have deduced from the processing list above, it is possible that on
 multiple source handlers. This can be used, for example, to render an XML file as HTML and copy it
 verbatim.
-Internally a tree structure is created reflecting the source directory hierarchy and each path that
-is handled by webgen. Normally a source handler creates one node from one path but it is also
-possible that a source handler creates multiple nodes from one path.
-> The name used for describing a directory or file once it is placed in the internal tree structure
-> is 'node'.
-{.information}
-After this internal tree structure is created, it is traversed and each node is processed. First the
-node is checked if has changed (the notion of 'changed' depends on many things but a node is
-changed, for example, if its meta information or the associated source path has changed since the
-last webgen run). If it has not changed, nothing needs to be written. Otherwise, the information
-needed to write out the node is gathered and its content is written to the output path represented
-by the node.
 ## Path Meta Information {#source-metainfo}
@@ -521,6 +506,39 @@ There are several types of extensions:
+# A webgen Run
+When webgen is started, it first looks for a cache file and uses it if it exists. The cache file
+provides information on the previous run and allows webgen to render only those paths that have
+changed since the last time.
+Each webgen run consists of one or more update/write cycles. During the update phase the internal
+tree structure is updated to reflect the current situation:
+* Nodes are created from newly found source paths.
+* If a source path was deleted since the last webgen run, the nodes created from it will be deleted.
+* All nodes in the tree are checked if they have changed and, if so, are marked for regeneration.
+> The name used for describing a directory or file once it is placed in the internal tree structure
+> is 'node'.
+{.information}
+After the update cycle has finished, the internal tree representation is up-to-date and contains all
+necessary information to write its nodes. This is done in the write phase which writes out all
+changed nodes.
+It is possible that the internal tree structure changes during the write phase. For example, after
+writing a page file fragments node for it may have been generated. After the write phase it is
+checked if something like this has happened. If webgen finds such a condition, a new update/write
+cycle is initiated. This is done as long as needed.
+Since it is possible that multiple update/write cycles are used in one webgen run, it is shown in
+the log messages when a new cycle started. This is necessary because sometimes some warning or error
+log messages may be generated during an earlier cycle but the error conditions are automatically
+solved in later cycles. By marking where the cycles start a user can compare the log messages of the
+different cycles and see what he needs to solve himself.
 # Extending webgen
 If you know the programming language Ruby a little bit, you can easily extend webgen and add new

data/doc/reference_configuration.page CHANGED

@@ -5,8 +5,14 @@ in_menu: false
 # Configuration Option Reference
-This reference describes all available configurations that can be set via the configuration file
-(or, if you want to have more control, via an extension file).
+This reference describes all available configurations that can be set via the [configuration
+file]({relocatable: manual.html#website-configfile}) `config.yaml` (or, if you want to have more
+control, via an extension file).
+The reference is splitted into sections to provide better navigation. A sub header under a category
+always specifies the name of a configuration option and after that comes a description and example
+code. The example code either shows how to set this option in the configuration file (for most
+configuration options) and/or how to use it in a webgen tag (for tag configuration options).
 ## General Options
@@ -17,10 +23,9 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `LANGUAGE` where `LANGUAGE` is a ISO-639-1/2 two or three letter language code
-    * Examples:
+    * Example for setting the option in the configuration file:
-          website.lang: deu
-          website.lang: fr
+          website.lang: de
 *   ### website.link\_to\_current\_page
@@ -30,7 +35,7 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `BOOLEAN` where `BOOLEAN` is `true` or `false`
-    * Examples:
+    * Example for setting the option in the configuration file:
           website.link_to_current_page: false
@@ -44,7 +49,7 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `[TYPE, LOCATION]` where `TYPE` is one of `:file` or `:string`
-    * Examples:
+    * Example for setting the option in the configuration file:
           website.cache: [:file, my.cache]
@@ -58,7 +63,11 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          common.sitemap.honor_in_menu: true
+      Example for setting the option directly in a tag:
           Sitemap with in-menu nodes: \{sitemap: {honor_in_menu: true}}
@@ -70,7 +79,11 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          common.sitemap.any_lang: true
+      Example for setting the option directly in a tag:
           Sitemap with nodes in any language: \{sitemap: {any_lang: true}}
@@ -82,7 +95,11 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `[KIND, ...]` where `KIND` is the kind of node that should be used.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          common.sitemap.used_kinds: [asset]
+      Example for setting the option directly in a tag:
           Sitemap with only asset nodes: \{sitemap: {used_kinds: [asset]}}
@@ -100,7 +117,7 @@ This reference describes all available configurations that can be set via the co
       `Webgen::Source::FileSystem`) and `ARG1`, `ARG2` and so on are the parameters for the source
       class. The supported parameters can be found in the documentation for each source class.
-    * Examples:
+    * Example for setting the option in the configuration file:
           sources: [[/, Webgen::Source::FileSystem, src], [/, Webgen::Source::FileSystem, /mnt/pictures, **/*.jpg]
@@ -113,7 +130,7 @@ This reference describes all available configurations that can be set via the co
       `Webgen::Output::FileSystem`) and `ARG1`, `ARG2` and so on are the parameters for the output
       class. The supported parameters can be found in the documentation for each output class.
-    * Examples:
+    * Example for setting the option in the configuration file:
           output: [Webgen::Output::FileSystem, custom_out]
@@ -121,15 +138,23 @@ This reference describes all available configurations that can be set via the co
 *   ### sourcehandler.patterns
     Specifies the path patterns that are used by the individual source handlers. This configuration
-    option is not normally set in the configuration file but in an extension file
-    (e.g. `ext/init.rb`) because otherwise the default entries would be overwritten.
+    option is not normally set directly in the configuration file but either in an extension file
+    (e.g. `ext/init.rb`) or using a [configuration file helper]({relocatable:
+    manual.html#website-configfile}) because otherwise the default entries would be overwritten.
     * Syntax: `\{NAME: [PATTERN, PATTERN, ...], ...}` where `NAME` is the
       name the name of a source handler and `PATTERN` are one or more path patterns.
-    * Examples (for `ext/init.rb`):
+    * Example for setting the option in `ext/init.rb`:
+          config = Webgen::WebsiteAccess.website.config
+          config['sourcehandler.patterns']['Webgen::SourceHandler::Copy'] << '**/*.swf'
-          config.sourcehandler.patterns['Webgen::SourceHandler::Copy'] << '**/*.swf'
+      Example for setting the option via the configuration file helper in the configuration file:
+          patterns:
+            Copy:
+              add: [**/*.swf]
 *   ### sourcehandler.invoke
@@ -141,9 +166,10 @@ This reference describes all available configurations that can be set via the co
       invocation (source handlers with a lower `ORDER` setting are executed earlier than ones with a
       higher `ORDER` setting) and `NAME` is the name of a source handler.
-    * Examples (for `ext/init.rb`):
+    * Example for setting the option in `ext/init.rb`:
-          config.sourcehandler.invoke[5] << 'Extension::MyNewSourceHandler'
+          config = Webgen::WebsiteAccess.website.config
+          config['sourcehandler.invoke'][5] << 'Extension::MyNewSourceHandler'
 *   ### sourcehandler.casefold
@@ -153,7 +179,7 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
           sourcehandler.casefold: true
@@ -164,7 +190,7 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
           sourcehandler.use_hidden_files: true
@@ -176,7 +202,7 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `[PATTERN, ...]` where `PATTERN` is a valid path pattern.
-    * Examples:
+    * Example for setting the option in the configuration file:
           sourcehandler.ignore: [**/*~, **/CVS/**]
@@ -188,7 +214,7 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
           sourcehandler.default_lang_in_output_path: true
@@ -202,7 +228,7 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `\{NAME: {MI_KEY: MI_VALUE, ...}, ...}` where `NAME` is either the name of a source
       handler or the special key `:all` which sets default meta info for all source handlers.
-    * Examples:
+    * Example for setting the option in the configuration file:
           default_meta_info:
             :all:
@@ -218,7 +244,7 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `PATH` where `PATH` is the absolute localized canonical name of the default template.
-    * Examples:
+    * Example for setting the option in the configuration file:
           sourcehandler.template.default_template: other.template
@@ -235,8 +261,9 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `\{SHORT: NAME, ...}` where `SHORT` is the short name of the content processor class
       `NAME`.
-    * Examples (for `ext/init.rb`):
+    * Examples for setting the option in `ext/init.rb`:
+          config = Webgen::WebsiteAccess.website.config
           config['contentprocessor.map']['newcp'] = 'Extension::MyNewContentProcessor'
@@ -247,7 +274,7 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
           contentprocessor.erubis.use_pi: true
@@ -260,7 +287,7 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `\{KEY: VALUE, ...}` where `KEY` and `VALUE` are key-value pairs of options where
       `KEY` needs to be a Symbol and not a String.
-    * Examples:
+    * Example for setting the option in the configuration file:
           contentprocessor.erubis.options: {:trim: true}
@@ -272,10 +299,9 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `PREFIX` where `PREFIX` is the prefix name.
-    * Examples:
+    * Example for setting the option in the configuration file:
           contentprocessor.tags.prefix: webgen
-          contentprocessor.tags.prefix: tag
 *   ### contentprocessor.tags.map
@@ -286,16 +312,18 @@ This reference describes all available configurations that can be set via the co
     * Syntax: `\{SHORT: NAME, ...}` where `SHORT` is the short name of the tag class `NAME`.
-    * Examples (for `ext/init.rb`):
+    * Example for setting the option in `ext/init.rb`:
+          config = Webgen::WebsiteAccess.website.config
           config['contentprocessor.tags.map']['highlight'] = 'Extension::MyHighlightingTag'
 ## Tag Specific Options
 These options are not normally set in the configuration file but given directly as options to the
-respective tag classes. Therefore, all examples in this section show the use of these options in
-files in Webgen Page Format.
+respective tag classes. Therefore, all options described in this section have an example which shows
+how to use the option in files in Webgen Page Format and most options also have an example which
+shows how to set the option in the configuration file.
 *   ### tag.breadcrumbtrail.separator
@@ -305,7 +333,11 @@ files in Webgen Page Format.
     * Syntax: `SEPARATOR` where `SEPARATOR` is a string (special HTML characters need to be properly
       escaped)
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.breadcrumbtrail.separator: '---'
+      Example for setting the option directly in a tag:
           Breadcrumb trail with different separator: \{breadcrumb_trail: {separator: ' --- '}}
@@ -316,7 +348,11 @@ files in Webgen Page Format.
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.breadcrumbtrail.omit_index_path: true
+      Example for setting the option directly in a tag:
           Breadcrumb trail with index path omitted: \{breadcrumb_trail: {omit_index_path: true}}
@@ -337,7 +373,11 @@ files in Webgen Page Format.
     * Syntax: `INTEGER` where `INTEGER` is any integer number
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.breadcrumbtrail.start_level: 2
+      Example for setting the option directly in a tag:
           Breadcrumb trail starting at level 2: \{breadcrumb_trail: {start_level: 2}}
@@ -349,7 +389,11 @@ files in Webgen Page Format.
     * Syntax: `INTEGER` where `INTEGER` is any integer number
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.breadcrumbtrail.end_level: 2
+      Example for setting the option directly in a tag:
           Breadcrumb trail ending at level 2: \{breadcrumb_trail: {end_level: 2}}
@@ -360,7 +404,11 @@ files in Webgen Page Format.
     * Syntax: `LANG` where `LANG` is one of <%= (require 'coderay'; CodeRay::Scanners.list.map {|n| '`' + n + '`'}.join(', ')) %>.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.coderay.lang: ruby
+      Example for setting the option directly in a tag:
           highlighting some ruby code \{coderay:: ruby}puts 5 + 5{coderay}
@@ -371,7 +419,11 @@ files in Webgen Page Format.
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.coderay.process_body: false
+      Example for setting the option directly in a tag:
           wrapping in a span: \{coderay:: {lang: ruby, process_body: false}}puts 5 + 5{coderay}
@@ -382,7 +434,11 @@ files in Webgen Page Format.
     * Syntax: `WRAP` where `WRAP` is either `div` or `span`
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.coderay.wrap: span
+      Example for setting the option directly in a tag:
           wrapping in a span: \{coderay:: {lang: ruby, wrap: span}}puts 5 + 5{coderay}
@@ -393,7 +449,11 @@ files in Webgen Page Format.
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.coderay.line_numbers: false
+      Example for setting the option directly in a tag:
           not showing line numbers: \{coderay:: {lang: ruby, line_numbers: false}}puts 5 + 5{coderay}
@@ -404,7 +464,11 @@ files in Webgen Page Format.
     * Syntax: `NUMBER` where `NUMBER` is an integer value.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.coderay.line_number_start: 4
+      Example for setting the option directly in a tag:
           starting with line 4: \{coderay:: {lang: ruby, line_number_start: 4}}puts 5 + 5{coderay}
@@ -415,7 +479,11 @@ files in Webgen Page Format.
     * Syntax: `NUMBER` where `NUMBER` is an integer value.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.coderay.bold_every: 2
+      Example for setting the option directly in a tag:
           every other line bold: \{coderay:: {lang: ruby, bold_every: 2}}puts 5 + 5{coderay}
@@ -426,7 +494,11 @@ files in Webgen Page Format.
     * Syntax: `NUMBER` where `NUMBER` is an integer value.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.coderay.tab_width: 4
+      Example for setting the option directly in a tag:
           tabulator == 4 spaces: \{coderay:: {lang: ruby, tab_width: 4}}puts 5 + 5{coderay}
@@ -439,7 +511,11 @@ files in Webgen Page Format.
     * Syntax: `FORMAT` where `FORMAT` is a string.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.date.format: '%Y-%m-%d'
+      Example for setting the option directly in a tag:
           very short date format: \{date: {format: '%Y-%m-%d'}}
@@ -451,7 +527,7 @@ files in Webgen Page Format.
     * Syntax: `COMMAND` where `COMMAND` is the to-be-executed command.
-    * Examples:
+    * Example for setting the option directly in a tag:
           executing a simple command \{exeucte_cmd: echo hallo}
@@ -463,7 +539,11 @@ files in Webgen Page Format.
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.executecommand.process_output: false
+      Example for setting the option directly in a tag:
           executing command without further processing \{execute_cmd: {command: 'echo hallo', process_output: false}}
@@ -474,7 +554,11 @@ files in Webgen Page Format.
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.executecommand.escape_html: false
+      Example for setting the option directly in a tag:
           executing command, output not escaped \{execute_cmd: {command: 'echo hallo', escape_html: false}}
@@ -487,7 +571,7 @@ files in Webgen Page Format.
     * Syntax: `FILENAME` where `FILENAME` is the name of a file
-    * Examples:
+    * Example for setting the option directly in a tag:
           including a file \{include_file: my_file.txt}
@@ -499,7 +583,11 @@ files in Webgen Page Format.
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.includefile.process_output: false
+      Example for setting the option directly in a tag:
           including a file without further processing \{include_file: {filename: my_file.txt, process_output: false}}
@@ -510,7 +598,11 @@ files in Webgen Page Format.
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.includefile.escape_html: false
+      Example for setting the option directly in a tag:
           including a file without escaping \{include_file: {filename: my_file.txt, escape_html: false}}
@@ -522,7 +614,11 @@ files in Webgen Page Format.
     * Syntax: `SEPARATOR` where `SEPARATOR` is a string (special HTML characters need to be properly
       escaped)
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.langbar.separator: ' --- '
+      Example for setting the option directly in a tag:
           Langbar with another separator: \{langbar: {separator: ' --- '}}
@@ -533,7 +629,11 @@ files in Webgen Page Format.
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.langbar.show_own_lang: false
+      Example for setting the option directly in a tag:
           Langbar with current page's lang not shown: \{langbar: {show_own_lang: false}}
@@ -545,11 +645,60 @@ files in Webgen Page Format.
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.langbar.show_single_lang: false
+      Example for setting the option directly in a tag:
           Langbar with single language not shown: \{langbar: {show_single_lang: false}}
+*   ### tag.langbar.lang\_names
+    This configuration option can be used to specify the language names that should be displayed
+    instead of the language codes.
+    * Syntax: `\{CODE: NAME, ...}` where `CODE` is a language code and `NAME` the associated language
+      name of the code.
+    * Example for setting the option in the configuration file:
+          tag.langbar.lang_names: \{de: Deutsch, en: English}
+      Example for setting the option directly in a tag:
+          Langbar with custom language names: \{langbar: {lang_names: {de: Deutsch, en: English}}}
+*   ### tag.link.path
+    The default mandatory configuration option for Tag::Link that specifies the (AL)CN path to which
+    should be linked.
+    * Syntax: `PATH` where `PATH` is an (absolute) (localized) canonical name.
+    * Example for setting the option directly in a tag:
+          You will find more information on the \{link: docu.html} page!
+*   ### tag.link.attr
+    Specifies additional HTML attributes that should be set on the link generated by Tag::Link.
+    * Syntax: `\{NAME: VALUE, ...}` where `NAME` is a valid HTML attribute name and `VALUE` its
+      value.
+    * Example for setting the option in the configuration file:
+          tag.link.attr: \{title: DocuPage}
+      Example for setting the option directly in a tag:
+          You will find more info on the \{link: {path: docu.html, attr: {title: DocuPage}}} page!
 *   ### tag.menu.used\_nodes
     Specifies the type of nodes that should be used for menu generation. If `all` is specified then
@@ -559,7 +708,11 @@ files in Webgen Page Format.
     * Syntax: `TYPE` where `TYPE` is one of `all`, `files` or `fragments`
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.menu.used_nodes: fragments
+      Example for setting the option directly in a tag:
           Show the fragment node menu: \{menu: {used_nodes: fragments}}
@@ -571,7 +724,11 @@ files in Webgen Page Format.
     * Syntax: `LEVEL` where `LEVEL` is a number that is greater or equal to one.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.menu.start_level: 2
+      Example for setting the option directly in a tag:
           Menu starting at level 2: \{menu: {start_level: 2}}
@@ -583,7 +740,11 @@ files in Webgen Page Format.
     * Syntax: `LEVEL` where `LEVEL` is a number that is greater or equal to one.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.menu.min_levels: 2
+      Example for setting the option directly in a tag:
           Menu that always shows at least 2 levels : \{menu: {min_levels: 2}}
@@ -595,7 +756,11 @@ files in Webgen Page Format.
     * Syntax: `LEVEL` where `LEVEL` is a number that is greater or equal to one.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.menu.max_levels: 2
+      Example for setting the option directly in a tag:
           Menu that always shows at most 2 levels : \{menu: {max_levels: 2}}
@@ -608,7 +773,11 @@ files in Webgen Page Format.
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.menu.show_current_subtree_only: false
+      Example for setting the option directly in a tag:
           Showing all subtrees: \{menu: {show_current_subtree_only: false}}
@@ -641,7 +810,11 @@ files in Webgen Page Format.
     * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
-    * Examples:
+    * Example for setting the option in the configuration file:
+          tag.menu.nested: false
+      Example for setting the option directly in a tag:
           Don't use nested lists: \{menu: {nested: false}}
@@ -649,16 +822,120 @@ files in Webgen Page Format.
 *   ### tag.relocatable.path
     The default mandatory configuration option for Tag::Relocatable that specifies the path that
-    should be made relocatable. This option is the default mandatory option for
-    Webgen::Tag::Relocatable.
+    should be made relocatable.
     * Syntax: `PATH` where `PATH` is a (localized) canonical name.
-    * Examples:
+    * Example for setting the option directly in a tag:
           <a href="\{relocatable: ../features.html}">Some Path</a>
+*   ### tag.tikz.path
+    The default mandatory configuration option for Tag::TikZ that specifies the (naturally
+    non-existing) source path that should be used for creating the TikZ image. The output path is
+    derived from this path the usual way. You shouldn't use a path that does already exist!
+    * Syntax: `PATH` where `PATH` is a relative or absolute source path.
+    * Example for setting the option directly in a tag:
+          \{tikz:: images/tikz.png}\tikz \draw (0,0) -- (0,2);{tikz}
+*   ### tag.tikz.libraries
+    Specifies the names of additional TikZ library names that should be used when creating the
+    image.
+    * Syntax: `[NAME, ...]` where `NAME` is the name of a TikZ library.
+    * Example for setting the option in the configuration file:
+          tag.tikz.libraries: [mindmap, arrows]
+      Example for setting the option directly in a tag:
+          \{tikz:: {path: images/tikz.png, libraries: [mindmap, arrows]}}
+          \tikz \draw (0,0) -- (0,2) -- (2,2);
+          {tikz}
+*   ### tag.tikz.opts
+    Specifies additional global options for the `tikzpicture` environment.
+    * Syntax: `OPTS` where `OPTS` is the string with the global options.
+    * Example for setting the option in the configuration file:
+          tag.tikz.opts: 'scale=3, line cap=round'
+      Example for setting the option directly in a tag:
+          \{tikz:: {path: images/tikz.png, opts: 'scale=3, line cap=round'}}
+          \tikz \draw (0,0) -- (0,2) -- (2,2);
+          {tikz}
+*   ### tag.tikz.resolution
+    Specifies the render and output resolutions that should be used to convert the TikZ image in PDF
+    format to the chosen image format. The first number specifies the render resolution and the
+    second one the output resolution. If the render resolution is higher than the output resolution,
+    the final image quality is better but the image needs to scaled down to the output resolution.
+    * Syntax: `RENDER_RES OUTPUT_RES` where `RENDER_RES` is the integer specifying the render
+      resolution and `OUTPUT_RES` is the integer specifying the output resolution.
+    * Example for setting the option in the configuration file:
+          tag.tikz.resolution: 300 72
+      Example for setting the option directly in a tag:
+          \{tikz:: {path: images/tikz.png, resolution: 300 72}}
+          \tikz \draw (0,0) -- (0,2) -- (2,2);
+          {tikz}
+*   ### tag.tikz.transparent
+    Specifies whether the generated image should be transparent. This only works when the path
+    specified by `tag.tikz.path` option has the extension `.png`! You should probably also set the
+    background of the generated image tag to transparent.
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+    * Example for setting the option in the configuration file:
+          tag.tikz.transparent: true
+      Example for setting the option directly in a tag:
+          \{tikz:: {path: images/tikz.png, transparent: true}}
+          \tikz \draw (0,0) -- (0,2) -- (2,2);
+          {tikz}
+*   ### tag.tikz.img\_attr
+    Specifies additional HTML attributes that should be set on the generated `img` tag.
+    * Syntax: `\{KEY:VALUE, ...}` where `KEY` is a valid HTML `img` tag attribute name and `VALUE`
+      the to-be-set value.
+    * Example for setting the option in the configuration file:
+          tag.tikz.img_attr: \{alt: Some TikZ picture}
+      Example for setting the option directly in a tag:
+          \{tikz:: {path: images/tikz.png, img_attr: {alt: Some TikZ picture}}}
+          \tikz \draw (0,0) -- (0,2) -- (2,2);
+          {tikz}
 ---
 ## Miscelleanous Configuration Options