webgen 0.5.0 → 0.5.1

data/Rakefile

@@ -145,6 +145,9 @@ EOF
       s.add_development_dependency('rcov', '>= 0.8.0')
       s.add_development_dependency('dcov', '>= 0.2.2')
       s.add_development_dependency('rubyforge', '>= 1.0.0')
+      s.add_development_dependency('RedCloth', '>= 3.0.0')
+      s.add_development_dependency('haml', '>= 2.0.1')
+      s.add_development_dependency('builder', '>= 2.1.0')
 
       s.require_path = 'lib'
 
@@ -173,7 +176,7 @@ EOF
 
   desc "Upload webgen documentation to Rubyforge homepage"
   task :publish_doc => [:doc] do
-    sh "rsync -avc htmldoc/ gettalong@rubyforge.org:/var/www/gforge-projects/webgen/documentation/#{(Webgen::VERSION.split('.')[0..-2] + ['x']).join('.')}"
+    sh "rsync -avc --delete htmldoc/ gettalong@rubyforge.org:/var/www/gforge-projects/webgen/documentation/#{(Webgen::VERSION.split('.')[0..-2] + ['x']).join('.')}"
   end
 
   desc 'Release webgen version ' + Webgen::VERSION
@@ -228,7 +231,7 @@ EOF
 
   desc "Upload the webgen website to Rubyforge"
   task :publish_website => [:website] do
-    sh "rsync -avc --exclude 'documentation/0.5.x' --exclude 'documentation/0.4.x' --exclude 'wiki' website/out/ gettalong@rubyforge.org:/var/www/gforge-projects/webgen/"
+    sh "rsync -avc --exclude 'documentation/0.5.x' --exclude 'documentation/0.4.x' --exclude 'wiki' --exclude 'robots.txt'  website/out/ gettalong@rubyforge.org:/var/www/gforge-projects/webgen/"
   end
 
 
@@ -255,6 +258,33 @@ EOF
     end
   end
 
