webgen 0.3.0

data/README

@@ -0,0 +1,16 @@
+webgen - a template based static website generator
+
+Copyright (C) 2004 Thomas Leitner
+
+>>> The documentation for webgen is in the doc/src subdirectory. <<<
+
+You can build the documentation by
+invoking
+ $ rake doc
+
+in the root of the package or by running webgen manually in the +doc+ directory:
+ $ ruby -I../lib ../bin/webgen
+
+This documentation is actually the same as the one on webgen.rubyforge.org. When releasing a new
+version of webgen, I run one of the above commands to create the pages and then only copy it to the
+website! :-)

data/Rakefile

@@ -0,0 +1,283 @@
+# -*- ruby -*-
+#
+# $Id$
+#
+# webgen: template based static website generator
+# Copyright (C) 2004 Thomas Leitner
+#
+# 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
+#
+
+
+begin
+  require 'rubygems'
+  require 'rake/gempackagetask'
+rescue Exception
+end
+
+require 'rake/clean'
+require 'rake/packagetask'
+require 'rake/rdoctask'
+require 'rake/testtask'
+
+# General actions  ##############################################################
+
+$:.push 'lib'
+require 'webgen/configuration'
+
+PKG_NAME = "webgen"
+PKG_VERSION = Webgen::VERSION.join( '.' )
+PKG_FULLNAME = PKG_NAME + "-" + PKG_VERSION
+PKG_SUMMARY = Webgen::SUMMARY
+PKG_DESCRIPTION = Webgen::DESCRIPTION
+
+SRC_RB = FileList['lib/**/*.rb']
+
+# The default task is run if rake is given no explicit arguments.
+
+desc "Default Task"
+task :default => :test
+
+
+# End user tasks ################################################################
+
+desc "Prepares for installation"
+task :prepare do
+  ruby "setup.rb config"
+  ruby "setup.rb setup"
+end
+
+
+desc "Installs the package #{PKG_NAME}"
+task :install => [:prepare] do
+  ruby "setup.rb install"
+end
+
+
+task :clean do
+  ruby "setup.rb clean"
+end
+
+
+CLOBBER << "doc/output"
+desc "Builds the documentation"
+task :doc => [:rdoc] do
+  chdir 'doc' do
+    puts "\nGenerating online documentation..."
+    ruby %{-I../lib ../bin/webgen -V 3 }
+    puts "\nValidating all generated documentation..."
+    sh 'find output/ -name "*.html" -exec xmllint --valid {} --catalogs --noout \;'
+  end
+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 |t|
+  ruby "-Ilib -Itest test/runtests.rb"
+end
+
+# Developer tasks ##############################################################
+
+
+PKG_FILES = FileList.new( [
+                            'setup.rb',
+                            'TODO',
+                            'COPYING',
+                            'README',
+                            'Rakefile',
+                            'ChangeLog',
+                            'VERSION',
+                            'install.rb',
+                            'bin/**/*',
+                            'lib/**/*.rb',
+                            'testsite/**/*',
+                            'tests/**/*',
+                            'doc/**/*'
+                          ]) do |fl|
+  fl.exclude( /\bsvn\b/ )
+  fl.exclude( 'testsite/output' )
+  fl.exclude( 'testsite/coverage' )
+  fl.exclude( 'doc/output' )
+end
+
+task :package => [:gen_files] do
+  chdir 'pkg' do
+    sh "rpaadmin packport #{PKG_NAME}-#{PKG_VERSION}"
+  end
+end
+
+task :gen_changelog do
+  sh "svn log -r HEAD:1 -v > ChangeLog"
+end
+
+task :gen_version do
+  puts "Generating VERSION file"
+  File.open( 'VERSION', 'w+' ) do |file| file.write( PKG_VERSION + "\n" ) end
+end
+
+task :gen_installrb do
+  puts "Generating install.rb file"
+  File.open( 'install.rb', 'w+' ) do |file|
+    file.write "
+require 'rpa/install'
+
+class Install_#{PKG_NAME} < RPA::Install::FullInstaller
+  name '#{PKG_NAME}'
+  version '#{PKG_VERSION}-1'
+  classification Application
+  build do
+    installdocs %w[COPYING ChangeLog TODO]
+    installdocs 'docs'
+    installrdoc %w[README] + Dir['lib/**/*.rb']
+    installdata
+  end
+  description <<-EOF
+#{PKG_SUMMARY}
+
+#{PKG_DESCRIPTION}
+  EOF
+end
+"
+    end
+end
+
+task :gen_files => [:gen_changelog, :gen_version, :gen_installrb]
+CLOBBER << "ChangeLog" << "VERSION" << "install.rb"
+
+Rake::PackageTask.new( PKG_NAME, PKG_VERSION ) do |p|
+  p.need_tar = true
+  p.need_zip = true
+  p.package_files = PKG_FILES
+end
+
+if !defined? Gem
+  puts "Package Target requires RubyGEMs"
+else
+  spec = Gem::Specification.new do |s|
+
+    #### Basic information
+
+    s.name = PKG_NAME
+    s.version = PKG_VERSION
+    s.summary = PKG_SUMMARY
+    s.description = PKG_DESCRIPTION
+
+    #### Dependencies, requirements and files
+
+    s.files = PKG_FILES.to_a
+
+    s.require_path = 'lib'
+    s.autorequire = nil
+
+    s.executables = ['webgen']
+    s.default_executable = 'webgen'
+
+    #### Documentation
+
+    s.has_rdoc = true
+    s.extra_rdoc_files = rd.rdoc_files.reject do |fn| fn =~ /\.rb$/ end.to_a
+    s.rdoc_options = ['--line-numbers', '-m README']
+
+    #### Author and project details
+
+    s.author = "Thomas Leitner"
+    s.email = "t_leitner@gmx.at"
+    s.homepage = "webgen.rubyforge.org"
+    s.rubyforge_project = "webgen"
+  end
+
+  Rake::GemPackageTask.new( spec ) do |pkg|
+    pkg.need_zip = true
+    pkg.need_tar = true
+  end
+
+end
+
+=begin
+desc "Creates a tag in the repository"
+task :tag do
+  repositoryPath = File.dirname( $1 ) if `svn info` =~ /^URL: (.*)$/
+  fail "Tag already created in repository " if /#{PKG_NAME}/ =~ `svn ls #{repositoryPath}/versions`
+  sh "svn cp -m 'Created version #{PKG_NAME}' #{repositoryPath}/trunk #{repositoryPath}/versions/#{PKG_NAME}"
+end
+=end
+
+desc "Upload documentation to homepage"
+task :uploaddoc => [:doc] do
+  Dir.chdir('doc/output')
+  sh "scp -r * gettalong@rubyforge.org:/var/www/gforge-projects/#{PKG_NAME}/"
+end
+
+
+# Misc tasks ###################################################################
+
+
+def count_lines( filename )
+  lines = 0
+  codelines = 0
+  open( filename ) do |f|
+    f.each do |line|
+      lines += 1
+      next if line =~ /^\s*$/
+      next if line =~ /^\s*#/
+      codelines += 1
+    end
+  end
+  [lines, codelines]
+end
+
+
+def show_line( msg, lines, loc )
+  printf "%6s %6s   %s\n", lines.to_s, loc.to_s, msg
+end
+
+
+desc "Show statistics"
+task :statistics do
+  total_lines = 0
+  total_code = 0
+  show_line( "File Name", "Lines", "LOC" )
+  SRC_RB.each do |fn|
+    lines, codelines = count_lines fn
+    show_line( fn, lines, codelines )
+    total_lines += lines
+    total_code  += codelines
+  end
+  show_line( "Total", total_lines, total_code )
+end
+
+
+def run_testsite( arguments = '' )
+  Dir.chdir("testsite")
+  ruby %{-I../lib #{arguments} ../bin/webgen -V 3 }
+end
+
+
+CLOBBER << "testsite/output" << "testsite/webgen.log"
+desc "Build the test site"
+task :testsite do
+  run_testsite
+end
+
+
+CLOBBER  << "testsite/coverage"
+desc "Run the code coverage tool on the testsite"
+task :coverage do
+  run_testsite '-rcoverage'
+end

data/TODO

@@ -0,0 +1,133 @@
+---- CURRENT ----
+
+* allow specification of metadata for gallery and picture pages
+* allow a template to use another template (templates as page description files?) (template2 uses template1)
+* ev. create a GalleryNode and put gallery/pictures pages beneath it???
+* ordering of picture/gallery files for menu
+* create webgen 0.2.0 to 0.3.0 converter
+* security concerns (setting different $SAFE level???)
+* register with Freshmeat.net
+* use code generator to create test file with all tags and all tag parameter configurations
+* check out http://jigsaw.w3.org/css-validator/check/referer
+
+---- DOCU ----
+
+* pictureGallery: document layout methods (how to extend), main things...
+* extend plugins section on main documentation page
+* add design gallery
+* DEV: self.logger.warn/error/info/debug can be used for messages
+
+---- FUTURE ----
+
+* tag 'resume', uses xmlresume2x to provide HTML version of xml resume
+* tag 'mrplot' -> generate a plot with mrplot
+* tag 'sitemap' -> generate site map
+* multi-lingual picture/gallery files
+* create thumbnails of pictures on the fly with rmagick
+* create logo "Created with webgen"
+* refactor menu: abstract menu generator+parser, concrete impls (vert. menu, horz. menu, ...)
+
+---- DONE ----
+
+W check if an xml validator is available in ruby* option for includeFile tag: escapeHTML (should special html tags be escaped?)
+W think about sequence of actions when program is executed
+W think about how the data is stored in tree/which data is stored in tree
+W set up directory structure and build system
+W write ideas and design considerations
+W create sample files to work on
+W change exception mechanism to use IDs for exceptions
+W update all exceptions to new exception format
+W implement hooks mechanism
+W enable writing of tree again after hooks mechanism installed
+W implement page templates using hooks (after dir read store reference to template file in hash)
+W review Node class, remove all plugin dependent things
+W review configuration class, remove all plugin dependent things
+W check if ansi color output is better (for warnings, debug, etc), should be able to turn off
+W restructure current files, make more readable
+W pagePlugin.buildNode: srcName = File.basename(srcName) in front of urlName = ...
+W pagePlugin.get_template_for_node: raise ... if node.nil?
+W change the classes which use the listener/composite module because of the refactorization
+W refactor current classes
+W implement tag <relocatable> for references that should be relocatable
+W FileCopyPlugin: check if file has changed and only then copy
+W think about how to print out warnings uniformly --> log4r
+W define format of config.yaml
+W redo configuration file as yaml file
+W meta tag replacer - replaces tag with contents of equally named node.metainfo entry
+W add yaml page files
+W add default values for configuration in configuration.rb
+W create super class for page plugins
+W implement "creation of files only when necessary" (i.e. if dependencies have changed)
+    use modification of source and target to check if source is newer -> changed
+    change the behaviour in file copy plugin
+W think about configureable list of files patterns which should always be ignored when reading src dir
+W replace current logging mechanism with Log4r
+W implement <template> meta-info tag (see template based)
+W redo tree transformer
+W refacture menu tag plugin
+W update default.css so that the page display correctly
+N convert everything to utf8 before writing -> the file need to have the correct encoding
+W better loggers for plugins (substitute real plugin name for "plugin")
+N think about logging levels and when to use which level
+W add multiple language support
+W speed up menu creation by caching the created menu and only substituting the relative paths
+W if a page in one language is in the menu, all other languages for this page should also be in the menu (-> de yaml project page, no selection in menu)
+W link creation for nodes should be done only in one place (now in menu and navbar tags)
+W navbar should be configurable (start tag, separator, end tag)
+W command line parameter for listing all available configuration options with default values
+W add check so that all needed metainfo tags are in read files
+W eventually put TreeUtils methods into Node
+W get_node_for_string should also work for absolute paths (ie. '/images' or '/projects/index.html')
+W relocatable tag fails for "{relocatable: /images/bghack.png}" in index.xpage
+W make get_relpath_to_node work for all nodes, not only page nodes
+W implement meta info backing file for page file types without metainfo (e.g. html fragments)
+W file name syntax: [0-9].name-with_blanks.[de].[EXTENSION] -> title: Name with blanks, Order: [0-9], Language: de
+W implement order tag for setting menu order
+W use rake, gem and setup.rb for installing and packaging
+W prevent creation of log file if nothing is done (on -p, -e, --help...)
+W put main and configuration class into the Webgen module
+W use code coverage tool (-rcoverage) for checking the coverage on the testSite (use with rake)
+W document existing files (RDOC)
+W check out http://validator.w3.org/check/referer -> use xmllint from libxml2 package
+W make file plugins case-insensitiv (convert all uppercase letters to lowercase)
+W generate VERSION file when packaging
+W list plugins by category instead of name (file handlers and tags should be grouped together)
+W make get_node_for_string work with page files as parameters (reference in home.xpage to projects page)
+W make get_node_for_string work with localized page names, i.e. /index.html/index.de.html to get the german version of the page
+W add option to lang tag: showAlways -> display lang menu when only one item would appear?
+W handle configuration options for tags uniformly (default configuration and per tag configuration)
+W add option to menu tag: showOnlyThisSubtree -> displays only one tree to a deeper level
+W redo TreeWalker -> tree should be walked separately for each registered plugin
+W add virtual menu nodes for external html files
+W add mechanism to document configuration parameters
+W modify tag configuration so that mandatory/optional arguments for tags are supported
+W add RedCloth and BlueCloth and RDOC page description files
+W use File.basename(filename, '.*) to strip ext, File.extname(filename) to get ext
+W add debug statements to method_added in configuration.rb
+W do not allow two or more page files in the same language, print warn
+* remove log4r support, add STDLIB logger support
+* one file format, many content formats
+* allow line breaks in tags (substitute: \n -> ' ', \n\n -> \n)
+* configuration should be ruby file with special syntax, to allow the specification of additional tags --> additional config file
+* create tags in config file which produce informational output about filehandlers and tags (param listing,...)
+* include version number in documentation
+* get_relpath_to_node: if destNode['external'] --> check for URL pattern
+* add mandatory param info to output of 'describe'
+* option for includeFile tag: escapeHTML (should special html tags be escaped?)
+* more tags (in docu: how to use them, parameters, ..., structure should be the same everywhere)
+* add facility to check output files on conformity to a HTML standard
+* tag 'wikilink'
+* file handler for 'picture gallery' files
+* add optional extension method to Plugin class
+* rename tag loader -> extension loader
+* document extension loader and its config file
+* document in file handler that :dir extension is used for directory handler
+* options for PageHandler: default file format if none given
+* state that if a dependency is not found (e.g. redcloth) the plugin is disabled and a warning issued
+* add example section for each plugin
+* add tests for all parameters with which webgen can be called
+* Bug in analyse_filename if langpart.length != 2 (write test!) -> was already handled gracefully ;-)
+* remove Plugin.plugin method -> use class name! (short class name, without modules, Test::Hallo.name.split(/::/).last )
+* remove extension(...) call from file handlers -> DefaultHandler#initialize
+* pagehandler + converter into own subdir
+* think about filename conflicts for picture pages

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/bin/webgen

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'webgen/webgen'
+
+Webgen::WebgenMain.new.main( ARGV )

data/doc/extension.config

@@ -0,0 +1,55 @@
+# -*- ruby -*-
+
+simple_tag( 'version' ) do |tag, node, refNode|
+  Webgen::VERSION.join( '.' )
+end
+
+class DescribeTag < Tags::DefaultTag
+
+  summary "Shows options for the specified file handler"
+  add_param 'plugin', nil, 'The plugin which should be described'
+  set_mandatory 'plugin', true
+
+  def initialize
+    super
+    @processOutput = false
+  end
+
+  def process_tag( tag, node, refNode )
+    filehandler = get_param( 'plugin' )
+    self.logger.debug { "Describing tag #{filehandler}" }
+    plugin = Webgen::Plugin.config.find {|k,v| v.plugin == filehandler }
+    self.logger.warn { "Could not describe plugin '#{filehandler}' as it does not exist" } if plugin.nil?
+    ( plugin.nil? ? '' : format_data( plugin[1] ) )
+  end
+
+  def format_data( data )
+    s = "<table>"
+    row = lambda {|desc, value| "<tr style='vertical-align: top'><td style='font-weight:bold'>#{desc}:</td><td>#{value}</td></tr>" }
+
+    [['Plugin Name', 'plugin'], ['Summary', 'summary'], ['Description', 'description']].each do |desc, name|
+      s += row[desc, data.send( name )] if eval( "data.#{name}" )
+    end
+
+    s += row['Dependencies', data.dependencies.join( ', ')] if data.dependencies
+
+    unless data.params.nil?
+      params = data.params.collect do |k,v|
+        "<span style='color: red'>#{v.name}</span>" + \
+        ( v.mandatory.nil? \
+          ? "&nbsp;=&nbsp;<span style='color: blue'>#{v.default.inspect}</span>" \
+          : " (=" + ( v.mandatoryDefault ? "default " : "" ) + "mandatory parameter)" ) + \
+        ": #{v.description}"
+      end
+      s += row['Parameters', params.join( "<br />\n" )]
+    end
+    s += row['Name of tag', (data.tag == :default ? "Default tag" : data.tag)] if data.tag
+    s += row['Extension', data.extension.inspect.gsub(/"/, '')] if data.extension
+
+    s += "</table>"
+  end
+
+end
+
+register_tag( 'describe', DescribeTag.new )
+