gettalong-webgen 0.5.4.20080929

data/doc/reference_configuration.page

@@ -0,0 +1,646 @@
+---
+title: Configuration Option Reference
+in_menu: false
+---
+
+# Configuration Option Reference
+
+This reference describes all available configurations that can be set via the configuration file
+(or, if you want to have more control, via an extension file).
+
+## General Options
+
+*   ### website.lang
+
+    Specifies the default language of the website. The default language is assigned, for example, to
+    page files for which a language is not explicitly specified.
+
+    * Syntax: `LANGUAGE` where `LANGUAGE` is a ISO-639-1/2 two or three letter language code
+
+    * Examples:
+
+          website.lang: deu
+          website.lang: fr
+
+
+*   ### website.link\_to\_current\_page
+
+    If this option is set to `true`, automatically generated links from a page to itself are
+    used. Otherwise, only the title of the page is shown.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is `true` or `false`
+
+    * Examples:
+
+          website.link_to_current_page: false
+
+
+*   ### website.cache
+
+    Specifies the type and location of the cache. Two types are currently supported: `:file` and
+    `:string`. The file cache type stores the cache in a file relative to the website directory. The
+    string cache type stores the cache directly in the second part of the configuration option (this
+    is only useful when webgen is used as a library).
+
+    * Syntax: `[TYPE, LOCATION]` where `TYPE` is one of `:file` or `:string`
+
+    * Examples:
+
+          website.cache: [:file, my.cache]
+
+
+## Commonly Used Options
+
+*   ### common.sitemap.honor\_in\_menu
+
+    Specifies whether the sitemap should only include nodes that have the meta information `in_menu`
+    set.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          Sitemap with in-menu nodes: \{sitemap: {honor_in_menu: true}}
+
+
+*   ### common.sitemap.any\_lang
+
+    Specifies whether the sitemap should include nodes in any language or only those without a
+    language or with the language of the node in which the sitemap tag is used.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          Sitemap with nodes in any language: \{sitemap: {any_lang: true}}
+
+
+*   ### common.sitemap.used\_kinds
+
+    Specifies the kind of nodes that should be used in the sitemap. This defaults to all nodes with
+    the kind `page`. If this is set to an empty array, any kind of node is used.
+
+    * Syntax: `[KIND, ...]` where `KIND` is the kind of node that should be used.
+
+    * Examples:
+
+          Sitemap with only asset nodes: \{sitemap: {used_kinds: [asset]}}
+
+
+## Source and Output Specific Options
+
+*   ### sources
+
+    Specifies one or more sources from which paths are read. This can also be used, for example, to
+    additionally add other directories as source directories that may or may not be located in the
+    website directory.
+
+    * Syntax: `[[MOUNT POINT, NAME, ARG1, ARG2, ...], ...]` where `MOUNT POINT` is the path under
+      which the source should be mounted, `NAME` is the name of the source class (for example,
+      `Webgen::Source::FileSystem`) and `ARG1`, `ARG2` and so on are the parameters for the source
+      class. The supported parameters can be found in the documentation for each source class.
+
+    * Examples:
+
+          sources: [[/, Webgen::Source::FileSystem, src], [/, Webgen::Source::FileSystem, /mnt/pictures, **/*.jpg]
+
+
+*   ### output
+
+    Specifies the output class that should be used for writing out the generated paths.
+
+    * Syntax: `[NAME, ARG1, ARG2, ...]` where `NAME` is the name of the output class (for example,
+      `Webgen::Output::FileSystem`) and `ARG1`, `ARG2` and so on are the parameters for the output
+      class. The supported parameters can be found in the documentation for each output class.
+
+    * Examples:
+
+          output: [Webgen::Output::FileSystem, custom_out]
+
+
+*   ### sourcehandler.patterns
+
+    Specifies the path patterns that are used by the individual source handlers. This configuration
+    option is not normally set in the configuration file but in an extension file
+    (e.g. `ext/init.rb`) because otherwise the default entries would be overwritten.
+
+    * Syntax: `\{NAME: [PATTERN, PATTERN, ...], ...}` where `NAME` is the
+      name the name of a source handler and `PATTERN` are one or more path patterns.
+
+    * Examples (for `ext/init.rb`):
+
+          config.sourcehandler.patterns['Webgen::SourceHandler::Copy'] << '**/*.swf'
+
+
+*   ### sourcehandler.invoke
+
+    Specifies the invocation order of the various source handlers. This configuration option should
+    normally only be used by extensions to register their source handlers!
+
+    * Syntax: `\{ORDER: [NAME, ...], ...}` where `ORDER` is a number identifying the priority of the
+      invocation (source handlers with a lower `ORDER` setting are executed earlier than ones with a
+      higher `ORDER` setting) and `NAME` is the name of a source handler.
+
+    * Examples (for `ext/init.rb`):
+
+          config.sourcehandler.invoke[5] << 'Extension::MyNewSourceHandler'
+
+
+*   ### sourcehandler.casefold
+
+    Specifies whether path names should be considered case-sensitive (set to `false`) or
+    case-insensitive (set to `true`).
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          sourcehandler.casefold: true
+
+
+*   ### sourcehandler.use\_hidden\_files
+
+    Specifies whether hidden files (those starting with a dot) should be used.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          sourcehandler.use_hidden_files: true
+
+
+*   ### sourcehandler.ignore
+
+    Specifies path patterns that should be ignored. All paths that match at least one of the
+    patterns are never used.
+
+    * Syntax: `[PATTERN, ...]` where `PATTERN` is a valid path pattern.
+
+    * Examples:
+
+          sourcehandler.ignore: [**/*~, **/CVS/**]
+
+
+*   ### sourcehandler.default\_lang\_in\_output\_path
+
+    Specifies whether output paths in the default language should have the language code in their
+    name.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          sourcehandler.default_lang_in_output_path: true
+
+
+*   ### sourcehandler.default\_meta\_info
+
+    Specifies default meta information for all source handlers or for specific ones. The
+    configuration file provides a shortcut for setting meta information items using the special
+    `default_meta_info` key (see the examples).
+
+    * Syntax: `\{NAME: {MI_KEY: MI_VALUE, ...}, ...}` where `NAME` is either the name of a source
+      handler or the special key `:all` which sets default meta info for all source handlers.
+
+    * Examples:
+
+          default_meta_info:
+            :all:
+              output_path_style: [:parent, :cnbase, :lang, :ext]
+            Webgen::SourceHandler::Page:
+              in_menu: true
+
+
+*   ### sourcehandler.template.default\_template
+
+    Specifies the name of the default template file of a directory. This template is used as
+    fallback when no specific template is specified.
+
+    * Syntax: `PATH` where `PATH` is the absolute localized canonical name of the default template.
+
+    * Examples:
+
+          sourcehandler.template.default_template: other.template
+
+
+## Content Processor Specific Options
+
+*   ### contentprocessor.map
+
+    This configuration option maps short names for content processor to their class names. The short
+    names are used, for example, in the procesing pipeline of a content block of a file in Webgen
+    Page Format. This configuration option is normally only used by extensions to register the short
+    name of a content processor!
+
+    * Syntax: `\{SHORT: NAME, ...}` where `SHORT` is the short name of the content processor class
+      `NAME`.
+
+    * Examples (for `ext/init.rb`):
+
+          config['contentprocessor.map']['newcp'] = 'Extension::MyNewContentProcessor'
+
+
+*   ### contentprocessor.erubis.use\_pi
+
+    Specifies whether Erubis should look for XML processing instructions or the standard ERB tags
+    when processing content.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          contentprocessor.erubis.use_pi: true
+
+
+*   ### contentprocessor.erubis.options
+
+    This configuration option can be used to specify additional options that the Erubis processor
+    should use.
+
+    * Syntax: `\{KEY: VALUE, ...}` where `KEY` and `VALUE` are key-value pairs of options where
+      `KEY` needs to be a Symbol and not a String.
+
+    * Examples:
+
+          contentprocessor.erubis.options: {:trim: true}
+
+
+*   ### contentprocessor.tags.prefix
+
+    Specifies the optional prefix that is used for tag names to avoid name clashes when another
+    content processor uses similar markup.
+
+    * Syntax: `PREFIX` where `PREFIX` is the prefix name.
+
+    * Examples:
+
+          contentprocessor.tags.prefix: webgen
+          contentprocessor.tags.prefix: tag
+
+
+*   ### contentprocessor.tags.map
+
+    This configuration option maps short names for tag classes to tag class names. The short names
+    are used in page and template files to specify the tag. This configuration option is normally
+    only used by extensions to register the short name of a content processor.
+
+    * Syntax: `\{SHORT: NAME, ...}` where `SHORT` is the short name of the tag class `NAME`.
+
+    * Examples (for `ext/init.rb`):
+
+          config['contentprocessor.tags.map']['highlight'] = 'Extension::MyHighlightingTag'
+
+
+## Tag Specific Options
+
+These options are not normally set in the configuration file but given directly as options to the
+respective tag classes. Therefore, all examples in this section show the use of these options in
+files in Webgen Page Format.
+
+*   ### tag.breadcrumbtrail.separator
+
+    Specifies the string that should be used as separator between indivdual parts of the breadcrumb
+    trail.
+
+    * Syntax: `SEPARATOR` where `SEPARATOR` is a string (special HTML characters need to be properly
+      escaped)
+
+    * Examples:
+
+          Breadcrumb trail with different separator: \{breadcrumb_trail: {separator: ' --- '}}
+
+
+*   ### tag.breadcrumbtrail.omit\_index\_path
+
+    Specifies that the last part of the breadcrumb trail should be omitted if it is an index path.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          Breadcrumb trail with index path omitted: \{breadcrumb_trail: {omit_index_path: true}}
+
+
+*   ### tag.breadcrumbtrail.start\_level
+
+    Specifies the level at which the breadcrumb trail starts. The default of 0 means to start a the
+    root directory. Setting this option to 1 starts the breadcrumb trail at the first level. If you
+    specify negative numbers, then everything is calculated from the end of the trail. Following is
+    a diagram showing the level numbers for a sample path:
+
+         0   1        2           3
+         /  dir1  /  dir2  /  myfile.html
+        -4  -3       -2          -1
+
+    Be aware that the you need to take the `tag.breadcrumbtrail.omit_index_path` option into
+    account when specifying the level number.
+
+    * Syntax: `INTEGER` where `INTEGER` is any integer number
+
+    * Examples:
+
+          Breadcrumb trail starting at level 2: \{breadcrumb_trail: {start_level: 2}}
+
+
+*   ### tag.breadcrumbtrail.end\_level
+
+    Specifies the level at which the breadcrumb trail ends. Have a look at the documentation for
+    `tag.breadcrumbtrail.start_level` for more information on the useable level numbers.
+
+    * Syntax: `INTEGER` where `INTEGER` is any integer number
+
+    * Examples:
+
+          Breadcrumb trail ending at level 2: \{breadcrumb_trail: {end_level: 2}}
+
+
+*   ### tag.coderay.lang
+
+    Specifies the language that should be used for syntax highlighting.
+
+    * Syntax: `LANG` where `LANG` is one of <%= (require 'coderay'; CodeRay::Scanners.list.map {|n| '`' + n + '`'}.join(', ')) %>.
+
+    * Examples:
+
+          highlighting some ruby code \{coderay:: ruby}puts 5 + 5{coderay}
+
+
+*   ### tag.coderay.process\_body
+
+    Specifies whether the body of the tag should be processed by the tags content processor first.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          wrapping in a span: \{coderay:: {lang: ruby, process_body: false}}puts 5 + 5{coderay}
+
+
+*   ### tag.coderay.wrap
+
+    Specifies in which HTML element the highlighted code should be wrapped.
+
+    * Syntax: `WRAP` where `WRAP` is either `div` or `span`
+
+    * Examples:
+
+          wrapping in a span: \{coderay:: {lang: ruby, wrap: span}}puts 5 + 5{coderay}
+
+
+*   ### tag.coderay.line\_numbers
+
+    Specifies whether line numbers should be shown.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          not showing line numbers: \{coderay:: {lang: ruby, line_numbers: false}}puts 5 + 5{coderay}
+
+
+*   ### tag.coderay.line\_number\_start
+
+    Specifies the line number that should be used for the first line.
+
+    * Syntax: `NUMBER` where `NUMBER` is an integer value.
+
+    * Examples:
+
+          starting with line 4: \{coderay:: {lang: ruby, line_number_start: 4}}puts 5 + 5{coderay}
+
+
+*   ### tag.coderay.bold\_every
+
+    Specifies the interval at which the line numbers should appear bold.
+
+    * Syntax: `NUMBER` where `NUMBER` is an integer value.
+
+    * Examples:
+
+          every other line bold: \{coderay:: {lang: ruby, bold_every: 2}}puts 5 + 5{coderay}
+
+
+*   ### tag.coderay.tab\_width
+
+    Specifies the number of spaces that should be used to replace tabulator characters.
+
+    * Syntax: `NUMBER` where `NUMBER` is an integer value.
+
+    * Examples:
+
+          tabulator == 4 spaces: \{coderay:: {lang: ruby, tab_width: 4}}puts 5 + 5{coderay}
+
+
+*   ### tag.date.format
+
+    Specifies the format that should be used for formatting the current date. The format string
+    needs to be in a format supported by Ruby's method
+    [Time#strftime](http://www.ruby-doc.org/core/classes/Time.html).
+
+    * Syntax: `FORMAT` where `FORMAT` is a string.
+
+    * Examples:
+
+          very short date format: \{date: {format: '%Y-%m-%d'}}
+
+
+*   ### tag.executecommand.command
+
+    Specifies the command that should be executed. This option is the default mandatory option for
+    Webgen::Tag::ExecuteCommand.
+
+    * Syntax: `COMMAND` where `COMMAND` is the to-be-executed command.
+
+    * Examples:
+
+          executing a simple command \{exeucte_cmd: echo hallo}
+
+
+*   ### tag.executecommand.process\_output
+
+    Specifies whether the output of the executed command should be further processed by the tags
+    content processor.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          executing command without further processing \{execute_cmd: {command: 'echo hallo', process_output: false}}
+
+
+*   ### tag.executecommand.escape\_html
+
+    Specifies whether special HTML characters in the output of the executed command should be escaped.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          executing command, output not escaped \{execute_cmd: {command: 'echo hallo', escape_html: false}}
+
+
+*   ### tag.includefile.filename
+
+    Specifies the name of the file that should be included. The filename needs to be relative to the
+    website directory or an absolute path. This option is the default mandatory option for
+    Webgen::Tag::IncludeFile.
+
+    * Syntax: `FILENAME` where `FILENAME` is the name of a file
+
+    * Examples:
+
+          including a file \{include_file: my_file.txt}
+
+
+*   ### tag.includefile.process\_output
+
+    Specifies whether the content of the file should be further processed by the tags content
+    processor.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          including a file without further processing \{include_file: {filename: my_file.txt, process_output: false}}
+
+
+*   ### tag.includefile.escape\_html
+
+    Specifies whether special HTML characters in the content of the file should be escaped.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          including a file without escaping \{include_file: {filename: my_file.txt, escape_html: false}}
+
+
+*   ### tag.langbar.separator
+
+    Specifies the string that should be used as separator between the individual language parts.
+
+    * Syntax: `SEPARATOR` where `SEPARATOR` is a string (special HTML characters need to be properly
+      escaped)
+
+    * Examples:
+
+          Langbar with another separator: \{langbar: {separator: ' --- '}}
+
+
+*   ### tag.langbar.show\_own\_lang
+
+    Specifies whether the link to the language of the current page should be displayed.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          Langbar with current page's lang not shown: \{langbar: {show_own_lang: false}}
+
+
+*   ### tag.langbar.show\_single\_lang
+
+    Specifies whether the list should be displayed even if there are no translations of the page
+    (i.e. when there is only one page).
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          Langbar with single language not shown: \{langbar: {show_single_lang: false}}
+
+
+*   ### tag.menu.used\_nodes
+
+    Specifies the type of nodes that should be used for menu generation. If `all` is specified then
+    all available menu nodes are used, if `files` is specified then only menu nodes that represent
+    files or directories are used and if `fragments` is specified then only the fragment nodes of
+    the displayed file are used.
+
+    * Syntax: `TYPE` where `TYPE` is one of `all`, `files` or `fragments`
+
+    * Examples:
+
+          Show the fragment node menu: \{menu: {used_nodes: fragments}}
+
+
+*   ### tag.menu.start\_level
+
+    Specifies the start level for the menu. All nodes with a lower level than this number are not
+    shown in the menu.
+
+    * Syntax: `LEVEL` where `LEVEL` is a number that is greater or equal to one.
+
+    * Examples:
+
+          Menu starting at level 2: \{menu: {start_level: 2}}
+
+
+*   ### tag.menu.min\_levels
+
+    Specifies the minimum number of levels that should always be shown. For example, if this is set
+    to `2` then two menu levels are always shown.
+
+    * Syntax: `LEVEL` where `LEVEL` is a number that is greater or equal to one.
+
+    * Examples:
+
+          Menu that always shows at least 2 levels : \{menu: {min_levels: 2}}
+
+
+*   ### tag.menu.max\_levels
+
+    Specifies the maximum number of levels that should be shown even if there would be more. For
+    example, if this is set to `2` then there are only shown at most two menu levels.
+
+    * Syntax: `LEVEL` where `LEVEL` is a number that is greater or equal to one.
+
+    * Examples:
+
+          Menu that always shows at most 2 levels : \{menu: {max_levels: 2}}
+
+
+*   ### tag.menu.show\_current\_subtree\_only
+
+    Specifies whether only the current subtree (ie. the subtree in which the node is that is
+    displayed) should be shown in the menu or all subtrees. This option takes effect when there are
+    at least two menu levels visible.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    * Examples:
+
+          Showing all subtrees: \{menu: {show_current_subtree_only: false}}
+
+
+*   ### tag.relocatable.path
+
+    The default mandatory configuration option for Tag::Relocatable that specifies the path that
+    should be made relocatable. This option is the default mandatory option for
+    Webgen::Tag::Relocatable.
+
+    * Syntax: `PATH` where `PATH` is a (localized) canonical name.
+
+    * Examples:
+
+          <a href="\{relocatable: ../features.html}">Some Path</a>
+
+
+---
+
+## Miscelleanous Configuration Options
+
+*   ### resources
+
+    A map from resource names to resource identifiers. Should only be used by extensions and not be
+    set in the configuration file.
+
+    * Syntax: `NAME` TODO
+
+# All things regarding logging
+config.logger.mask(nil, :doc => 'Only show logging events which match the regexp mask')
+
+
+
+
+