+  EXCLUDED_FOR_TESTS=FileList.new(['lib/webgen/cli{*,**/*}', 'lib/webgen/version.rb',
+                                   'lib/webgen/output.rb', 'lib/webgen/source.rb',
+                                   'lib/webgen/tag.rb', 'lib/webgen/default_config.rb',
+                                  ])
+
+  EXCLUDED_FOR_DOCU=FileList.new(['lib/webgen/cli{*,**/*}', 'lib/webgen/contentprocessor/context.rb',
+                                  'lib/webgen/*/base.rb', 'lib/webgen/sourcehandler/fragment.rb',
+                                 ])
+
+  desc "Checks for missing test/docu"
+  task :check_missing do
+    puts 'Files for which no test exists:'
+    Dir['lib/webgen/**/*'].each do |path|
+      next if File.directory?(path) || EXCLUDED_FOR_TESTS.include?(path)
+      test_path = 'test/test_' + path.gsub(/lib\/webgen\//, "").tr('/', '_')
+      puts ' '*4 + path unless File.exists?(test_path)
+    end
+
+    puts
+    puts 'Files for which no docu exists:'
+    Dir['lib/webgen/*/*'].each do |path|
+      next if EXCLUDED_FOR_DOCU.include?(path)
+      docu_path = 'doc/' + path.gsub(/lib\/webgen\//, "").gsub(/\.rb$/, '.page')
+      puts ' '*4 + path unless File.exists?(docu_path)
+    end
+  end
+
 end
 
 task :clobber => ['dev:clobber']

data/VERSION

@@ -1 +1 @@
-0.5.0
+0.5.1

data/doc/contentprocessor.template

@@ -0,0 +1,10 @@
+---
+template: extensions.template
+--- name:summary pipeline:erb,tags,maruku,blocks
+
+The short name of the content processor (used, for example, in the `pipeline` option of a block in a
+file in [Webgen Page Format]({relocatable: webgen_page_format.html}) is `<%=
+context.website.config['contentprocessor.map'].invert[context.content_node['title']] %>`.
+
+--- name:content
+<webgen:block name='content' />

data/doc/contentprocessor/blocks.page

@@ -0,0 +1,67 @@
+---
+title: Webgen::ContentProcessor::Blocks
+---
+## Description
+
+This processor replaces a special xml tag with rendered blocks. It is used, for example, in
+templates to define the place where the actual page content should be. The short name of the
+processor is `blocks`!
+
+The general syntax is as follows:
+
+    <webgen:block name='BLOCK_NAME' chain='(L)CN;(L)CN;...' />
+
+So it is basically an XML tag with two attributes, `name` and `chain`. The `name` attribute
+specifies the name of the block that should be rendered in place of the block tag. The next node in
+the used node chain needs to have a block that is named so, otherwise an error is thrown (if there
+is only one node left in the node chain that node is used). The block is rendered according to its
+render pipeline and then inserted.
+
+The optional attribute `chain` specifies the node chain that should be used for rendering the
+block. Its value needs to be a list of (localized) canonical names of nodes separated by semicolons
+that should be used as node chain. If this attribute is not specified the default node chain is
+used.
+
+This is more easily explained with examples. Assume we have a `default.template` file, a
+`page.template` file and a `my.page` file with the following contents:
+
+The `default.template` file:
+
+    --- name:content, pipeline:blocks
+    before default
+    <webgen:block name='content' />
+    after default 1
+    <webgen:block name='content' chain='page.template;my.page' />
+    after default 2
+
+The `page.template` file:
+
+    --- name:content, pipeline:blocks
+    before page 1
+    <webgen:block name='content' />
+    after page 1
+
+And the `my.page` file:
+
+    --- name:content
+    The content of the page file.
+
+When `my.page` gets rendered to `my.html`, the node chain looks like this by default:
+
+    default.template ---> my.page
+
+The first webgen block tag just inserts the rendered block named `content` of `my.page`. The second
+block tag uses a custom node chain. Therefore the block named `content` of `page.template` gets
+rendered using the node chain:
+
+    page.template ---> my.page
+
+and then inserted. Summing up the above, the rendered file `my.html` will then look like this:
+
+    before default 1
+    The content of the page file.
+    after default 1
+    before page 1
+    The content of the page file.
+    after page 1
+    after default 2

data/doc/contentprocessor/builder.page

@@ -0,0 +1,80 @@
+---
+title: Webgen::ContentProcessor::Builder
+---
+## Description
+
+This content processor can be used to programatically create XHTML/XML documents
+([Reference][1]). The top builder object is provided through the `xml` object. There are also other
+objects provided by webgen available - have a look at the [erb documentation]({relocatable:
+erb.html}). The short name of the processor is `builder`!
+
+> This extension is only available if you have installed the [builder][1] library. The preferred way
+> to do this is via Rubygems:
+>
+>     gem install builder
+{.exclamation}
+
+
+## Examples
+
+Here is a short sample of content that is valid Ruby and uses the special `xml` object:
+
+    xml.h1("This a h1 header", :id => 'myid')
+
+    xml.p do |p|
+      p.text! "You can just write "
+      p.b "your"
+      p.text! "paragraphs here and"
+      p.a("link", :href => "http://someurl.com")
+      p.text! "them below. This is also a"
+      p.i "nice"
+      p.text! "format!"
+    end
+
+    xml.blockquote(:class => 'information') do |bq|
+      bq.text! "Citations are easy too."
+      bq.text! "Really. And you can assign them attributes."
+    end
+
+    xml.ul do |ul|
+      ul.li "Lists"
+      ul.li "aren't"
+      ul.li "difficult"
+      ul.li "either."
+    end
+
+
+Following is a complete example which shows how to use this extension in a page file which generates
+a custom XML document (the `content` block has to be valid Ruby!):
+
+    ---
+    output_path_style: [:parent, :cnbase, ['.', :lang], '.xml']
+    title: Person Object
+    template: ~
+    --- pipeline:builder
+    xml.persons(:path => node.absolute_lcn) do |p|
+      p.person do |b|
+        b.firstname('Thomas')
+        b.lastname('Leitner')
+      end
+      p.person do |b|
+        b.firstname('Other first')
+        b.lastname('Other last')
+      end
+    end
+
+The above will produce the following output:
+
+    <persons path="/test.xml">
+      <person>
+        <firstname>Thomas</firstname>
+        <lastname>Leitner</lastname>
+      </person>
+      <person>
+        <firstname>Other first</firstname>
+        <lastname>Other last</lastname>
+      </person>
+    </persons>
+
+
+[1]: http://builder.rubyforge.org "Homepage of builder library"

data/doc/contentprocessor/erb.page

@@ -1,38 +1,56 @@
 ---
 title: Webgen::ContentProcessor::Erb
 ---
+## Description
 
-> TODO: This needs to be redone
-{.exclamation}
+This processer uses ERB (embedded Ruby) to process content. For detailed information about ERB have
+a look at its documentation by executing `ri ERB` or the [ruby documentation
+site](http://www.ruby-doc.org/)! The short name of the processor is `erb`!
+
+You can use the following special objects in your ERB code:
+
+* `context`: This object provides the whole rendering context, the following objects are just for
+  backwards compatibility.
+
+* `ref_node` (or `context.ref_node`): The reference node which is the source of the ERB code that is
+  executed. Should be used, for example, for resolving paths.
+
+* `node` (or `context.content_node`): The node that gets currently rendered. Should be used for
+  retrieving meta information.
+
+* `dest_node` (or `context.dest_node`): The node in which the result gets inserted. Should be used
+  for calculating relative paths.
+
+Here is a small usage example. The following put in a page file
 
-#### Evaluating ERB Tags
-
-TODO: ev move this to the ContentProcessor/Erb documentation???
-
-The evaluation of ERB (embedded ruby) tags is optional and only done if the meta information
-`useERB` is set to `true`. The use of ERB allows to add dynamic content without using webgen tags.
-Following is an example of a file which uses ERB:
-
-<notextile>
-<pre>
-\---
-title: Test page with ERB
-useERB: true
-\---
-This page has the following meta info items:
-&lt;% node.meta_info.each do |key, value| %&gt;
-    * &lt;%=key %&gt;: &lt;%=value %&gt;
-&lt;% end %&gt;
-</pre>
-</notextile>
-
-This would output all meta information for the file. There are some objects available which you can
-use in your ERB code:
-
-* `node`: the node for the current file (normally a page file)
-* `ref_node`: the reference node, i.e. the node in which the content will be embedded (normally a
-  template file)
-
-*Caveat*: you may need to ensure that the ERB start and end tags are not processed by the content
-converter. For example, with Textile you may need to surround the ERB code with &lt;textile&gt;
-tags!
+    Counting 5 items dynamically:
+    <%% for i in 1..5 %>
+      * item <%%= i %>
+    <%% end %>
+
+    Outputting all meta information:
+    <%% node.meta_info.each do |k,v| %>
+      * <%%= k %> = <%%= v %>
+    <%% end %>
+
+... will give the result:
+
+    Counting 5 items dynamically:
+    <% for i in 1..5 %>
+      * item <%= i %>
+    <% end %>
+
+    Outputting all meta information:
+    <% node.meta_info.each do |k,v| %>
+      * <%= k %> = <%= v %>
+    <% end %>
+
+The second line shows the first form of the ERB tags which executes Ruby code but does not output
+anything: it just starts a `for` loop. On the third line the second form of ERB tags is used to
+output the result of the Ruby code (note the equation sign!). And the fourth line completes the
+`for` loop by adding the needed `end` keyword.
+
+> You may need to ensure that the ERB start and end tags are not processed by the content
+> processor. For example, when using the RedCloth content processor, you may need to surround the
+> ERB code with `<textile>` tags!
+{.exclamation}

data/doc/contentprocessor/haml.page

@@ -0,0 +1,47 @@
+---
+title: Webgen::ContentProcessor::Haml
+---
+## Description
+
+This processor converts the content, which is assumed to be in the Haml markup language, to valid
+XHTML by using the Haml library. For detailed information about Haml have a look at the [Haml
+Homepage][1]! The short name of the processor is `haml`!
+
+You can use some special objects provided by webgen in your Haml markup. These are the same objects
+that are available to the `erb` processor, have a look at its [documentation page]({relocatable:
+erb.html}).
+
+> This extension is only available if you have installed the [haml][1] library. The preferred way to
+> do this is via Rubygems:
+>
+>     gem install haml
+{.exclamation}
+
+
+## Example
+
+Here is a short sample of a text in Haml markup:
+
+    %h1#myid This a h1 header
+
+    %p
+      You can just write
+      %b your
+      paragraphs here and
+      %a{:href => 'http://someurl.com'} link
+      them below. This is a
+      %strong nice
+      format!
+
+    %blockquote.information
+      Citations are easy too.
+      Really. And you can assign them attributes.
+
+    %ul
+      %li Lists
+      %li aren't
+      %li difficult
+      %li either.
+
+
+[1]: http://haml.hamptoncatlin.com/

data/doc/contentprocessor/maruku.page

@@ -0,0 +1,41 @@
+---
+title: Webgen::ContentProcessor::Maruku
+---
+## Description
+
+This processor converts the content, which is assumed to be in Markdown markup, to HTML by using the
+Maruku library. Maruku is a Markdown processor which supports a superset of Markdown, including
+support for assigning ids and classes to every element, support for Markdown inside HTML elements
+and footnotes. The short name of the processor is `maruku`!
+
+For detailed information about Maruku have a look at the [Maruku Homepage][1]. There you will find
+information about the general Markdown syntax as well as information about the extras added by
+Maruku.
+
+> Maruku is the default markup content processor for webgen as its markup syntax is easy to learn
+> and nice to look at. Give it a try!
+{.info}
+
+Example
+-------
+
+Here is a short sample of a text in Markdown+Extras markup:
+
+    # This a h1 header    {#myid}
+
+    You can just write *your* paragraphs here and
+    [link][1] them below. This is **nice** format!
+
+    > Citations are easy too.
+    > Really. And you can assign them attributes.
+    {.information}
+
+    * Lists
+    * aren't
+    * difficult
+    * either.
+
+    [1]: http://someurl.com
+
+
+[1]: http://maruku.rubyforge.org/

data/doc/contentprocessor/rdoc.page

@@ -0,0 +1,36 @@
+---
+title: Webgen::ContentProcessor::RDoc
+---
+## Description
+
+This content processors converts content written in RDoc markup (the default documentation format
+for Ruby source files, [reference][1]) to HTML. The short name of the processor is `rdoc`!
+
+> This extension needs the [new RDoc implementation][2] and is not compatible with the
+> implementation included in the Ruby distribution. The preferred way to install the new
+> implementation is via Rubygems:
+>
+>     gem install rdoc
+{.exclamation}
+
+[1]: http://rdoc.rubyforge.org/rdoc/ "RDoc Reference"
+[2]: http://rubyforge.org/projects/rdoc/ "New RDoc implementation"
+
+## Example
+
+Here is a short sample of a text in RDoc markup:
+
+    = This a h1 header
+
+    You can just write *your* paragraphs here and <a href="http://someurl.com">link</a> them below.
+    This is also a _nice_ format!
+
+    <blockquote class='information>
+    Citations are easy too.
+    Really. And you can assign them attributes.
+    </blockquote>
+
+    * Lists
+    * aren't
+    * difficult
+    * either.

data/doc/contentprocessor/redcloth.page

@@ -0,0 +1,40 @@
+---
+title: Webgen::ContentProcessor::RedCloth
+---
+## Description
+
+This processor converts the content, which is assumed to be in Textile markup, to HTML by using the
+RedCloth library. For detailed information about Textile have a look at the [Textile Reference][1]!
+The short name of the processor is `redcloth`!
+
+> This extension is only available if you have installed the [redcloth][2] library. The preferred
+> way to do this is via Rubygems:
+>
+>     gem install RedCloth
+{.exclamation}
+
+
+Example
+-------
+
+Here is a short sample of a text in Textile markup:
+
+    h1(#myid). This a h1 header
+
+    You can just write *your* paragraphs here and
+    "link":http://someurl.com them below. This is also a
+    **nice** format!
+
+    <blockquote class='information>
+    Citations are easy too.
+    Really. And you can assign them attributes.
+    </blockquote>
+
+    * Lists
+    * aren't
+    * difficult
+    * either.
+
+
+[1]: http://hobix.com/textile/
+[2]: http://whytheluckystiff.net/ruby/redcloth/