webgen 0.5.0 → 0.5.1

data/doc/tag/date.page

@@ -0,0 +1,31 @@
+---
+title: Webgen::Tag::Date
+used_options:
+  - tag.date.format
+---
+## Description
+
+The date tag is used to display the current time in a specific format (the format of Ruby's inbuilt
+method [Time#strftime][1]). Have a look a the examples below to see some possible outputs.
+
+[1]: http://www.ruby-doc.org/core/classes/Time.html
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{date:}</td>
+  <td>{date:}</td>
+</tr>
+<tr>
+  <td>\{date: {format: '%A, %Y-%m-%d'}}</td>
+  <td>{date: {format: '%A, %Y-%m-%d'}}</td>
+</tr>
+<tr>
+  <td>\{date: {format: %x - %X}}</td>
+  <td>{date: {format: %x - %X}}</td>
+</tr>
+</table>

data/doc/tag/executecommand.page

@@ -0,0 +1,26 @@
+---
+title: Webgen::Tag::ExecuteCommand
+used_options:
+  - tag.executecommand.command
+  - tag.executecommand.process_output
+  - tag.executecommand.escape_html
+---
+## Description
+
+The execute command tag is used to include the output from a shell command.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{execute_cmd: uname -p}</td>
+  <td><pre>{execute_cmd: uname -p}</pre></td>
+</tr>
+<tr>
+  <td>\{execute_cmd: {command: 'ruby -v'}}</td>
+  <td><pre>{execute_cmd: {command: 'ruby -v'}}</pre></td>
+</tr>
+</table>

data/doc/tag/includefile.page

@@ -0,0 +1,32 @@
+---
+title: Webgen::Tag::IncludeFile
+used_options:
+  - tag.includefile.filename
+  - tag.includefile.process_output
+  - tag.includefile.escape_html
+---
+## Description
+
+The include file tag is used to include the content of a file. The filename needs to be specified
+relative to the website directory or an absolute filename.
+
+> By surrounding the include file tag with a syntax highlighting tag it is possible to highlight the
+> contents of a file.
+{.information}
+
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{include_file: {filename: AUTHORS, process_output: false}}</td>
+  <% if File.exists?(File.join(context.website.directory, 'AUTHORS')) %>
+  <td><pre>{include_file: {filename: AUTHORS, process_output: false}}</pre></td>
+  <% else %>
+  <td><pre>{include_file: {filename: ../AUTHORS, process_output: false}}</pre></td>
+  <% end %>
+</tr>
+</table>

data/doc/tag/langbar.page

@@ -0,0 +1,22 @@
+---
+title: Webgen::Tag::Langbar
+used_options:
+  - tag.langbar.separator
+  - tag.langbar.show_own_lang
+  - tag.langbar.show_single_lang
+---
+## Description
+
+This tag is used to display a list of links to translations of the page.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{langbar:}</td>
+  <td>{langbar:}</td>
+</tr>
+</table>

data/doc/tag/menu.page

@@ -0,0 +1,90 @@
+---
+title: Webgen::Tag::Menu
+used_options:
+  - tag.menu.used_nodes
+  - tag.menu.start_level
+  - tag.menu.min_levels
+  - tag.menu.max_levels
+  - tag.menu.show_current_subtree_only
+---
+## Description
+
+The menu tag builds a seemingly simple menu using HTML lists. However, it is very flexible due to
+its many options that let you decide every detail of the menu.
+
+> The menu is constructed using HTML lists with `ul` and `li` tags.  However, the menu normally
+> looks better if no discs are shown for the menu items (using the CSS directive `list-style-type:
+> none`).
+{.information}
+
+It uses the meta information `in_menu` and `sort_info` to determine which nodes should be in the
+menu and how they should be ordered. A separate menu tree is then created from all nodes for each
+language.
+
+By setting the option `tag.menu.used_nodes` to `fragments`, the menu tag can also be used for
+generating an in-page content menu of all the header sections.
+
+> When using the option value `files` for `tag.menu.used_nodes`, all nodes which are only in the
+> menu because they have fragment nodes beneath them are not included in the menu.
+{.exclamation}
+
+The rendered menu consists of `ul` and `li` tags and the links to the menu entries as well as a
+surrounding `div` tag. The `li` tags have special CSS classes set for styling. These CSS class names
+are as follows:
+
+* `webgen-menu-submenu`: Set if the menu item contains sub menu items.
+* `webgen-menu-submenu-inhierarchy`: Set if the menu item contains sub menu items and it is in the
+  sub tree of the rendered node.
+* `webgen-menu-item-selected`: Set if the menu item corresponds to the rendered node.
+
+
+## "Static" Menus
+
+It is also possible to define a "static" menu or to augment the dynamic menu with static entries by
+using virtual files. They can be used to structure the menu the way you like it. This way it is also
+possible to add one page under two different headings:
+
+    features.en.html:
+      in_menu: true
+      title: Features
+      url: index.en.html#features
+
+    newdir:
+      sort_info: 2
+
+    newdir/new.en.html:
+      sort_info: 1
+      in_menu: true
+      url: ../features.en.html
+
+There is no need to specify `in_menu` for `newdir` since a page under the directory is in the
+menu. Also be aware that you need to set the language explicitly if a file should only appear in the
+menu for a specific language. Otherwise it appears in every menu. The `url` specifies the file that
+should be shown when clicked on the generated link.
+
+A completely "static" menu can be generated by only using virtual directories and files and not
+setting `in_menu` for any other node.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{menu: }</td>
+  <td>{menu:}</td>
+</tr>
+<tr>
+  <td>\{menu: {used_nodes: all}}</td>
+  <td>{menu: {used_nodes: all}}</td>
+</tr>
+<tr>
+  <td>\{menu: {used_nodes: files}}</td>
+  <td>{menu: {used_nodes: files}}</td>
+</tr>
+<tr>
+  <td>\{menu: {used_nodes: fragments}}</td>
+  <td>{menu: {used_nodes: fragments}}</td>
+</tr>
+</table>

data/doc/tag/metainfo.page

@@ -0,0 +1,29 @@
+---
+title: Webgen::Tag::Metainfo
+---
+## Description
+
+The meta tag is used to copy meta information verbatim. It is used as fallback when no other tag
+class for a specific tag name could not be found. For example, if you define a meta information with
+the key `revision`, you can put the tag `\{revision:}` into a block of a page file and the value
+gets substituted automatically.
+
+An every day usage example for the meta tag would be including the title of a page in the
+`head`-section of a HTML template or specifying the language of the HTML file by using the
+`\{lang:}` tag.
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{title: }</td>
+  <td>{title:}</td>
+</tr>
+<tr>
+  <td>\{lang: }</td>
+  <td>{lang:}</td>
+</tr>
+</table>

data/doc/tag/relocatable.page

@@ -0,0 +1,38 @@
+---
+title: Webgen::Tag::Relocatable
+used_options:
+  - tag.relocatable.path
+---
+## Description
+
+This tag ensures that the relative path to the specified path is always correct. 
+
+When the tag is used, it changes the directory part of the supplied path name to a relative path to
+the destination and is most often used in template files. A relocatable tag looks like this:
+`\{relocatable: default.css}`. If this was put into a template and the template was used by a file
+in a subdirectory, then the `relocatable` tag would put `../default.css` into the output file; thus
+ensuring that the relative path to file is valid.
+
+> You can only use the `relocatable` tag with paths that are handled by webgen. If you want to
+> handle paths that are not normally handled by webgen, create a virtual path for them.
+{.exclamation}
+
+If the specified path is an absolute URL (like `http://webgen.rubyforge.org`), it will just return
+it. And if you specify an URL fragment, this fragment has to exist. If you don't want to resolve a
+fragment, just don't specify it in the tag but afterwards!
+
+## Examples
+
+<table class="examples">
+<tr>
+  <th>Usage</th><th>Output</th>
+</tr>
+<tr>
+  <td>\{relocatable: /default.css}</td>
+  <td>{relocatable: /default.css}</td>
+</tr>
+<tr>
+  <td>\{relocatable: ../}</td>
+  <td>{relocatable: ../}</td>
+</tr>
+</table>

data/doc/webgen_page_format.page

@@ -72,8 +72,8 @@ be set.
 The name uniquely identifies a content block and is used to access it. The only option used by
 webgen is the `pipeline` option which specifies the processing pipeline for the block. The
 processing pipeline is used for rendering the block by using the specified content processors in the
-specified order. There are several different content processors available - have a look at the
-[content processor listing]({relocatable: contentprocessor/}) for an overview.
+specified order. There are many different content processors available - have a look at the
+[extensions page]({relocatable: extensions.html}) for an overview.
 
 There are also defaults for the name and the options of a block but they can be overwritten. You can
 use one of two ways to do this:

data/lib/webgen/cli/utils.rb

@@ -10,7 +10,7 @@ module Webgen::CLI
   class Utils
 
     USE_ANSI_COLORS = !Config::CONFIG['arch'].include?('mswin32')
-    DEFAULT_WIDTH = %x{stty size}.split.collect {|n| n.to_i }.last rescue 72
+    DEFAULT_WIDTH = ((size = %x{stty size 2>/dev/null}).length > 0 ? x.split.last.to_i : 72) rescue 72
 
     # Used for dynamically formatting the text (setting color, bold face, ...).
     def self.method_missing(id, text = nil)

data/lib/webgen/contentprocessor.rb

@@ -58,6 +58,11 @@ module Webgen
     autoload :Blocks, 'webgen/contentprocessor/blocks'
     autoload :Maruku, 'webgen/contentprocessor/maruku'
     autoload :RedCloth, 'webgen/contentprocessor/redcloth'
+    autoload :Erb, 'webgen/contentprocessor/erb'
+    autoload :Haml, 'webgen/contentprocessor/haml'
+    autoload :Sass, 'webgen/contentprocessor/sass'
+    autoload :RDoc, 'webgen/contentprocessor/rdoc'
+    autoload :Builder, 'webgen/contentprocessor/builder'
 
     # Return the list of all available content processors.
     def self.list

data/lib/webgen/contentprocessor/builder.rb

@@ -0,0 +1,26 @@
+module Webgen::ContentProcessor
+
+  # Processes content that is valid Ruby to build an XML tree. This is done by using the +builder+
+  # library.
+  class Builder
+
+    # Process the content of +context+ which needs to be valid Ruby code. The special variable +xml+
+    # should be used to construct the XML content.
+    def call(context)
+      require 'builder'
+
+      node = context.content_node
+      ref_node = context.ref_node
+      dest_node = context.dest_node
+
+      xml = ::Builder::XmlMarkup.new(:indent => 2)
+      eval(context.content, binding, context.ref_node.absolute_lcn)
+      context.content = xml.target!
+      context
+    rescue Exception => e
+      raise RuntimeError, "Error using Builder to generate XML: #{e.message}", e.backtrace
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/context.rb

@@ -1,4 +1,5 @@
 require 'webgen/contentprocessor'
+require 'webgen/websiteaccess'
 
 module Webgen::ContentProcessor
 
@@ -13,6 +14,9 @@ module Webgen::ContentProcessor
   #                   special nodes of the chain (see #ref_node, #content_node).
   class Context
 
+    include Webgen::WebsiteAccess
+    public :website
+
     # Processing options
     attr_accessor :options
 

data/lib/webgen/contentprocessor/erb.rb

@@ -0,0 +1,24 @@
+module Webgen::ContentProcessor
+
+  # Processes embedded Ruby statements.
+  class Erb
+
+    # Process the Ruby statements embedded in the content of +context+.
+    def call(context)
+      require 'erb'
+
+      node = context.content_node
+      ref_node = context.ref_node
+      dest_node = context.dest_node
+
+      erb = ERB.new(context.content)
+      erb.filename = context.ref_node.absolute_lcn
+      context.content = erb.result(binding)
+      context
+    rescue Exception => e
+      raise RuntimeError, "Erb processing failed: #{e.message}", e.backtrace
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/haml.rb

@@ -0,0 +1,25 @@
+module Webgen::ContentProcessor
+
+  # Processes content in Haml markup using the +haml+ library.
+  class Haml
+
+    # Convert the content in +haml+ markup to HTML.
+    def call(context)
+      require 'haml'
+
+      locals = {
+        :context => context,
+        :node => context.content_node,
+        :ref_node => context.ref_node,
+        :dest_node => context.dest_node,
+      }
+      context.content = ::Haml::Engine.new(context.content, :filename => context.ref_node.absolute_lcn).
+        render(Object.new, locals)
+      context
+    rescue Exception => e
+      raise RuntimeError, "Error converting Haml markup to HTML: #{e.message}", e.backtrace
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/maruku.rb

@@ -10,7 +10,7 @@ module Webgen::ContentProcessor
       context.content = ::Maruku.new(context.content, :on_error => :raise).to_html
       context
     rescue Exception => e
-      raise "Maruku to HTML conversion failed: #{e.message}"
+      raise RuntimeError, "Maruku to HTML conversion failed: #{e.message}", e.backtrace
     end
 
   end

data/lib/webgen/contentprocessor/rdoc.rb

@@ -0,0 +1,17 @@
+module Webgen::ContentProcessor
+
+  # Converts content in RDoc markup (the native Ruby documentation format) to HTML. Needs the newer
+  # RDoc implementation provided as +rdoc+ gem!
+  class RDoc
+
+    # Convert the content in RDoc markup to HTML.
+    def call(context)
+      require 'rdoc/markup/to_html'
+
+      context.content = ::RDoc::Markup::ToHtml.new.convert(context.content)
+      context
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/sass.rb

@@ -0,0 +1,18 @@
+module Webgen::ContentProcessor
+
+  # Processes content in Sass markup (used for writing CSS files) using the +haml+ library.
+  class Sass
+
+    # Convert the content in +sass+ markup to CSS.
+    def call(context)
+      require 'sass'
+
+      context.content = ::Sass::Engine.new(context.content, :filename => context.ref_node.absolute_lcn).render
+      context
+    rescue Exception => e
+      raise RuntimeError, "Error converting Sass markup to CSS: #{e.message}", e.backtrace
+    end
+
+  end
+
+end