webgen 0.3.8 → 0.4.0

data/doc/src/documentation/plugins/tag/resource.page

@@ -0,0 +1,35 @@
+---
+title: Resource
+inMenu: true
+template: /plugin.template
+plugin: Tag/Resource
+---
+h2(#description). Description
+
+
+The resource tag is used to include a resource either verbatim (i.e. its content is copied) or by
+its path. For more information about resources have a look at the {plugin: Core/ResourceManager}.
+
+This tag is mostly used in templates to include the webgen CSS and JS resources.
+
+
+h2(#examples). Examples
+
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td><notextile>\{resource: webgen-logo}</notextile></td>
+  <td><notextile>{resource: webgen-logo}</notextile></td>
+</tr>
+<tr>
+  <td><notextile>\{resource: w3c-valid-xhtml11}</notextile></td>
+  <td><notextile>{resource: w3c-valid-xhtml11}</notextile></td>
+</tr>
+<tr>
+  <td><notextile>\{resource: {name: webgen-css, insert: data}}</notextile></td>
+  <td><notextile>{resource: {name: webgen-css, insert: data}}</notextile></td>
+</tr>
+</table>

data/doc/src/documentation/plugins/tag/sitemap.page

@@ -0,0 +1,35 @@
+---
+title: Sitemap
+inMenu: true
+template: /plugin.template
+plugin: Tag/Sitemap
+---
+h2(#description). Description
+
+
+The SitemapTag is used to display a site map of the current website. There are two operation modi:
+if the parameter {param: Tag/Sitemap:honorInMenu} is @true@, then only those pages are shown in the
+sitemap for which the @inMenu@ meta information is set. If it is @false@, then all pages are
+displayed. The tag also respects the @orderInfo@ meta information!
+
+*Caveat*: Only page files are shown in the sitemap and from those not all, but only the ones in the
+language of the page file the sitemap tag is used in (i.e. the tag shows the sitemap for a specific
+language).
+
+
+h2(#examples). Examples
+
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td><notextile>\{sitemap: }</notextile></td>
+  <td><notextile>{sitemap: }</notextile></td>
+</tr>
+<tr>
+  <td><notextile>\{sitemap: {honorInMenu: false}}</notextile></td>
+  <td><notextile>{sitemap: {honorInMenu: false}}</notextile></td>
+</tr>
+</table>

data/doc/src/documentation/plugins/tag/wikilink.page

@@ -0,0 +1,33 @@
+---
+title: WikiLink
+inMenu: true
+template: /plugin.template
+plugin: Tag/WikiLink
+---
+h2(#description). Description
+
+
+This tag can be used to add a link to a wiki page. It is used on this website to automatically
+provide a "Feedback" link for each page.
+
+
+h2(#examples). Examples
+
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td><notextile>\{wikilink: }</notextile></td>
+  <td><notextile>{wikilink: }</notextile></td>
+</tr>
+<tr>
+  <td><notextile>\{wikilink: {relURL: hallo}}</notextile></td>
+  <td><notextile>{wikilink: {relURL: hallo}}</notextile></td>
+</tr>
+<tr>
+  <td><notextile>\{wikilink: {relURL: hallo, linkText: MoinMoin}}</notextile></td>
+  <td><notextile>{wikilink: {relURL: hallo, linkText: MoinMoin}}</notextile></td>
+</tr>
+</table>

data/doc/src/documentation/references/index.page

@@ -1,7 +1,6 @@
 ---
 title: References
 directoryName: References
-orderInfo: 25
 ---
 h2. About
 

data/doc/src/documentation/references/meta_info_reference.page

@@ -1,22 +1,99 @@
 ---
 title: Meta Info Reference
 inMenu: true
-orderInfo: 25
 ---
 h2. Meta Information Reference
 
 Following is a list of all the meta information items that are used in one way or another by a
 plugin, be it a file handler plugin, a tag plugin...
 
-table{border: 1px solid black}.
-|_. Name         |_. Type  |_. Example    |_. Valid for   |_. Description|
-|*blocks*        |Hash     |\{format: markdown, name: sidebar}|Page file|Sets the name and format of content blocks.|
-|*directoryName* |String   |Img Directory |Page file      |Only used if set on a directory index page file; specifies the title of the directory for which it is the index file. If it is not specified, the title of the directory  will be used.|
-|*indexFile*     |String   |getting.page  |Directory      |Sets the directory index file for the directory overriding the default value.|
-|*inMenu*        |Boolean  |true          |Any            |Specifies if the file/directory should appear in menus.|
-|*lang*          |String   |de            |Page file      |Sets the language for the page file. Has to be the two character code for the language.|
-|*orderInfo*     |Integer  |15            |Any            |Sets the orderering information for the file/directory.|
-|*template*      |String   |my.template   |Page file      |Sets the template for the page file overriding the default value.|
-|*title*         |String   |New Title     |Any            |Sets the title for the file/directory.|
-|*useERB*        |Boolean  |false         |Page file      |Specifies if the content blocks of the page file should be processed with ERB overriding the default value.|
-|*emoticonPack*  |String   |bigeyes       |Page file      |Sets the emoticon package which should be used for the page.|
+<table class="metainfo">
+<tr>
+  <th>Name</th><th>Type</th><th>Example</th><th>Valid for</th><th>Description</th>
+</tr>
+<tr>
+  <th>blocks</th>
+  <td>Array of Arrays</td>
+  <td>[[content, markdown], [sidebar, html]]</td>
+  <td>Page/Template file</td>
+  <td>Sets the name and format of content blocks. Each sub-array contains, in this order, the name
+      of the block and its format.</td>
+</tr>
+<tr>
+  <th>directoryName</th>
+  <td>String</td>
+  <td>Image Directory</td>
+  <td>Page file</td>
+  <td>Only used if set on a directory index page file; specifies the title of the directory for
+      which it is the index file. If it is not specified, the title of the directory will be
+      used.</td>
+</tr>
+<tr>
+  <th>indexFile</th>
+  <td>String</td>
+  <td>getting.page</td>
+  <td>Directory</td>
+  <td>Sets the directory index file for the directory overriding the default value.</td>
+</tr>
+<tr>
+  <th>inMenu</th>
+  <td>Boolean</td>
+  <td>true</td>
+  <td>Any</td>
+  <td>Specifies if the file/directory should appear in menus.</td>
+</tr>
+<tr>
+  <th>lang</th>
+  <td>String</td>
+  <td>de</td>
+  <td>Page file</td>
+  <td>Sets the language for the page file. Has to be a valid ISO-639-1/2 character code for the language.</td>
+</tr>
+<tr>
+  <th>orderInfo</th>
+  <td>Integer</td>
+  <td>15</td>
+  <td>Any</td>
+  <td>Sets the ordering information for the file/directory. The value 0 is used as default and means 'not set'.
+      You should only use numbers greater than zero. However, if you want a menu item to always appear as first item,
+      it is recommended to use the value -1. When sorting nodes, the @orderInfo@ value is used first. If the values for both
+      nodes are the same, then they are sorted according to their @title@ meta information.
+  </td>
+</tr>
+<tr>
+  <th>template</th>
+  <td>String</td>
+  <td>my.template</td>
+  <td>Page/Template file</td>
+  <td>Sets the template for the page/template file overriding the default value.</td>
+</tr>
+<tr>
+  <th>title</th>
+  <td>String</td>
+  <td>New Title</td>
+  <td>Any</td>
+  <td>Sets the title for the file/directory.</td>
+</tr>
+<tr>
+  <th>useERB</th>
+  <td>Boolean</td>
+  <td>false</td>
+  <td>Page/Template file</td>
+  <td>Specifies if the content blocks of the page/template file should be processed with ERB overriding the default value.</td>
+</tr>
+<tr>
+  <th>linkAttrs</th>
+  <td>Hash</td>
+  <td>\{title: Hallo, class: extra}</td>
+  <td>Any</td>
+  <td>Specifies additional attribute-value pairs (in form of a Hash) that should be added to a link to the file/directory.</td>
+</tr>
+<tr>
+  <th>emoticonPack</th>
+  <td>String</td>
+  <td>bigeyes</td>
+  <td>Page file</td>
+  <td>Sets the emoticon package which should be used for the page.</td>
+</tr>
+</table>
+

data/doc/src/documentation/references/parameter_reference.page

@@ -1,7 +1,6 @@
 ---
 title: Plugin Parameter Reference
 inMenu: true
-orderInfo: 22
 ---
 h2. Plugin Parameter Reference
 

data/doc/src/documentation/references/webpage_format.page

@@ -0,0 +1,249 @@
+---
+title: WebPage Format
+inMenu: true
+---
+
+h1. The WebPage Format
+
+
+The WebPage Format is a custom format designed for page and template files. It consists of one or
+more blocks of data, is very simple and easy to use.
+
+
+h2(#structure). Structure
+
+
+A file using the WebPage Format consists of one or more blocks which are the smallest units
+recongnized. Blocks are separated from each other through a line containing only three dashes. This
+is illustrated in the following examples which are all valid files in WebPage Format:
+
+<pre>
+Here is a block!
+</pre>
+
+<pre>
+This is one block of the file
+\---
+This is another block.
+</pre>
+
+<pre>
+Block 1
+\--- block2
+Block 2
+\--- block3
+Block 3...
+</pre>
+
+If you want to use three dashes in a block but you don't want to end the block, you have to escape
+them with a backslash character, like this:
+
+<pre>
+Block 1
+\\---
+still Block 1
+\--- block2
+Block 2
+</pre>
+
+All of the above examples show one kind of block, the content block. However, there may also be
+another type of block: the meta information block. Following is a short description of both kinds,
+starting with the meta information block.
+
+
+h3(#metainfo-block). Meta Information Block
+
+
+Each file in WebPage Format can have zero or one meta information blocks. This block is specified at
+the beginning of the file. To tell the parser that the first block is the meta information block and
+not a content block, you have to start the file with three dashes:
+
+<pre>
+\---
+title: The title set by Meta info
+\---
+This is the content of the file
+</pre>
+
+The above defines a meta information block and a content block. The meta information block has to be
+in YAML format and should contain key-value pairs of meta information. YAML is a simple markup
+language designed for ease of use. For more information about YAML, have a look at
+"www.yaml.org":http://www.yaml.org!
+
+
+h3(#content-blocks). Content Blocks
+
+
+A content block is used to provide content in a specific format. Each file in WebPage Format needs
+to have at least one content block which may be empty. However, it can have as many content blocks
+as necessary. Each content block needs to have a unique name and a format specifier.
+
+The name uniquely identifies a content block and is used to access it. The format specifier defines
+in which format the content block was written. The important thing is that all the formats can be
+converted into HTML/XML! There are several different formats available - have a look a the {plugin:
+ContentConverter} section.
+
+There may also be defaults for the two identifiers but they can be overwritten. There are two ways
+to do this:
+
+* you either specify the name and format of the block on the line with the three dashes
+* or you use the special meta information block to define the names and formats of all blocks.
+
+The following example uses the first technique to override the name and/or the format:
+
+<pre>
+1. content block of the file
+\--- sidebar, markdown
+2. content block of the file
+\--- other
+3. content block of the file
+</pre>
+
+The first block has no identifieres set (there is no line with three dashes and the identifieres).
+Therefore the default values for both are used: @content@ is the default block name and @default@ is
+the default format specifier. However, these defaults can be overridden by the plugins.
+
+The second block is named @sidebar@ and uses the format @markdown@. As you see, first the name of
+the block is specified and then, separated by a comma, the format specifier. The format identifier
+can be omitted as shown for the third block, the default value is then used.
+
+You can also set the name and format of the content blocks by using the special @blocks@ meta
+information. It is an array of arrays and each sub-array contains, in this order, the name of the
+block and its format. The above example can therefore also be written like this:
+
+<pre>
+\---
+blocks: [[content,default], [sidebar, markdown], [other, ~]]
+\---
+1. content block of the file
+\---
+2. content block of the file
+\---
+3. content block of the file
+</pre>
+
+With everything said above the example should be clear except maybe for the last sub-array. The
+first entry specifies the name, @other@, and the second the format, @~@. The tilde has a special
+meaning in YAML format, namely null or empty. This means that we want to use the default format for
+the last block.
+
+The *default name* for a block is @content@ and is used if no explicit name is given on the line
+with the three dashes or in the blocks meta information at the correct index. The precedence is
+(from high to low): --- line, blocks meta information, default value.
+
+The *default format* for a block is @default@ and the rules stated above for the block name apply to
+the default format as well.
+
+
+h2(#tags). webgen Tags
+
+
+Tags are used to generate content. During processing of a file in WebPage Format so called 'tags'
+are replaced with dynamic content. For example, the menu you can see to the left was generated by a
+tag. This makes it easier to add or remove menu items. If the menu was not generated, you would have
+to change every file which uses the menu.
+
+
+h3(#tags-usage). Usage
+
+
+Tags are defined by a special markup code. A tag has the following structure:
+
+<pre>\{tagname: {parameters}}</pre>
+
+Every time a tag is found in a file, the registered plugin for the tag is called. The plugin returns
+a string which is put into the output file instead of the tag. The output a tag plugin can produce
+ranges from something simple to something complex. For example, the {plugin: Tag/Meta} plugin copies
+any additional meta information specified in the file verbatim into the correct place in the output
+file. And in contrast, the {plugin: Tag/Menu} plugin generates a whole menu tree.
+
+If you want to use the markup code used for tags, you need to escape the tag with a backslash, like
+this:
+
+<pre>\\\{tagname: {parameters}}</pre>
+
+
+h3(#tags-params). Parameters
+
+
+A tag can have zero or more parameters some of which are mandatory. You can see the supported
+parameters (and if they are mandatory) for each tag on the tag's plugin page. The default mandatory
+parameter can be specified in a special way, see the examples below. The format used for parsing the
+parameters is YAML.
+
+Here some examples with tags and parameters:
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>@\{tagname: }@</td>
+  <td>No parameters specified</td>
+</tr>
+<tr>
+  <td>@\{tagname: test.html}@</td>
+  <td>The default mandatory parameter is set to @test.html@. This form can only be used if there is only one mandatory parameter</td>
+</tr>
+<tr>
+  <td>@\{tagname: {param1: value1, param2: value2}}@</td>
+  <td>Two parameters (param1 and param2) specified</td>
+</tr>
+</table>
+
+
+h2(#processing). Processing
+
+
+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.
+
+
+h3(#proc-html). Converting to HTML
+
+
+The conversion of a content block to HTML is done via the {plugin: ContentConverter} plugins. Each
+plugin is able to convert a special marked-up text to HTML.
+
+
+h3(#proc-erb). Evaluating ERB Tags
+
+
+The evaluation of ERB (embedded ruby) tags is optional and only done if the meta information
+@useERB@ is set to @true@. The use of ERB allows to add dynamic content without using webgen tags.
+Following is an example of a file which uses ERB:
+
+<notextile>
+<pre>
+\---
+title: Test page with ERB
+useERB: true
+\---
+This page has the following meta info items:
+&lt;% node.meta_info.each do |key, value| %&gt;
+    * &lt;%=key %&gt;: &lt;%=value %&gt;
+&lt;% end %&gt;
+</pre>
+</notextile>
+
+This would output all meta information for the file. There are some objects available which you can
+use in your ERB code:
+
+* @node@: the node for the current file (normally a page file)
+* @ref_node@: the reference node, i.e. the node in which the content will be embedded (normally a
+  template file)
+
+
+h3(#proc-tags). Evaluating webgen Tags
+
+
+Tags have already been mentioned in the <a href="{relocatable: '#tags'}">webgen tags</a> section.