webgen 0.3.6 → 0.3.7

data/doc/src/documentation/plugins/{filehandler → filehandlers}/copy.page

@@ -4,7 +4,7 @@ inMenu: true
 ---
 h2. Information
 
-<notextile>{describe: FileCopyHandler}</notextile>
+<notextile>{describe: CopyFileHandler}</notextile>
 
 h2. Description
 

data/doc/src/documentation/plugins/{filehandler/directory.page → filehandlers/directoryhandler.page}

@@ -4,7 +4,7 @@ inMenu: true
 ---
 h2. Information
 
-<notextile>{describe: DirHandler}</notextile>
+<notextile>{describe: DirectoryHandler}</notextile>
 
 h2. Description
 
@@ -15,7 +15,7 @@ file handlers page is generated by the index file of the @filehandler@ directory
 
 Normally, webgen shows a warning if it could not find the directory index file for a directory.
 However, there are most certainly directories which should not have an index file, e.g. a directory
-with pictures only. To prevent webgen from displaying warnings for such directories, you can add the
+with images only. To prevent webgen from displaying warnings for such directories, you can add the
 following meta information to a backing file:
 
 <pre>
@@ -24,3 +24,12 @@ dirWithOnlyImages:
 </pre>
 
 This will prevent webgen from showing warnings because you explicitly define a null index file.
+
+If you do not want to use directory index files, you can set the parameter @indexFile@ to @nil@ in
+the configuration file, like this:
+
+<pre>
+DirectoryHandler:
+  indexFile: ~
+</pre>
+

data/doc/src/documentation/plugins/{filehandler/galleryhandler.page → filehandlers/gallery.page}

@@ -1,19 +1,22 @@
 ---
-title: Picture Gallery File Handler
+title: Gallery File Handler
 inMenu: true
 ---
 h2. Information
 
-<notextile>{describe: PictureGalleryFileHandler}</notextile>
+<notextile>{describe: GalleryFileHandler}</notextile>
 
 h2. Description
 
-This file handler uses picture gallery description files to automatically build picture galleries.
-These picture galleries are highly configurable and themeable through the use of page templates.
+This file handler uses image gallery description files to automatically build image galleries.
+These image galleries are highly configurable and themeable through the use of page templates.
 
 h2. Gallery Description Files
 
-The gallery description files are written in YAML and specify
+The gallery description files have YAML as file format and can either be written by hand or can be
+edited using the <a href="{relocatable: /documentation/webgen_gallery_editor.page}">webgen-gallery-editor</a>.
+
+A gallery description file specifies
 
 * which images should be used
 * the titles/descriptions of the images
@@ -25,12 +28,12 @@ The two most important things on this list are which images should be used and t
 images have to be in the website source directory! You can/should not specify images outside the
 source directory as these images are not automatically copied to the destination directory and
 automatice thumbnail creation may not work correctly. And the layout defines how the main, gallery
-and picture pages look like.
+and image pages look like.
 
 Here is an example gallery description file:
 <pre>
 title: Example Gallery
-picsPerPage: 32
+imagesPerPage: 32
 files: example/**/*.jpg
 
 mainPage:
@@ -52,8 +55,12 @@ example/img2.jpg
 So, we define the title of the gallery first and change the @picsPerPage@ setting. Every plugin
 parameter can be changed by using its name as key and assigning a new value to it. The key
 @mainPage@ can be used to set meta information for the main page. Likewise, the key @galleryPages@
-can be used to set meta information for the gallery pages and if the key is the name of a picture,
-its meta information is set to the specified values.
+can be used to set meta information for the gallery pages and if the key is the name of an image,
+its value is used as meta information for the image.
+
+You can specify the order of the images by setting the @orderInfo@ meta information on the images.
+Normally, the images are sorted by their title or, if no title was entered, by their filename. By
+setting the @orderInfo@ meta information you can reorder them.
 
 h2. Types of Generated Pages
 
@@ -65,15 +72,15 @@ There are three different page types:
 * *gallery pages*: Each gallery page should have a list of all the images on it. The number of
   images per gallery page can be defined via a parameter.
 
-* *picture pages*: Each picture page should display its picture and, maybe, additional information.
+* *image pages*: Each image page should display its image and, maybe, additional information.
 
 h2. Layouter plugins
 
