webgen 0.5.8 → 0.5.9

data/doc/reference_configuration.page

@@ -163,12 +163,33 @@ configuration options) and/or how to use it in a webgen tag (for tag configurati
 
     * Example for setting the option in the configuration file:
 
-          sources: [[/, Webgen::Source::FileSystem, src], [/, Webgen::Source::FileSystem, /mnt/pictures, **/*.jpg]
+          sources: [[/, Webgen::Source::FileSystem, src], [/, Webgen::Source::FileSystem, /mnt/pictures, **/*.jpg]]
 
       Also have a look at the [file system source documentation]({relocatable:
       source/filesystem.html}) for more examples!
 
 
+*   ### passive\_sources
+
+    Specifies one or more sources which are not actively used during the node creation time, ie. no
+    nodes are created from these sources by default. Instead, they lie dormant until later and are
+    only used if resolving a path fails. Then it is checked if a passive source for the requested
+    path exists and if so, a node is created from it. If a node created from a passive source is not
+    used anymore, it is automatically deleted.
+
+    * 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.
+
+    <%= show_default['passive_sources'] %>
+
+    * Example for setting the option in the configuration file:
+
+          passive_sources:
+            [[/, Webgen::Source::Resource, webgen-passive-sources], [/, Webgen::Source::FileSystem, /mnt/pictures, **/*.jpg]]
+
+
 *   ### output
 
     Specifies the output class that should be used for writing out the generated paths.
@@ -184,6 +205,20 @@ configuration options) and/or how to use it in a webgen tag (for tag configurati
           output: [Webgen::Output::FileSystem, custom_out]
 
 
+*   ### output.do\_deletion
+
+    Specifies whether the output class should delete generated paths once the source paths are not
+    available anymore.
+
+    * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`.
+
+    <%= show_default['output.do_deletion'] %>
+
+    * Example for setting the option in the configuration file:
+
+          output.do_deletion: true
+
+
 *   ### sourcehandler.patterns
 
     Specifies the path patterns that are used by the individual source handlers. This configuration
@@ -295,7 +330,7 @@ configuration options) and/or how to use it in a webgen tag (for tag configurati
 
           default_meta_info:
             :all:
-              output_path_style: [:parent, :cnbase, :lang, :ext]
+              output_path_style: [:parent, :basename, :lang, :ext]
             Webgen::SourceHandler::Page:
               in_menu: true
 
@@ -319,12 +354,14 @@ configuration options) and/or how to use it in a webgen tag (for tag configurati
 *   ### 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
+    names are used, for example, in the processing 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`.
+    * Syntax: `\{SHORT: NAME, SHORT: [NAME, TYPE], ...}` where `SHORT` is the short name of the
+      content processor class `NAME`. The second form allows one to additionally specify the type
+      `TYPE` of the content processor which has to be `:binary` or `:text`. If the first form is
+      used, then the type defaults to `:text`.
 
     <%= show_default['contentprocessor.map'] %>
 
@@ -332,6 +369,7 @@ configuration options) and/or how to use it in a webgen tag (for tag configurati
 
           config = Webgen::WebsiteAccess.website.config
           config['contentprocessor.map']['newcp'] = 'Extension::MyNewContentProcessor'
+          config['contentprocessor.map']['newcp'] = ['Extension::MyNewContentProcessor', :binary]
 
 
 *   ### contentprocessor.erubis.use\_pi
@@ -407,6 +445,20 @@ configuration options) and/or how to use it in a webgen tag (for tag configurati
           config['contentprocessor.tags.map']['highlight'] = 'Extension::MyHighlightingTag'
 
 
+*   ### contentprocessor.tidy.options
+
+    This configuration option can be used to set the command line options for the `tidy` program
+    which is used by the [content processor `tidy`]({relocatable: contentprocessor/tidy.html}).
+
+    * Syntax: `STRING` where `STRING` is the string holding the command line options.
+
+    <%= show_default['contentprocessor.tidy.options'] %>
+
+    * Example for setting the option in the configuration file:
+
+          contentprocessor.tidy.options: "-utf8"
+
+
 ## Tag Specific Options
 
 These options are not normally set in the configuration file but given directly as options to the
@@ -614,6 +666,32 @@ shows how to set the option in the configuration file.
           tabulator == 4 spaces: \{coderay:: {lang: ruby, tab_width: 4}}puts 5 + 5{coderay}
 
 
+*   ### tag.coderay.css
+
+    Specifies how the highlighted code should be styled.
+
+    If set to `style`, the CSS style attributes are set directly on the various HTML elements.
+
+    If set to `class`, only classes are set on the HTML elements and a default external stylesheet
+    is used - the [content processor head]({relocatable: contentprocessor/head.html}) is needed for
+    this to work.
+
+    If set to `other`, only classes are set like with the `class` value but no default external
+    stylesheet is used. You have to provide the styles yourself.
+
+    * Syntax: `STYLE` where `STYLE` is either `style`, `css` or `other`.
+
+    <%= show_default['tag.coderay.css'] %>
+
+    * Example for setting the option in the configuration file:
+
+          tag.coderay.css: style
+
+      Example for setting the option directly in a tag:
+
+          with external stylesheet: \{coderay:: {lang: ruby, css: class}}puts 5 + 5{coderay}
+
+
 *   ### tag.date.format
 
     Specifies the format that should be used for formatting the current date. The format string

data/doc/reference_metainfo.page

@@ -8,7 +8,7 @@ extension, be it a source handler, a tag or any other extension. Each meta infor
 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.
+* Then the paths for which this item is useful are listed.
 * And at last follows a detailed description.
 
 
@@ -110,7 +110,7 @@ information for nodes created by them.
 
 {:miref}
 * String: `de`
-* Page files
+* Any
 
 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.
@@ -124,6 +124,16 @@ meta information needs to be set before a node gets created.
 Specifies additional attribute-value pairs (in form of a Hash) that should be added to a link to the
 path.
 
+### meta
+
+{:miref}
+* Hash: `\{author: Thomas Leitner, generator: My program}`
+* Page files
+
+Specifies names and values for `<meta>` HTML tags. These key-value pairs are then properly escaped
+and inserted into the output file by [`ContentProcessor::Head`]({relocatable:
+contentprocessor/head.html}).
+
 ### modified\_at
 
 {:miref}
@@ -160,11 +170,11 @@ Controls whether the index path should appear in a breadcrumb trail despite the
 ### output\_path\_style
 
 {:miref}
-* Array: `[:parent, :cnbase, [., :lang], .html]`
+* Array: `[:parent, :basename, [., :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
+`:basename` 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!
@@ -220,3 +230,13 @@ Sets the template for the page/template file overriding the default value. If se
 * Any
 
 Sets the title for the path.
+
+### used\_nodes
+
+{:miref}
+* Array: `[*.en.html, test.de.html]`
+* Any
+
+The value of this meta information needs to be an array of alcn patterns. All nodes that match at
+least one of the patterns are considered to be dependencies of the node. Therefore if any of these
+nodes change, the node will be regenerated, too.

data/doc/reference_website_styles.page

@@ -17,10 +17,10 @@ browser:
 
 <%
 context.content_node.tree.node_access[:alcn].select do |name, node|
-  node.is_directory? && node.parent == context.content_node.tree[File.join(context.content_node.parent.absolute_lcn, '/website_styles')]
+  node.is_directory? && node.parent == context.content_node.tree[File.join(context.content_node.parent.alcn, '/website_styles/')]
 end.sort.each do |name, node|
 %>
-<h2 id="<%= node.cn %>"><%= node.cn %></h2>
+<h2 id="<%= node.cn.chomp('/') %>"><%= node.cn %></h2>
 <div class="website-styles">
 <%= context.dest_node.link_to(node, :link_text => "Full window version") %>
 <object type="text/html" data="<%= context.dest_node.route_to(node) %>">Nothing</object>

data/doc/sourcehandler/feed.page

@@ -7,12 +7,6 @@ This source handler automatically generates an atom or RSS feed for a set of fil
 [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)
@@ -31,11 +25,13 @@ The following meta information keys are supported:
 
 *   `atom` (OPTIONAL)
 
-    An atom feed is generated if this key is set to `true`. Defaults to `true`.
+    An atom feed is generated if this key is set to `true`. Defaults to `true`. The generated file
+    name derives from the feed file name but the extension is changed to `atom`.
 
 *   `rss` (OPTIONAL)
 
-    A RSS feed is generated if this key is set to `true`. Defaults to `true`.
+    A RSS feed is generated if this key is set to `true`. Defaults to `true`. The generated file
+    name derives from the feed file name but the extension is changed to `rss`.
 
 *   `rss_version` (OPTIONAL)
 
@@ -98,8 +94,10 @@ The following meta information keys of page files are used if they are specified
 
     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
+The default implementation supports the generation of atom and RSS feeds by using templates shipped
+with webgen (the extension `feed` is changed to `atom` for atom feeds and to `rss` for rss feeds).
+The default templates are located under the ALCNs `/templates/atom_feed.template` and
+`/templates/rss_feed.template` and are automatically created and used if no such paths exist in the
+webgen website. You can also override the default generation mechanism on a file per file basis 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

@@ -13,16 +13,21 @@ This source handler provides the ability to set meta information for any path. I
 * `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`.
+  into account, ie. `/index.html` won't match but `/index.en.html` will.
 
 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:
+to-be-assigned meta information as values. The patterns can be normal file system paths or node
+(a)lcns but you can also use some special characters like `*` (match any file), `**` (match
+recursively or expansively) and `?` (match a single character). You can find the full information in
+the documentation for [File.fnmatch].
+
+All this is best showed in an example:
 
     --- name:paths
     /**/index.page:
-      output_path_style: [:parent, :cnbase, :ext, [., :lang]]
+      output_path_style: [:parent, :basename, :ext, [., :lang]]
 
     mypic.jpg:
       in_menu: true
@@ -39,3 +44,5 @@ second form is taken relative to the directory in which the meta information fil
 
 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).
+
+[File.fnmatch]: http://ruby-doc.org/core/classes/File.html#M002603

data/doc/sourcehandler/page.page

@@ -3,10 +3,10 @@ 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.
+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. The extension
+`page` is changed to `html` for the output file and canonical names.
 
 *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

data/doc/sourcehandler/sitemap.page

@@ -5,13 +5,8 @@ title: Webgen::SourceHandler::Sitemap
 
 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
-{.warning}
+../webgen_page_format.html}). The output and canonical names have the extension `xml` instead of
+`sitemap`.
 
 The following meta information keys are supported:
 
