webgen 0.4.7 → 0.5.0

data/doc/src/documentation/basics.page

@@ -1,148 +0,0 @@
----
-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

@@ -1,104 +0,0 @@
----
-title: Extending webgen
-inMenu: true
----
-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:
-
-* debug
-* info
-* warn
-* error
-
-The methods are named after the log levels and can be invoked by using
-@logger.{debug|info|warn|error}@. You need to provide a string as argument or a block which returns
-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: 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/@!
-
-h3. CLI Command Plugins
-
-For this you need to write a new command class and put its file into the @plugin@ folder of the
-website. Have a look at the "cmdparse API reference":http://cmdparse.rubyforge.org/rdoc/index.html
-for information about how to write a command class.
-
-There are basically two ways for a command plugin:
-
-* Easiest one
-
-  You just declare a new class derived from @CmdParse::Command@ and include the
-  @Webgen::CommandPlugin@ module. After you have included this module, you can use all standard
-  plugin directives, like @summary@ or @add_param@. Also, this command gets automatically added to
-  the main @CommandParser@ class. Thus, the @initialize@ method must not take any arguments!
-
-  <pre>
-  class SimpleCommand < CmdParse::Command
-
-  include Webgen::CommandPlugin
-
-  summary "Describe simple command"
-  add_param 'firstParam', 45, 'Description of firstParam'
-
-  def initialize
-    super( 'simple', false )
-    self.short_desc = "This is a sample for a simple command."
-  end
-
-  def usage; "Usage: #{@options.program_name} [global options] simple"; end
-
-  def execute( args )
-    # do something useful
-  end
-
-  end
-  </pre>
-
-* Easy one
-
-  You only need to go this way when the @initialize@ method of your command class needs to
-  arguments!!
-
-  Like before, you declare your new command class. This time however, you need include the
-  @Webgen::PluginDefs@ module and set the constant @VIRTUAL@ to true. This prevents the plugin
-  system from automatically instantiating an object. You then need to instantiate an object and add
-  it to the main @CommandParser@ class. This can be done by calling the @add_cmdparser_command@ of
-  the configuration plugin.
-
-  <pre>
-  class OtherCommand < CmdParse::Command
-
-  include Webgen::PluginDefs
-
-  VIRTUAL = true
-
-  summary "Describe other simple command"
-
-  def initialize( arg )
-    super( 'otherSimple', false )
-    @arg = arg
-    self.short_desc = "This is a second sample for a simple command."
-  end
-
-  def usage; "Usage: #{@options.program_name} [global options] otherSimple"; end
-
-  def execute( args )
-    # do something useful
-  end
-
-  end
-
-  Webgen::Plugin['Configuration'].add_cmdparser_command( OtherCommand.new( 5 ) )
-  </pre>

data/doc/src/documentation/howto.page

