webgen 0.4.7 → 0.5.0

data/doc/src/documentation/index.page

@@ -1,50 +0,0 @@
----
-directoryName: Documentation
-title: Preface
----
-h2. Preface
-
-
-p={font-size: 150%; color:red}. *This documentation is for webgen {version: }! However, most parts
-are valid for all webgen 0.4.x releases!*
-
-
-The source files for this website are in the @doc/src@ directory of the webgen distribution. Have a
-look at them to see a real world example on how to use webgen!
-
-
-h2. Spelling of the name "webgen"
-
-
-I often see that the name of the program is misspelled: WebGen, Webgen, WEBGEN, ... It is just
-*webgen*, all lower case!
-
-
-h2. Philosophy of webgen
-
-
-There are some things about webgen which I think are important to mention. It's about how webgen
-works and what you can expect when you start webgen.
-
-* <b>webgen runs till the end and does not stop on errors!</b>
-
-  I did not like it when webgen stopped because there was an error in the configuration file or an
-  error in a page file. So if something exceptional happens it is logged so that the user can see
-  what happened and a useful default alternative is used instead. For example, if no default
-  template was found in the source directory, a dummy template is used instead.
-
-  Therefore it is also not necessary to install the dependencies (although you would be wise to do
-  it, so that you can use all the features of webgen). If a dependency is not found (e.g. RedCloth
-  for Textile support), the specific feature is turned off and a warning gets issued.
-
-* <b>Useful default values for everything!</b>
-
-  You _do not need_ to configure webgen if you are happy with the default values. webgen provides
-  default values for every configuration option.
-
-* <b>Every important thing gets logged!</b>
-
-  The logging mechanism is not only used to log error and warning messages, but also to log
-  informational and debug messages. For the normal user, the error and warning messages are
-  important. Developers who extend webgen by writing a new plugin can use the informational and
-  debug messages to see what is going on and to help them develop the plugin.

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

@@ -1,16 +0,0 @@
----
-title: Default
-directoryName: ContentConverter
-inMenu: true
-omitIndexFileInBreadcrumbTrail: false
-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/haml.page

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

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

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

@@ -1,21 +0,0 @@
----
-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/maruku.page

@@ -1,23 +0,0 @@
----
-title: Maruku
-inMenu: true
-template: /plugin.template
-plugin: ContentConverter/Maruku
----
-h2(#description). Description
-
-
-Converts content written using Markdown markup
-("Reference":http://daringfireball.net/projects/markdown/) to HTML. However, it also implements all
-features described on the "PHP Markdown Extra":http://www.michelf.com/projects/php-markdown/extra/
-page. For more information have a look at the "Maruku homepage":http://maruku.rubyforge.org !
-
-
-h2(#caveat). Caveat
-
-
-This plugin is only available if you have installed the "maruku":http://maruku.rubyforge.org
-library. The preferred way to do this is via Rubygems:
-
-  gem install maruku
-

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

@@ -1,11 +0,0 @@
----
-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/sass.page

@@ -1,36 +0,0 @@
----
-title: Sass
-inMenu: true
-template: /plugin.template
-plugin: ContentConverter/Sass
----
-h2(#description). Description
-
-
-Converts content written using Sass markup ("Homepage":http://haml.hamptoncatlin.com/) to CSS. This
-content converter is only useful for writing CSS page files. You have to make sure to change the
-output name style sothat the extension @css@ is used and to stop the template chain - see the
-example below!
-
-You can use the following page file as a template for your sass files:
-
-<pre>
-\---
-outputNameStyle: [:name, [., :lang], .css]
-template: ~
-validator: ~
-\--- content, sass
-p
-  :background-color grey
-  :padding 5px
-</pre>
-
-
-h2(#caveat). Caveat
-
-
-This plugin is only available if you have installed the
-"haml":http://haml.hamptoncatlin.com/ library. The preferred way to do this is via
-Rubygems:
-
-  gem install haml

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

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

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

@@ -1,17 +0,0 @@
----
-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.
-
-It also provides support for "custom variables" through the {param: Core/Configuration:customVars}
-parameter. This facility can be used to store and access global variables that have been defined in
-the <a href="{relocatable: /documentation/basics.page#config}">configuration file</a> through, for
-example, the {plugin: Tag/CustomVar} plugin.
-

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

@@ -1,220 +0,0 @@
----
-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 unless {param: Core/FileHandler:useHiddenFiles} is set to @true@)
-# 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
-
-You should not use one of the following characters in file or directory names:
-
-    ; / ? : @ & = + $ ,
-
-If you do use one of them webgen may not work correctly!
-
-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/basics.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.