@@ -44,3 +39,9 @@ The following meta information keys of files are used if they are specified:
 *   `priority`
 
     The priority of the file in respect to the other files.
+
+The generation of the sitemap is done via a template and the template used needs to be located under
+the ALCN `/templates/sitemap.template`. This default template is automatically created and used if
+no such path exists in the webgen website. You can also override the default generation mechanism on
+a file per file basis by adding a `template` block in the sitemap file which is then used to generate
+the sitemap.

data/doc/tag/coderay.page

@@ -8,6 +8,7 @@ used_options:
   - tag.coderay.line_number_start
   - tag.coderay.bold_every
   - tag.coderay.tab_width
+  - tag.coderay.css
 ---
 ## Description
 
@@ -15,6 +16,9 @@ This tag applies syntax highlighting to its body by using the [coderay][1] libra
 to highlight many different languages (see `tag.coderay.lang` documentation). The body of the tag
 specifies what should be highlighted.
 
+By using the configuration option `tag.coderay.css` you can specify whether you want to have inline
+styles, the default external stylesheet file or your own stylesheet file.
+
 > 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}
@@ -43,7 +47,7 @@ specifies what should be highlighted.
   <% 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>
+  <td>\{coderay:: {lang: ruby, wrap: span, css: class}}puts 5+5{coderay}</td>
+  <td><code>{coderay:: {lang: ruby, wrap: span, css: class}}puts 5+5{coderay}</code></td>
 </tr>
 </table>

