dokkit 0.4.4 → 0.5.0

data/History.txt

@@ -1,7 +1,139 @@
-== 0.3.1
+== 0.5.0 / 2008-08-21
 
-* fixed bug #19332: now meta configuration informations are parsed
-  correctly in presence of newlines at the beginning of file.
+* huge code refactoring
+
+* many bug fixes
+
+* improved support for partial; now, by default, file name beginning
+  with an underscore are considered partial, e.g.:
+
+    render :partial => 'partial'
+
+  The code above, will render 'doc/pages/_partial' using the current
+  output format.
+
+* new configuration dsl syntax, e.g.:
+
+    environment do |env|
+
+      env.configure do |configure|
+        configure.document_dir = 'doc/documents'
+      end
+
+      env.select_document do |selection|
+        selection.include('*')
+        selection.exclude('*.draft')
+      end
+
+    end
+
+== 0.4.4 / 2008-08-10
+
+* fixed a bug that prevented to use custom dokkit models; to get
+  more information about custom models please refer to
+  http://dokkit.rubyforge.org/models/models.html    
+
+* dokkit gem no longer depends on haml; if you want to use haml you
+  have to install it
+
+* an error message is displayed when an output format is associated
+  to a formatter that doesn't support it 
+
+== 0.4.3 / 2008-08-05
+
+* fixed haml dependency in gem package 
+
+== 0.4.2 / 2008-08-05
+
+* added 'formatter' configuration key
+
+With the 'formatter' key, users can select the formatter to use for
+rendering the current document.
+
+The example configuration below tell dokkit to use maruku filters
+(maruku-html, maruku-latex) to render the same markdown source document
+in html and latex format:
+
+   ---
+   formatter: maruku
+   format:
+   - html
+   - latex
+   ---
+
+The example above is equivalent to:
+
+   ---
+   format:
+   - html
+       filter:
+       - erb
+       - maruku-html
+   - latex
+       filter:
+       - erb
+       - maruku-latex
+   ---
+
+The default value for 'formatter' key is 'deplate'. Current available
+formatters are: deplate, maruku, haml.
+
+* added haml filter
+
+The example below will applies haml postfiltering to the document layout:
+
+   ---
+   format:
+   - html
+       postfilter:
+       - haml
+   ---
+
+* easier access to configuration hash
+
+The erb code below returns the value of @configuration['title']:
+
+   ---
+   title: Document title
+   ---
+   Title of the document: <%= title %>   
+
+== 0.4.1 / 2008-07-27
+
+* added support for postfiltering (now erb processing is done in the
+  postfiltering step)
+
+* added experimental support for tidy postfilter
+
+Postfiltering is accessible through postfilter configuration key.
+
+Example:
+
+   ---
+   format:
+   - text
+   - latex
+   - html:
+       postfilter:
+       - erb
+       - tidy
+   ---
+   Content of the document.
+
+The example above will render the document producing plain text, latex
+and html output. In particular, the html output will be postprocessed by
+erb and tidy filters.
+
+== 0.4.0 / 2008-07-18
+
+* improved support for partials and nested layouts
+
+* added cache support
+
+* easy environment setup with the introduction of a configuration
+   container
+
+* a lot of code refactoring and bug fixes
 
 == 0.3.0 / 2008-01-09
 

data/Manifest.txt

@@ -9,6 +9,7 @@ lib/dokkit/cache.rb
 lib/dokkit/cache/cache.rb
 lib/dokkit/environment.rb
 lib/dokkit/environment/basic.rb
+lib/dokkit/environment/container.rb
 lib/dokkit/environment/helpers.rb
 lib/dokkit/environment/helpers/extmap.rb
 lib/dokkit/environment/helpers/fileselection.rb
@@ -21,6 +22,7 @@ lib/dokkit/filters/haml.rb
 lib/dokkit/filters/maruku.rb
 lib/dokkit/filters/nil.rb
 lib/dokkit/filters/tidy.rb
+lib/dokkit/filters/yaml.rb
 lib/dokkit/hash.rb
 lib/dokkit/logging.rb
 lib/dokkit/logging/logger.rb
