webgen 0.3.2 → 0.3.3

data/doc/src/documentation/cli.page

@@ -0,0 +1,12 @@
+---
+title: Command Line Interface
+inMenu: true
+menuOrder: 20
+---
+h2. Command Line Interface
+
+The command line interface (CLI) has a command style syntax like Subversion's @svn@ or Rubygems'
+@gem@. Following are the available commands and their parameters. Have a look at the usage
+description to see how to use each command.
+
+<notextile>{clidesc: }</notextile>

data/doc/src/documentation/gettingstarted.page

@@ -0,0 +1,150 @@
+---
+title: Getting Started
+inMenu: true
+menuOrder: 10
+---
+h1. Getting Started with webgen
+
+h2. The Needed Directories
+
+Webgen utilizes the following directories. These directories are in the direcctory in which the
+webgen command is issued.
+
+* @src@: The source directory in which all the source files for the website are.
+
+* @output@: This directory is created, if it does not exist, when webgen is run. All the output
+            files are put into this directory
+
+* @log@: If the logging mechanism is configured to write the log messages to files, this is the
+         directory where the log files will be. It will be created if it does not exist.
+
+* @plugin@: The extension directory. You can put self-written plugins into this directory so that
+            they can be used by webgen. All <tt>*.rb</tt> files in this directory and its
+            subdirectories are loaded as plugins.
+
+h2. Create basic website structure
+
+And now, let's make a website!
+
+First, you need to create the basic directories. You can let webgen do this:
+
+<pre>
+~ > webgen create sample_site
+</pre>
+
+Webgen created the @sample_site@ directory which holds all directories necessary for running webgen.
+So you can run webgen to create your website. Just change into the @sample_site@ directory and run
+webgen
+
+<pre>
+~ > cd sample_site
+~/sample_site > webgen
+</pre>
+
+Easy! Webgen has parsed the @src@ directory and has created the HTML output. However, as we did not
+write any content yet, there is not much to see (only the default page). So let's do that now!
+
+h2. Add Content to the Website
+
+When using the @create@ command, webgen does not only create the needed directories but it also
+provides you with some default files:
+
+* @src/default.template@: The default template for the new website.
+* @src/default.css@: The default css file for the new website.
+* @src/index.page@: The index page for the root directory of the website.
+
+The basic scaffolding is already in place, we only have to change @index.page@ and add other page
+files. Just open the file @index.page@ in your favorite text editor and change its content. After
+that we create a new file, @hello.page@, with the following content:
+
+<pre>
+\---
+title: Sample hello page
+inMenu: true
+\---
+This is a sample page with the title "{title:}" and it is in the menu!!!
+</pre>
+
+After that, run webgen in the @sample_site@ directory and then open @output/index.html@ to view your
+website.
+
+Just add page files and other content to your website and let it grow!
+
+h2. Using Meta Information in Pages
+
+Meta information is specified at the beginning of a page file. Have a look at the
+<a href="{relocatable: plugins/filehandler/pagehandler.html}">documentation</a> to see how that is done
+in detail!
+
+We are now going to use meta information to customize our website! Open the file @default.template@
+and add this before the &lt;/body&gt; tag:
+
+<pre>
+  <div class="bar">
+    File last changed on \{filemdate: }!
+  </div>
+</pre>
+
+The part @\{filemdate: }@ is called a tag. Tags are implemented using plugins and they can be used to
+insert dynamic content when webgen is run. For example, the menu on the page is generated with the
+@\{menu: }@ tag! If webgen sees a tag during the processing of a page for which no tag plugin
+exists, it looks at the meta information of the page. If there is a meta information entry with the
+tag name, it uses that content instead. We will use that now!
+
+Open the file @hello.page@ and add the following meta information:
+
+<pre>
+filemdate: 10.4.2005
+</pre>
+
+so that @hello.page@ looks like this:
+
+<pre>
+\---
+title: Sample hello page
+inMenu: true
+filemdate: 10.4.2005
+\---
+This is a sample page with the title "{title:}" and it is in the menu!!!
+</pre>
+
+Run webgen and view the output! The tag @\{filemdate: }@ got substituted by the value specified in
+the meta information. As we have not put any meta information in the @index.page@ file, a warning is
+issued when webgen is run and no date is shown on the page!
+
+h2. Write a Simple Plugin
+
+Because we are not quite happy with our basic file modification time tag, we are going to write a
+simple tag plugin.
+
+Create the file @plugin/filemdate.rb@ with the following content:
+
+<pre>
+require 'webgen/plugins/tags/tags'
+
+module Tags
+
+  class FileMDateTag < DefaultTag
+
+    summary "Puts the modification time of the file on the page"
+    depends_on 'Tags'
+
+    def initialize
+      super
+      register_tag( 'filemdate' )
+    end
+
+    def process_tag( tag, node, refNode )
+      return File.mtime( node.recursive_value( 'src' ) ).to_s
+    end
+
+  end
+
+end
+</pre>
+
+That's all! The new plugin gets loaded when webgen starts and it is used when the tag @filemdate@ is
+encountered. We can now safely remove the @filemdate@ meta info from the file @hello.page@ although
+you can leave it there - it won't do any harm.
+
+Again, just run webgen and view the output!