-Each layouter plugin defines a different "style" of picture gallery. Have a look at the available
-layouter plugins and choose one for your picture gallery. If you think they do not look good enough,
+Each layouter plugin defines a different "style" of image gallery. Have a look at the available
+layouter plugins and choose one for your image gallery. If you think they do not look good enough,
 you can define your own layouter in the extension file. You only need to derive a new class from
 DefaultGalleryLayouter and define the layout methods.
 
 h2. Examples
 
-You can view an example gallery <a href="{relocatable: /Design_Gallery_1.page}">here</a>!
+You can view an example gallery <a href="{relocatable: /Screenshots_1.page}">here</a>!

data/doc/src/documentation/plugins/{filehandler/pagehandler.page → filehandlers/page.page}

@@ -4,7 +4,7 @@ inMenu: true
 ---
 h2. Information
 
-<notextile>{describe: PageHandler}</notextile>
+<notextile>{describe: PageFileHandler}</notextile>
 
 h2. Description
 
@@ -102,7 +102,7 @@ The template will always be processed with ERB!
 h3. Format
 
 The content of page description can be written in different formats. Have a look at the
-<a href="{relocatable: ../contenthandler}">Content Handlers</a> to get an overview of the existing
+<a href="{relocatable: ../contenthandlers}">Content Handlers</a> to get an overview of the existing
 formats.
 
 h2. Default settings
@@ -128,8 +128,10 @@ The following defaults are used:
     and @name@ must not contain any dots. Also: if two page descriptions files have the same
     @name@ part, they should define the same content for different languages as webgen consideres
     them as "one" page file in two languages.
-  * language: This is the language code for this file. It is the international two letter acronym
-    and if it is not specified, it defaults to @en@.
+  * language: This is the language code for this file. The codes defined in ISO-639-1 (2 char codes)
+    and ISO-639-2 (3 char codes) can/should be used for defining the language. However, you should stick
+    to one code and do not use any other code for the same language (i.e. only use @en@ and not
+    additionally @eng@ or vice versa). If the language is not specified, it defaults to @en@.
 
   Consider the following examples:
     * @name.page@ -> title: Name, language: en, ordering: 0

data/doc/src/documentation/plugins/{gallerylayouter → gallerylayouters}/index.page

@@ -1,14 +1,18 @@
 ---
 directoryName: Gallery Layouters
 ---
-h2. About
+h2. Information
+
+<notextile>{describe: DefaultGalleryLayouter}</notextile>
+
+h2. Description
 
 Gallery layouters are used to define layouts for galleries. Each plugin defines how the main page,
-the gallery pages and the picture pages look like. To do this, each plugin has to define three methods:
+the gallery pages and the image pages look like. To do this, each plugin has to define three methods:
 
 * <tt>main( data )</tt>
 * <tt>gallery( data, gIndex )</tt>
-* <tt>picture( data, gIndex, iIndex )</tt>
+* <tt>image( data, gIndex, iIndex )</tt>
 
 The @data@ parameter is a @Hash@ with all the information available about the gallery. The @gIndex@
 and the @iIndex@ parameters are indices for the current gallery and the current image.

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

@@ -26,3 +26,7 @@ listed in the "Information" section of each plugin page. Also note that plugins
 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.
+
+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
+"www.yaml.org":http://www.yaml.org for more information about supported types!

data/doc/src/documentation/plugins/menustyles/{vertical-dropdown.page → verticaldropdown.page}

@@ -9,7 +9,7 @@ h2. Information
 h2. Description
 
 Builds a vertical menu with CSS drop down menus. This one is similar to the horizontal dropdown menu
-and the information on the <a href="{relocatable: horizontal-dropdown.page}">Horizontal
+and the information on the <a href="{relocatable: horizontaldropdown.page}">Horizontal
 Dropdown</a> page also applies for this menu style.
 
 h2. Example

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

@@ -0,0 +1,7 @@
+---
+title: Miscellaneous Plugins
+directoryName: Misc Plugins
+---
+h2. About
+
+These plugins do not fit in any other category and are therefore located here.

data/doc/src/documentation/plugins/miscplugins/smileyreplacer.page

