webgen 0.4.1 → 0.4.2

data/doc/src/documentation/plugins/contentconverter/default.page

@@ -2,6 +2,7 @@
 title: Default
 directoryName: ContentConverter
 inMenu: true
+omitIndexFileInBreadcrumbTrail: false
 template: /plugin.template
 plugin: ContentConverter/Default
 ---

data/doc/src/documentation/plugins/contentconverter/xmlbuilder.page

@@ -40,8 +40,8 @@ The above will produce the following output:
 <pre>
 <persons>
   <person>
-  <firstname>Thomas</firstname>
-  <lastname>Leitner</lastname>
+    <firstname>Thomas</firstname>
+    <lastname>Leitner</lastname>
   </person>
   <person>
     <firstname>Other first</firstname>

data/doc/src/documentation/plugins/core/configuration.page

@@ -9,3 +9,9 @@ h2(#description). Description
 
 The configuration plugin provides a place for all the parameters which do not belong to a specific
 plugin, like the default language setting.
+
+It also provides support for "custom variables" through the {param: Core/Configuration:customVars}
+parameter. This facility can be used to store and access global variables that have been defined in
+the <a href="{relocatable: /documentation/basics.page#config}">configuration file</a> through, for
+example, the {plugin: Tag/CustomVar} plugin.
+

data/doc/src/documentation/plugins/core/resourcemanager.page

@@ -34,13 +34,7 @@ Speaking of the output path, each resource has four properties:
 h2(#resources). Predefined Resources
 
 A reason why webgen has a ResourceManager is the possibility to ship predefined resources with
-webgen. These resources can be used by any website developed with webgen.
-
-*Credits*:
-
-* webgen-icons-<notextile>*</notextile>: These icons were taken from the "CrystalClear" package from
-"http://www.kde-look.org/content/show.php?content=25668":http://www.kde-look.org/content/show.php?content=25668
-* webgen-emoticons-<notextile>*</notextile>: Credits for the individual emoticon packs are listed on the {plugin:
-Misc/SmileyReplacer} page
-
-<notextile>{predefinedResources:}</notextile>
+webgen. These resources can be used by any website developed with webgen. The list of predefined
+resources can be viewed on the
+<a href="{relocatable: /documentation/references/resource_reference.page}">Resource Reference</a>
+page.

data/doc/src/documentation/plugins/file/defaulthandler.page

@@ -2,6 +2,7 @@
 title: DefaultHandler
 directoryName: File
 inMenu: true
+omitIndexFileInBreadcrumbTrail: false
 template: /plugin.template
 plugin: File/DefaultHandler
 ---

data/doc/src/documentation/plugins/file/sipttrahandler.page

@@ -0,0 +1,18 @@
+---
+title: SipttraHandler
+inMenu: true
+template: /plugin.template
+plugin: File/SipttraHandler
+---
+h2(#description). Description
+
+This plugin handles <a href="{relocatable:/documentation/references/sipttra_format.page}">sipttra</a>
+(Simple Plain Text Tracker) files. This is a custom text format which one can use if a sophisticated
+tracker like Bugzilla or Trac is an overkill.
+
+The special key @webgen-metainfo@ in the meta information section of a sipttra file can be used to
+define meta information for the generated page.
+
+If you have created a sipttra file, you should also use a
+<a href="{relocatable: /examples/sipttra_styles}">sipttra style</a> to specify how
+the generated tracker page should look like.

data/doc/src/documentation/plugins/file/templatehandler.page

@@ -12,9 +12,7 @@ using a page file.
 
 These files have the same format as page files - more information about this format can be found
 in the <a href="{relocatable: /documentation/references/webpage_format.page}">WebPage Format reference</a>.
-Also be aware that the template handler uses the content format set for the page handler! This is
-normally something like Textile or Markdown, if you want to use plain HTML you have to explicitly
-specify it!
+The default content format for template files is HTML (contrary to page files).
 
 The parameter {param: File/TemplateHandler:defaultTemplate} specifies the name of the default
 template which is used when no explicit template for a page file is set via the meta information
@@ -24,11 +22,30 @@ default template isn't found in the root directory, no template is used at all.
 you create a default template in the root directory, it is used as template for all page files that
 have no explicit template set.
 
-It is also possible to nest templates. This makes it possible, for example, to create a general
-website layout and then to create a special image gallery layout which uses the general one. As the
-template files have the same format as page files, you just need to set the @template@ meta
-information on a template to specify the template in which it should be nested.
+webgen also uses the concept of a template chain to support multiple templates for one page file!
+For example, assume that
 
-This page uses two templates: a general one which defines the overall layout of the website (the
-menus and so on) and a specific plugin documentation template which provides the general information
-section.
+* the page file @index.page@ has set the @template@ meta information to @special.template@,
+* the template @special.template@ has no @template@ meta information set and
+* the page file @other.page@ also has no @template@ meta information set.
+
+The template chain for @index.page@ would look like this
+
+@default.template@ <= @special.template@ <= @index.page@
+
+whereas the template chain for @other.page@ would look like this
+
+@default.template@ <= @index.page@
+
+The first case also means that the @special.template@ is nested in the @default.template@! This
+makes it possible, for example, to create a general website layout and then to create a special
+image gallery layout which uses the general one.
+
+To stop the template handler from further searching for a template, you explicitly need set a null
+template for the page or template file:
+
+  template: ~
+
+This is useful if you want to have a different @default.template@ in a sub directory which should
+provide a different look-and-feel for this subtree as the @default.template@ in the root of the
+website.

data/doc/src/documentation/plugins/file/thumbnailwriter.page

@@ -14,8 +14,11 @@ The {param: File/ThumbnailWriter:thumbnailSize} parameter has to be in the forma
 where WIDTH and HEIGHT are numeric values specifying the width and the height for the thumbnail.
 
 The {param: File/ThumbnailWriter:resizeMethod} parameter specifies how the image should be resized
-for creating the thumbnail. The following pictures illustrate the differences between the settings
-for a thumbnail size of 100x100:
+for creating the thumbnail. *Be aware* that the value has to be a symbol, not a string (@:normal@
+instead of @normal@)!
+
+The following pictures illustrate the differences between the settings for a thumbnail size of
+100x100:
 
 <table class="examples">
 <tr>

data/doc/src/documentation/plugins/htmlvalidator/default.page

@@ -2,6 +2,7 @@
 title: Default
 directoryName: HtmlValidator
 inMenu: true
+omitIndexFileInBreadcrumbTrail: false
 template: /plugin.template
 plugin: HtmlValidator/Default
 ---

data/doc/src/documentation/plugins/index.page

@@ -32,7 +32,7 @@ Following is a list of the default namespaces and what they are used for:
 
 * *ContentConverter/*: plugins used for converting content into HTML
 * *Core/*: the core plugins of webgen
-* *File/*: all plugins handling files (ie. derived from {plugin: File/DefaultHandler}
+* *File/*: all plugins handling files (ie. derived from {plugin: File/DefaultHandler})
 * *HtmlValidator/*: HTML validator plugins
 * *MenuStyle/*: menu style plugins
 * *Misc/*. miscellaneous plugins
@@ -45,7 +45,7 @@ h3(#plugin-param). Plugin Parameters
 Each plugin can define parameters which can be used to configure the plugin. These parameters are
 listed at the top of each plugin page. Also note that plugins can use the parameters from their
 "parent plugins" - this allows a group of plugins which have similar functionality (e.g. the menu
-style plugins) to share common configuration values. The names of the "super plugins" are enclosed
+style plugins) to share common configuration values. The names of the "parent plugins" are enclosed
 in parentheses after the plugin names in the "General Information" section.
 
 Parameters can have various types: String, Number, Boolean, Array... When setting a parameter via

data/doc/src/documentation/plugins/menustyle/default.page

@@ -2,6 +2,7 @@
 title: Default
 directoryName: MenuStyle
 inMenu: true
+omitIndexFileInBreadcrumbTrail: false
 template: /plugin.template
 plugin: MenuStyle/Default
 ---

data/doc/src/documentation/plugins/tag/breadcrumbtrail.page

@@ -10,6 +10,14 @@ h2(#description). Description
 The breadcrumb trail tag is used to display the hierarchy for the current page. You can see it in
 action above the main content area.
 
+The {param: Tag/BreadcrumbTrail:omitLast} parameter can be used for always omitting the last path
+component in the trail (which is normally the page itself).
+
+The {param: Tag/BreadcrumbTrail:omitIndexFile} parameter can be used to omit the last path component
+if it is an index file for an directory (see {plugin: File/DirectoryHandler} for more information
+about index files). This behaviour can be overridden for individual index files by setting the meta
+information @omitIndexFileInBreadcrumbTrail@.
+
 
 h2(#examples). Examples
 
@@ -26,4 +34,8 @@ h2(#examples). Examples
   <td><notextile>\{breadcrumbTrail: {separator: " HELLO "}}</notextile></td>
   <td><notextile>{breadcrumbTrail: {separator: " HELLO "}}</notextile></td>
 </tr>
+<tr>
+  <td><notextile>\{breadcrumbTrail: {omitLast: true}}</notextile></td>
+  <td><notextile>{breadcrumbTrail: {omitLast: true}}</notextile></td>
+</tr>
 </table>

data/doc/src/documentation/plugins/tag/customvar.page

@@ -0,0 +1,11 @@
+---
+title: CustomVar
+inMenu: true
+template: /plugin.template
+plugin: Tag/CustomVar
+---
+h2(#description). Description
+
+
+The custom variable tag is used to output the value of a custom variable defined using the {param:
+Core/Configuration:customVars} parameter.

data/doc/src/documentation/plugins/tag/default.page

@@ -2,6 +2,7 @@
 title: Default
 directoryName: Tag
 inMenu: true
+omitIndexFileInBreadcrumbTrail: false
 template: /plugin.template
 plugin: Tag/Default
 ---

data/doc/src/documentation/references/index.page

@@ -12,11 +12,19 @@ This part of the documentation contains some references for your convenience:
   Describes the structure and format of the WebPage Format, the format used, for
   example, for page and template files.
 
+* <b><a href="{relocatable: sipttra_format.page}">sipttra Format Reference</a></b>
+
+  Describes the sipptra (Simple Plain Text Tracker) format.
+
 * <b><a href="{relocatable: meta_info_reference.page}">Meta Information Reference</a></b>
 
   Provides an overview over all special meta information keys that can be used in conjunction with
   webgen.
 
+* <b><a href="{relocatable: resource_reference.page}">Resource Reference</a></b>
+
+  Provides an overview over all predefined resources!
+
 * <b><a href="{relocatable: parameter_reference.page}">Parameter Reference</a></b>
 
   Lists the parameters for all plugins for easy search and retrieval.

data/doc/src/documentation/references/meta_info_reference.page

@@ -23,11 +23,18 @@ plugin, be it a file handler plugin, a tag plugin...
   <th>directoryName</th>
   <td>String</td>
   <td>Image Directory</td>
-  <td>Page file</td>
-  <td>Only used if set on a directory index page file; specifies the title of the directory for
+  <td>Any</td>
+  <td>Only used if set on a directory index file; specifies the title of the directory for
       which it is the index file. If it is not specified, the title of the directory will be
       used.</td>
 </tr>
+<tr>
+  <th>emoticonPack</th>
+  <td>String</td>
+  <td>bigeyes</td>
+  <td>Page file</td>
+  <td>Sets the emoticon package which should be used for the page.</td>
+</tr>
 <tr>
   <th>indexFile</th>
   <td>String</td>
@@ -49,6 +56,22 @@ plugin, be it a file handler plugin, a tag plugin...
   <td>Page file</td>
   <td>Sets the language for the page file. Has to be a valid ISO-639-1/2 character code for the language.</td>
 </tr>
+<tr>
+  <th>linkAttrs</th>
+  <td>Hash</td>
+  <td>\{title: Hallo, class: extra}</td>
+  <td>Any</td>
+  <td>Specifies additional attribute-value pairs (in form of a Hash) that should be added to a link to the file/directory.</td>
+</tr>
+<tr>
+  <th>omitIndexFileInBreadcrumbTrail</th>
+  <td>Boolean</td>
+  <td>false</td>
+  <td>Index file</td>
+  <td>Controls whether the index file should appear in a breadcrumb trail despite the setting of the
+      {param: Tag/BreadcrumbTrail:omitIndexFile} parameter.
+  </td>
+</tr>
 <tr>
   <th>orderInfo</th>
   <td>Integer</td>
@@ -60,6 +83,16 @@ plugin, be it a file handler plugin, a tag plugin...
       nodes are the same, then they are sorted according to their @title@ meta information.
   </td>
 </tr>
+<tr>
+  <th>outputNameStyle</th>
+  <td>String</td>
+  <td>[:name, [".", :lang], ".html"]</td>
+  <td>Page file</td>
+  <td>Sets a custom output name style for the specified page file only. The basename is substituted for the value @:name@
+      and the language for the value @:lang@. Strings are used verbatim. If @:lang@ is specified in a sub-array, the whole
+      sub-array is omitted, if the parameter {param: File/PageHandler:defaultLangInFilename} is false.
+  </td>
+</tr>
 <tr>
   <th>template</th>
   <td>String</td>
@@ -82,19 +115,5 @@ plugin, be it a file handler plugin, a tag plugin...
   <td>Page/Template file</td>
   <td>Specifies if the content blocks of the page/template file should be processed with ERB overriding the default value.</td>
 </tr>
-<tr>
-  <th>linkAttrs</th>
-  <td>Hash</td>
-  <td>\{title: Hallo, class: extra}</td>
-  <td>Any</td>
-  <td>Specifies additional attribute-value pairs (in form of a Hash) that should be added to a link to the file/directory.</td>
-</tr>
-<tr>
-  <th>emoticonPack</th>
-  <td>String</td>
-  <td>bigeyes</td>
-  <td>Page file</td>
-  <td>Sets the emoticon package which should be used for the page.</td>
-</tr>
 </table>
 

data/doc/src/documentation/references/resource_reference.page

@@ -0,0 +1,18 @@
+---
+title: Resource Reference
+inMenu: true
+---
+h2. Resource Reference
+
+
+The following list shows all resources that are shipped with webgen and that can be used via the
+{plugin: Tag/Resource} plugin.
+
+*Credits*:
+
+* webgen-icons-<notextile>*</notextile>: These icons were taken from the "CrystalClear" package from
+"http://www.kde-look.org/content/show.php?content=25668":http://www.kde-look.org/content/show.php?content=25668
+* webgen-emoticons-<notextile>*</notextile>: Credits for the individual emoticon packs are listed on the {plugin:
+Misc/SmileyReplacer} page
+
+<notextile>{predefinedResources:}</notextile>

data/doc/src/documentation/references/sipttra_format.page

@@ -0,0 +1,241 @@
+---
+title: Sipttra Format
+inMenu: true
+---
+
+h1. The Sipttra Format
+
+
+h2(#sipttra). What is sipptra?
+
+
+sipttra is the acronym for <b>S</b>imple <b>P</b>lain <b>T</b>ext <b>T</b>racker. It is a ticket
+tracker which stores everything inside a human readable text file. Therefore it can be used with any
+text editor and no additional program to edit it is needed.
+
+sipttra supports categories with different types, a special milestone category and, naturally,
+tickets.
+
+As everything is stored in a text file, sipttra is not intended to be used by many concurrent users.
+It is a simple and easy system for one-man-projects as well as small projects with not many
+developers.
+
+
+h2(#structure). Types
+
+
+sipttra is line and not character based. This means that it only operates on whole lines and each
+line can have a different type. This section describes the available types and the next section
+explains how these types can be used in a sipttra file.
+
+
+h3(#categories). Categories
+
+
+A category has a name and a type which have to be unique among all categories. Therefore it is not
+possible to define two equal category lines in one sipttra file. Tickets can only be defined for
+categories. The category type further distinquishes the tickets of a category name. For example,
+normally you have at least open bugs and closed bugs. For sipttra, this means that you have defined
+a category named bugs with type open and another category named bugs with type closed.
+
+A category is defined like this:
+
+<pre>
+  ### CATEGORY (type) ###
+</pre>
+
+or
+
+<pre>
+  # CATEGORY (type) #
+</pre>
+
+The line has to start with one or more hashes, the category name, the category type and finally the
+same number of hashes as at the start of the line. These items have to be separated from each other
+by spaces.
+
+The tickets of a category are of the same type as the category itself. The special type @closed@
+signifies that the tickets in the category are closed, tickets from all other category types are
+considered to be open.
+
+
+h3(#milestones). Milestone Category
+
+
+The milestone category is defined like a normal category. However, the type in parenthesis is
+omitted, like this:
+
+<pre>
+  ### Milestones ###
+</pre>
+
+A sipttra file can contain exactly one such milestone category! This is the only distinction between
+normal categories and the milestone category.
+
+
+h3(#tickets). Tickets
+
+
+Tickets are defined like this:
+
+<pre>
+   * NAME (YYYY-MM-DD) [BELONGS_TO] summary
+     further description
+
+     still in the description
+</pre>
+
+Basically all parts are optional. However, if no summary is specified it is assumed to be empty. The
+name uniquely distinguishes the ticket among all tickets independent of the category. The date in
+parenthesis is considered to be the due date, ie. the date on which this ticket should be closed.
+The 'belongs to' part in square brackets defines a relationship to another ticket. The summary part
+is a short description of the ticket. All following lines which are either empty or indented exactly
+two spaces belong to the detailed description of the ticket (one can use Markdown syntax in the
+detailed description). *Caveats*: if one wants to only specify a name and a summary for a ticket,
+these two parts have to be separated by a colon sothat the parser can distinguish them. Also be
+aware that the spaces between the individual parts are mandatory!
+
+Here are some examples for valid tickets:
+
+<pre>
+  * name1: summary
+
+  * name2 (2007-02-15) my summary here
+
+  * name3 [othername] yeah, this also works
+    with additional description
+
+    which still belongs to ticket name3
+</pre>
+
+Two important attributes for tickets are defined indirectly:
+
+* status: The status is defined by the category type to which a ticket belongs
+* priority: The priorites of the tickets are defined by their order. The ticket defined first in a
+  category has the highest priority, the last defined ticket the lowest.
+
+Tickets for the milestone category are defined like normal tickets. However, milestone tickets must
+have a name defined!
+
+
+h3(#comments). Comments
+
+
+Comment lines are allowed everywhere in a sipttra file! Each line which is neither a category line,
+a ticket line or a line belonging to an additional description of a ticket becomes a comment line.
+Also be aware that if a line for a ticket or category is not well structured, it automatically
+becomes a comment line.
+
+
+h2(#fileformat). The sipttra File Format
+
+
+A sipttra file starts with an optional meta information part. If you want to have a meta information
+part the sipttra file has to start with three dashes on the first line. Everything till the next
+line with three dashes is considered to be meta information. This meta information part has to be
+valid YAML.
+
+The main part consists of the tracker definition. It is read line by line from top to bottom:
+
+* All lines before the first category line are considered to be comment lines.
+* Tickets always belong to the last defined category.
+* The same category can not be defined twice in one sipttra file!
+
+
+h2(#examples). Examples
+
+
+Here are some example sipttra files.
+
+<pre>
+\---
+webgen-metainfo:
+  inMenu: true
+  title: Project Status
+\---
+
+### Milestones ###
+
+* Feb07 (2007-02-28) Bug fixes and small enhancements
+  - include patches/requests created since 0.4.1 release
+  - add support for sipttra files, the Simple Plain Text Tracker
+
+* F: Ideas and todo items for future versions
+
+  This milestone holds all ideas/todo items/requests which are implemented some
+  time in the future.
+
+
+Here could be some potential comment! :)
+
+### Features (open) ###
+
+* T001 [Feb07] one ticket
+
+* T002 [F] another ticket
+  this is additional text
+
+
+### Features (closed) ###
+
+* T003 [F] and another closed ticket
+
+
+### Bugs (open) ###
+
+* T008 [Feb07] you should really close this bug!
+
+
+### Bugs (closed) ###
+
+* T009 [Feb07] yeah, very cool, a closed bug!
+</pre>
+
+
+<pre>
+This are just some
+comment lines
+here!
+
+### Milestones ###
+
+* Feb07 (2007-02-28) Bug fixes and small enhancements
+
+Here could be some potential comment! :)
+
+### Features (open) ###
+
+* T001 [Feb07] one ticket
+
+* T002 [Feb07] another ticket
+  this is additional text
+
+
+### Features (closed) ###
+
+* T003 [Feb07] and another closed ticket
+
+### Bugs (open) ###
+
+* T008 [Feb07] you should really close this bug!
+
+
+### Bugs (closed) ###
+
+* T009 [Feb07] yeah, very cool, a closed bug!
+</pre>
+
+
+<pre>
+### Features (open) ###
+
+* T001 [Feb07] one ticket
+
+* T002 [F] another ticket
+  this is additional text
+
+
+### Features (closed) ###
+
+* T003 [F] and another closed ticket
+</pre>