data/doc/src/documentation/index.page

@@ -36,18 +36,6 @@ works and what you can expect when you start webgen.
   important. Developers who extend webgen by writing a new plugin can use the informational and
   debug messages to see what is going on and to help them develop the plugin.
 
-h2. Usage
-
-Webgen uses two directories: one to read the source files from and an other to write the output
-files to. The default source directory is @src@ and the default output directory is @output@. The
-source directory can be structured in any way you like, there is no restriction in respect of the
-number of directories or files.
-
-To build the website you simple need to change to the parent directoy of the source directory and
-type @webgen@. If everything is okay, no output will appear and you can point your browser to the
-output directory and view your website. If not, webgen tries to give detailed information about what
-happened and why something could not be done correctly.
-
 h2. Configuration
 
 Webgen provides a default configuration out of the box. If you can live with that, you do not need
@@ -57,7 +45,7 @@ in the current directory for the configuration file.
 
 If you want to get the configuration values you can run webgen like this
 <pre>
-  $ webgen -c
+  $ webgen show config
 </pre>
 
 The list shows sorted by the plugin name the current values and the default values for each
@@ -66,9 +54,3 @@ plugin name as top level key and each configuration option as a key/value pair.
 looks like this:
 
 <pre class="webgen-file">{includeFile: /../../../testsite/config.yaml}</pre>
-
-h2. Plugins
-
-Webgen is written with extensibility in mind; therefore most of its features are implemented with
-plugins, only the core functions are not plugins. Use the menu to view the documentation for
-individual plugins.

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

@@ -0,0 +1,33 @@
+---
+title: Backing File Handler
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: BackingFileHandler}</notextile>
+
+h2. Description
+
+The backing file handler is used to set meta information for other files. It can be used to set
+additional meta information for page description files. However, its main purpose is to add virtual
+pages and directories.
+
+h2. File Format
+
+The files are written in YAML and have a very easy structure:
+<pre>
+filename1.en.html:
+  metainfo1: value1
+  metainfo2: value2
+filename1.de.html:
+  metainfo21: value21
+</pre>
+
+Your can use relative and absoulte paths in the filenames. However, you cannot specify meta
+information for files which are in one of the parent directories of the backing file.
+
+Using backing files you can add virtual files and directories. If the file specified in the entry
+does not exist, a node for that file will be created. This will also create the whole directory tree
+this virtual node is in. It allows you, for example, to add external items to the menu. You need
+to specify the +dest+ meta information which points to the actual location of the referenced page.
+

data/doc/src/documentation/{filehandler → plugins/filehandler}/directory.page

@@ -11,5 +11,4 @@ h2. Description
 The directory handler is used for processing directories. It creates the target directories and
 additionally an index file for each directory can be specified. If specified, this file is used
 instead of the plain directory index for displaying purposes. For example, the menu item for the
-file handlers page is generated by the index file for the directory @documentation/filehandler@ on
-this website.
+file handlers page is generated by the index file of the @filehandler@ directory.

