gettalong-webgen 0.5.4.20080929

data/doc/reference_metainfo.page

@@ -0,0 +1,213 @@
+---
+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.
+
+### 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 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.
+
+### 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.
+{.exclamation}
+
+### 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/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,82 @@
+---
+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).
+
+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.
+
+*   `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`.
+
+*   `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.
+
+*   `icon` (OPTIONAL)
+
+    The absolute localized canonical name of the feed's icon image.
+
+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.
+
+*   `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.

data/doc/sourcehandler/metainfo.page

@@ -0,0 +1,41 @@
+---
+title: Webgen::SourceHandler::Metainfo
+---
+## Description
+
+This source handler provides the ability to set meta information for any path. It uses files in
+[Webgen Page Format]({relocatable: ../webgen_page_format.html}) which can have two special blocks:
+
+* `paths`: This block specifies meta information for paths and therefore this meta information is
+  applied before a node for a path is created. This can be used, for example, to change the output
+  path style. When specifying patterns, remember that the patterns are matched against paths!
+
+* `alcn`: This block specifies meta information for nodes and this meta information is applied
+  directly after a node has been created. When specifying patterns, remember that the patterns are
+  matched against absolute localized canonical names! So you always need to take the language part
+  into account, ie. `/index.html` won't match but `/index.en.html`.
+
+When no name is specified in the meta information file, the first block is assumed to be the `paths`
+block and the second block is assumed to be the `alcn` block. The format of the two blocks is the
+same: they need to be in YAML format and provide a hash with path patterns as keys and the
+to-be-assigned meta information as values. This is best showed in an example:
+
+    --- name:paths
+    /**/index.page:
+      output_path_style: [:parent, :cnbase, :ext, [., :lang]]
+
+    mypic.jpg:
+      in_menu: true
+    --- name:alcn
+    **/index.en.html:
+      in_menu: true
+
+All paths named `index.page` are assigned a new output path style. This has to be done in the
+`paths` block because otherwise it would have no effect. And the file `mypic.jpg` will show up in
+the menu. Notice, that the first form is specified as an absolute path pattern and the second
+not. If this meta information file lies in the root directory there is no difference between those
+two approaches. However, when it lies in a sub directory, the first form is still absolute but the
+second form is taken relative to the directory in which the meta information file is in.
+
+And last but not least, all nodes with a localized canonical name of `index.en.html` will show up in
+the menu (again, notice that the pattern is relative).

data/doc/sourcehandler/page.page

@@ -0,0 +1,30 @@
+---
+title: Webgen::SourceHandler::Page
+---
+## Description
+
+This source handler uses page files which are used to specify the actual content for the
+website. These files are written using [Webgen Page Format]({relocatable:
+../webgen_page_format.html}). Therefore they contain the content for the web page and, optionally,
+meta information.
+
+*In contrast* to other handled files, page files can never be unlocalized! If they have no language
+set, the default language specified using the configuration option `website.lang` is used. This
+means that for the default language set to English and a source path named `index.page`, the
+language meta information is automatically set to English.
+
+## Fragment nodes
+
+The page handler automatically generates fragment nodes for all found header tags in the block named
+`content` (i.e. `h1`, `h2`, ...) that have an `id` attribute set. The default markup language Maruku
+automatically generates an `id` attribute for all headers. If you use another markup language or
+plain old HTML, you might need to set the `id` attributes by hand.
+
+> The reason why only header tags with an `id` attribute are used is that only those can be
+> referenced and linked to later.
+{.information}
+
+The generated fragment nodes can be used like any other node. So you can link to them and use them
+in a menu. Concerning the menu, there is a setting for the `tag.menu.used_nodes` option called
+`fragments` which only uses the fragment node of the current page to generate a menu. This allows to
+generate a nice overview of the page.

data/doc/sourcehandler/sitemap.page

@@ -0,0 +1,46 @@
+---
+title: Webgen::SourceHandler::Sitemap
+---
+## Description
+
+This source handler automatically generates a sitemap based on the specification of
+[sitemaps.org](http://sitemaps.org) from a file in [Webgen Page Format]({relocatable:
+../webgen_page_format.html}).
+
+> This extension can only be used if you have installed the [builder](http://builder.rubyforge.org)
+> library. The preferred way to do this is via Rubygems:
+>
+>     gem install builder
+{.exclamation}
+
+The following meta information keys are supported:
+
+*   `site_url` (MANDATORY)
+
+    The base url of the website for which the sitemap is generated.
+
+*   `default_change_freq` (OPTIONAL)
+
+    The default change frequency of a file.
+
+*   `default_priority` (OPTIONAL)
+
+    The default priority of a file.
+
+You can also specify all common sitemap configuration options to customize the output of the source
+handler.
+
+The following meta information keys of files are used if they are specified:
+
+*   `modified_at`
+
+    The time at which the file was last modified, used as the time at which this feed entry was
+    updated.
+
+*   `change_freq`
+
+    The change frequency of the the file.
+
+*   `priority`
+
+    The priority of the file in respect to the other files.