webgen 0.3.8 → 0.4.0

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

@@ -0,0 +1,26 @@
+---
+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

@@ -0,0 +1,15 @@
+---
+title: DefaultHandler
+directoryName: File
+inMenu: true
+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

@@ -0,0 +1,37 @@
+---
+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/gettingstarted.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

@@ -0,0 +1,181 @@
+---
+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.
+* *mainPageMetaInfo*: Used for setting additional meta information for the main page.
+* *galleryPagesMetaInfo*: Used for setting additional meta information for the gallery 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!
+
+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

@@ -0,0 +1,154 @@
+---
+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.

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

@@ -0,0 +1,34 @@
+---
+title: TemplateHandler
+inMenu: true
+template: /plugin.template
+plugin: File/TemplateHandler
+---
+h2(#description). Description
+
+The template handler processes the templates found in the source directory. Templates, as the name
+already implies, normally specify the layout and the overall "picture" of a web page that is defined
+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 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
+@template@. webgen assumes that the default template is in the same directory as the page file.
+However, if it can not be found there, the parent directory is searched for it and so on. If a
+default template isn't found in the root directory, no template is used at all. This means that when
+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.
+
+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.