@@ -35,6 +37,7 @@ lib/dokkit/resource/extensions/html.rb
 lib/dokkit/resource/extensions/url.rb
 lib/dokkit/resource/filenamehelper.rb
 lib/dokkit/tasklib.rb
+lib/dokkit/tasklib/base.rb
 lib/dokkit/tasklib/clean.rb
 lib/dokkit/tasklib/render.rb
 lib/models/simple/Rakefile
@@ -46,10 +49,14 @@ lib/models/simple/doc/layouts/simple.latex
 lib/models/simple/doc/layouts/simple.text
 lib/models/simple/doc/pages/simple.deplate
 lib/models/simple/setup/setup.rb
-tasks/annotations.rake
-tasks/doc.rake
+tasks/ann.rake
+tasks/bones.rake
 tasks/gem.rake
+tasks/git.rake
 tasks/manifest.rake
+tasks/notes.rake
+tasks/post_load.rake
+tasks/rdoc.rake
 tasks/rubyforge.rake
 tasks/setup.rb
 tasks/spec.rake

data/README.txt

@@ -4,34 +4,52 @@ dokkit
 
 == DESCRIPTION:
   
-dokkit is a document generator. It was inspired by rote but now it is
-completely independent from it. dokkit uses filters like deplate and
-maruku to generate output in a large variety of formats (tex, html,
-docbook, plain text, ...).
+dokkit is a document generator that is suitable for static website
+generation too. dokkit uses formatters like deplate and maruku to
+generate output in tex, html and plain text.
 
 With dokkit you can:
 
 * generate static websites
-* generate many types of documents in many formats (html, tex, plain text, etc.)
-* write your documents using a simple wiki syntax and obtain high quality output
+
+* generate many types of documents in many formats
+
+* write your documents using a simple wiki syntax and obtain high
+  quality output (with pdflatex)
+
 * generate different output formats from the same source document 
-* use models to quickly generate the documents you want (technical report, invoice, howto, guides, presentation, website, etc.)
+
+* use models to quickly generate the documents you want (technical
+  report, howto, guides, presentation, website, etc.)
+
 * simply derive new documentation models from the existing ones
-* simply modify existing models to fit your needs
 
-For more information please execute:
+* simply modify existing models to fit your needs
 
