webgen 0.3.8 → 0.4.0

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

@@ -0,0 +1,39 @@
+---
+title: ThumbnailWriter
+inMenu: true
+template: /plugin.template
+plugin: File/ThumbnailWriter
+---
+h2(#description). Description
+
+
+This plugin is used by other plugins to create thumbnails for images. For example, the {plugin:
+File/GalleryHandler} uses it to automatically create thumbnails for all images in an image gallery.
+
+The {param: File/ThumbnailWriter:thumbnailSize} parameter has to be in the format "WIDTHxHEIGHT"
+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:
+
+<table class="examples">
+<tr>
+  <td>Original image (320x240)</td><td>@:normal@ (100x75)</td><td>@:cropped@ (100x100)</td>
+</tr>
+<tr>
+  <td style="vertical-align: top"><img src="{relocatable: /images/thumb_example.jpg}" alt="Thumbnail example image" /></td>
+  <td style="vertical-align: top"><img src="{relocatable: /images/thumb_example_normal.jpg}" alt="Thumbnail using normal resize method" /></td>
+  <td style="vertical-align: top"><img src="{relocatable: /images/thumb_example_cropped.jpg}" alt="Thumbnail using cropped resize method" /></td>
+</tr>
+</table>
+
+
+h2(#caveat). Caveat
+
+
+This plugin is only available if you have installed the
+"rmagick":http://rmagick.rubyforge.org/ library. The preferred way to do this is via
+Rubygems:
+
+  gem install rmagick

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

@@ -0,0 +1,12 @@
+---
+title: Default
+directoryName: HtmlValidator
+inMenu: true
+template: /plugin.template
+plugin: HtmlValidator/Default
+---
+h2(#description). Description
+
+
+This is the base plugin (does not provide any functionality) for all HTML validators. Have a look at
+individual validators to see what they can do for you!

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

@@ -0,0 +1,12 @@
+---
+title: xmllint
+inMenu: true
+template: /plugin.template
+plugin: HtmlValidator/xmllint
+---
+h2(#description). Description
+
+This plugin uses the @xmllint@ program from the "libxml2":http://www.xmlsoft.org package. @xmllint@
+can be used to validate an XML (and therefore an XHTML) file against a DTD, a RelaxNG schema or a
+WXS schema. For more information about where to put the DTD or schema files, have a look at the
+@libxml2@ documentation that comes bundled.

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

@@ -1,31 +1,52 @@
 ---
 title: Plugins
-orderInfo: 30
 directoryName: Plugins
 ---
-h2. About
+h2(#about). About
 
-All available plugins in the distribution are described in this section. Choose a plugin category
+
+All available plugins in the distribution are described in this section. Choose a plugin namespace
 to get more information!
 
-h2. Plugins
 
-webgen is written with extensibility in mind; therefore most of its features are implemented with
+h2(#plugins). Plugins
+
+
+webgen is written with extensibility in mind; therefore most of its features are implemented using
 plugins, only the core functions are not plugins.
 
 Writing your own plugins is not difficult, too! If you need a specific functionality, implement a
 plugin and put it under the site specific @plugin@ directory - then the plugin gets loaded with the
 others. It's so easy!
 
-For more information have a look at the <a href="{relocatable: /rdoc/index.html}">API documentation</a>!
+For more information have a look at the <a href="{relocatable: /api.html}">API documentation</a>!
+
+
+h3(#plugin-naming). Naming of Plugins
+
+
+Plugin names have an easy structure. The first part (before the slash) describes the namespace it is
+located in, the second part is the actual plugin name.
+
+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}
+* *HtmlValidator/*: HTML validator plugins
+* *MenuStyle/*: menu style plugins
+* *Misc/*. miscellaneous plugins
+* *Tags/*: all tag plugins used by {plugin: Core/TagProcessor}
+
+
+h3(#plugin-param). Plugin Parameters
 
-h2. Parameters
 
 Each plugin can define parameters which can be used to configure the plugin. These parameters are
-listed in the "Information" section of each plugin page. Also note that plugins can use the
-parameters from their "super 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 in parentheses after the plugin name in the "Information" section.
+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
+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
 the configuration file, you need to ensure that it has the proper type. Have a look at

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

@@ -0,0 +1,19 @@
+---
+title: Default
+directoryName: MenuStyle
+inMenu: true
+template: /plugin.template
+plugin: MenuStyle/Default
+---
+h2(#description). Description
+
+
+This is the base plugin for all menu styles which are used by the {plugin: Tag/Menu} plugin. Menu
+Styles are used to build different types of menus. Some web sites use vertical menus on the left or
+right side, some horizontal menus at the top. It's up to you to chose the best suited menu style for
+your website!
+
+This plugin defines some parameters that are used by the individual menu style plugins sothat
+the generated menus can be styled more easily with CSS.
+
+Have a look at the individual menu styles for more information!

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

@@ -0,0 +1,32 @@
+---
+title: Horizontal
+directoryName: MenuStyle
+inMenu: true
+template: /plugin.template
+plugin: MenuStyle/Horizontal
+---
+h2(#description). Description
+
+
+Builds a horizontal menu; each menu level gets its own menu bar.
+
+*Caveat*: You should link to the @webgen-css@ resource in your template as this plugin defines some
+CSS styles!
+
+
+h2(#examples). Examples
+
+
+<table class="examples">
+<tr>
+  <th>Used parameters</th><th>Resulting menu</th>
+</tr>
+<tr>
+  <td>Using default values</td>
+  <td>{menu: {menuStyle: horizontal}}</td>
+</tr>
+<tr>
+  <td>Using default values and some CSS styles</td>
+  <td>{menu: {menuStyle: horizontal, options: {divClass: menu-example-horiz}}}</td>
+</tr>
+</table>

data/doc/src/documentation/plugins/{menustyles → menustyle}/horizontaldropdown.page

@@ -1,26 +1,31 @@
 ---
-title: Horizontal Dropdown
+title: HorizontalDropdown
+directoryName: MenuStyle
 inMenu: true
+template: /plugin.template
+plugin: MenuStyle/HorizontalDropdown
 ---
-h2. Information
+h2(#description). Description
 
-<notextile>{describe: HorizontalDropdownMenuStyle}</notextile>
-
-h2. Description
 
 Builds a horizontal menu with CSS drop down menus. This menu should work fine in any browser
 supporting CSS and the @:hover@ selector (Mozilla based browsers like Firefox, Opera and Konqueror
-are fine, does NOT work in IE 6 on Windows XP).
+are fine, does NOT work in IE 6 on Windows XP, not tested with IE 7).
+
+*Caveat*: You should link to the @webgen-css@ resource in your template as this plugin defines some
+CSS styles!
+
 
-h2. Style Advice
+h2(#style). Style Advice
 
-The menu works by only using CSS, not DHTML or anything else. Here is a list of CSS selectors and
-descriptions how these selectors can be used to style various parts of the menu. You have to pay
+
+The menu works by only using CSS, not DHTML or anything else. Following is a list of CSS selectors
+and descriptions how these selectors can be used to style various parts of the menu. You have to pay
 attention to the last element in the selector (@ul@, @li@, or @a@). When you want to style menu
 items, you normally want to use @a@. You should also be aware of the use of the @>@ sign, there is a
 dramatic difference between writing @li a@ and @li > a@ (the former selecting ALL @a@ elements of
 the list item, i.e. all @a@ elements in submenus too; and the latter only selecting the direct
-descendant)!
+descendants)!
 
 table{border: 1px solid black}.
 |<code>.webgen-menu-horiz-dd ul > li > a</code>|Style the top level menu items (the ones that are always shown)|
@@ -28,15 +33,16 @@ table{border: 1px solid black}.
 |<code>.webgen-menu-horiz-dd ul ul > li > a</code>|Style the drop down menu items|
 |<code>.webgen-menu-horiz-dd li:hover > a</code>|Style the hovered-over menu item|
 
-h2. Example
-
-Basic menu as it appears by default, nothing styled additionally with CSS:
-
-<notextile>{menu: {menuStyle: horizontal-dropdown}}</notextile>
 
-<br />
-The same menu with a little CSS magic:
+h2(#examples). Examples
 
-<notextile>{menu: {menuStyle: horizontal-dropdown, options: {divClass: horiz-dd-menu}}}</notextile>
 
-<br/>
+<table class="examples">
+<tr>
+  <th>Used parameters</th><th>Resulting menu</th>
+</tr>
+<tr>
+  <td>Using default values</td>
+  <td>{menu: {menuStyle: horizontal-dropdown}}</td>
+</tr>
+</table>

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

@@ -0,0 +1,34 @@
+---
+title: Section
+directoryName: MenuStyle
+inMenu: true
+template: /plugin.template
+plugin: MenuStyle/Section
+---
+h2(#description). Description
+
+
+Builds a simple menu showing only the sections of the current page.
+
+
+h2(#examples). Examples
+
+<table class="examples">
+<tr>
+  <th>Used parameters</th><th>Resulting menu</th>
+</tr>
+<tr>
+  <td>Using default values</td>
+  <td>{menu: {menuStyle: section}}</td>
+</tr>
+<tr>
+  <td>\{menu: {menuStyle: section, options: {maxLevels: 1, numberSections: false}}}</td>
+  <td>{menu: {menuStyle: section, options: {maxLevels: 1, numberSections: false}}}</td>
+</tr>
+</table>
+
+
+h3(#sample). Sample sub section
+
+
+This section is just for demonstration purposes for the examples.

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

@@ -0,0 +1,48 @@
+---
+title: Vertical
+directoryName: MenuStyle
+inMenu: true
+template: /plugin.template
+plugin: MenuStyle/Vertical
+---
+h2(#description). Description
+
+
+This menu style builds a seemingly simple vertical menu. However, it is very flexible due to its
+many parameters that let you decide every detail of the menu. Have a look at the examples to see
+what is possible!
+
+
+h2(#style). Style Advice
+
+
+The menu is constructed using HTML lists with @ul@ and @li@ tags. However, the menu looks better if
+no discs are shown for the menu items (using the CSS directive <code>list-style-type: none</code>).
+
+
+h2(#examples). Examples
+
+
+Following are some examples of this menu style with varying parameter values (without CSS styling).
+
+<table class="examples">
+<tr>
+  <th>Used parameters</th><th>Resulting menu</th>
+</tr>
+<tr>
+  <td>Using default values</td>
+  <td>{menu: {menuStyle: vertical}}</td>
+</tr>
+<tr>
+  <td>\{menu: {menuStyle: vertical, options: {maxLevels: 1}}}</td>
+  <td>{menu: {menuStyle: vertical, options: {maxLevels: 1}}}</td>
+</tr>
+<tr>
+  <td>\{menu: {menuStyle: vertical, options: {showCurrentSubtreeOnly: false, maxLevels: 3}}}</td>
+  <td>{menu: {menuStyle: vertical, options: {showCurrentSubtreeOnly: false, maxLevels: 3}}}</td>
+</tr>
+<tr>
+  <td>\{menu: {menuStyle: vertical, options: {startLevel: 2, maxLevels: 3}}}</td>
+  <td>{menu: {menuStyle: vertical, options: {startLevel: 2, maxLevels: 3}}}</td>
+</tr>
+</table>

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

@@ -0,0 +1,29 @@
+---
+title: VerticalDropdown
+directoryName: MenuStyle
+inMenu: true
+template: /plugin.template
+plugin: MenuStyle/VerticalDropdown
+---
+h2(#description). Description
+
+
+Builds a vertical menu with CSS drop down menus. This one is similar to the menu defined by {plugin:
+MenuStyle/HorizontalDropdown} and the information on its page also applies for this menu style.
+
+*Caveat*: You should link to the @webgen-css@ resource in your template as this plugin defines some
+CSS styles!
+
+
+h2(#examples). Examples
+
+
+<table class="examples">
+<tr>
+  <th>Used parameters</th><th>Resulting menu</th>
+</tr>
+<tr>
+  <td>Using default values</td>
+  <td>{menu: {menuStyle: vertical-dropdown}}</td>
+</tr>
+</table>

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

@@ -0,0 +1,9 @@
+---
+title: Misc Plugins
+directoryName: Misc
+---
+h2(#description). Description
+
+
+These plugins do not fit into any other category and are therefore located here. They are very
+useful nonetheless!

data/doc/src/documentation/plugins/{miscplugins → misc}/smileyreplacer.page

@@ -1,28 +1,29 @@
 ---
-title: Smiley Replacer
+title: SmileyReplacer
 inMenu: true
+template: /plugin.template
+plugin: Misc/SmileyReplacer
 emoticonPack: ~
 ---
-h2. Information
+h2(#description). Description
 
-<notextile>{describe: SmileyReplacer}</notextile>
-
-h2. Description
 
 This plugin replaces smiley (ie. such sequences as <notextile>;-), :-)</notextile>, ...) with
 emoticons - graphics which express the same emotion as the smiley.
 
-You can enable or disable the replacement of smileys globally by setting the parameter @emoticonPack@
-to an existing smiley package or @nil@. However, if a page has the meta information @emoticonPack@,
-this meta info takes precedence over the global value. So, if the replacement is globally enabled,
-you can disable it for a specifc page by setting the meta information @emoticonPack@ to @nil@ (this
-was done for this page so that you can see the character representation of the smileys). You can
-also change the used emoticon package for one page only by setting @emoticonPack@ to another
-package name.
+You can enable or disable the replacement of smileys globally by setting the parameter {param:
+Misc/SmileyReplacer:emoticonPack} to an existing smiley package or @nil@. However, if a page has the
+meta information @emoticonPack@, this meta info takes precedence over the global value. So, if the
+replacement is globally enabled, you can disable it for a specifc page by setting the meta
+information @emoticonPack@ to @nil@ (this was done for this page so that you can see the character
+representation of the smileys). You can also change the used emoticon package for one page only by
+setting @emoticonPack@ to another package name.
+
+
+h2(#available-packs). Available Emoticon Packs
 
-h2. Available Emoticon Packs
 
-Here is a table showing the available smileys and their representation with various emoticons
+Following is a table showing the available smileys and their representation with various emoticon
 packages. The header shows the smiley you have to use so that you get one of the emoticons below it,
 depending on the used emoticon package.
 

data/doc/src/documentation/plugins/misc/syntaxhighlighter.page

@@ -0,0 +1,26 @@
+---
+title: SyntaxHighlighter
+inMenu: true
+template: /plugin.template
+plugin: Misc/SyntaxHighlighter
+---
+h2(#description). Description
+
+
+This plugin is used by other plugins to highlight source code. It is used, for example, by {plugin:
+Tag/IncludeFile}.
+
+The available languages for syntax highlighting depend on the version of coderay you have installed.
+
+
+h2(#caveat). Caveat
+
+
+You should link to the @webgen-css@ resource in your template as this plugin defines some CSS
+styles!
+
+This plugin is only available if you have installed the
+"coderay":http://coderay.rubychan.de/ library. The preferred way to do this is via
+Rubygems:
+
+  gem install coderay