webgen 0.5.7 → 0.5.8

data/doc/reference_website_styles.page

@@ -0,0 +1,28 @@
+---
+title: Website Styles Reference
+---
+
+Following is a list of all website styles that are included in the webgen distribution. Each style
+can be used when creating a website by using the command
+
+    webgen create -b default -b STYLE_NAME SITE_DIR
+
+or applied later using the command
+
+    webgen apply STYLE_NAME
+
+When you click on the link provided for each website style, you will get a full browser preview of
+the respective website style. You can then return to this list by using the *back button* of your
+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')]
+end.sort.each do |name, node|
+%>
+<h2 id="<%= node.cn %>"><%= 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>
+</div>
+<% end %>

data/doc/source/filesystem.page

@@ -0,0 +1,39 @@
+---
+title: Webgen::Source::FileSystem
+---
+## Description
+
+This is the default source extension used when creating a new webgen website. It uses files that
+match a certain glob (default value for the glob is to match all files) under a specific directory.
+
+> The default configuration for a new website uses all files under the `src` directory.
+{.information}
+
+The first parameter for the file system source is the directory under which the to-be-used files are
+and the second, optional, parameter specifies a glob (see [Dir.glob]).
+
+[Dir.glob]: http://ruby-doc.org/core/classes/Dir.html#M002375
+
+## Examples
+
+The used sources can be specified via the [`sources` configuration option]({relocatable:
+../reference_configuration.html#sources}), so each of the examples below can be specified in the
+`config.yaml` file.
+
+1.  The default configuration: all files under the `src` folder of the website directory
+
+        sources: [[/, Webgen::Source::FileSystem, src]]
+
+2.  The default configuration and additionally all files under a `misc` directory:
+
+        sources:
+          - [/, Webgen::Source::FileSystem, src]
+          - [/, Webgen::Source::FileSystem, misc]
+
+3.  The default configuration and mounting all image files from an external directory under the
+    `/images/` directory:
+
+        sources:
+          - [/, Webgen::Source::FileSystem, src]
+          - [/images/, Webgen::Source::FileSystem, /media/storage/pictures, **/*.jpg]
+

data/doc/source/tararchive.page

@@ -0,0 +1,40 @@
+---
+title: Webgen::Source::TarArchive
+---
+## Description
+
+The tar archive source can be used to include the files from a (possibly gzipped) tar archive. The
+used archive can be stored locally on the file system but it is also possible to use archives
+accessible via the http(s) and ftp protcols.
+
+> This extension is only available if you have installed the [archive-tar-minitar][1] library. The
+> preferred way to do this is via Rubygems:
+>
+>     gem install archive-tar-minitar
+{.warning}
+
+The first parameter for the tar archive source is the URL of the archive and the second, optional,
+parameter specifies a glob (see [File.fnmatch]) for selecting the to-be-used files/directories in the
+tar archive.
+
+[File.fnmatch]: http://ruby-doc.org/core/classes/File.html#M002603
+[1]: http://raa.ruby-lang.org/project/minitar/
+
+## Examples
+
+The used sources can be specified via the [`sources` configuration option]({relocatable:
+../reference_configuration.html#sources}), so each of the examples below can be specified in the
+`config.yaml` file.
+
+1.  Using all files/directories from a local tar archive in addition the default configuration:
+
+        sources:
+          - [/, Webgen::Source::FileSystem, src]
+          - [/, Webgen::Source::TarArchive, archive.tar]
+
+2.  Using images stored in a remote gzipped tar archive in addition to the default configuration:
+
+        sources:
+          - [/, Webgen::Source::FileSystem, src]
+          - [/, Webgen::Source::TarArchive, http://www.example.com/archive/data.tgz, **/*.jpg]
+

data/doc/tag/tikz.page

@@ -84,7 +84,8 @@ edge node {0,1,R} (A)
   <td>
   {tikz:: {path: chain.png, libraries: [arrows,automata,shadows,positioning],
     opts: "->,>=stealth,shorten >=1pt,auto,node distance=2.8cm,on grid,semithick,
-    every state/.style={fill=red,draw=none,circular drop shadow,text=white}"}}
+    every state/.style={fill=red,draw=none,circular drop shadow,text=white}",
+    resolution: 300 72}}
 \node[initial,state] (A) {$q_a$};
 \node[state] (B) [above right=of A] {$q_b$};
 \node[state] (D) [below right=of A] {$q_d$};

data/doc/webgen_page_format.page

@@ -10,7 +10,7 @@ easy to use.
 ## Structure
 
 A file using the Webgen Page Format consists of one or more blocks which are the smallest units
-recongnized. Blocks are separated from each other through a line containing three dashes. This is
+recognized. Blocks are separated from each other through a line containing three dashes. This is
 illustrated in the following examples which are all valid files in WebPage Format:
 
 Example 1:
@@ -66,17 +66,18 @@ it, it feels like just writing a plain text document.
 
 A content block is used to provide content in a specific format. Each file in Webgen Page 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 additional options can also
-be set.
-
-The name uniquely identifies a content block and is used to access it. The only option used by
-webgen is the `pipeline` option which specifies the processing pipeline for the block. The
-processing pipeline is used for rendering the block by using the specified content processors in the
-specified order. There are many different content processors available - have a look at the
-[extensions page]({relocatable: extensions.html}) for an overview.
-
-There are also defaults for the name and the options of a block but they can be overwritten. You can
-use one of two ways to do this:
+blocks as necessary. This functionality can be used, for example, to provide the main content of an
+HTML page in one block and sidebar content in another one.
+
+Each content block needs to have a unique name and additional options can also be set. The name
+uniquely identifies a content block and is used to access it. The only option used by webgen is the
+`pipeline` option which specifies the processing pipeline for the block. The processing pipeline is
+used for rendering the block by using the specified content processors in the specified order. There
+are many different content processors available - have a look at the [extensions page]({relocatable:
+extensions.html}) for an overview.
+
+webgen extensions that use files in Webgen Page Format may specify defaults for the name and the
+options of a block but these defaults can be overwritten. You can use one of two ways to do this:
 
 * you either specify the name and additional options of the block on the starting line with the
   three dashes

data/doc/website_styles.metainfo

@@ -0,0 +1,8 @@
+website_styles/*/default.template:
+  template: ~
+
+website_styles/*/:
+  index_path: style.html
+
+website_styles/:
+  index_path: ~

data/lib/webgen/blackboard.rb

@@ -4,12 +4,12 @@ module Webgen
 
   # A blackboard object provides two features for inter-object communication:
   #
-  # * services: An object can add a service to the blackboard which can be called by any other
+  # * *services*: An object can add a service to the blackboard which can be called by any other
   #   object by just specifing the service name. Therefore it is easy to change the underlying
   #   implementation of the service and there are no hard dependencies on specific class or method
   #   names.
   #
-  # * listeners: Objects may register themselves for specific messsage names and get notified when
+  # * *listeners*: Objects may register themselves for specific messsage names and get notified when
   #   such a message gets dispatched.
   #
   # For a list of all available services and messages have a look at the main Webgen documentation

data/lib/webgen/cache.rb

@@ -5,15 +5,15 @@ require 'facets/kernel/constant'
 
 module Webgen
 
-  # A cache object provides access to various caches to speed up rendering of a website.
+  # A cache object provides access to various caches to speed up rendering of a website:
   #
-  # permanent:: The permanent cache should be used for data that should be available between webgen
+  # [permanent] The permanent cache should be used for data that should be available between webgen
   #             runs.
   #
-  # volatile:: The volatile cache is used for data that can easily be regenerated but might be
+  # [volatile] The volatile cache is used for data that can easily be regenerated but might be
   #            expensive to do so. This cache is not stored between webgen runs.
   #
-  # standard:: The standard cache saves data between webgen runs and returns the cached data (not
+  # [standard] The standard cache saves data between webgen runs and returns the cached data (not
   #            the newly set data) if it is available. This is useful, for example, to store file
   #            modifcation times and check if a file has been changed between runs.
   #

data/lib/webgen/cli.rb

@@ -8,16 +8,17 @@ module Webgen
 
   # Namespace for all classes that act as CLI commands.
   #
-  # = Implementing a CLI command
+  # == Implementing a CLI command
   #
   # Each CLI command class needs to be put into this module and has to end with +Command+, otherwise
   # it is not used. A CLI command is an extension that can be invoked from the webgen command and
   # thus needs to be derived from CmdParse::Command. For detailed information on this class and the
   # whole cmdparse package have a look at http://cmdparse.rubyforge.org!
   #
-  # = Sample CLI command
+  # == Sample CLI command
   #
-  # Here is a sample CLI command extension:
+  # Here is a sample CLI command extension which could be put, for example, into the
+  # <tt>ext/init.rb</tt> of a webgen website:
   #
   #   require 'webgen/cli'
   #
@@ -26,13 +27,13 @@ module Webgen
   #     def initialize
   #       super('sample', false)
   #       self.short_desc = "This sample command just outputs its parameters"
-  #       self.description = Utils.format("Uses the global verbosity level and outputs additional " +
+  #       self.description = Webgen::CLI::Utils.format("Uses the global verbosity level and outputs additional " +
   #         "information when the level is set to verbose!")
   #       @username = nil
   #       self.options = CmdParse::OptionParserWrapper.new do |opts|
   #         opts.separator "Options:"
   #         opts.on('-u', '--user USER', String,
-  #           'Specify an additional user name to output') {|@username|}
+  #           'Specify an additional user name to output') {|username| @username = username}
   #       end
   #     end
   #
@@ -51,8 +52,8 @@ module Webgen
   #
   #   end
   #
-  # Note the use of Utils.format in the initialize method so that the long text gets wrapped
-  # correctly! The Utils class provides some other useful methods, too!
+  # Note the use of Webgen::CLI::Utils.format in the initialize method so that the long text gets
+  # wrapped correctly! The Utils class provides some other useful methods, too!
   #
   # For information about which attributes are available on the webgen command parser instance have
   # a look at Webgen::CLI::CommandParser!
@@ -61,6 +62,7 @@ module Webgen
     autoload :RunCommand, 'webgen/cli/run_command'
     autoload :CreateCommand, 'webgen/cli/create_command'
     autoload :WebguiCommand, 'webgen/cli/webgui_command'
+    autoload :ApplyCommand, 'webgen/cli/apply_command'
 
     autoload :Utils, 'webgen/cli/utils'
 
@@ -84,7 +86,7 @@ module Webgen
       # set or empty, the current working directory.
       def initialize # :nodoc:
         super(true)
-        @directory = (ENV['WEBGEN_WEBSITE'].to_s.empty? ? Dir.pwd : ENV['WEBGEN_WEBSITE'])
+        @directory = nil
         @verbosity = :normal
         @log_level = ::Logger::WARN
         @log_filter = nil
@@ -101,19 +103,30 @@ module Webgen
         end
         self.add_command(CmdParse::HelpCommand.new)
         self.add_command(CmdParse::VersionCommand.new)
-        Webgen::CLI.constants.select {|c| c =~ /.+Command$/ }.each do |c|
-          self.add_command(Webgen::CLI.const_get(c).new, (c.to_s == 'RunCommand' ? true : false))
-        end
       end
 
       # Utility method for sub-commands to create the correct Webgen::Website object.
       def create_website
-        website = Webgen::Website.new(@directory) do |config|
-          config['logger.mask'] = @log_filter
+        if !defined?(@website)
+          @website = Webgen::Website.new(@directory) do |config|
+            config['logger.mask'] = @log_filter
+          end
+          @website.logger.level = @log_level
+          @website.logger.verbosity = @verbosity
+        end
+        @website
+      end
+
+      # :nodoc:
+      def parse(argv = ARGV)
+        super do |level, cmd_name|
+          if level == 0
+            create_website.init
+            Webgen::CLI.constants.select {|c| c =~ /.+Command$/ }.each do |c|
+              self.add_command(Webgen::CLI.const_get(c).new, (c.to_s == 'RunCommand' ? true : false))
+            end
+          end
         end
-        website.logger.level = @log_level
-        website.logger.verbosity = @verbosity
-        website
       end
 
     end

data/lib/webgen/cli/apply_command.rb

@@ -0,0 +1,66 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/cli'
+require 'webgen/websitemanager'
+
+module Webgen::CLI
+
+  # The CLI command for applying a bundle to a webgen website.
+  class ApplyCommand < CmdParse::Command
+
+    def initialize #:nodoc:
+      super('apply', false)
+      @force = false
+
+      self.short_desc = 'Apply a website bundle to an existing webgen website'
+      self.options = CmdParse::OptionParserWrapper.new do |opts|
+        opts.separator "Options:"
+        opts.on('-f', '--[no-]force', 'Specifies whether files should be overwritten (default: no)') do |val|
+          @force = val
+        end
+        opts.separator ""
+        opts.separator "Arguments:"
+        opts.separator opts.summary_indent + "BUNDLE_NAME: The name of a bundle shipped with webgen. The name is "
+        opts.separator opts.summary_indent + "    matched against all possible bundle names and if there is only "
+        opts.separator opts.summary_indent + "    match the bundle is applied."
+        opts.separator opts.summary_indent + "BUNDLE_URL:  The URL of a bundle (needs to be a tar archive"
+      end
+    end
+
+    def usage # :nodoc:
+      "Usage: #{commandparser.program_name} [global options] apply [options] (BUNDLE_NAME|BUNDLE_URL)"
+    end
+
+    def show_help # :nodoc:
+      super
+      wm = Webgen::WebsiteManager.new(commandparser.directory)
+
+      puts
+      puts "Available bundles:"
+      puts Utils.headline('Bundles')
+      wm.bundles.sort.each {|name, entry| Utils.hash_output(name, entry.instance_eval { @table }) }
+    end
+
+    # 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)
+        raise "You need to specify a valid webgen website directory!"
+      elsif args.length == 0
+        raise OptionParser::MissingArgument.new('STYLE')
+      else
+        name = Utils.match_bundle_name(wm, args[0])
+        puts "The following files in the website directory will be created or overwritten:"
+        puts wm.bundles[name].paths.sort.join("\n")
+        continue = @force
+        if !continue
+          print "Procede? (yes/no): "
+          continue = ($stdin.readline =~ /y(es)?/)
+        end
+        wm.apply_bundle(name) if continue
+      end
+    end
+
+  end
+
+end

data/lib/webgen/cli/create_command.rb

@@ -11,17 +11,17 @@ module Webgen::CLI
     def initialize #:nodoc:
       super('create', false)
       self.description = Utils.format("If the verbosity level is set to verbose, the created files are listed.")
-      @template = 'default'
-      @style = 'andreas07'
+      @bundles = []
 
-      self.short_desc = 'Create a basic webgen website with selectable template/style'
+      self.short_desc = 'Create a basic webgen website from website bundles'
       self.options = CmdParse::OptionParserWrapper.new do |opts|
         opts.separator "Options:"
-        opts.on('-t', '--template TEMPLATE', String, 'A website template or "none" (default: default)') do |val|
-          @template = (val == 'none' ? nil : val)
-        end
-        opts.on('-s', '--style STYLE', String, 'A website style or "none" (default: andreas07)') do |val|
-          @style = (val == 'none' ? nil : val)
+        opts.on('-b', '--bundle BUNDLE', String, "A website bundle name/URL or 'none'. Can be used more than once (default: [default, style-andreas07])") do |val|
+          if val.downcase == 'none'
+            @bundles = nil
+          elsif !@bundles.nil?
+            @bundles << val
+          end
         end
         opts.separator ""
         opts.separator "Arguments:"
@@ -38,11 +38,9 @@ module Webgen::CLI
       wm = Webgen::WebsiteManager.new(commandparser.directory)
 
       puts
-      puts "Available templates and styles:"
-      puts Utils.headline('Templates')
-      wm.templates.sort.each {|name, entry| Utils.hash_output(name, entry.instance_eval { @table }) }
-      puts Utils.headline('Styles')
-      wm.styles.select {|k,v| k =~ /^website-|[^-]+/ }.sort.each {|name, entry| Utils.hash_output(name, entry.instance_eval { @table }) }
+      puts "Available bundles:"
+      puts Utils.headline('Bundles')
+      wm.bundles.sort.each {|name, entry| Utils.hash_output(name, entry.instance_eval { @table }) }
     end
 
     # Create a webgen website in the directory <tt>args[0]</tt>.
@@ -52,11 +50,19 @@ module Webgen::CLI
       else
         wm = Webgen::WebsiteManager.new(args[0])
         paths = wm.create_website
-        paths += wm.apply_template(@template) if @template
-        paths += wm.apply_style(@style) if @style
+        begin
+          if @bundles
+            @bundles = ['default', 'style-andreas07'] if @bundles.empty?
+            @bundles.each {|name| paths += wm.apply_bundle(Utils.match_bundle_name(wm, name)) }
+          end
+        rescue
+          require 'fileutils'
+          FileUtils.rm_rf(args[0])
+          raise
+        end
         if commandparser.verbosity == :verbose
           puts "The following files were created in the directory #{args[0]}:"
-          puts paths.sort.collect {|f| "- " + f }.join("\n")
+          puts paths.sort.join("\n")
         end
       end
     end

data/lib/webgen/cli/utils.rb

@@ -83,6 +83,29 @@ module Webgen::CLI
       puts
     end
 
+    # Tries to match +name+ to a unique bundle name of the WebsiteManager +wm+. If this can not be
+    # done, it is checked whether +name+ is actually a valid bundle URL and if so, the URL source is
+    # added to the bundles of +wm+.
+    #
+    # Returns the correct bundle name or raises an error.
+    def self.match_bundle_name(wm, name)
+      matches = wm.bundles.keys.select {|k| k =~ /#{Regexp.escape(name)}/}
+      if matches.size > 1
+        raise ArgumentError.new("#{name} matches more than one bundle: #{matches.join(", ")}")
+      elsif matches.size == 0
+        begin
+          source = Webgen::Source::TarArchive.new(name)
+          wm.add_source(source, 'custom-URL-source')
+          name = 'custom-URL-source'
+        rescue
+          raise ArgumentError.new("#{name} is neither a valid bundle name nor a valid URL")
+        end
+      else
+        name = matches.first
+      end
+      name
+    end
+
   end
 
 end