data/doc/src/documentation/{filehandler → plugins/filehandler}/galleryhandler.page

@@ -76,4 +76,4 @@ DefaultGalleryLayouter and define the layout methods.
 
 h2. Examples
 
-You can view an example gallery <a href="{relocatable: /Design_Gallery_1.page}">here</a>!
+You can view an example gallery <a href="{relocatable: /Design_Gallery_1.html}">here</a>!

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

@@ -0,0 +1,20 @@
+---
+title: Plugins
+menuOrder: 30
+directoryName: Plugins
+---
+h2. About
+
+All available plugins in the distribution are described in this section. Choose a plugin category
+to get more information!
+
+h2. Plugins
+
+Webgen is written with extensibility in mind; therefore most of its features are implemented with
+plugins, only the core functions are not plugins.
+
+Writing your own plugins is not difficult, too! If you need a specific functionality, implement a
+plugin and put it under the site specific @plugin@ directory - then the plugin gets loaded with the
+others. It's so easy!
+
+For more information have a look at the <a href="{relocatable: /rdoc/index.html}">API documentation</a>!

data/doc/src/documentation/plugins/system/configuration.page

@@ -0,0 +1,12 @@
+---
+title: Configuration
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: Configuration}</notextile>
+
+h2. Description
+
+The configuration plugin provides a place for all the parameters which have global influence, like
+the global language setting.

data/doc/src/documentation/plugins/system/index.page

@@ -0,0 +1,7 @@
+---
+title: System Plugins
+directoryName: System Plugins
+---
+h2. About
+
+The system plugins provide core functionality for webgen.

data/doc/src/documentation/plugins/system/logging.page

@@ -0,0 +1,13 @@
+---
+title: Logging
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: Logging}</notextile>
+
+h2. Description
+
+The logging plugin provides a logging mechanism which can be used to analyse errors of the website.
+If the parameter @logToFile@ is true, then the log messags will not appear on the error console but
+they are written to log files which reside in the @log@ directory.

data/doc/src/documentation/{tags → plugins/tags}/executecommand.page

@@ -14,6 +14,5 @@ h2. Examples
 
 table{border:1px solid black}.
 |_.Command|_.Output|
-|\{execute: date}|<pre class="webgen-file">{execute: date}</pre>|
 |\{execute: ls}|<pre class="webgen-file">{execute: ls}</pre>|
 |\{execute: uname -p}|<pre class="webgen-file">{execute: uname -p}</pre>|

data/doc/src/documentation/{tags → plugins/tags}/index.page

@@ -19,9 +19,9 @@ Tags are defined by a special markup code. A tag has the following structure:
 
 Every time a tag is found in a source file, the registered plugin for the tag is called. The plugin
 returns a string which is put into the output file instead of the tag. The output a tag plugin can
-produce ranges from something simple to something complex. For example, the <a href="{relocatable: meta.page}">
+produce ranges from something simple to something complex. For example, the <a href="{relocatable: meta.html}">
 Meta Tag</a> plugin copies any additional info specified in the source file verbatim
-into the correct place in the output file. And in contrast, the <a href="{relocatable: menu.page}">
+into the correct place in the output file. And in contrast, the <a href="{relocatable: menu.html}">
 Menu Tag</a> plugin generates a whole menu tree.
 
 h2. Tag Parameters

data/doc/src/documentation/{tags → plugins/tags}/langbar.page

@@ -15,7 +15,7 @@ item.
 
 h2. Examples
 
-Here is a <a href="{relocatable: multilang.page}">link</a> to a page which is translated to several
+Here is a <a href="{relocatable: multilang.html}">link</a> to a page which is translated to several
 languages (more or less ;-). Have a look at it and don't forget to view the page in the other
 languages!
 

data/doc/src/documentation/{tags → plugins/tags}/menu.de.page

@@ -1,5 +1,6 @@
 ---
 title: Menütag
+inMenu: true
 ---
 <div class="section">
 

data/doc/src/documentation/{tags → plugins/tags}/menu.page

@@ -12,7 +12,7 @@ The menu tag is used to generate a menu for the website. You can see such a menu
 page. To get a list of all supported parameters for the menu tag, have a look at its API
 documentation.
 