@@ -0,0 +1,38 @@
+---
+title: Smiley Replacer
+inMenu: true
+emoticonPack: ~
+---
+h2. Information
+
+<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.
+
+h2. Available Emoticon Packs
+
+Here is a table showing the available smileys and their representation with various emoticons
+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.
+
+Note: I have found these smileys in various places on the Internet and think they are free to use.
+If not, please mail me sothat I can remove them!
+
+Credits:
+
+* smellies: I have taken the smellies emoticons from "Kebawe.com":http://kebawe.com/smellies/ !
+* crystal: The crystal emoticons are from "http://kde-look.org/content/show.php?content=10681":http://kde-look.org/content/show.php?content=10681 .
+* icqstyle: These are from "http://kde-look.org/content/show.php?content=23226":http://kde-look.org/content/show.php?content=23226 .
+
+<notextile>{showEmoticonPacks:}</notextile>

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

@@ -0,0 +1,20 @@
+---
+title: Breadcrumb Trail
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: BreadcrumbTrailTag}</notextile>
+
+h2. Description
+
+The breadcrumb trail tag is used to display the hierarchy for the current page. You can see it in
+action on the left side of the header.
+
+h2. Examples
+
+table{border:1px solid black}.
+|_.Command|_.Output|
+|\{breadcrumbTrail:}|{breadcrumbTrail:}|
+|<notextile>\{breadcrumbTrail: {separator: " HALLO "}}</notextile>|<notextile>{breadcrumbTrail: {separator: " HALLO "}}</notextile>|
+

data/doc/src/documentation/plugins/tags/download.page

@@ -0,0 +1,23 @@
+---
+title: Download
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: DownloadTag}</notextile>
+
+h2. Description
+
+This tag is used to provide a nice download link. The download link includes the following parts:
+
+* *download icon* [optional]: an icon which shows that the file can be downloaded
+* *file icon*: an icon showing the type of the file (PDF file, music file, video file,...)
+* *link to file*: the link to the file
+* *file size*: the size of the file if it can be calculated
+
+h2. Examples
+
+table{border:1px solid black}.
+|_.Command|_.Output|
+|<notextile>\{download: {url: /images/screenshots/wge-image.png, alwaysShowDownloadIcon: true}}</notextile>|<notextile>{download: {url: /images/screenshots/wge-image.png, alwaysShowDownloadIcon: true}}</notextile>|
+|<notextile>\{download: download.page}</notextile>|<notextile>{download: download.page}</notextile>|

data/doc/src/documentation/plugins/tags/resource.page

@@ -10,7 +10,7 @@ h2. Description
 
 The resource tag is used to include a resource either verbatim (i.e. its content is copied) or by
 path. For more information about resources have a look at the
-<a href="{relocatable: ../resourcemanager.page}">Resource Manager</a>.
+<a href="{relocatable: ../coreplugins/resourcemanager.page}">Resource Manager</a>.
 
 h2. Examples
 

data/doc/src/documentation/plugins/tags/sitemap.page

@@ -8,8 +8,7 @@ h2. Information
 
 h2. Description
 
-The SitemapTag is used to display the site map of the current web site. It contains all the pages of
-the web site and their hierarchy.
+The SitemapTag is used to display the site map of the current web site.
 
 h2. Examples
 

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

@@ -0,0 +1,8 @@
+---
+title: References
+directoryName: References
+orderInfo: 25
+---
+h2. About
+
+Some references for your convenience!

data/doc/src/documentation/{meta_info_reference.page → references/meta_info_reference.page}

@@ -19,3 +19,4 @@ table{border: 1px solid black}.
 |*template*      |String   |my.template   |Page file      |Sets the template for the page file overriding the default value.|
 |*title*         |String   |New Title     |Any            |Sets the title for the file/directory.|
 |*useERB*        |Boolean  |false         |Page file      |Specifies if the content blocks of the page file should be processed with ERB overriding the default value.|
+|*emoticonPack*  |String   |bigeyes       |Page file      |Sets the emoticon package which should be used for the page.|

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

@@ -0,0 +1,12 @@
+---
+title: Plugin Parameter Reference
+inMenu: true
+orderInfo: 22
+---
+h2. Plugin Parameter Reference
+
+Each plugin can specify <a href="{relocatable: ../plugins}">parameters</a>. Here is a list of all
+available parameters for a quick lookup, ordered by category and then name (only plugins with
+parameters are shown!):
+
+<notextile>{listPluginParameters:}</notextile>

data/doc/src/documentation/webgen_gallery_editor.page

