webgen 0.4.0 → 0.4.1

data/ChangeLog

@@ -1,4 +1,80 @@
 ------------------------------------------------------------------------
+r590 | thomas | 2007-01-12 11:03:52 +0100 (Fri, 12 Jan 2007) | 1 line
+Changed paths:
+   M /trunk/webgen/Rakefile
+
+* fixed Rake task
+------------------------------------------------------------------------
+r589 | thomas | 2007-01-12 11:02:54 +0100 (Fri, 12 Jan 2007) | 2 lines
+Changed paths:
+   M /trunk/webgen/TODO
+   M /trunk/webgen/doc/src/default.template
+   M /trunk/webgen/doc/src/documentation/references/meta_info_reference.page
+   M /trunk/webgen/doc/src/news.page
+
+* updated meta information reference for template
+* updated date for release
+------------------------------------------------------------------------
+r588 | thomas | 2007-01-12 10:55:32 +0100 (Fri, 12 Jan 2007) | 1 line
+Changed paths:
+   M /trunk/webgen/lib/webgen/plugins/filehandlers/template.rb
+   M /trunk/webgen/test/fixtures/sample_site/src/index.de.page
+   M /trunk/webgen/test/unittests/tc_filehandler_template.rb
+
+* updated File/TemplateHandler sothat when meta information template is set to nil no template is used
+------------------------------------------------------------------------
+r587 | thomas | 2007-01-11 08:01:10 +0100 (Thu, 11 Jan 2007) | 2 lines
+Changed paths:
+   M /trunk/webgen/TODO
+   M /trunk/webgen/doc/metainfo.yaml
+   M /trunk/webgen/doc/src/default.template
+   A /trunk/webgen/doc/src/documentation/basics.page
+   M /trunk/webgen/doc/src/documentation/extending_webgen.page
+   D /trunk/webgen/doc/src/documentation/gettingstarted.page
+   M /trunk/webgen/doc/src/documentation/index.page
+   M /trunk/webgen/doc/src/documentation/plugins/core/filehandler.page
+   M /trunk/webgen/doc/src/documentation/plugins/file/directoryhandler.page
+   M /trunk/webgen/doc/src/documentation/references/index.page
+   A /trunk/webgen/doc/src/documentation/tutorial.page (from /trunk/webgen/doc/src/documentation/gettingstarted.page:586)
+   M /trunk/webgen/doc/src/news.page
+
+* splitted getting started page into two pages
+* updated parts of the documentation thanks to John Gabriele how pointed out some flaws
+------------------------------------------------------------------------
+r586 | thomas | 2007-01-10 17:46:05 +0100 (Wed, 10 Jan 2007) | 5 lines
+Changed paths:
+   M /trunk/webgen/Rakefile
+   M /trunk/webgen/TODO
+   M /trunk/webgen/lib/webgen/config.rb
+   A /trunk/webgen/lib/webgen/plugins/miscplugins/rendered_files.rb
+   A /trunk/webgen/lib/webgen/rake
+   A /trunk/webgen/lib/webgen/rake/webgentask.rb
+   D /trunk/webgen/lib/webgen/raketasks.rb
+
+* added Misc/RenderFiles plugin by Jeremy Hinegardner
+* added rake task for webgen by Jeremy Hinegardner (with some small modifications)
+* removed my own rake task as the version of Jeremy is more complete
+* updated rake file to use new webgen task
+* fixed Webgen.data_dir to use expanded paths
+------------------------------------------------------------------------
+r585 | thomas | 2007-01-10 16:48:08 +0100 (Wed, 10 Jan 2007) | 1 line
+Changed paths:
+   M /trunk/webgen/lib/webgen/node.rb
+   M /trunk/webgen/test/unittests/tc_node.rb
+
+* bug fix: Windows full path starting with LETTER:/ matched absolute url regexp - this was bad for the root node
+------------------------------------------------------------------------
+r584 | thomas | 2007-01-09 07:30:36 +0100 (Tue, 09 Jan 2007) | 3 lines
+Changed paths:
+   M /trunk/webgen/Rakefile
+   M /trunk/webgen/TODO
+   M /trunk/webgen/lib/webgen/config.rb
+   A /trunk/webgen/lib/webgen/raketasks.rb
+
+* bumped version number
+* added a rake task for running webgen
+* fixed Rakefile to use new webgen rake task
+------------------------------------------------------------------------
 r582 | thomas | 2007-01-05 11:12:50 +0100 (Fri, 05 Jan 2007) | 1 line
 Changed paths:
    M /trunk/webgen/doc/src/default.template