@@ -1,221 +0,0 @@
----
-title: Howto...?
-inMenu: true
-
-howtos:
-  - - create a website?
-    - |
-      You can create the needed structure by hand (which would be not so much to do). However, it's
-      still easier using the @webgen@ command line tool:
-
-        webgen create -t project -s andreas07 my_site
-
-      This will create a webgen website in the directory @my_site@ using the specified template and
-      style.
-
-  - - use a website/gallery/sipttra style?
-    - |
-      Just use the @webgen@ command line tool:
-
-        webgen use website_style STYLE_NAME
-        webgen use gallery_style STYLE_NAME
-        webgen use sipttra_style STYLE_NAME
-
-      Be aware that destination files may be overwritten!
-
-  - - set plugin parameters?
-    - |
-      You can set plugin parameters for all plugins via the configuration file. For example, say you
-      want to set the {param: File/DefaultHandler:linkToCurrentPage} parameter to @true@, then you
-      would add the following to the configuration file:
-
-        File/DefaultHandler:
-          linkToCurrentPage: true
-
-      There is a second possibility for tags: you can set the parameters directly in the tag
-      definition, like this:
-
-        \{breadcrumbTrail: {omitLast: true, separator: ' | '}}
-
-  - - change the default language?
-    - |
-      To use, for example, German as the default language, put the following into the configuration file:
-
-        Core/Configuration:
-          lang: de
-
-  - - set a different content format for page files?
-    - |
-      If you want to change the default content format, you need to add the following to your
-      configuration file (assuming you didn't set the {param: Core/FileHandler:defaultMetaInfo} parameter):
-
-        File/PageHandler:
-          defaultMetaInfo:
-            blocks: [[content, FORMAT_NAME]]
-
-      This will set the default format to FORMAT_NAME.
-
-      If you just want to change the format for a block, you should do it like this:
-
-      <notextile><pre><code>--- content, FORMAT_NAME
-        This is the block
-      </code></pre></notextile>
-
-  - - set the default meta information for files created by a specific file handler?
-    - |
-      Use the configuration file! For example, to change the default content format
-      to markdown and @inMenu@ to @true@ for page files use the following in your configuration file:
-
-        File/PageHandler:
-          defaultMetaInfo:
-            blocks: [[content, markdown]]
-            inMenu: true
-
-  - - ignore files in the source directory?
-    - |
-      This can be done using the {param: Core/FileHandler:ignorePaths} parameter. For example, to
-      ignore all files starting in @core@, you would put the following in the configuration file:
-
-        Core/FileHandler:
-          ignorePaths: [**/core*]
-
-      Be aware that the parameter overwrites the default setting. For more information on which
-      path patterns are supported, have a look a the
-      <a href="{relocatable: plugins/core/filehandler.page#pathpattern}">path pattern documentation</a>!
-
-  - - change the output name format of page file?
-    - |
-      Set the {param: File/PageHandler:outputNameStyle} in the configuration file to globally change
-      how the output names for page files are constructed or use the @outputNameStyle@ meta
-      information to change it only for individual page files!
-
-      For more information have a look at the documentation of the
-      {param: File/PageHandler:outputNameStyle} parameter!
-
-  - - use embedded ruby in page/template files?
-    - |
-      Have a look at the <a href="{relocatable: references/webpage_format.page#proc-erb}">ERB section</a> of
-      the WebPage Format reference!
-
-  - - modify the template chain?
-    - |
-      First, have a look at the {plugin: File/TemplateHandler} documentation!
-
-      To stop the template chain at a specific template or even at the page file itself, specify a
-      null template in the meta information, like this:
-
-        template: ~
-
-      To nest templates, you just need to specify the template in the meta information section:
-
-        template: my_special.template
-
-      Be aware that if no @template@ meta information is specified for a page or template file, the
-      template handler automatically searches for a default template in directory and the parent
-      directories of the file!
-
-  - - localize a directory name?
-    - |
-      Just set the @directoryName@ meta information on the localized directory index files!
-
-  - - provide additional attributes on links to a page file?
-    - |
-      You can specify additional attributes for a page file using the @linkAttrs@ meta information.
-      Take the following page file:
-
-      <notextile><pre><code>---
-      title: Tutorial
-      inMenu: true
-      linkAttrs:
-        title: This is a rather large tutorial
-        accesskey: D
-        tabindex: 5
-      ---
-      Yippieh, this is my tutorial!
-      </code></pre></notextile>
-
-      When a link to this page is created the specified attributes always get set on this link!
-
-  - - add page specific sidebar content?
-    - |
-      There are many ways to accomplish this, I will show only one way here using blocks. Add the
-      following to the sidebar in your @default.template@:
-
-        <% if node.node_info[:pagedata].blocks.has_key?( 'sidebar' ) %>
-          \{block: sidebar}
-        <% end %>
-
-      This will include the contents of the block @sidebar@ in the sidebar if such a block exists
-      for a page. Then just add a sidebar block to each page file which needs it. Following is such
-      a sample page file:
-
-      <notextile><pre><code>This is the main content block
-      --- sidebar
-      This is the sidebar block and everything in here goes to the sidebar!
-      </code></pre></notextile>
-
-  - - use global variables?
-    - |
-      First you need to set some global variables in your configuration file:
-
-        Core/Configuration:
-          customVars:
-            myVar: This is really nice!
-            myOtherVar: another content
-
-      Then you can use the {plugin: Tag/CustomVar} to output the variables:
-
-        \{customVar: myVar}
-
-  - - create XML output?
-    - |
-      This can be achieved manually (by setting the content format of the page file to @html@ and
-      then directly creating the XML elements) or by using the {plugin: ContentConverter/XmlBuilder}
-      plugin !
-
-  - - use emoticons instead of ASCII smileys?
-    - |
-      Either globally enable an emoticon pack in the configuration file, like this:
-
-        Misc/SmileyReplacer:
-          emoticonPack: crystal
-
-      Or enable smiley replacement only on a specific page file using the meta information, like
-      this:
-
-        emoticonPack: crystal
-
-  - - syntax highlight an included file?
-    - |
-      This can be done using the {plugin: Tag/IncludeFile} plugin. Make sure you have @coderay@
-      installed! Here is an example which includes a syntax highlighted ruby file:
-
-        \{includeFile: {filename: happy.rb, highlight: ruby}}
-
-  - - create a static menu?
-    - |
-      Have a look at the <a href="{relocatable: plugins/core/filehandler.page#metainfo-file}">meta information backing file</a> documentation!
-
-      You can use virtual nodes in the output backing section to define virtually any menu structure
-      you like, including things like having menu entries that point to the same page and links to
-      external pages!
-
----
-h1. How to...?
-
-
-This is a collection of some commonly asked questions on how to accomplish certain things with
-webgen. If you have an idea for a new howto, don't hestitate to write me a
-<a href="mailto:t_leitner@gmx.at">email</a>!
-
-<notextile>
-<ul>
-<% node['howtos'].each_with_index do |howto, h_index| %>
-  <li><a href="javascript: toogle('howto-<%= h_index %>')"><%= howto[0] %></a>
-      <div id="howto-<%= h_index %>" style="display: none">
-        <%= @plugin_manager['ContentConverter/Textile'].call( howto[1].to_s ) %>
-      </div>
-  </li>
-<% end %>
-</ul>
-</notextile>