thewoolleyman-webgen 0.5.8.20090419

data/doc/reference_metainfo.page

@@ -0,0 +1,222 @@
+---
+title: Meta Information Reference
+---
+# Meta Information Reference
+
+Following is a list of all the meta information items that are used in one way or another by an
+extension, be it a source handler, a tag or any other extension. Each meta information description
+follows the same pattern:
+
+* First the type of the value and an example value are listed.
+* Then the paths for which this item is valid are listed.
+* And at last follows a detailed description.
+
+
+{:miref: .meta-information-ref}
+
+### author
+
+{:miref}
+* String: `Thomas Leitner`
+* Any
+
+Sets the author of the path. This information is used, for example, by Webgen::SourceHandler::Feed.
+
+### author\_url
+
+{:miref}
+* String: `http://webgen.rubyforge.org`
+* Any where `author` is also set
+
+Sets the homepage of the author of the path. This information is used, for example, by
+Webgen::SourceHandler::Feed and normally only when `author` is also set.
+
+### blocks
+
+{:miref}
+* Hash of Hashes: `\{default: {pipeline:textile}, 1: {name: content, pipeline:maruku,erb,tags}}`
+* Files in Webgen Page Format
+
+Specifies the default names and additional options for the blocks. The special key `default` is used
+to set default options for all blocks. Specific options for (or the name of) a block can be set by
+using the block index as key (numbering starts from one).
+
+### change\_freq
+
+{:miref}
+* String: `hourly`
+* Any
+
+Sets the change frequency of the page. This information is used, for example, by the sitemap source
+handler. You can use the following values for this key: `hourly, daily, weekly, monthly, yearly,
+never`.
+
+### created\_at
+
+{:miref}
+* Time: `2008-08-14 10:25:34 +02:00`
+* Any
+
+Sets the time when the path was created. This information cannot automatically be derived for paths
+provided by Webgen::Source::FileSystem, so this has to be set manually.
+
+> Note that the value needs to be a valid [YAML timestamp](http://yaml.org/type/timestamp.html) and
+> needs to include the time part.
+{.information}
+
+### draft
+
+{:miref}
+* Boolean: `true`
+* Any
+
+If this meta information is set on a path, no node will be created from it. This is useful to add
+content to a website which should only be used later on.
+
+### fragments\_in\_menu
+
+{:miref}
+* Boolean: `false`
+* Page files
+
+Specifies if the fragment nodes of the page file should be in the menu.
+
+### index\_path
+
+{:miref}
+* String: `myindex.html`
+* Directories
+
+Sets the directory index path for the directory overriding the default value.
+
+### in\_menu
+
+{:miref}
+* Boolean: `true`
+* Any
+
+Specifies if the path should appear in menus.
+
+### kind
+
+{:miref}
+* String: `page`
+* Any
+
+Specifies the kind of the path. Some source handlers define a default value for this meta
+information for nodes created by them.
+
+### lang
+
+{:miref}
+* String: `de`
+* Page files
+
+Sets the language for the path. Has to be a valid ISO-639-1/2 character code for the language. This
+meta information needs to be set before a node gets created.
+
+### link\_attrs
+
+{:miref}
+* Hash: `\{title: Hallo, class: extra}`
+* Any
+
+Specifies additional attribute-value pairs (in form of a Hash) that should be added to a link to the
+path.
+
+### modified\_at
+
+{:miref}
+* Time: `2008-08-14 10:25:34 +02:00`
+* Any
+
+Sets the time when the path was last modified. This information is automatically set for paths
+provided by Webgen::Source::FileSystem (the file modification is used) but can be overridden by
+setting it manually. If not set to a valid time, the time when webgen is executed is used for this
+meta information.
+
+> Note that the value needs to be a valid [YAML timestamp](http://yaml.org/type/timestamp.html) and
+> needs to include the time part.
+{.information}
+
+### no\_output
+
+{:miref}
+* Boolean: `true`
+* Any
+
+Specifies whether an output path for the node should be written or not. This differs from `draft`
+that a node for the path gets created nonetheless.
+
+### omit\_index\_path
+
+{:miref}
+* Boolean: `false`
+* Index paths
+
+Controls whether the index path should appear in a breadcrumb trail despite the setting of the
+`tag.breadcrumbtrail.omit_index_path` option.
+
+### output\_path\_style
+
+{:miref}
+* Array: `[:parent, :cnbase, [., :lang], .html]`
+* Any
+
+Sets a custom output path style for the specified path. The basename is substituted for the value
+`:cnbase` and the language for the value `:lang`. Strings are used verbatim. If `:lang` is specified
+in a sub-array, the whole sub-array is omitted, if the configuration option
+`sourcehandler.default_lang_in_output_path` is false. For more and detailed information, have look
+at the [output path creation section]({relocatable: manual.html#source-output}) of the manual!
+
+> This meta information has to be set BEFORE a node gets created. Setting this value is therefore
+> only useful, for example, in the `paths` block of a meta information backing file.
+{.important}
+
+### priority
+
+{:miref}
+* Float: `0.5`
+* Any
+
+Specifies the priority of this file in respect to all the other files of the website. This
+information is used, for example, by the sitemap source handler.
+
+### routed\_title
+
+{:miref}
+* String: `Image Directory`
+* Any
+
+Only used if set on a directory index path; specifies the title of the directory for which it is the
+index path. If this meta information is not specified, the title of the directory will be used
+instead.
+
+### sort\_info
+
+{:miref}
+* Integer or String: `15`
+* Any
+
+Sets the sort information for the path. Any String or Integer value can be used here. When two nodes
+are compared using this information and both have Integers, then an Integer comparision is
+done. Otherwise a String comparision is done.
+
+Setting a String value is useful, for example, for specifying dates as sort information.
+
+### template
+
+{:miref}
+* String or null: `my.template` or `~`
+* Page/Template files
+
+Sets the template for the page/template file overriding the default value. If set to null
+(i.e. `~`), no template is used for the page/template file!
+
+### title
+
+{:miref}
+* String: `New Title`
+* Any
+
+Sets the title for the path.

data/doc/source/filesystem.page

@@ -0,0 +1,39 @@
+---
+title: Webgen::Source::FileSystem
+---
+## Description
+
+This is the default source extension used when creating a new webgen website. It uses files that
+match a certain glob (default value for the glob is to match all files) under a specific directory.
+
+> The default configuration for a new website uses all files under the `src` directory.
+{.information}
+
+The first parameter for the file system source is the directory under which the to-be-used files are
+and the second, optional, parameter specifies a glob (see [Dir.glob]).
+
+[Dir.glob]: http://ruby-doc.org/core/classes/Dir.html#M002375
+
+## Examples
+
+The used sources can be specified via the [`sources` configuration option]({relocatable:
+../reference_configuration.html#sources}), so each of the examples below can be specified in the
+`config.yaml` file.
+
+1.  The default configuration: all files under the `src` folder of the website directory
+
+        sources: [[/, Webgen::Source::FileSystem, src]]
+
+2.  The default configuration and additionally all files under a `misc` directory:
+
+        sources:
+          - [/, Webgen::Source::FileSystem, src]
+          - [/, Webgen::Source::FileSystem, misc]
+
+3.  The default configuration and mounting all image files from an external directory under the
+    `/images/` directory:
+
+        sources:
+          - [/, Webgen::Source::FileSystem, src]
+          - [/images/, Webgen::Source::FileSystem, /media/storage/pictures, **/*.jpg]
+

data/doc/source/tararchive.page

@@ -0,0 +1,40 @@
+---
+title: Webgen::Source::TarArchive
+---
+## Description
+
+The tar archive source can be used to include the files from a (possibly gzipped) tar archive. The
+used archive can be stored locally on the file system but it is also possible to use archives
+accessible via the http(s) and ftp protcols.
+
+> This extension is only available if you have installed the [archive-tar-minitar][1] library. The
+> preferred way to do this is via Rubygems:
+>
+>     gem install archive-tar-minitar
+{.warning}
+
+The first parameter for the tar archive source is the URL of the archive and the second, optional,
+parameter specifies a glob (see [File.fnmatch]) for selecting the to-be-used files/directories in the
+tar archive.
+
+[File.fnmatch]: http://ruby-doc.org/core/classes/File.html#M002603
+[1]: http://raa.ruby-lang.org/project/minitar/
+
+## Examples
+
+The used sources can be specified via the [`sources` configuration option]({relocatable:
+../reference_configuration.html#sources}), so each of the examples below can be specified in the
+`config.yaml` file.
+
+1.  Using all files/directories from a local tar archive in addition the default configuration:
+
+        sources:
+          - [/, Webgen::Source::FileSystem, src]
+          - [/, Webgen::Source::TarArchive, archive.tar]
+
+2.  Using images stored in a remote gzipped tar archive in addition to the default configuration:
+
+        sources:
+          - [/, Webgen::Source::FileSystem, src]
+          - [/, Webgen::Source::TarArchive, http://www.example.com/archive/data.tgz, **/*.jpg]
+

data/doc/sourcehandler.template

@@ -0,0 +1,21 @@
+---
+template: extensions.template
+--- name:summary pipeline:erb,tags,maruku,blocks
+<%
+patterns = context.website.config['sourcehandler.patterns'][context.content_node['title']]
+if patterns
+%>
+This source handler operates on paths that match one of the following path patterns (see the [path pattern documentation]({relocatable: manual.html#source-pathpattern}) for more information): `<%= patterns.join(', ') %>`
+<% end %>
+
+<%
+meta_info = context.website.config['sourcehandler.default_meta_info'][context.content_node['title']]
+if meta_info
+%>
+Following is the default meta information set on any node created by this source handler:
+<pre>
+<%= meta_info.to_yaml.gsub(/^---/, '').strip %>
+</pre>
+<% end %>
+--- name:content
+<webgen:block name='content' />

data/doc/sourcehandler/copy.page

@@ -0,0 +1,19 @@
+---
+title: Webgen::SourceHandler::Copy
+---
+## Description
+
+This source handler copies files from the source to the output directory, optionally running a
+content processor over the content. It is useful, for example, for CSS stylesheets, javascript files
+and images.
+
+It decides using the file extension if a content processor should be used and which one. If the
+short name of a content processor is the first part of the file extension, the file is processed by
+this content processor and the first part is removed from the file extension. Otherwise no
+processing is done at all. For example, a file named `hello.jpg` just gets copied verbatimly but a
+file named `usage.erb.html` gets preprocessed by the `erb` content processor and written to a file
+named `usage.html`. As you can see in this example, the processor name gets stripped from the file
+extension.
+
+If you want to use a specific content processor for processing a file, have a look at its
+documentation page which shows the unique short name that needs to be used in the file extension.

data/doc/sourcehandler/directory.page

@@ -0,0 +1,27 @@
+---
+title: Webgen::SourceHandler::Directory
+---
+## Description
+
+The directory handler is used for handling directories, ie. it creates the target directories.
+Additionally an index path for each directory can be specified which is used instead of the plain
+directory index for displaying purposes. This means that when the directory path is specified
+(e.g. by Webgen::Tag::Relocatable) the index path is returned.
+
+The name of the index path is specified with the meta information `index_path` which is set to
+`index.html` by default. This meta information needs to be set directly on the directory node (for
+example, via a meta information backing file).
+
+The title for a directory can be set via the `title` meta information on the directory itself.
+However, if the directory has an index path, the meta information `routed_title` of the index path
+is used for the directory title. This enables webgen to provide correctly localized directory names.
+
+Normally, webgen shows a warning if it could not find the directory index path for a directory.
+However, there are most certainly directories which should not have an index path, for example, a
+directory containing only images. To prevent webgen from displaying warnings for such directories,
+you can set a null index path using a meta information backing file:
+
+    dirWithOnlyImages:
+      index_path: ~
+
+This will prevent webgen from showing warnings because you explicitly define a null index path.

data/doc/sourcehandler/feed.page

@@ -0,0 +1,105 @@
+---
+title: Webgen::SourceHandler::Feed
+---
+## Description
+
+This source handler automatically generates an atom or RSS feed for a set of files from a file in
+[Webgen Page Format]({relocatable: ../webgen_page_format.html}) (the format which is also used for
+page files).
+
+> This extension is only available if you have installed the [feedtools][1] library. The preferred
+> way to do this is via Rubygems:
+>
+>     gem install feedtools
+{.warning}
+
+The following meta information keys are supported:
+
+*   `entries` (MANDATORY)
+
+    A LCN pattern (or an array of LCN patterns) which specify the page files that should be
+    used. Other matched files are excluded from the list.
+
+    > Be aware that if you want to include a single file or files in a specific language only you
+    > need to include the language part since this is a LCN and not a CN pattern, eg. `mypage.html`
+    > won't work but `mypage.en.html` will!
+    {.information}
+
+*   `number_of_entries` (OPTIONAL)
+
+    The number of entries that should be included in the feed. Defaults to 10.
+
+*   `atom` (OPTIONAL)
+
+    An atom feed is generated if this key is set to `true`. Defaults to `true`.
+
+*   `rss` (OPTIONAL)
+
+    A RSS feed is generated if this key is set to `true`. Defaults to `true`.
+
+*   `rss_version` (OPTIONAL)
+
+    The RSS version that should be used for generating the RSS feed. Defaults to `2.0`.
+
+*   `site_url` (MANDATORY)
+
+    The base url of the website for which the feed is generated.
+
+*   `author` (MANDATORY)
+
+    Specifies the author of the feed.
+
+*   `author_url` (OPTIONAL)
+
+    Specifies the URL of the homepage of the author.
+
+*   `title` (MANDATORY)
+
+    The title of the feed.
+
+*   `description` (OPTIONAL)
+
+    A short description of the feed.
+
+*   `created_at` (OPTIONAL)
+
+    The time at which this feed was created. Defaults to the current time if not set. Has the same
+    format as the meta information `created_at`.
+
+*   `content_block_name` (OPTIONAL)
+
+    The name of the block that should be used for the content of the feed entries. If not specified
+    the name `content` is used. Be aware that each page file that can appear in the feed needs to
+    have such a block!
+
+The following meta information keys of page files are used if they are specified:
+
+*   `created_at`
+
+    The time at which the page file was created, used as the publication time.
+
+*   `modified_at`
+
+    The time at which the page file was last modified, used as the time at which this feed entry was
+    updated.
+
+    > This is the field that is used to sort the entries.
+    {.information}
+
+*   `title`
+
+    The title of the page file, used as title of the feed entry.
+
+*   `author`
+
+    The name of the author of the page file, used as the author of the feed entry.
+
+*   `author_url`
+
+    The URL of the homepage of the author. Only used if the `author` meta information is also set.
+
+The default implementation supports the generation of atom and RSS feeds. You can override the
+default generation mechanism by adding an `atom_template` and/or `rss_template` block in the feed
+file which are then used to generate the atom or the RSS feed respectively.
+
+[1]: http://sporkmonger.com/projects/feedtools