webgen 0.3.8 → 0.4.0

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

@@ -0,0 +1,15 @@
+---
+title: Default
+directoryName: ContentConverter
+inMenu: true
+template: /plugin.template
+plugin: ContentConverter/Default
+---
+h2(#description). Description
+
+
+This is the base plugin (does not provide any functionality) for all "content to HTML" converters.
+These converters are used, for example, for page files to allow the page creators to use a format he
+likes.
+
+Have a look at the individual converters for more information!

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

@@ -0,0 +1,10 @@
+---
+title: HTML
+inMenu: true
+template: /plugin.template
+plugin: ContentConverter/HTML
+---
+h2(#description). Description
+
+
+Handles content written in plain HTML, i.e. the content is just copied and no changes are made.

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

@@ -0,0 +1,21 @@
+---
+title: Markdown
+inMenu: true
+template: /plugin.template
+plugin: ContentConverter/Markdown
+---
+h2(#description). Description
+
+
+Converts content written using Markdown markup
+("Reference":http://daringfireball.net/projects/markdown/) to HTML.
+
+
+h2(#caveat). Caveat
+
+
+This plugin is only available if you have installed the
+"bluecloth":http://www.deveiate.org/projects/BlueCloth library. The preferred way to do this is via
+Rubygems:
+
+  gem install bluecloth

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

@@ -0,0 +1,11 @@
+---
+title: RDoc
+inMenu: true
+template: /plugin.template
+plugin: ContentConverter/RDoc
+---
+h2(#description). Description
+
+
+Converts content written in RDoc (default documentation system for Ruby source files,
+"reference":http://rdoc.sourceforge.net/doc/) to HTML.

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

@@ -0,0 +1,21 @@
+---
+title: Textile
+inMenu: true
+template: /plugin.template
+plugin: ContentConverter/Textile
+---
+h2(#description). Description
+
+
+Converts content written using Textile markup ("Reference":http://hobix.com/textile/) to HTML.
+
+
+h2(#caveat). Caveat
+
+
+This plugin is only available if you have installed the
+"redcloth":http://whytheluckystiff.net/ruby/redcloth/ library. The preferred way to do this is via
+Rubygems:
+
+  gem install redcloth
+

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

@@ -0,0 +1,61 @@
+---
+title: XmlBuilder
+inMenu: true
+template: /plugin.template
+plugin: ContentConverter/XmlBuilder
+---
+h2(#description). Description
+
+
+This plugin can be used to programatically create XHTML/XML documents
+("Reference":http://builder.rubyforge.org). The top builder object is provided through the @xml@
+object.
+
+
+h2(#examples). Examples
+
+
+Following is a short example on how to use this plugin in a page file which generates a custom XML
+document (the block has to be valid Ruby!):
+
+<pre>
+\---
+outputNameStyle: [:name, ['.', :lang], '.xml']
+title: Person Object
+\--- content, xmlbuilder
+xml.persons do |p|
+  xml.person do |b|
+    b.firstname('Thomas')
+    b.lastname('Leitner')
+  end
+  xml.person do |b|
+    b.firstname('Other first')
+    b.lastname('Other last')
+  end
+end
+</pre>
+
+The above will produce the following output:
+
+<pre>
+<persons>
+  <person>
+  <firstname>Thomas</firstname>
+  <lastname>Leitner</lastname>
+  </person>
+  <person>
+    <firstname>Other first</firstname>
+    <lastname>Other last</lastname>
+  </person>
+</persons>
+</pre>
+
+
+h2(#caveat). Caveat
+
+
+This plugin is only available if you have installed the
+"builder":http://builder.rubyforge.org library. The preferred way to do this is via
+Rubygems:
+
+  gem install builder

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

@@ -0,0 +1,11 @@
+---
+title: Configuration
+inMenu: true
+template: /plugin.template
+plugin: Core/Configuration
+---
+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.

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

@@ -0,0 +1,214 @@
+---
+title: FileHandler
+inMenu: true
+template: /plugin.template
+plugin: Core/FileHandler
+---
+h2(#description). Description
+
+The FileHandler plugin is one of the two main workhorses, the other being the {plugin:
+Core/TagProcessor}. When running webgen the FileHandler is responsible for traversing the source
+directory and creating the internal representation of all handled files as well as writing the
+output files by using the individual file handler plugins. These file handler plugins reside in the
+{plugin: File} namespace. Also, the FileHandler is responsible for managing the "meta information
+backing file":#metainfo-file.
+
+There are many different file handler plugins available, ranging from very simple ones, like copying a
+file verbatim from the source to the output directory, to complicated ones, like creating HTML files
+from page files or creating whole image galleries from a simple gallery defintion file!
+
+The following sections give an overview of how the "file handling":#filehandling is done by webgen,
+how "path patterns":#pathpattern work and how to specify and use "meta information":#metainfo.
+
+
+h2(#filehandling). Handling of files in the source directory
+
+
+Following is the list of rules how files in the source directory are handled by webgen:
+
+# All file/directory names in the source directory are fetched (actually, only those file/directory
+  names without a leading dot)
+# Those files which match an {param: Core/FileHandler:ignorePaths} pattern are excluded
+# The path patterns for each file handler plugin are matched against the remaining files and all
+  matching files are then handled by the file handler plugin
+
+As you might have deduced from the processing list above, it is possible that one file/directory is
+handled by multiple file handler plugins. This can be used, for example, to render an XML file as
+HTML and copy it verbatim.
+
+Internally a tree structure is created reflecting the source directory hierarchy and each file that
+will be created by webgen is represented by a node in the tree, as displayed in the following in
+image.
+
+p=. <img src="{relocatable: /images/node_diagram.png}" alt="Internal tree structure" />
+
+The source directory layout is shown on the left side and the internal tree structure/output layout
+on the right. As you can see, some files are copied verbatim (e.g. the images), others are copied
+not all (e.g. @default.template@) and still others have multiple output files (e.g.
+@project/documentation.page@).
+
+
+h2(#pathpattern). Path Patterns
+
+
+Each file handler plugin specifies path patterns which are used to locate the files that the plugin
+can handle. Normally these patterns are used to match file extensions, however, they are much more
+powerful. For detailed information have a look at
+"Dir.glob":http://ruby-doc.org/core/classes/Dir.html#M002375 .
+
+The path patterns that are handled by a particular file handler plugin are stated on its
+documentation page and cannot be changed for most plugins, eg. the {plugin: File/PageHandler} will
+always handle @.page@ files. However, the information about how these path patterns work are useful
+for the usage of webgen because of two reasons:
+
+* so that the user knows which files will be processed by a specific file handler plugin
+* so that the user can specify path patterns for some special file handler plugins that support
+  additional path patterns, like the {plugin: File/CopyHandler}.
+
+Here are some example path patterns:
+
+<table class="examples">
+<tr><th>Path Pattern</th><th>Result</th></tr>
+<tr>
+  <td><notextile><code>*/*.html</code></notextile></td>
+  <td>All files with the extension @html@ in the subdirectories of the source directory</td>
+</tr>
+<tr>
+  <td><notextile><code>**/*.html</code></notextile></td>
+  <td>All files with the extension @html@ in all directories</td>
+</tr>
+<tr>
+  <td><notextile><code>**/{foo,bar}*</code></notextile></td>
+  <td>All files in all directories which start with @foo@ or @bar@</td>
+</tr>
+<tr>
+  <td><notextile><code>**/???</code></notextile></td>
+  <td>All files in all directories whose file name is exactly three characters long</td>
+</tr>
+</table>
+
+
+
+h2(#metainfo). File Meta Information
+
+
+Each file can have meta information, i.e. information about the file itself, associated with it, for
+example the title of the file, if it should appear in a menu and so on. Some file types allow this
+meta information to be specified directly in the file, e.g. page files. However, meta information
+can also be specified in the "meta information backing file":#metainfo-file.
+
+
+h3(#metainfo-param). The @defaultMetaInfo@ parameter
+
+
+This parameter can be used to override the default meta information set for a file handler plugin.
+The keys are the names of file handler plugins and the values are the meta information. You can
+either set the parameter directly or use the special functionality provided by the
+<a href="{relocatable: /documentation/gettingstarted.page#config}">configuration file</a> to
+set it for a file handler plugin.
+
+
+h3(#metainfo-file). The meta information backing file
+
+
+The meta information backing file contains meta information about files/directories in the source
+directory. It has two sections both of which have to be in YAML format and both have to have the
+same structure: a source backing section and an output backing section which is optional.
+
+The source backing section is used to apply meta information to a file before a node for this file
+is created. A file handler plugin can therefore use this meta information during the creation of the
+node. Make sure that you use a valid source path, i.e. a path that resolves to a file in the source
+directory!
+
+The output backing section is used to apply meta information after _all_ nodes have been created and
+to create so called "virtual nodes". The paths specified in the output backing section have to be
+valid output path, not source paths! If a specified path resolves to an already created node, the
+meta information is applied to this node. Otherwise, a virtual node is created with the specified
+meta information and empty content - a virtual node _never_ creates a real output file! This
+facility can be used, for example, to include links to external web pages in menus or to create the
+a whole menu with custom sections and multiple reference in different sections to the same node!
+
+Following is a sample meta information backing file with explanations afterwards:
+
+<pre>
+index.page:
+  inMenu: true
+  orderInfo: 2
+
+images:
+  indexFile: ~
+\---
+index.page:
+  inMenu: false
+
+wiki.html:
+  title: Link to wiki
+  url: http://myhost.com/path/to/my/wiki
+  inMenu: true
+  orderInfo: 5
+
+api.html:
+  title: API Reference
+  url: http://myhost.com/api
+
+virtdir/:
+  indexFile: index.html
+
+virtdir/index.html:
+  title: A virtual index file
+  inMenu: true
+  url: /index.page
+
+virtdir/other.html:
+  inMenu: true
+  url: /otherdir/linked.de.page
+</pre>
+
+The above sample meta information backing file consists of both sections: the mandatory source
+section and the optional output section. As you can see each section is described using a hash of
+hashes, i.e. the keys are paths and the values are the meta information hashes.
+
+The source section specifies additional meta information for the @index.page@ file and for the
+@images@ directory: the @index.page@ gets the @inMenu@ and @orderInfo@ meta information set and it
+is specified that the @images@ directory has no @indexFile@.
+
+The output section is more interesting than the source section:
+
+* The first entry references an existing file, therefore the meta information for that file
+  (@index.page@) is set appropriately.
+* The second entry specifies that under the @root@ directory a virtual node with the path
+  @wiki.html@ should be created (the node will be virtual as the path references no existing file).
+  It should have the specified title and should be in the menu with the specified
+  order. Furthermore, a special @*url*@ key is used. This key can only be used for virtual file
+  nodes (not directory nodes) in the output section and it specifies the link target for the node.
+  So, whenever a reference to @wiki.html@ is requested the resolved @url@ is returned. This @url@
+  can be a link to an outside page or it can refer to another node, as described below. The @url@ is
+  assumed to be relative to the directory the virutal node is in.
+* The third entry also specifies a virtual node linking to an external page, but one which will not
+  appear in a menu. Such nodes are normally inserted into the output section so that the {plugin:
+  Tag/Relocatable} can be used.
+* The last three entries add virtual entries to the menu to show how one page can appear in more
+  than one directory: the @virtdir/index.html@ links to the top level @index.page@ and
+  @virtdir/other.html@ links to a page in another subdirectory, namely @/otherdir/linked.de.page@.
+
+
+h3(#metainfo-processing). Processing order
+
+
+There is clearly defined order in which meta information is applied to a node for a file:
+
+# The default meta information for a node is specified via a directive in the plugin file handler
+  that creates the node (this means that it is possible that no default meta information is
+  specified). If such a default meta information is set for a plugin file handler it is shown on its
+  plugin documentation page.
+# Overridden by values that are set for the plugin file handler for the node in the {param:
+  Core/FileHandler:defaultMetaInfo} parameter.
+# Overridden by the meta information specified for the file in the source backing section of the
+  meta information backing file.
+# Now the node is created by the file handler plugin with this meta information. During the node
+  creation, it is possible that the meta information is overridden by meta information extracted
+  from the file by the file handler plugin (e.g. the {plugin: File/PageHandler} parses the file
+  name to extract meta information like the title of the node and uses the meta information
+  specified in the file itself).
+# After all nodes are created, meta information specified in the output backing section of the meta
+  file backing file is applied.

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

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

@@ -0,0 +1,46 @@
+---
+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.
+
+*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/plugins/core/tagprocessor.page

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