@@ -0,0 +1,82 @@
+---
+title: Webgen Gallery Editor
+inMenu: true
+orderInfo: 20
+---
+h2. About
+
+This application is based on Qt > 3.1 and therefore needs the
+"qtruby":http://rubyforge.org/projects/korundum/ package. It is basically an editor for editing
+webgen gallery description files. You can easily set all of the required parameters and assign a
+title and a description to each image.
+
+<b>Be aware that this application is only alpha quality! Do not report any bugs concerning this
+application!</b>
+
+h2. How To Use
+
+h3. Starting the editor
+
+You can start the editor by calling @webgen-gallery-editor@. This opens up the main window.
+
+<img src="{relocatable: /images/screenshots/wge-main.png}" alt="Main window when editing" title="Main Window when editing" />
+
+At the beginning all widgets are disabled; they get enabled as soon as you create a new gallery
+description file or open an existing one.
+
+h3. Creating a new gallery description file
+
+Select @File->New...@ which requires you to enter a name for the new gallery description file. All
+the fields are filled with the default values. After that you can start editing!
+
+h3. Editing gallery description files
+
+You can specify the basic gallery information like gallery title, file pattern, ... in the upper
+half of the main window. The meta information you specify for the main page gets included in the
+main page; likewise the meta information you specify for the gallery pages gets included in every
+gallery page.
+
+The lower half of the main window consists of four parts
+
+* *The list of images*:
+
+  This list gets automatically updated whenever you change the file pattern. So you have a live
+  preview of which images get included in the gallery. When you click on an image, it will be shown
+  in the image preview pane. Also, the image meta information table and the title and description
+  fields will be updated to show the current values for the selected image.
+
+* *The image preview pane*:
+
+  Here you will see the selected image. It will be scaled so that it fits into the available space,
+  but it will not be enlarged if the space available is bigger than the image.
+
+* *The image meta information*:
+
+  Here you can enter additional meta information for the selected image.
+
+* *Title and Description fields*:
+
+  As these two meta information fields are used most often, they got their own widgets.
+
+
+As entering the title and description for the images is the main use for the webgen gallery editor,
+there is an easy way to do this:
+
+# Select the first image.
+
+# Enter a title in the title field. When you are finished press @CTRL+ENTER@. This will set the
+  focus to the description field.
+
+# Enter the description and when you are finished, press @CTRL+ENTER@ again. The next image will be
+  selected and the focus wil be set to the title field so that you can continue describing the images.
+
+
+h3. Using the meta information widgets
+
+You need to specify the name of the meta information in the first column and the value in the second
+column of the widget. You can only use certain kinds of values:
+
+* Integer: just type a number
+* String: just type the string
+* Boolean: the special values @true@ and @false@ will be used as boolean values.
+* Nil: the special value @nil@ will be used as nil value

data/doc/src/download.page

@@ -12,11 +12,11 @@ Download: "http://rubyforge.org/frs/?group_id=296":http://rubyforge.org/frs/?gro
 
 h2. Dependencies
 
-* "cmdparse":http://cmdparse.rubyforge.org version 1.0.3 or higher
+* "cmdparse":http://cmdparse.rubyforge.org version 2.0.0 or higher
 * "RedCloth":http://redcloth.rubyforge.org version 2.0.10 or higher if you want Textile support
 * "BlueCloth":http://www.deveiate.org version 1.0.0 or higher if you want Markdown support
 * "RMagick":http://rmagick.rubyforge.org/ version 1.7.1 or higher if you want automatic thumbnail
-  creation for picture galleries
+  creation for image galleries
 
 h2. Installation
 

data/doc/src/features.page

@@ -16,7 +16,7 @@ h2. Feature list
 * <h3>File Handler (for handling the files in the source directory)</h3>
 
   * Powerful file copy handler for copying single files or entire directories to the output directory
-  * Support for gallery definition files -> generates entire picture gallery, automatic thumbnail creation
+  * Support for gallery definition files -> generates entire image galleries, with automatic thumbnail creation
 
 * <h3>Page Description Files (for define web pages)</h3>
 
@@ -28,7 +28,7 @@ h2. Feature list
 
   * Standard distribution provides often used tags
   * Menu tag can generate different types of menus (simple menus and ones with CSS drop downs)
-  * Navbar tag generates a navigation bar so that one always knows where he is in the hierarchy
+  * Breadcrumb trail tag generates a breadcrumb trail so that one always knows where he is in the hierarchy
   * Relocatable tag for automatically generating correct relative paths to files
   * ... and much more!
 
@@ -36,3 +36,4 @@ h2. Feature list
 
   * Automatically checks generated files if they are standard conform
   * Supports 'virtual files' via meta information backing files
+  * Support for automatic smiley replacement with emoticons(:-))