-  dokkit --help
+For more information about dokkit visit the website[http://dokkit.rubyforge.org/]
 
 == FEATURES/PROBLEMS:
   
-dokkit key features are:
+dokkit's features are:
+
+* a smart building system based on rake
 
-* a smart building system based on rake[http://rake.rubyforge.org]
-* a documentation directory structure organized in pages, layouts, configuration files, resources
 * a templating system based on ERB
-* a simple and flexible configuration system based on YAML
+
+* a flexible configuration system based on YAML that supports shared
+  configuration files and ‘in header’ configuration
+
+* an extensible formatting system that uses deplate and maruku as built-in filters
+  
+* convention over configuration: for example, you don’t need to give a
+  layout name to use if a layout with the same name of the processed
+  document is found in doc/layouts folder
+
+* support for nested layouts
+
 * support for partials
+    
+* support for caching
 
 == SYNOPSIS:
 
@@ -51,9 +69,9 @@ To create a new documentation environment in <dirname> run:
 
 == QUICK START
 
-  $ dokkit mydocument
-  $ cd mydocument
-  $ rake
+  dokkit mydocument
+  cd mydocument
+  rake
 
 == LICENSE:
 

data/Rakefile

@@ -11,15 +11,19 @@ task :default => 'spec:run'
 
 PROJ.name = 'dokkit'
 PROJ.version = Dokkit::VERSION
-PROJ.summary = 'dokkit is an open source document generator'
+
+PROJ.summary = 'dokkit is an open source document generator that is suitable for static website generation too.'
+
 PROJ.authors = 'Andrea Fazzi'
 PROJ.email = 'andrea.fazzi@alca.le.it'
 PROJ.url = 'http://dokkit.rubyforge.org'
-PROJ.description = paragraphs_of('README.txt', 1).join("\n\n")
-PROJ.changes = paragraphs_of('History.txt', 0..1).join("\n\n")
-PROJ.rubyforge_name = 'dokkit'
-PROJ.dependencies = ['deplate', 'rake', 'maruku']
-PROJ.need_zip = true
-PROJ.spec_opts << ['--format', 'specdoc', '--color']
-PROJ.rdoc_exclude << "models/simple"
+PROJ.rubyforge.name = 'dokkit'
+PROJ.gem.dependencies = ['deplate', ['rake', '>= 0.8.1'], 'maruku']
+PROJ.gem.need_zip = true
+PROJ.spec.opts << ['--format', 'specdoc', '--color']
+PROJ.rdoc.exclude << "models/simple"
+PROJ.rdoc.remote_dir = 'rdoc'
+
+PROJ.svn.path = 'dokkit-core'
+
 # EOF

data/lib/dokkit.rb

@@ -51,5 +51,5 @@ rescue LoadError
 end  
 
 module Dokkit
-  VERSION = '0.4.4'
+  VERSION = '0.5.0'
 end 

data/lib/dokkit/cache/cache.rb

@@ -23,7 +23,12 @@ module Dokkit
     
     def add_dependency(source_fn, format, dep)
       @deps[source_fn] ||= { format => [] }
-      @deps[source_fn][format] << dep unless (dep.nil? or @deps[source_fn][format].include?(dep))
+      if @deps[source_fn][format]
+        @deps[source_fn][format] << dep unless (dep.nil? or @deps[source_fn][format].include?(dep))
+      else
+        @deps[source_fn][format] = []
+        @deps[source_fn][format] << dep unless (dep.nil? or @deps[source_fn][format].include?(dep))
+      end
     end
     
     def load

data/lib/dokkit/environment.rb

@@ -6,6 +6,7 @@
 # (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
 #                                                                          
 
+require 'dokkit/environment/container'
 require 'dokkit/environment/basic'
 require 'dokkit/environment/helpers'
 

data/lib/dokkit/environment/basic.rb

@@ -1,7 +1,7 @@
 #                                                                          
 # File 'basic.rb' created on 01 mag 2008 at 15:37:33.                    
 #
-# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+# See 'dokkit.rb' or +LICENSE+ for license information.                      
 #                                                                          
 # (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
 #                                                                          
@@ -9,6 +9,7 @@
 require 'ostruct'
 require 'dokkit'
 require 'dokkit/environment'
+require 'dokkit/environment/helpers'
 require 'dokkit/logging'
 require 'dokkit/factory'
 require 'dokkit/resource'
@@ -18,40 +19,135 @@ require 'dokkit/cache'
 
 module Dokkit
   module Environment
-    module Basic
 
-      # When included in a container, initialize it.
-      def initialize
+    def environment(&blk) Basic.new(&blk); end
+    
+    class Basic < Container
+
+      include Dokkit::Environment::Helper
+      
+      def initialize(&blk)
+        super
         add_lib_to_load_path
-        yield self if block_given?
-        define_tasks
-      end
+        
+        init_extmap
+        init_services
+        
+        yield self if block_given?        
 
-      # Add lib folder to the load path.
-      def add_lib_to_load_path
-        $: << 'lib'
+        define_tasks
       end
-
-      # Define rake tasks for the environment.
+      
       def define_tasks
         render
         clean
       end
-
-      # Setup a console logger.
-      def logger
-        @logger ||= Logging::Observer::Console.logger
+      
+      def init_services
+        methods.select { |meth| meth =~ /register_/ }.each { |meth| send(meth) }
       end
-
-      # Setup cache.
-      def cache
-        @cache ||= Cache.new
+      
+      def register_document_fs
+        register :document_fs do
+          Environment::Helper::FileSelection.new(configuration.document_dir) do |fs|
+            fs.include('**/*')
+            fs.exclude('**/*.yaml')
+          end
+        end
+      end
+      
+      def register_data_fs
+        register :data_fs do
+          Environment::Helper::FileSelection.new(configuration.data_dir) do |fs|
+            fs.include('**/*')
+          end
+        end
+      end
+      
+      def register_extmap
+        register :extmap do
+          Helper::ExtMap.new(configuration.document_dir)
+        end
+      end
+      
+      def register_filter_factory
+        register :filter_factory do
+          Dokkit::Factory.new do |factory|
+            factory.add('nil') { Dokkit::Filter::Nil.new } 
+            factory.add('erb') { |document| Dokkit::Filter::ERB.new(document) }
+            factory.add('yaml') { |document| Dokkit::Filter::YAML.new(document) }
+            factory.add('tidy') { Dokkit::Filter::Tidy.new }
+            factory.add('maruku-html') { Dokkit::Filter::MarukuHTML.new }
+            factory.add('deplate-latex') { Dokkit::Filter::DeplateLatex.new }
+            factory.add('deplate-html') { Dokkit::Filter::DeplateHTML.new }
+            factory.add('deplate-text') { Dokkit::Filter::DeplateText.new }
+            factory.add('haml') { |document| Dokkit::Filter::Haml.new(document) }
+          end
+          
+        end
+      end
+      
+      def register_resource_factory
+        register :resource_factory do
+          Factory.new do |factory|
+            factory.add(:document, &document_factory_block)
+            factory.add(:data, &data_factory_block)
+          end        
+        end
+      end
+      
+      def register_cache
+        register :cache do
+          Cache.new
+        end
+      end
+      
+      def register_render
+        register :render do
+          TaskLib::Render.new do |task|
+            task.logger = logger
+            task.resource_factory = resource_factory
+            task.document_fns = document_fs.files
+            task.data_fns = data_fs.files
+          end
+        end
+      end
+      
+      def register_clean
+        register :clean do
+          TaskLib::Clean.new do |task|
+            task.logger = logger
+            task.output_dir = configuration.output_dir
+            task.cache_dir = configuration.cache_dir
+          end
+        end
+      end
+      
+      def register_logger
+        register :logger do
+          Logging::Observer::Console.logger          
+        end
+      end
+      
+      def register_configuration
+        register :configuration do
+          OpenStruct.new(default_configuration)
+        end
+      end
+      
+      # Add lib folder to the load path.
+      def add_lib_to_load_path
+        $: << 'lib'
       end
 
+      def init_extmap
+        @extmap = { }
+      end
+      
       def default_filter_chain
         { 
           'deplate' => { 'html' => ['erb', 'deplate-html'], 'latex' => ['erb', 'deplate-latex'], 'text' => ['erb', 'deplate-text']},
-          'maruku' => { 'html' => ['erb', 'maruku-html'], 'latex' => ['erb', 'maruku-latex'], 'text' => ['erb', 'maruku-text']},
+          'maruku' => { 'html' => ['erb', 'maruku-html'], 'latex' => ['erb', 'maruku-latex'] },
           'haml' => { 'html' => ['haml'] },
         }  
       end
@@ -59,121 +155,51 @@ module Dokkit
       def default_postfilter_chain
         { 'html' => ['erb'], 'latex' => ['erb'], 'text' => ['erb'] }  
       end
-      
-      # Return an OpenStruct object to setup documentation
-      # directories. Instantiate the object only once.
-      #
-      # configuration.document_dir :: set/get documents folder.
-      # configuration.config_dir :: set/get configs folder.
-      # configuration.layout_dir :: set/get layouts folder.
-      # configuration.data_dir :: set/get data folder.
-      # configuration.output_dir :: set/get output folder.
-      # configuration.cache_dir :: set/get cache folder.
-      #
-      def configuration
-        @configuration ||= OpenStruct.new({ :document_dir => 'doc/pages',
-                                            :config_dir => 'doc/configs',
-                                            :layout_dir => 'doc/layouts',
-                                            :data_dir => 'doc/data',
-                                            :output_dir => 'output',
-                                            :cache_dir => '.cache',
-                                            :default_filter_chain => default_filter_chain,
-                                            :default_postfilter_chain => default_postfilter_chain })
-      end
-
-
-      # Return a Dokkit::Environment::Helper::FileSelection object
-      # with the list of documents in configuration.document_dir
-      # folder and its subdir. The object is instantiated only
-      # once. By default all files in configuration.document_dir and
-      # subdirs are included.
-      def documents
-        @documents ||= Environment::Helper::FileSelection.new(configuration.document_dir) do |fs|
-          fs.include('**/*')
-          fs.exclude('**/*.yaml')
-        end
-      end
-
-      # Return a Dokkit::Environment::Helper::FileSelection object
-      # with the list of data files in configuration.data_dir folder
-      # and its subdir. The object is instantiated only once.
-      def data
-        @data ||= Environment::Helper::FileSelection.new(configuration.data_dir).include('**/*')
-      end
-
-      # Return a Dokkit::Environment::Helper::ExtMap object that map
-      # an extension code block to document files using glob patterns.
-      def extmap
-        @extmap ||= Helper::ExtMap.new(configuration.document_dir)
-      end
-      
-      # Construct a filter factory and register filters.
-      def filter_factory
-        @filter_factory ||= Dokkit::Factory.new do |factory|
-          factory.add('nil' => lambda { Dokkit::Filter::Nil.new } )
-          factory.add('erb' => lambda { |binding| Dokkit::Filter::ERB.new(binding) } )
-          factory.add('tidy' => lambda { Dokkit::Filter::Tidy.new } )
-          factory.add('maruku-html' => lambda { Dokkit::Filter::MarukuHTML.new } )
-          factory.add('deplate-latex' => lambda { Dokkit::Filter::DeplateLatex.new } )
-          factory.add('deplate-html' => lambda { Dokkit::Filter::DeplateHTML.new } )
-          factory.add('deplate-text' => lambda { Dokkit::Filter::DeplateText.new } )
-          factory.add('haml' => lambda { |document| Dokkit::Filter::Haml.new(document) } )
-        end
-      end
 
-      # Construct a resource factory to get resource instances
-      # (i.e. document and data). The object is instantiated only
-      # once.
-      def resource_factory
-        @resource_factory ||= Factory.new do |factory|
-          factory.add(:document => document_factory_block)
-          factory.add(:data => data_factory_block)
+      def default_configuration
+        {
+          :document_dir => 'doc/pages',
+          :config_dir => 'doc/configs',
+          :layout_dir => 'doc/layouts',
+          :data_dir => 'doc/data',
+          :output_dir => 'output',
+          :cache_dir => '.cache',
+          :default_filter_chain => default_filter_chain,
+          :default_postfilter_chain => default_postfilter_chain 
+        }                    
+      end
+
+      def document
+        register :document do
+          Resource::Document.new(source_fn, configuration.marshal_dump) do |document|
+            document.logger = logger
+            document.cache = cache
+            document.resource_factory = resource_factory
+            document.filter_factory = filter_factory
+          end          
         end
       end
-
+      
       # Return a block that is able to construct a Document instance.
       def document_factory_block
         lambda do |source_fn|
-          Resource::Document.new(source_fn, 
-                                 configuration.marshal_dump, 
-                                 logger, 
-                                 cache, 
-                                 resource_factory,
-                                 filter_factory, 
-                                 &extmap[source_fn])
+          Resource::Document.new(source_fn, configuration.marshal_dump) do |document|
+            document.logger = logger
+            document.cache = cache
+            document.resource_factory = resource_factory
+            document.filter_factory = filter_factory
+            document.extend @extmap[source_fn] if @extmap[source_fn]
+          end
         end
       end
-
-      # Return a block that is able to construct a Data instance.
+      
       def data_factory_block
         lambda do |source_fn|
           Resource::Data.new(source_fn, configuration.marshal_dump)
         end
       end
 
-      # Define render tasklib.
-      def render
-        TaskLib::Render.new(logger, resource_factory, documents.files, data.files)   
-      end
-
-      # Define clean tasklib.
-      def clean
-        TaskLib::Clean.new(logger, configuration.marshal_dump)
-      end
-
-    end
-  end
-end
-
-module Dokkit
-  module Environment
-    module Basic
-
-      # Define a setup container.
-      class Container
-        include Dokkit::Environment::Basic
-      end
-
     end
+    
   end
 end