webgen 0.4.0 → 0.4.1

data/doc/src/documentation/{gettingstarted.page → tutorial.page}

@@ -1,108 +1,8 @@
 ---
-title: Getting Started
+title: Tutorial
 inMenu: true
 ---
-h1(#basics). Basics
-
-
-h2(#directories). The Needed Directories
-
-
-webgen needs a special directory structure so that it can work correctly. Basically, you have a
-website directory under which the following directories have to be:
-
-* @src@: The source directory in which all the source files for the website are. The name of this
-  directory cannot be changed!
-* @output@: This directory is created, if it does not exist, when webgen is run. All the output
-  files are put into this directory. The name of this directory and its location can be customized
-  using the parameter {param: Core/Configuration:outDir}.
-* @plugin@: The extension directory. You can put self-written plugins into this directory so that
-  they can be used by webgen. All <notextile><tt>*.rb</tt></notextile> files in this directory and
-  its subdirectories are loaded as plugins. The name of this directory can't be customized, too!
-
-The directory in which these directories are in is called the *website directory*.
-
-
-h2(#cmdline). The @webgen@ Command
-
-
-The executable for webgen is called... webgen ;-) It uses a command style syntax (like Subversion's
-@svn@ or Rubygem's @gem@ commands) through the "cmdparse":http://cmdparse.rubyforge.org library. To
-get an overview of the possible commands run
-
-<pre>
-  $ webgen help
-</pre>
-
-This will output something like this:
-
-<pre>
-Usage: webgen [options] COMMAND [options] [COMMAND [options] ...] [args]
-
-Available commands:
-  check          Checks things like validity of the config file or the availability of optional libraries
-    config         Checks the validity of the configuration and outputs the used options (=default command)
-    libs           Checks the availability of optional libraries used by plugins
-  create         Creates the basic directories and files for webgen.
-  help           Provide help for individual commands
-  run            Runs webgen, ie. generates the HTML files (=default command)
-  show           Shows various information
-    config         Shows information like the parameters for all or the matched plugins
-    plugins        Shows the available plugins
-  use            Changes the used website or gallery styles
-    gallery_style  Changes the used gallery style
-    website_style  Changes the used website style
-  version        Show the version of the program
-
-Global options:
-    -d, --directory DIR              The website directory, if none specified, current directory is used.
-    -V, --verbosity LEVEL            The verbosity level (0-3)
-    -h, --help                       Show help
-    -v, --version                    Show the version of the program
-</pre>
-
-
-As you can see, webgen supports many commands, from checking the validity of the configuration and
-the available libraries to displaying the configuration values. However, the main command is the
-@run@ command which does the actual website generation. This command uses the current working
-directory as website directory if none was specified via the @-d@ option.
-
-For more information on how the commands work have a look at the
-"cmdparse":http://cmdparse.rubyforge.org documentation!
-
-
-h2(#config). Configuration
-
-
-webgen provides a default configuration out of the box. If you can live with that, you do not need
-to write any configuration files. Because most people cannot, you can use your own configuration
-file. The configuration file has to be written in YAML and is called @config.yaml@. webgen assumes
-it to be in the website directory.
-
-Each plugin can specify parameters which can be configured through the configuration file. You can
-display a list of all available parameters by running
-
-<pre>
-  $ webgen show config
-</pre>
-
-(This information is also provided on this website, have a look at the
-<a href="{relocatable: plugins}">plugins section</a>!)
-
-The list shows sorted by the plugin name the current values and the default values for each
-parameter. Each parameter can be overridden in the configuration file by specifing the plugin name
-as top level key and each parameter and value as a key/value pair. Therefore a configuration file
-looks like this (this is the one for the webgen homepage):
-
-<pre class="webgen-file">{includeFile: ../../config.yaml}</pre>
-
-There is a special key for file handler plugins: @defaultMetaInfo@. It's value should be a hash with
-the default meta information for nodes created by the plugin. The value is used to update the
-correct part of the {param: Core/FileHandler:defaultMetaInfo} parameter *if and only if* no value
-for the {param: Core/FileHandler:defaultMetaInfo} parameter has been set in the configuration file!
-
-
-h1(#website-creation). Website Creation Tutorial
+h1(#website-creation). Tutorial
 
 
 This short tutorial shows you how to create a website with webgen.
@@ -135,7 +35,7 @@ example:
   $ webgen use website_style default
 </pre>
 
-Existing files may be overwritten be this command (after asking). However, this command is not able
+Existing files may be overwritten by this command (after asking). However, this command is not able
 to delete previously copied website style files, so you have to remove them yourself!
 
 Have a look at the <a href="{relocatable: /examples}">examples</a> sections to see demonstrations
@@ -255,6 +155,9 @@ you can leave it there - it won't do any harm.
 
 Again, just run webgen and view the output!
 
+For more information on how to write plugins have a look at the
+<a href="{relocatable: extending_webgen.page}">extending webgen section</a>!
+
 
 h2(#website-conclusio). Conclusion
 

data/doc/src/news.page

@@ -5,6 +5,17 @@ inMenu: true
 h2. News
 
 
+h3(#news-2007-01-12). 12.01.2007 - webgen 0.4.1
+
+
+A minor release with bug fixes and some small enhancements:
+
+* webgen Windows bug resolved: webgen now really runs on Windows - thanks for the fast feedback!
+* Rake task for running webgen - thanks to Jeremy Hinegardner for providing it!
+* Meta information @template@ can now be set to @nil@ to specify that no template should be used!
+* Small documentation updates - thanks to John Gabriel for pointing out some flaws!
+
+
 h3(#news-2007-01-05). 05.01.2007 - webgen 0.4.0
 
 

data/lib/webgen/config.rb

@@ -1,7 +1,7 @@
 #
 #--
 #
-# $Id: config.rb 531 2006-11-17 17:56:14Z thomas $
+# $Id: config.rb 586 2007-01-10 16:46:05Z thomas $
 #
 # webgen: template based static website generator
 # Copyright (C) 2004 Thomas Leitner
@@ -24,7 +24,7 @@ require 'rbconfig'
 
 module Webgen
 
-  VERSION = [0, 4, 0]
+  VERSION = [0, 4, 1]
   AUTHOR = 'Thomas Leitner <t_leitner@gmx.at>'
   SUMMARY = "webgen is a templated based static Web site generator."
   DESCRIPTION = "webgen is a Web site generator implemented in Ruby. " \
@@ -40,9 +40,9 @@ module Webgen
   # Returns the data directory for webgen.
   def self.data_dir
     unless defined?( @@data_dir )
-      @@data_dir = File.join( Config::CONFIG["datadir"], "webgen" )
+      @@data_dir = File.expand_path( File.join( Config::CONFIG["datadir"], "webgen" ) )
 
-      @@data_dir =  File.join( File.dirname( __FILE__ ), '..', '..', 'data', 'webgen') if !File.exists?( @@data_dir )
+      @@data_dir =  File.expand_path( File.join( File.dirname( __FILE__ ), '..', '..', 'data', 'webgen') ) if !File.exists?( @@data_dir )
 
       raise "Could not find webgen data directory! This is a bug, report it please!" unless File.directory?( @@data_dir )
     end

data/lib/webgen/node.rb

@@ -1,7 +1,7 @@
 #
 #--
 #
-# $Id: node.rb 576 2007-01-03 19:41:12Z thomas $
+# $Id: node.rb 585 2007-01-10 15:48:08Z thomas $
 #
 # webgen: template based static website generator
 # Copyright (C) 2004 Thomas Leitner
@@ -118,7 +118,9 @@ class Node
   def absolute_path
     return @precalc[:absolute_path] if @precalc
 
-    if @path =~ ABSOLUTE_URL
+    if @parent.nil?
+      '/'
+    elsif @path =~ ABSOLUTE_URL
       @path
     else
       full_path.sub( /^#{Node.root( self ).path}/, '/' )

data/lib/webgen/plugins/filehandlers/template.rb

@@ -1,7 +1,7 @@
 #
 #--
 #
-# $Id: template.rb 542 2006-12-19 08:29:39Z thomas $
+# $Id: template.rb 588 2007-01-12 09:55:32Z thomas $
 #
 # webgen: template based static website generator
 # Copyright (C) 2004 Thomas Leitner
@@ -77,6 +77,8 @@ module FileHandlers
         node['template'] = template_node
       elsif node['template'].kind_of?( Node )
         template_node = node['template']
+      elsif node.meta_info.has_key?( 'template' ) && node['template'].nil?
+        template_node = nil
       else
         log(:info) { "Using default template for <#{node.node_info[:src]}>" }
         template_node = get_default_template( node.parent, param( 'defaultTemplate' ) )

data/lib/webgen/plugins/miscplugins/rendered_files.rb

@@ -0,0 +1,75 @@
+#
+#--
+# rendered_files.rb :
+#
+#   webgen miscellaneous plugin to record the paths of all the files and
+#   directories written during rendering.
+#
+# Copyright (C) 2007 Jeremy Hinegardner
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or (at
+# your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+# USA
+#
+#++
+#
+
+
+
+
+load_plugin 'webgen/plugins/filehandlers/filehandler'
+
+module MiscPlugins
+
+  # This plugin registers as a listener for message :after_node_written
+  # with the 'Core/FileHandler' plugin.
+  #
+  # When its callback is invoked, if the node in question is a file or
+  # directory it records the nodes fully expanded path in @files
+  #
+  # The list of files currently rendered can then be retrieved by
+  # getting a handle on this plugin and calling +files+.
+  #
+  #   Example:
+  #
+  #       @plugin_manager['Misc/RenderedFiles'].files
+  #
+  class RenderedFilesPlugin < Webgen::Plugin
+    infos( :name => 'Misc/RenderedFiles',
+           :author => 'Jeremy Hinegardner <jeremy@hinegardner.org>',
+           :summary => 'Keeps track of all the files and directories written during rendering.')
+
+    depends_on 'Core/FileHandler'
+
+    attr_reader :files
+
+    def initialize(plugin_manager)
+      super
+      @plugin_manager['Core/FileHandler'].add_msg_listener(:after_node_written, method(:record_file))
+      @files = []
+    end
+
+    #######
+    private
+    #######
+
+    # we use expand_path to remove possible environmental parameters
+    # or ../'s in the path
+    def record_file(node)
+      if node.is_file? or node.is_directory? then
+        @files << File.expand_path(node.full_path)
+      end
+    end
+  end
+end

data/lib/webgen/rake/webgentask.rb

@@ -0,0 +1,161 @@
+# -*- ruby -*-
+
+#
+#--
+# webgentask.rb:
+#
+#   Define a task library for running webgen
+#
+# Copyright (C) 2007 Jeremy Hinegardner
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or (at
+# your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+# USA
+#
+#++
+#
+
+require 'rake'
+require 'rake/tasklib'
+
+module Webgen
+
+  module Rake
+
+    ##
+    # A Rake task that generates a webgen website.
+    #
+    # It is assumed that you have already used the 'webgen' command
+    # to create the base directory for the site.  This task is here
+    # to make it easier to integrate the generation of the website
+    # within the broader scope of another project.
+    #
+    # === Basics
+    #
+    #   require 'webgen/rake/webgentask'
+    #
+    #   Webgen::Rake::WebgenTask.new do |t|
+    #       t.directory = File.join(Dir.pwd, "webgen")
+    #   end
+    #
+    # === Attributes
+    #
+    # The attributes available to the task in the new block are:A
+    #
+    # * name              - the name of the task.  This can also be set as
+    #                       a parameter to new (default :webgen)
+    # * directory         - the root directory of the webgen site
+    #                       (default File.join(Dir.pwd, "webgen")
+    # * clobber_outdir    - remove webgens output directory on clobber
+    #                       (default false)
+    #
+    # === Tasks Provided
+    #
+    # The tasks provided are :
+    #
+    # * webgen         - create the website
+    # * clobber_webgen - remove all the files created during creation
+    #
+    # If the +name+ attribute is changed then the tasks are changed
+    # to reflect that.  For Example:
+    #
+    #   Webgen::Rake::WebgenTask.new(:my_webgen) do |t|
+    #       t.clobber_outdir = true
+    #   end
+    #
+    # This will create tasks:
+    #
+    # * my_webgen
+    # * clobber_my_webgen
+    #
+    class WebgenTask < ::Rake::TaskLib
+
+      # Name of webgen task. (default is :webgen)
+      attr_accessor :name
+
+      # The directory of the webgen site.  This would be the
+      # directory of your config.yaml file.  Or the parent
+      # directory of the src/ directory for webgen
+      #
+      # The default for this is assumed to be
+      #   File.join(Dir.pwd,"webgen")
+      attr_accessor :directory
+
+      # During the clobber, should webgen's output directory be
+      # clobbered.  The default is false
+      attr_accessor :clobber_outdir
+
+      # Create a webgen task
+      def initialize(name = :webgen)
+        @name           = name
+        @directory      = File.join(Dir.pwd, "webgen")
+        @clobber_outdir = false
+
+        yield self if block_given?
+
+        @rendered_files = FileList.new
+
+        define
+      end
+
+      def define
+        desc "Run webgen"
+        task @name do |t|
+          Dir.chdir(@directory) do
+            begin
+              # some items from webgen may be sensitive to the
+              # current directory when it runs
+
+              require 'webgen/website'
+              @website = Webgen::WebSite.new @directory
+              @out_dir = File.expand_path(@website.param_for_plugin('Core/Configuration', 'outDir'))
+              @website.render
+              puts "Webgen rendered to : #{@out_dir}"
+
+              file_list = @website.manager['Misc/RenderedFiles'].files
+
+              # remove @out_dir from the list of rendered_files
+              file_list.delete @out_dir
+
+              @rendered_files << file_list
+            rescue => e
+              puts "Webgen task failed: #{e}"
+              raise e
+            end
+          end
+        end
+
+        clobber_task = paste("clobber_",@name)
+
+        # bit of conundrum here since we don't know what files
+        # to remove until they have been generated, so we have
+        # to generate all the files to remove them.
+        #
+        # I don't know of the right way to do this yet.
+        desc "Remove webgen products"
+        task clobber_task => [@name] do
+          rm_rf @rendered_files
+          if @clobber_outdir then
+            rm_r @out_dir rescue nil
+          end
+        end
+
+        task :clobber => [clobber_task]
+        self
+      end
+
+    end
+  end
+end
+