data/Rakefile

@@ -30,10 +30,11 @@ require 'rake/packagetask'
 require 'rake/rdoctask'
 require 'rake/testtask'
 
-# General actions  ##############################################################
+# General things  ##############################################################
 
-$:.push 'lib'
+$:.push File.expand_path( File.join( File.dirname(__FILE__), 'lib' ) )
 require 'webgen/config'
+require 'webgen/rake/webgentask'
 
 PKG_NAME = "webgen"
 PKG_VERSION = Webgen::VERSION.join( '.' )
@@ -43,8 +44,8 @@ PKG_DESCRIPTION = Webgen::DESCRIPTION
 
 SRC_RB = FileList['lib/**/*.rb']
 
-# The default task is run if rake is given no explicit arguments.
 
+# The default task is run if rake is given no explicit arguments.
 desc "Default Task"
 task :default => :test
 
@@ -63,13 +64,31 @@ task :install => [:prepare] do
   ruby "setup.rb install"
 end
 
+
 CLEAN.exclude( 'doc/src/documentation/plugins/core' )
+CLEAN.exclude( 'doc/output/documentation/plugins/core' )
 task :clean do
   ruby "setup.rb clean"
 end
 
+
 desc "Creates the whole documentation"
-task :doc => [:rdoc, :webgen_doc]
+task :doc => [:rdoc, :webgen]
+
+Webgen::Rake::WebgenTask.new do |webgen|
+  webgen.directory = File.join( File.dirname( __FILE__ ), 'doc' )
+  webgen.clobber_outdir = true
+end
+task :webgen => [:create_examples]
+
+rd = Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'doc/output/rdoc'
+  rdoc.title    = PKG_NAME
+  rdoc.options << '--line-numbers' << '--inline-source' << '-m README'
+  rdoc.rdoc_files.include( 'README' )
+  rdoc.rdoc_files.include( 'lib/**/*.rb' )
+end
+
 
 CLOBBER << "doc/examples"
 CLOBBER << "doc/src/examples/website_templates"
@@ -216,20 +235,6 @@ Following is the list of all available gallery styles:
 
 end
 
-CLOBBER << "doc/output"
-desc "Generates the webgen documentation"
-task :webgen_doc => [:create_examples] do
-  puts "\nGenerating online documentation..."
-  ruby %{-Ilib bin/webgen -d doc -V 2 }
-end
-
-rd = Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'doc/output/rdoc'
-  rdoc.title    = PKG_NAME
-  rdoc.options << '--line-numbers' << '--inline-source' << '-m README'
-  rdoc.rdoc_files.include( 'README' )
-  rdoc.rdoc_files.include( 'lib/**/*.rb' )
-end
 
 task :test do
   ruby "-Ilib -Itest test/runtests.rb"

data/TODO

@@ -1,5 +1,7 @@
 ---- CURRENT ----
 