data/doc/tag/includefile.page

@@ -8,7 +8,7 @@ used_options:
 ## Description
 
 The include file tag is used to include the content of a file. The filename needs to be specified
-relative to the website directory or an absolute filename.
+relative to the website directory or as an absolute filename.
 
 > By surrounding the include file tag with a syntax highlighting tag it is possible to highlight the
 > contents of a file.

data/doc/tag/menu.page

@@ -27,6 +27,9 @@ generating an in-page content menu of all the header sections.
 
 > When using the option value `files` for `tag.menu.used_nodes`, all nodes which are only in the
 > menu because they have fragment nodes beneath them are not included in the menu.
+>
+> However, when using the value `all` for `tag.menu.used_nodes`, some nodes which have `in_menu` set
+> to `false` may appear in the menu if they have fragments beneath them that are in the menu!
 {.important}
 
 The rendered menu consists of `ul` and `li` tags and the links (or `span` elements) to the menu

data/lib/webgen/cli/apply_command.rb

@@ -44,7 +44,7 @@ module Webgen::CLI
     # Apply the style specified in <tt>args[0]</tt> to the webgen website.
     def execute(args)
       wm = Webgen::WebsiteManager.new(commandparser.directory)
-      if !File.directory?(commandparser.directory)
+      if !File.directory?(wm.website.directory)
         raise "You need to specify a valid webgen website directory!"
       elsif args.length == 0
         raise OptionParser::MissingArgument.new('STYLE')

