thewoolleyman-webgen 0.5.8.20090419

data/doc/tag/link.page

@@ -0,0 +1,44 @@
+---
+title: Webgen::Tag::Link
+used_options:
+  - tag.link.path
+  - tag.link.attr
+---
+## Description
+
+This tag can be used to generate a link to an (absolute) (localized) canonical path. The generated
+link will behave exactly like the ones generated by, for example, the breadcrumb trail tag or the
+menu tag. So it respects the setting of the configuration option `website.link_to_current_page`
+which means that if this option is set to `false` only a `span` element and not an `a` element is
+created.
+
+The configuration option `tag.link.attr` lets you specify additional HTML options that should be set
+on the generated link. It can also be used to set the link text via the special `:link_text` key!
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{link: /default.css}</td>
+  <td>{link: /default.css}</td>
+</tr>
+<tr>
+  <td>\{link: link.html}</td>
+  <td>{link: link.html}</td>
+</tr>
+<tr>
+  <td>\{link: link.html#description}</td>
+  <td>{link: link.html#description}</td>
+</tr>
+<tr>
+  <td>\{link: ../}</td>
+  <td>{link: ../}</td>
+</tr>
+<tr>
+  <td>\{link: {path: relocatable.html, attr: {:link_text: A nicer link text, title: Just a title}}}</td>
+  <td>{link: {path: relocatable.html, attr: {:link_text: A nicer link text, title: Just a title}}}</td>
+</tr>
+</table>

data/doc/tag/menu.page

@@ -0,0 +1,106 @@
+---
+title: Webgen::Tag::Menu
+used_options:
+  - tag.menu.used_nodes
+  - tag.menu.start_level
+  - tag.menu.min_levels
+  - tag.menu.max_levels
+  - tag.menu.show_current_subtree_only
+  - tag.menu.nested
+---
+## Description
+
+The menu tag builds a seemingly simple menu using HTML lists. However, it is very flexible due to
+its many options that let you decide every detail of the menu.
+
+> The menu is constructed using HTML lists with `ul` and `li` tags.  However, the menu normally
+> looks better if no discs are shown for the menu items (using the CSS directive `list-style-type:
+> none`).
+{.information}
+
+It uses the meta information `in_menu` and `sort_info` to determine which nodes should be in the
+menu and how they should be ordered. A separate menu tree is then created from all nodes for each
+language.
+
+By setting the option `tag.menu.used_nodes` to `fragments`, the menu tag can also be used for
+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.
+{.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
+follows:
+
+* `webgen-menu-levelNUMBER`: Set on all menu items and can be used to style specific menu levels
+  only. `NUMBER` is replaced with the actual menu level, so the first level menu entries will get a
+  `webgen-menu-level1` class.
+* `webgen-menu-submenu`: Set if the menu item contains sub menu items.
+* `webgen-menu-submenu-inhierarchy`: Set if the menu item contains sub menu items and it is in the
+  sub tree of the rendered node.
+* `webgen-menu-item-selected`: Set if the menu item corresponds to the rendered node.
+
+The option `tag.menu.nested` decides whether a nested menu or a non-nested is generated. When
+setting this option to `false` you need to ensure that `tag.menu.show_current_subtree_only` is set
+to `true` and `tag.menu.min_levels` is set to `1`. Both ensure that no other subtree obfuscates the
+menu.
+
+> Set `tag.menu.nested` to `false` if you want to generate, for example, a horizontal menu, ie. a
+> menu that has one horizontal bar for each menu level.
+{.information}
+
+## "Static" Menus
+
+It is also possible to define a "static" menu or to augment the dynamic menu with static entries by
+using virtual files. They can be used to structure the menu the way you like it. This way it is also
+possible to add one page under two different headings:
+
+    features.en.html:
+      in_menu: true
+      title: Features
+      url: index.en.html#features
+
+    newdir:
+      sort_info: 2
+
+    newdir/new.en.html:
+      sort_info: 1
+      in_menu: true
+      url: ../features.en.html
+
+There is no need to specify `in_menu` for `newdir` since a page under the directory is in the
+menu. Also be aware that you need to set the language explicitly if a file should only appear in the
+menu for a specific language. Otherwise it appears in every menu. The `url` specifies the file that
+should be shown when clicked on the generated link.
+
+A completely "static" menu can be generated by only using virtual directories and files and not
+setting `in_menu` for any other node.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{menu: }</td>
+  <td>{menu:}</td>
+</tr>
+<tr>
+  <td>\{menu: {used_nodes: all}}</td>
+  <td>{menu: {used_nodes: all}}</td>
+</tr>
+<tr>
+  <td>\{menu: {used_nodes: files}}</td>
+  <td>{menu: {used_nodes: files}}</td>
+</tr>
+<tr>
+  <td>\{menu: {used_nodes: fragments}}</td>
+  <td>{menu: {used_nodes: fragments}}</td>
+</tr>
+<tr>
+  <td>\{menu: {used_nodes: all, nested: false}}</td>
+  <td>{menu: {used_nodes: all, nested: false}}</td>
+</tr>
+</table>

data/doc/tag/metainfo.page

@@ -0,0 +1,29 @@
+---
+title: Webgen::Tag::Metainfo
+---
+## Description
+
+The meta tag is used to copy meta information verbatim. It is used as fallback when no other tag
+class for a specific tag name could not be found. For example, if you define a meta information with
+the key `revision`, you can put the tag `\{revision:}` into a block of a page file and the value
+gets substituted automatically.
+
+An every day usage example for the meta tag would be including the title of a page in the
+`head`-section of a HTML template or specifying the language of the HTML file by using the
+`\{lang:}` tag.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{title: }</td>
+  <td>{title:}</td>
+</tr>
+<tr>
+  <td>\{lang: }</td>
+  <td>{lang:}</td>
+</tr>
+</table>

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.
+{.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
+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/tag/tikz.page

@@ -0,0 +1,158 @@
+---
+title: Webgen::Tag::TikZ
+used_options:
+  - tag.tikz.path
+  - tag.tikz.libraries
+  - tag.tikz.opts
+  - tag.tikz.resolution
+  - tag.tikz.transparent
+  - tag.tikz.img_attr
+---
+## Description
+
+This tag provides support for automatically generating graphics with the fantastic PGF/TikZ library
+for LaTeX. You will need to have a current LaTeX distribution with the PGF/TikZ library installed
+and ImageMagick for this to work. You will also need Ghostscript if you want support for transparent
+PNG images. More exactly, you will need to have the programs `pdflatex` (usually included in the
+LaTeX distribution - for generating a PDF from the LaTeX document that describes the PGF/TikZ
+graphic), `pdfcrop` (usually included in the LaTeX distribution - to crop the generated PDF and
+throw away useless borders), `convert` (provided by ImageMagick - to convert the generated PDF
+document to an image file format and to optionally resize them) and `gs` (provided by the
+Ghostscript package - to generate transparent PNG images).
+
+When using this tag, you need to set at least the default mandatory parameter `tag.tikz.path`. This
+path specifies the source path that should be used for generating the image and should not
+exist. The output path is dervied from this path the usual way. The extension used for this
+parameter specifies the final image format that is used (a good choice is PNG). All other parameters
+are optional. The commands for creating the PGF/TikZ picture are specified in the body of the
+tag. Have a look at some of the examples below to set the power of PGF/TikZ.
+
+If you want to generate transparent images, you will need to set `tag.tikz.transparent` to `true`
+and specify a `tag.tikz.path` with a `.png` extension.
+
+## Examples
+
+These examples are taken (sometimes a little bit altered) from the great PGF Manual included in the
+PGF/TikZ distribution.
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+
+<tr>
+  <td>
+  <pre>
+  \{tikz:: house.png}
+  \tikz \draw[thick,rounded corners=8pt]
+  (0,0) -- (0,2) -- (1,3.25) -- (2,2) -- (2,0) -- (0,2) -- (2,2) -- (0,0) -- (2,0);
+  {tikz}
+  </pre>
+  </td>
+  <td>
+  {tikz:: house.png}
+  \tikz \draw[thick,rounded corners=8pt]
+  (0,0) -- (0,2) -- (1,3.25) -- (2,2) -- (2,0) -- (0,2) -- (2,2) -- (0,0) -- (2,0);
+  {tikz}
+  </td>
+</tr>
+
+<tr>
+  <td>
+  <pre>
+  \{tikz:: {path: chain.png, libraries: [arrows,automata,shadows,positioning],
+    opts: "->,>=stealth,shorten >=1pt,auto,node distance=2.8cm,on grid,semithick,
+    every state/.style={fill=red,draw=none,circular drop shadow,text=white}",
+    resolution: 300 72}}
+\node[initial,state] (A) {$q_a$};
+\node[state] (B) [above right=of A] {$q_b$};
+\node[state] (D) [below right=of A] {$q_d$};
+\node[state] (C) [below right=of B] {$q_c$};
+\node[state] (E) [below=of D] {$q_e$};
+\path (A) edge node {0,1,L} (B)
+edge node {1,1,R} (C)
+(B) edge [loop above] node {1,1,L} (B)
+edge node {0,1,L} (C)
+(C) edge node {0,1,L} (D)
+edge [bend left] node {1,0,R} (E)
+(D) edge [loop below] node {1,1,R} (D)
+edge node {0,1,R} (A)
+(E) edge [bend left] node {1,0,R} (A);
+  {tikz}
+  </pre>
+  </td>
+  <td>
+  {tikz:: {path: chain.png, libraries: [arrows,automata,shadows,positioning],
+    opts: "->,>=stealth,shorten >=1pt,auto,node distance=2.8cm,on grid,semithick,
+    every state/.style={fill=red,draw=none,circular drop shadow,text=white}"}}
+\node[initial,state] (A) {$q_a$};
+\node[state] (B) [above right=of A] {$q_b$};
+\node[state] (D) [below right=of A] {$q_d$};
+\node[state] (C) [below right=of B] {$q_c$};
+\node[state] (E) [below=of D] {$q_e$};
+\path (A) edge node {0,1,L} (B)
+edge node {1,1,R} (C)
+(B) edge [loop above] node {1,1,L} (B)
+edge node {0,1,L} (C)
+(C) edge node {0,1,L} (D)
+edge [bend left] node {1,0,R} (E)
+(D) edge [loop below] node {1,1,R} (D)
+edge node {0,1,R} (A)
+(E) edge [bend left] node {1,0,R} (A);
+  {tikz}
+  </td>
+</tr>
+
+<tr>
+  <td>
+  Not transparent and standard res
+  <pre>
+  \{tikz:: {path: mindmap.png, libraries: [mindmap]}}
+  \path[mindmap,concept color=black,text=white]
+    node[concept] {Computer Science}
+    [clockwise from=0]
+    child[concept color=red] { node[concept] {technical} }
+    child[concept color=orange] { node[concept] {theoretical} };
+  {tikz}
+  </pre>
+  </td>
+  <td>
+  {tikz:: {path: mindmap.png, libraries: [mindmap]}}
+  \path[mindmap,concept color=black,text=white]
+    node[concept] {Computer Science}
+    [clockwise from=0]
+    child[concept color=red] { node[concept] {technical} }
+    child[concept color=orange] { node[concept] {theoretical} };
+  {tikz}
+  </td>
+</tr>
+
+<tr>
+  <td>
+  Transparent and high res
+  <pre>
+  \{tikz:: {path: mindmap-low.png, libraries: [mindmap],
+     img_attr: {style: 'background:transparent'},
+     transparent: true, resolution: 300 72}}
+  \path[mindmap,concept color=black,text=white]
+    node[concept] {Computer Science}
+    [clockwise from=0]
+    child[concept color=red] { node[concept] {technical} }
+    child[concept color=orange] { node[concept] {theoretical} };
+  {tikz}
+  </pre>
+  </td>
+  <td>
+  {tikz:: {path: mindmap-high.png, libraries: [mindmap],
+    img_attr: {style: 'background:transparent'},
+    transparent: true, resolution: 300 72}}
+  \path[mindmap,concept color=black,text=white]
+    node[concept] {Computer Science}
+    [clockwise from=0]
+    child[concept color=red] { node[concept] {technical} }
+    child[concept color=orange] { node[concept] {theoretical} };
+  {tikz}
+  </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.