-This page is available in <a href="{relocatable: menu.page/menu.de.html}">German</a>. Try and go to
+This page is available in <a href="menu.de.html">German</a>. Try and go to
 the german version of this page. You will see that the menu items for which translations exist
 change their names.
 

data/doc/src/download.page

@@ -12,6 +12,7 @@ Download: "http://rubyforge.org/frs/?group_id=296":http://rubyforge.org/frs/?gro
 
 h2. Dependencies
 
+* "cmdparse":http://cmdparse.rubyforge.org version 1.0.1 or higher
 * "RedCloth":http://redcloth.rubyforge.org version 2.0.10 or higher if you want Textile support
 * "BlueCloth":http://www.deveiate.org version 1.0.0 or higher if you want Markdown support
 * "RMagick":http://rmagick.rubyforge.org/ version 1.7.1 or higher if you want automatic thumbnail

data/doc/src/index.page

@@ -1,5 +1,5 @@
 ---
-title: Home
+title: HomePage
 inMenu: true
 directoryName: Webgen
 ---
@@ -10,35 +10,53 @@ h2. Welcome
 This whole site was generated with webgen and provides an online demonstration of its features.
 Choose from the menu what you want to see from or know about webgen!
 
+If you have an idea for a new feature, "request
+it!":http://rubyforge.org/tracker/?atid=1210&group_id=296&func=browse. If you have found a bug, you
+can "report it here!":http://rubyforge.org/tracker/?atid=1207&group_id=296&func=browse Also, there
+are "forums":http://rubyforge.org/forum/?group_id=296 and a "mailing
+list":http://rubyforge.org/mail/?group_id=296 available if you have any questions!
+
 h2. News
 
-*Webgen 0.3.2 released!!!*
+*Webgen 0.3.3 released!!!*
+
+Major changes:
+
+* New command line interface based on "CommandParser":http://cmdparse.rubyforge.org
+* Now you can let webgen create the basic directories and files by executing @webgen create my_site@
+* New logging plugin lets you have more control over logging and log files
+* Now each website can have a plugin directory
+* New parameters for: <a href="{relocatable: documentation/plugins/tags/wikilink.html}">wikilink</a>
+* Changed format of backing files -> have a look at the <a href="{relocatable: documentation/plugins/filehandler/backing.html}">documentation</a>!
+* Removed obsolete Extension Loader plugin
+* Fixed bugs
+
+
+<b>Webgen 0.3.2 released!!!</b>
 
 Bug fix release for bug #1637 and other bugs
 
-h2. News
 
 *Webgen 0.3.1 released!!!*
 
 Major changes:
 
-* Better DefaultLayouter for picture galleries (<a href="{relocatable: Design_Gallery_1.page}">online demo</a>)
-* Output names for page files now customizable (see <a href="{relocatable: documentation/filehandler/pagehandler.page}">PageHandler</a>)
+* Better DefaultLayouter for picture galleries (<a href="{relocatable: Design_Gallery_1.html}">online demo</a>)
+* Output names for page files now customizable (see <a href="{relocatable: documentation/plugins/filehandler/pagehandler.html}">PageHandler</a>)
 * On-the-fly creation of thumbnails for pictures with RMagick
-* New tags: <a href="{relocatable: documentation/tags/sitemap.page}">sitemap</a>
+* New tags: <a href="{relocatable: documentation/plugins/tags/sitemap.html}">sitemap</a>
 * Tag @lang@ renamed, new name @langbar@!
 * New parameters for @menu@ tag
 * Automatic checking of HTML files on their validness
 * Fixed bugs
 
-h2. News
 
 *Webgen 0.3.0 released!!!*
 
 Major changes:
 
 * Textile, Markdown, RDOC and HTML as content format supported!!!
-* New tags: <a href="{relocatable: documentation/tags/wikilink.page}">wikilink</a>
+* New tags: <a href="{relocatable: documentation/plugins/tags/wikilink.html}">wikilink</a>
 * Improved plugin system
 * On-the-fly creation of new tags
 * Fixed bugs