webgen 0.5.0 → 0.5.1

data/doc/reference_metainfo.page

@@ -73,6 +73,15 @@ path.
 
 Specifies whether an output path for this node gets written or not.
 
+### 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}

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,20 @@
+---
+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 identification string 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/metainfo.page

@@ -1,117 +1,40 @@
 ---
-title: SourceHandler::Metainfo
+title: Webgen::SourceHandler::Metainfo
 ---
-
-> TODO: This information needs to be updated
-{.exclamation}
-
-### The meta information backing file {#metainfo-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
-sections are separated by three dashes on an otherwise empty line.
-
-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 (localized) canonical names (for assigning meta info to existing nodes) or
-* a path pattern for matching against localized canonical names (for assigning meta info to multiple
-  existing nodes)
-* the desired output names (for creating virtual nodes)!
-
-The different cases are handled like this:
-
-* If a path has a `*` or a `?` in it, it is considered a path pattern and the meta information is
-  assigned to all nodes whose localized canonical name matches the pattern.
-
-  > Since the localized canonical name of the nodes are used, you need to remember that the pattern
-  > `**/*.html` sets the meta information on all nodes ending in `.html` whereas the pattern
-  > `**/*.en.html` only sets the meta information on English nodes ending in `.html`.
-  {.information}
-
-* If a specified path resolves to an already created node, the meta information is applied to this
-  node.
-
-* If the path ends in an slash, a directory node is created with the meta information.
-
-* 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 specify meta information common to a set of nodes (for
-example, the author of blog pages), to include links to external web pages in menus or to create a
-whole menu with custom sections and multiple references in different sections to the same node!
-
-Following is a sample meta information backing file with explanations afterwards:
-
-    index.page:
-      inMenu: true
-      sort_info: 2
-
-    images:
-      indexFile: ~
-    ---
-    index.html:
-      inMenu: false
-
-    wiki.html:
-      title: Link to wiki
-      url: http://myhost.com/path/to/my/wiki
-      inMenu: true
-      sort_info: 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
-
-    **/*.html:
-      author: The Real Author
-
-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 `sort_info` 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.html`) 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 virtual 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
-  Tag/Relocatable plugin can be used.
-
-* The next 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`.
-
-* The last entry set the `author` meta information on all nodes that end with `.html`.
+## 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!
+
+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

@@ -1,32 +1,14 @@
 ---
 title: Webgen::SourceHandler::Page
 ---
+## Description
 
-> TODO: this needs to be redone!
-{.exclamation}
+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.
 
-
-### Processing
-
-TODO: redo this whole section
-
-There is a well defined procesing order for files in WebPage Format:
-
-* After reading in the file, it is split into the blocks.
-
-* Each content block is converted to HTML (depends on the format specifier) and the HTML sections
-  are resolved (caveat: only those with an `id` attribute)
-
-* When writing out the file, the converted content is first processed with ERB (if specified to do
-  so),
-
-* then webgen tags are replaced and,
-
-* finally, the result is written.
-
-The first two steps happen when the file is read and the last three when the file is written.
-
-#### Converting to HTML
-
-The conversion of a content block to HTML is done via the ContentConverter plugins. Each plugin is
-able to convert a special marked-up text to HTML.
+*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.

data/doc/sourcehandler/template.page

@@ -0,0 +1,45 @@
+---
+title: Webgen::SourceHandler::Template
+---
+## Description
+
+The template handler processes the templates files. 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 are in [Webgen Page Format]({relocatable: ../webgen_page_format.html}) (the format which is
+also used for page files).
+
+The configuration option `sourcehandler.template.default_template` specifies the name of the default
+template which is used when no explicit template 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.
+
+webgen also uses the concept of a template chain to support multiple templates for one page
+file. For example, assume that
+
+* the page file `index.page` has set the `template` meta information to `special.template`,
+* the template `special.template` has no `template` meta information set and
+* the page file `other.page` also has no `template` meta information set.
+
+The template chain for `index.page` would look like this
+
+    default.template <-- special.template <-- index.page
+
+whereas the template chain for `other.page` would look like this
+
+    default.template <-- index.page
+
+The first case also means that the `special.template` is nested in the `default.template`. 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.
+
+To stop the template handler from further searching for a template, you explicitly need to set a
+null template for the page or template file:
+
+    template: ~
+
+This is useful if you want to have a different `default.template` in a sub directory which should
+provide a different look-and-feel for this subtree as the `default.template` in the root of the
+website.

data/doc/sourcehandler/virtual.page

@@ -0,0 +1,49 @@
+---
+title: Webgen::SourceHandler::Virtual
+---
+## Description
+
+This source handler uses files in [Webgen Page Format]({relocatable: ../webgen_page_format.html})
+which are used to specify virtual paths. Virtual paths don't really exist as source paths but are
+useful nonetheless. For example, they allow to include links to external content in automatically
+generated menus. They are never written out since they define no real content!
+
+The `content` block of the source path is used and its content needs to be a hash in YAML
+format. The keys are relative or absolute source paths names and the values meta information for
+them. Any meta information can be set on a virtual path but one meta information key is special:
+`url`. This meta information specifies, relative to the directory in which the source file is in,
+the output path for the virtual node. If no `url` meta information is specified, the source path
+itself is used as output path.
+
+Following is a sample virtual source files with explanations afterwards:
+
+    \--- !omap
+    - /documentation/:
+
+    - /documentation/index.html:
+        routed_title: Documentation
+
+    - download_and_installation.html:
+        in_menu: true
+        sort_info: 25
+        url: index.html#download__installation
+
+    - /documentation/api.html:
+        title: API Reference
+        url: http://myhost.com/api
+
+> The example does not use a normal hash but an ordered YAML map. This ensures that the virtual
+> nodes are created in the order they appear in the file.
+{.information}
+
+The first entry specifies that a directory `/documentation` should be created. The virtual file
+handler recognizes this because the given path ends in a slash!. Then a virtual index file for the
+virtual directory is created. This would be done, for example, when the documentation directory is
+created by an external program.
+
+The third entry specifies a virtual file that should in the menu and should have a certain sort
+information. When this virtual file is referenced, the path given by the `url` key is returned. This
+example shows how to make a single link to a fragment appear in automatically generated menus.
+
+And the fourth entry specifies another virtual file whose output path is an URL pointing to
+`http://myhost.com/api`.

data/doc/tag.template

@@ -0,0 +1,26 @@
+---
+template: extensions.template
+--- name:summary pipeline:erb,tags,maruku,blocks
+
+The following tag names are registered for this tag class:
+<%= context.website.config['contentprocessor.tags.map'].
+      select {|k,v| v == context.content_node['title']}.
+      map {|k,v| '`' + (k.kind_of?(Symbol) ? k.inspect : k.to_s) + '`'}.join(', ') %>
+
+<% if context.content_node['used_options'] %>
+This tag uses the following options (see [configuration option reference]({relocatable:
+reference_configuration.html}) for detailed information on the options):
+
+<%
+for option in context.content_node['used_options']
+  temp = 'mandatory' if !context.website.config.meta_info[option][:mandatory].nil?
+  temp += ' default' if context.website.config.meta_info[option][:mandatory] == 'default'
+%>* `<%= option %>` <%= temp ? '(' + temp + ')' : '' %>
+<%
+  temp = nil
+end
+ %>
+
+<% end %>
+--- name:content
+<webgen:block name='content' />

data/doc/tag/breadcrumbtrail.page

@@ -0,0 +1,32 @@
+---
+title: Webgen::Tag::BreadcrumbTrail
+used_options:
+  - tag.breadcrumbtrail.separator
+  - tag.breadcrumbtrail.omit_last
+  - tag.breadcrumbtrail.omit_index_path
+---
+## Description
+
+The breadcrumb trail tag is used for displaying the hierarchy of the current page. The behavior of
+the `tag.breadcrumbtrail.omit_index_path` option can be overridden for individual index paths by
+setting the meta information `omit_index_path` accordingly.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{breadcrumb_trail:}</td>
+  <td>{breadcrumb_trail:}</td>
+</tr>
+<tr>
+  <td>\{breadcrumb_trail: {separator: " HELLO "}}</td>
+  <td>{breadcrumb_trail: {separator: " HELLO "}}</td>
+</tr>
+<tr>
+  <td>\{breadcrumb_trail: {omit_last: true}}</td>
+  <td>{breadcrumb_trail: {omit_last: true}}</td>
+</tr>
+</table>

data/doc/tag/coderay.page

@@ -0,0 +1,49 @@
+---
+title: Webgen::Tag::Coderay
+used_options:
+  - tag.coderay.lang
+  - tag.coderay.process_body
+  - tag.coderay.wrap
+  - tag.coderay.line_numbers
+  - tag.coderay.line_number_start
+  - tag.coderay.bold_every
+  - tag.coderay.tab_width
+---
+## Description
+
+This tag applies syntax highlighting to its body by using the [coderay][1] library which can be used
+to highlight many different languages (see `tag.coderay.lang` documentation). The body of the tag
+specifies what should be highlighted.
+
+> It is easy to include and highlight an entire file by combining this tag with the `include_file` tag:
+>
+>     \{coderay:: ruby}{include_file: test.rb}{coderay}
+{.information}
+
+> This extension is only available if you have installed the [coderay][1] library. The preferred
+> way to do this is via Rubygems:
+>
+>     gem install coderay
+{.exclamation}
+
+[1]: http://coderay.rubychan.de/ "The Coderay homepage"
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{coderay:: {lang: ruby, bold_every: 2}}{include_file: lib/webgen/version.rb}{coderay}</td>
+  <% if File.exists?(File.join(context.website.directory, 'lib/webgen/version.rb')) %>
+  <td>{coderay:: {lang: ruby, bold_every: 2}}{include_file: lib/webgen/version.rb}{coderay}</td>
+  <% else %>
+  <td>{coderay:: {lang: ruby, bold_every: 2}}{include_file: ../lib/webgen/version.rb}{coderay}</td>
+  <% end %>
+</tr>
+<tr>
+  <td>\{coderay:: {lang: ruby, wrap: span}}puts 5+5{coderay}</td>
+  <td><code>{coderay:: {lang: ruby, wrap: span}}puts 5+5{coderay}</code></td>
+</tr>
+</table>