webgen 0.4.7 → 0.5.0

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

@@ -1,11 +0,0 @@
----
-title: Core Plugins
-directoryName: Core
----
-h2(#Description). Description
-
-The plugins in this namespace provide the core functionality for webgen. They allow webgen to
-* handle resources
-* read files from the source directory
-* substitute tags in page files
-

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

@@ -1,40 +0,0 @@
----
-title: ResourceManager
-inMenu: true
-template: /plugin.template
-plugin: Core/ResourceManager
----
-h2(#description). Description
-
-The ResourceManager plugin provides access to the resources which are shipped with webgen, for
-example, the emoticons. Furthermore, it allows the user to specify their own resources.
-
-A resource can either be included directly which means that the content of the resource is written
-into the HTML file. Or it can be referenced in which case only the path is written into the HTML
-file and the content of the resource itself is written to its predefined output path. Be aware that
-a resource is *only* written to its output path if it is referenced at least once (for example, by
-the plugin {plugin: Tag/Resource})!
-
-Speaking of the output path, each resource has four properties:
-
-* *resoure name*:
-  It is unique among all resources and used to access the resource.
-* *output path*:
-  This is the path relative to output directory where the resource will be written to if it is
-  referenced at least once.
-* *type*:
-  There are two different types of resources: file resources and memory resources.
-** A *file* resource references a file in the file system. The content of this type of resource
-   cannot be changed during a webgen run and this type mostly used for images and other binary files.
-** A *memory* resource only exists during a webgen run and its content can be changed. This type of
-   resource is used, for example, by plugins to specify addditional CSS formatting rules or
-   Javascript code.
-* *description*: A short description of the resource.
-
-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. 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/core/tagprocessor.page

@@ -1,17 +0,0 @@
----
-title: TagProcessor
-inMenu: true
-template: /plugin.template
-plugin: Core/TagProcessor
----
-h2(#description). Description
-
-The TagProcessor plugin, apart from the {plugin: Core/FileHandler}, is the main workhorse. It is
-responsible for parsing HTML content and replacing special constructs, so called tags, with dynamic
-content. For more information on how these tags look like, how they are used and why they are
-useful, have a look at the <a href="{relocatable: /documentation/references/webpage_format.page}">page file format description</a>!
-
-Each tag has a unique name and an associated handler plugin. Therefore it is very easy to define new
-tags. webgen already comes with many tag plugins that handle simple things, like including a file,
-to advanced things, like generating a menu (the menus used on this homepage are generated
-dynamically with webgen). These tag plugins reside in the {plugin: Tag} namespace.

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

@@ -1,26 +0,0 @@
----
-title: CopyHandler
-inMenu: true
-template: /plugin.template
-plugin: File/CopyHandler
----
-h2(#description). Description
-
-This plugin has two operation modes:
-
-* All files that match the {param: File/CopyHandler:erbPaths} parameter are processed with ERB and
-  then written out. The leading letter @r@ is stripped from the extension (e.g. @.rhtml@) to form
-  the output file name. During processing with ERB the current @node@ object is available. This
-  operation mode is useful, for example, for @.rhtml@ files (HTML with embedded ruby) or @.rcss@
-  files (CSS files with embedded ruby).
-
-* All files that match the {param: File/CopyHandler:paths} parameter are copied from the source to
-  the output directory without modification. This is useful, for example, for CSS stylesheets,
-  javascript files and images.
-
-When a file matches against both parameters, it is handled as if it matches only against {param:
-File/CopyHandler:erbPaths}.
-
-Also note that files are written only if the source file is newer than the output file! This means
-that, for example, images are copied only during the first webgen run and not during the second if
-the image files have not changed.

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

@@ -1,16 +0,0 @@
----
-title: DefaultHandler
-directoryName: File
-inMenu: true
-omitIndexFileInBreadcrumbTrail: false
-template: /plugin.template
-plugin: File/DefaultHandler
----
-h2(#description). Description
-
-The DefaultHandler is the base plugin for all file handler plugins. It is used to hold the
-parameters that apply to all file handler plugins and it provides default implementations for some
-methods as well as the functionality to specify path patterns.
-
-For information on how the files in the source directory are generally handled have a look at the
-{plugin: Core/FileHandler#filehandling}.

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

@@ -1,37 +0,0 @@
----
-title: DirectoryHandler
-inMenu: true
-template: /plugin.template
-plugin: File/DirectoryHandler
----
-h2(#description). Description
-
-The directory handler is used for handling directories, ie. it creates the target directories.
-Additionally an index file for each directory can be specified. If it is specified, this file is
-used instead of the plain directory index for displaying purposes. This means that when the
-directory path is resolved (e.g. by the {plugin: Tag/Relocatable}) the index file is returned.
-
-The name of the index file is specified with the @indexFile@ meta information on a directory node.
-This meta information is set by default and can be overridden globally by using the special
-@defaultMetaInfo@ param for the @DirectoryHandler@ in the
-<a href="{relocatable: /documentation/basics.page#config}">configuration file</a> or by
-setting it on individual directories using the
-<a href="{relocatable: ../core/filehandler.page#metainfo-file}">meta information backing file</a>.
-
-The title for a directory can be set via the @title@ meta information on the directory itself.
-However, if the directory has an index file, the meta information @directoryName@ of the index file
-is used for the directory title. This allows different directory names based on the current
-language.
-
-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 only images. To prevent webgen from displaying warnings for such directories, you can set a
-null index file using the meta information backing file:
-
-<pre>
-dirWithOnlyImages:
-  indexFile: ~
-</pre>
-
-This will prevent webgen from showing warnings because you explicitly define a null index file. This
-can also be done globally in the configuration file!

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

@@ -1,190 +0,0 @@
----
-title: GalleryHandler
-inMenu: true
-template: /plugin.template
-plugin: File/GalleryHandler
----
-h2(#description). Description
-
-
-This file handler uses image gallery files to automatically build image galleries. These image
-galleries are highly configurable and theme-able through the use of different gallery styles - have
-a look at the <a href="{relocatable: /examples/gallery_styles}">examples section</a>!
-
-
-h2(#structure). Structure of image galleries
-
-
-An image gallery consists of three types of page files:
-
-* *image pages*: An image page is created for each image. Normally the title, the unresized image,
-   the image description and possible other information as well as navigational links (link to the
-   next/previous image etc.) are displayed.
-* *gallery pages*: A gallery page displays a list of images (number of images per gallery page is
-   customizable). If more images than the maximum number of images per gallery page exist, then two
-   or more gallery pages are created.
-* *main page*: A main page is only created if two or more gallery pages exist and is used for
-   displaying links to the gallery pages.
-
-All these pages are created automatically by the gallery handler, but they don't have any content;
-everything is done by the templates of a gallery style. The parameters {param:
-File/GalleryHandler:imagePageTemplate}, {param: File/GalleryHandler:galleryPageTemplate} and {param:
-File/GalleryHandler:mainPageTemplate} define which templates should be used for image pages, gallery
-pages and the main page. The default values can be overwritten in the gallery file!
-
-
-h2(#gallery-styles). Gallery styles
-
-
-Gallery styles are used... to style image galleries ;-) A gallery style consists of templates and,
-optionally, plugins. A minimal gallery style consists of the following files:
-
-* @gallery_image.template@
-* @gallery_gallery.template@
-* @gallery_main.template@
-
-To display all available gallery styles use the following command:
-
-<pre>
-$ wegben help use gallery_style
-</pre>
-
-To use a specific gallery style called STYLE issue the following command:
-
-<pre>
-$ wegben use gallery_style STYLE
-</pre>
-
-This copies all normal gallery style files from the gallery style to the source directory and all
-plugins to the plugin directory, maybe overwritting files (you are asked before copying if you would
-like to procede). However, this command is not able to delete previously copied gallery style files,
-so you have to remove them yourself.
-
-For information about how a gallery style can be created have a look at
-<a href="{relocatable: /documentation/extending_webgen.page}">extending webgen section</a>!
-
-
-h2(#file-format). Gallery File Format
-
-
-A gallery file has YAML as file format and is easy to create. It consists of two sections which are
-separated by a line consisting only of three dashes: the configuration section and the image
-section.
-
-
-h3(#file-format-config-sec). The configuration section
-
-
-The first section of a gallery file is the configuration section in which you define the basic
-properties of your image gallery like the title or how many images should be displayed per page. By
-using the name of a gallery handler parameter as key you can override its value. Additionally the
-following keys are used by the gallery handler:
-
-* *title*: The title of the gallery. If this key is not specified, the capitalized file name is used.
-* *filename*: The base filename used for creating the page files. If not specified it is created from
-  the title.
-* *lang*: The language used by the gallery. If not specified, the default language is used.
-* *mainPageMetaInfo*: Used for setting additional meta information for the main page.
-* *galleryPagesMetaInfo*: Used for setting additional meta information for the gallery pages.
-* *imagePagesMetaInfo*: Used for setting additional meta information for all image pages.
-* *layouter*: Plugin used for additional gallery tasks, has to be registered under
-  @GalleryLayouter/&lt;layouter-name&gt;@
-* *thumbnailSize*: The size of the thumbnails, can also be set individually for each image.
-* *thumbnailResizeMethod*: The method used for creating the thumbnails, can also be set individually
-  for each image.
-
-For more information about the last two items have a look at {plugin: File/ThumbnailWriter}!
-
-Two nearly always specified parameters should also be mentioned here: {param:
-File/GalleryHandler:imagesPerPage} and {param: File/GalleryHandler:images}. The first specifies how
-many images should be placed on a single gallery page. The second one specifies which images should
-be used the whole image gallery. These images have to be somewhere in the website source directory!
-You can/should not specify images outside the source directory as these images are not automatically
-copied to the output directory and automatic thumbnail creation may not work correctly!
-
-If you want to create a multi-lingual gallery, you need to create two gallery files which specify
-the same @filename@ key and different @lang@ keys. It's best to first create one gallery file, fill
-in all the information and then copy it and change the @filename@ and @lang@ keys as well as all the
-other language specific information like titles and descriptions.
-
-All other key-value pairs specified are not used by webgen. However, as layouter plugins have access
-to the whole configuration section they may use their own configuration keys.
-
-
-h3(#file-format-image-sec). The image section
-
-
-The second section is the image data section in which additional data can be set for images. It has
-the image file paths as keys. These paths have to be relative to the gallery file! The following
-keys are used and/or set by the gallery handler:
-
-* *title*: The title of the image. If not set, a default value will be assigned.
-* *template*: The template file for the image page. If not set, the value of the parameter {param:
-   File/GalleryHandler:imagePageTemplate} will be used.
-* *orderInfo*: The images are sorted according to this key. If this key is not set, the title is
-   used; if this is also not set, the image file name is used for sorting.
-* *thumbnail*: If this key is set for an image, the value is assumed to be the path to a thumbnail
-   for this image. Otherwise, it is set by the gallery handler and a thumbnail is created
-   automatically (if the {plugin: File/ThumbnailWriter} could be loaded).
-* *thumbnailSize*: The size of the automatically created thumbnail in the format "WIDTHxHEIGHT"
-   where WIDTH and HEIGHT are numeric values specifying the width and the height. If not set, the
-   value from the configuration section is used. If that is also not set, a default value is used
-   (see {param: File/ThumbnailWriter:thumbnailSize}).
-* *thumbnailResizeMethod*: The method used to create the automatic thumbnail. For more information
-   about the possible values have a look at {param: File/ThumbnailWriter:resizeMethod}. If
-   not set, the value from the configuration section is used, If that is also not set, a default
-   value is used (see {param: File/ThumbnailWriter:resizeMethod}).
-* *exif*: If not set and the exif reading library is installed, it is assigned the exif information
-   of the image. The exif reading library can be installed using <code>gem install exifr</code>
-
-
-h2(#thumbnail-creation). Automatic thumbnail creation
-
-
-The gallery handler is able to automatically create thumbnails for the images in the image gallery
-if the {plugin: File/ThumbnailWriter} is available. If so, the @thumbnailSize@ and
-@thumbnailResizeMethod@ keys described above are used to create the thumbnail.
-
-If the plugin is not available, you either have to explicitly specify a thumbnail via the
-@thumbnail@ key for an image or the @width@ and @height@ attributes of the HTML @img@ tag are used
-to scale the full image to the thumbnail size.
-
-
-h2(#file-format-example). Example gallery file
-
-
-The following example gallery file shows the most common used configuration options:
-
-<pre>
-title: Example Gallery
-imagesPerPage: 32
-images: example/**/*.jpg
-
-mainPageMetaInfo:
-    inMenu: false
-    otherKey: value
-
-galleryPagesMetaInfo:
-    orderInfo: 10
-    inMenu: true
-\---
-example/dir1/img1.jpg:
-    title: Test title
-    description: Long description of image
-
-example/img2.jpg:
-    title: Title2 of pic
-    mykey: mydata
-</pre>
-
-First the title of the gallery is set and the {param: File/GalleryHandler:imagesPerPage} parameter
-value is overridden. Then it is specified that all files with the extension @jpg@ under the
-directory @example@ should be used for this image gallery.
-
-The next two keys set the meta information for the main page and the gallery pages. Be aware that
-the @orderInfo@ meta information is set for the gallery pages. This implies that the gallery handler
-automatically increments the @orderInfo@ value for each gallery page sothat they are sorted and
-displayed in the menu correctly.
-
-The second section sets the meta information for the images of the gallery. All meta information set
-for the images will be available to the image template.

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

@@ -1,154 +0,0 @@
----
-title: PageHandler
-inMenu: true
-template: /plugin.template
-plugin: File/PageHandler
----
-h2(#description). Description
-
-
-Page files are used to specify the actual content for the website. They contain the content for a
-web page and, optionally, meta information. For information about the format used for page files
-have a look at the <a href="{relocatable: /documentation/references/webpage_format.page}">WebPage Format reference</a>.
-The default values for the content block name and format specifier have been overwritten by setting
-a default for the @blocks@ meta information!
-
-
-h2(#conventions). Conventions
-
-
-h3(#inputfile-naming). Page file naming
-
-
-The filename of a page file should be in the following format sothat meta information can be
-extracted correctly and that referencing a page file works correctly:
-
-p=. <b>[orderInfo.]name[.lang].extension</b>
-
-* @orderInfo@
-
-  This part is optional and has to consist purely of the digits 0 to 9. It's value is used for the
-  meta information @orderInfo@. If not specified, it defaults to the value zero.
-
-* @lang@
-
-  This part is optional and has to be an "ISO-639-1/2":http://www.loc.gov/standards/iso639-2/
-  language identifier (two or three characters (a-z) long). If not specified, it is assumed that the
-  page file is written in the default language set via {param: Core/Configuration:lang}.
-
-* @extension@
-
-  This has to be @page@ for now.
-
-* @name@
-
-  This part is used on the one hand for the @title@ meta information (but with these
-  transformations: '_' and '-' become spaces). On the other hand, the standardized page and
-  localized page names are derived from it. @name@ must not contain any dots. Also: if two page
-  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. If the @name@ parts and the languages
-  are the same, webgen can't distinguish the two page files and raises an error.
-
-Following are some examples of page file names:
-
-<table class="examples">
-<tr><th>Filename</th><th>Parsed meta information</th></tr>
-<tr>
-  <td>@name.page@</td>
-  <td>title: Name, language: en, orderInfo: 0</td>
-</tr>
-<tr>
-  <td>@name.de.page@</td>
-  <td>title: Name, language: de, orderInfo: 0</td>
-</tr>
-<tr>
-  <td>@01.name_of-file.eo.page@</td>
-  <td>title: Name of file, language: de, orderInfo: 1</td>
-</tr>
-</table>
-
-Notice: The first two examples define the same content for two different languages (en and de) as
-they have the same @name@ part.
-
-
-h3(#outputfile-naming). Output file naming
-
-
-The output name of a page file can be customized using the {param: File/PageHandler:outputNameStyle}
-parameter (which can be overridden by setting the @outputNameStyle@ meta information). This allows
-to change the output name so that, for example, Apache's built in "select HTML file by language"
-magic can be utilized.
-
-
-h3(#pagename). Standardized page names for referencing page files
-
-
-As described above the name part of the page file filename is used for creating the *standardized
-page name* and the *standardized localized page name* as follows:
-
-* standardized page name: &lt;name part&gt;.page
-* standardized localized page name: &lt;name part&gt;.&lt;language code&gt;.page
-
-When two page files have the same name part, they have a common standardized page name but different
-standardized localized page names. As the output name of a page file can be customized, it is not
-wise to reference a page file by its output file name. Use the standardized page names instead.
-Therefore if you reference a page file using the standardized page name, you will always get the
-page file in the current language. If you use the standardized localized page name, you will always
-get the page file in the specified language. So, all in all, you can reference a page file by (in
-order of preference): the standardized page name, the standardized local page name and the output
-name.
-
-These conventions are best shown using examples:
-
-<table class="examples">
-<tr><th>Filename</th><th>Standardized page name</th><th>Standardized localized page name</th></tr>
-<tr>
-  <td>@hallo.page@</td>
-  <td>@hallo.page@</td>
-  <td>@hallo.en.page@ (if the default language is English)</td>
-</tr>
-<tr>
-  <td>@the_others.de.page@</td>
-  <td>@the_others.page@</td>
-  <td>@the_others.de.page@</td>
-</tr>
-<tr>
-  <td>@12.documentation.eo.page@</td>
-  <td>@documentation.page@</td>
-  <td>@documentation.eo.page@</td>
-</tr>
-</table>
-
-
-h2(#howto-metainfo). How meta information is set
-
-
-As meta information can be defined in page files, the following sections explains in more detail
-what is done in step 4 of the list from the section "Processing order" in {plugin:
-Core/FileHandler#metainfo-processing}:
-
-* Meta information from the filename
-
-  Meta information derived from the filename overrides the default meta information. This includes
-  the meta information @orderInfo@, @lang@ and @title@.
-
-* Meta information from the meta information section of the page file
-
-  All meta information from this part set previously set meta information, especially the meta
-  information @lang@, @orderInfo@ and @title@!
-
-
-h2(#fragment-nodes). Fragment Nodes
-
-
-As a page file specifies the content of web page, it normally has sections, subsections and so on
-(created by the @h1@ - @h6@ HTML tags). Nodes for these sections are created under the page file
-node sothat they can be used later by webgen plugins. However, there are certain restrictions:
-
-* Only sections of the block named 'content' (the default name for the main block) are added to the
-  page file node
-* Only already existing sections _WITH_ an @id@ attribute are used. This means that sections without
-  and @id@ attribute and sections defined later via webgen tags or ERB are not used!
-
-A plugin using these fragment nodes is {plugin: MenuStyle/Section} which displays an in-page content
-menu.