+* modify WebSite to allow better use (factor out loading of plugins into own method, do not call init in #render method, ...)
+* fix TreeWalker (call it!)
 * show error message when configuration file is invalid (Webgen::WebSite)
 * fix website styles menus to have a style for current menu item with <span> instead of <a>
 * add a common class to the menu element (either a or span, depending on Fil/DefaultFileHandler:linkToCurrentPage) for easier referencing in CSS styles (update menu CSS style afterwards for horiz-dd, vert-dd, ...)
@@ -369,3 +371,6 @@ W do not allow two or more page files in the same language, print warn
 * document that source directory is now always called src - no parameter anymore
 * document somewhere which objects are available when processing templates/pages files with ERB
 * document evaluation order of page files (first content converted from Textile/Markdown/... to HTML, then ERB, then tags)
+* create a rake task for running webgen (like the rdoc task)
+* documentation: split getting started into basics and tutorial pages
+* make it possible to set meta information template to nil

data/VERSION

@@ -1 +1 @@
-0.4.0
+0.4.1

data/doc/metainfo.yaml

@@ -21,7 +21,10 @@ images:
   indexFile: ~
 
 
-documentation/gettingstarted.page:
+documentation/basics.page:
+  orderInfo: 1
+
+documentation/tutorial.page:
   orderInfo: 3
 
 documentation/extending_webgen.page:

data/doc/src/default.template

@@ -40,13 +40,17 @@
           <% end %>
           <h1>Tips</h1>
           <ul class="list">
-            <li>The <a href="{relocatable: /documentation/gettingstarted.en.page}">Getting Started</a> page contains everything one needs to get going with webgen!</li>
+            <li>The <a href="{relocatable: /documentation/basics.en.page}">basics page</a>contains everything one needs to get going with webgen!</li>
             <li>Descriptions for plugins can be found in the <a href="{relocatable:documentation/plugins}">plugins  section</a></li>
           </ul>
         </div>
 
         <div id="rightside">
           <h1>Latest news</h1>
+          <p><strong>2007-01-12: </strong>
+            webgen 0.4.1 released! Bug fix for running webgen on Windows and other small updates!
+            <a href="{relocatable: news.en.page#news-2007-01-12}">More...</a>
+          </p>
           <p><strong>2007-01-05: </strong>
             webgen 0.4.0 released! Major update to the core and plugins and many new features added!
             <a href="{relocatable: news.en.page#news-2007-01-05}">More...</a>

data/doc/src/documentation/basics.page

@@ -0,0 +1,148 @@
+---
+title: Basics
+inMenu: true
+---
+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.
+
+You can invoke a command by specifying it after the executable name. If we also think of the
+executable @webgen@ as a command, then the options for a command are specified directly after the
+command name and before the next command or any arguments. For example, all the following command
+lines are valid:
+
+<pre>
+  $ webgen
+  $ webgen run
+  $ webgen -d doc run
+  $ webgen -V 0 create -t project
+  $ webgen show config
+  $ webgen help create
+  $ webgen help show config
+</pre>
+
+The commands on the first and second line do the same because of the @run@ command being the default
+command. The third command specifies a global option, as does the fourth. However, the fourth also
+specifies a command specific option @-t@. The fifth command shows how nested commands are used; in
+this case the @config@ command under the @show@ command is executed. The last two commands show how
+the included @help@ command works: the sixth command shows the help for the @create@ command and the
+last one shows it for the nested @show config@ command.
+
+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!
+
+
+h2(#filetypes). File Types
+
+
+webgen can handle different file types in the source directory through its plugin concept. The
+{plugin: File} plugins are used for this task.
+
+The most important files are the page and template files as they are used to define the content and
+the layout of your website. Have a look at the
+ <a href="{relocatable:references/webpage_format.page}">WebPage Format</a> documentation to see how
+these files look like and how they are structured. After that have a look at the documentation for
+the plugins {plugin: File/PageHandler} and {plugin: File/TemplateHandler} as they are responsible
+for handling the page and template files!
+
+You can naturally use any other type of file in the webgen source directory. However, be aware that
+some files may not be processed by webgen when no file handler plugin for them exist. For example,
+there is currently no file handler plugin for @.svg@ files, so those files would be ignored. If you
+just want to have files copied from the source to the output directory (like images or CSS files),
+the {plugin: File/CopyHandler} plugin is what you need!
+
+
+h2(#goingon). From here on...
+
+
+Now that you know the basics, you can go on to the
+ <a href="{relocatable: tutorial.page}">tutorial</a> to create your first website with webgen!

data/doc/src/documentation/extending_webgen.page

@@ -6,6 +6,9 @@ h2. Extending webgen
 
 h3. General
 
+p={font-size: 150%; color: red}. *This part of the homepage is out of date and will be updated soon!*
+
+
 There is a logging mechanism available for informational and debugging purposes. Four different log
 levels are available:
 
@@ -21,7 +24,7 @@ a string.
 h3. Normal plugins (new tags, file handlers, etc)
 
 As webgen is plugin-based, it can be extended very easily. A simple example is shown in the
-<a href="{relocatable: gettingstarted.page#website-plugin}">Getting Started</a> guide.
+<a href="{relocatable: tutorial.page#website-plugin}">tutorial</a>.
 
 If you want more sophisticated examples of plugins, have a look at webgen itself and the plugins
 that get shipped with it. They can be found in the directory @lib/webgen/plugins/@!

data/doc/src/documentation/index.page

@@ -1,10 +1,13 @@
 ---
 directoryName: Documentation
+title: Preface
 ---
-h2. Information
+h2. Preface
 
 
-p={font-size: 150%; color: red}. *!!! This documentation is for webgen {version: } !!!*
+p={font-size: 150%; color:red}. *This documentation is for webgen {version: }! However, most parts
+are valid for all webgen 0.4.x releases!*
+
 
 The source files for this website are in the @doc/src@ directory of the webgen distribution. Have a
 look at them to see a real world example on how to use webgen!
@@ -17,7 +20,7 @@ I often see that the name of the program is misspelled: WebGen, Webgen, WEBGEN,
 *webgen*, all lower case!
 
 
-h2. Philosophy
+h2. Philosophy of webgen
 
 
 There are some things about webgen which I think are important to mention. It's about how webgen

data/doc/src/documentation/plugins/core/filehandler.page

@@ -104,7 +104,7 @@ h3(#metainfo-param). The @defaultMetaInfo@ parameter
 This parameter can be used to override the default meta information set for a file handler plugin.
 The keys are the names of file handler plugins and the values are the meta information. You can
 either set the parameter directly or use the special functionality provided by the
-<a href="{relocatable: /documentation/gettingstarted.page#config}">configuration file</a> to
+<a href="{relocatable: /documentation/basics.page#config}">configuration file</a> to
 set it for a file handler plugin.
 
 

data/doc/src/documentation/plugins/file/directoryhandler.page

@@ -14,7 +14,7 @@ directory path is resolved (e.g. by the {plugin: Tag/Relocatable}) the index fil
 The name of the index file is specified with the @indexFile@ meta information on a directory node.
 This meta information is set by default and can be overridden globally by using the special
 @defaultMetaInfo@ param for the @DirectoryHandler@ in the
-<a href="{relocatable: /documentation/gettingstarted.page#config}">configuration file</a> or by
+<a href="{relocatable: /documentation/basics.page#config}">configuration file</a> or by
 setting it on individual directories using the
 <a href="{relocatable: ../core/filehandler.page#metainfo-file}">meta information backing file</a>.
 

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

@@ -4,4 +4,23 @@ directoryName: References
 ---
 h2. About
 
-Some references for your convenience!
+
+This part of the documentation contains some references for your convenience:
+
+* <b><a href="{relocatable: webpage_format.page}">WebPage Format Reference</a></b>
+
+  Describes the structure and format of the WebPage Format, the format used, for
+  example, for page and template files.
+
+* <b><a href="{relocatable: meta_info_reference.page}">Meta Information Reference</a></b>
+
+  Provides an overview over all special meta information keys that can be used in conjunction with
+  webgen.
+
+* <b><a href="{relocatable: parameter_reference.page}">Parameter Reference</a></b>
+
+  Lists the parameters for all plugins for easy search and retrieval.
+
+* <b><a href="{relocatable: /api.html}">API Reference</a></b>
+
+  Provides detailed API documentation through RDOC generated documents.

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

@@ -65,7 +65,8 @@ plugin, be it a file handler plugin, a tag plugin...
   <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>
+  <td>Sets the template for the page/template file overriding the default value. If set to @nil@, no
+      template is used for the page/template file!</td>
 </tr>
 <tr>
   <th>title</th>