data/lib/webgen/cli/utils.rb

@@ -11,8 +11,8 @@ module Webgen::CLI
   # Provides methods for other CLI classes for formatting text in a consistent manner.
   class Utils
 
-    USE_ANSI_COLORS = !Config::CONFIG['arch'].include?('mswin32')
-    DEFAULT_WIDTH = if Config::CONFIG['arch'].include?('mswin32')
+    USE_ANSI_COLORS = Config::CONFIG['host_os'] !~ /mswin|mingw/
+    DEFAULT_WIDTH = if Config::CONFIG['host_os'] =~ /mswin|mingw/
                       72
                     else
                       ((size = %x{stty size 2>/dev/null}).length > 0 ? size.split.last.to_i : 72) rescue 72

data/lib/webgen/common.rb

@@ -1,7 +1,5 @@
 # -*- encoding: utf-8 -*-
 
-require 'pathname'
-
 module Webgen
 
   # Namespace for classes and methods that provide common functionality.
@@ -9,13 +7,6 @@ module Webgen
 
     autoload :Sitemap, 'webgen/common/sitemap'
 
-    # Make the given +path+ absolute by prepending the absolute path +base+ if necessary. Also
-    # resolves all '..'  and '.' references in +path+.
-    def self.absolute_path(path, base)
-      raise(ArgumentError, 'base has to be an absolute path') unless base =~ /\//
-      Pathname.new(path =~ /^\// ? path : File.join(base, path)).cleanpath.to_s
-    end
-
   end
 
 end

data/lib/webgen/contentprocessor.rb

@@ -18,8 +18,13 @@ module Webgen
   #
   # After writing the content processor class, one needs to add it to the
   # <tt>contentprocessor.map</tt> hash so that it is used by webgen. The key for the entry needs to
-  # be a short name without special characters or spaces and the value is the class name, not as
-  # constant but as a string.
+  # be a short name without special characters or spaces and the value can be:
+  #
+  # * the class name, not as constant but as a string - then this content processor is assumed to
+  #   work with textual data -, or
+  #
+  # * an array with the class name like before and the type, which needs to be <tt>:binary</tt> or
+  #   <tt>:text</tt>.
   #
   # == Sample Content Processor
   #
@@ -52,6 +57,8 @@ module Webgen
   #   end
   #
   #   WebsiteAccess.website.config['contentprocessor.map']['replacer'] = 'SampleProcessor'
+  #   # Or one could equally write
+  #   # WebsiteAccess.website.config['contentprocessor.map']['replacer'] = ['SampleProcessor', :text]
   #
   module ContentProcessor
 
@@ -67,6 +74,8 @@ module Webgen
     autoload :Erubis, 'webgen/contentprocessor/erubis'
     autoload :RDiscount, 'webgen/contentprocessor/rdiscount'
     autoload :Fragments, 'webgen/contentprocessor/fragments'
+    autoload :Head, 'webgen/contentprocessor/head'
+    autoload :Tidy, 'webgen/contentprocessor/tidy'
 
     # Return the list of all available content processors.
     def self.list
@@ -75,10 +84,16 @@ module Webgen
 
     # Return the content processor object identified by +name+.
     def self.for_name(name)
-      klass = WebsiteAccess.website.config['contentprocessor.map'][name]
+      klass, cp_type = WebsiteAccess.website.config['contentprocessor.map'][name]
       klass.nil? ? nil : WebsiteAccess.website.cache.instance(klass)
     end
 
+    # Return whether the content processor identified by +name+ is processing binary data.
+    def self.is_binary?(name)
+      WebsiteAccess.website.config['contentprocessor.map'][name].kind_of?(Array) &&
+        WebsiteAccess.website.config['contentprocessor.map'][name].last == :binary
+    end
+
     # Helper class for accessing content processors in a Webgen::Context object.
     class AccessHash