webby 0.8.4 → 0.9.0

data/examples/webby/content/{manual → user-manual}/index.txt

@@ -1,6 +1,6 @@
 --- 
-title:      Manual
-created_at: Wed Aug 29 08:57:00 -0600 2007
+title:      User Manual
+created_at: 2007-08-29 08:57:00.000000 -06:00
 filter:
   - erb
   - textile
@@ -10,12 +10,14 @@ filter:
 
 p(title). Table of Contents
 
-<toc />
+<toc toc_range="h2-h6" />
 </div>
 
+h1. <%= h(@page.title) %>
+
 h2. Introduction
 
-Webby was created out of the need for a simple way to build and manage small websites. The desire was for a system that could take files written in plain text, combine them with a layout file and produce web pages. In this system, a single page can be written quickly without the need for HTML markup; the look and feel of the entire site can be changed by modifying the site layout file.
+Webby was created out of the desire for a simple way to build and manage small websites. The goal was a system that could take files written in plain text, combine them with a layout file and produce web pages. In this system, a single page can be written quickly without the need for HTML markup; the look and feel of the entire site can be changed by modifying the site layout file.
 
 <% graphviz :path => "images", :alt => "Webby Overview" do %>
 digraph overview {
@@ -50,67 +52,68 @@ Webby is written in the Ruby programming language. To install and run Webby you
 
 h3. Installation
 
-Webby is easily installed as a Ruby gem. From a command prompt type in the following:
+Webby is easily installed as a Ruby gem. From a command prompt type the following:
 
-<pre>
-sudo gem install -y webby
-</pre>
+pre. sudo gem install webby
 
 This will install Webby and all its required dependencies.
 
-bq. For those users installing Webby on the Windows platform, please omit the @sudo@ portion of the above command. You will also need to specify the *mswin32* versions of the _mongrel_ and _hpricot_ gems when prompted.
-
 To make use of all the features Webby has to offer, the following gems should also be installed. These gems provide different ways to transform text into HTML or CSS.
 
-<pre>
-sudo gem install -y RedCloth
-sudo gem install -y BlueCloth
-sudo gem install -y haml
-sudo gem install -y coderay
-sudo gem install -y ultraviolet
-</pre>
+* RedCloth
+* rdiscount
+* haml
+* coderay
+* ultraviolet
 
-Webby can also use a few other programs to clean up generated HTML and to created pretty graphs and pictures. Where external programs are required, they will be duly noted in the manual.
+Webby can also use a few other programs to clean up generated HTML and to create pretty graphs and pictures. Where external programs are required, they will be duly noted in the manual.
 
 h3. Running Webby
 
-When the Webby gem is installed it also installs a @webby@ executable program. This program is used to create a new website and to update the associated rake tasks when a new version of Webby is released. Typing in @webby --help@ will show you the options this program supports. After you create a website, though, the webby command will not be needed. 
+When Webby is installed, two command line programs are installed alongside the gem: @webby@ and @webby-gen@. The latter program is used to create a new Webby site folder and files. The former program is used within the site folder to generate the final site output from the content and layouts. Type @webby --help@ on the command line to see the options this program supports.
 
 <pre>
-$ webby --help
+webby --help
 
-Usage: webby [options] site
+Usage: webby [options] task [task args]
 
-    -u, --update                     update the rake tasks for the site
+    -D, --describe [PATTERN]         describe the tasks (matching optional PATTERN), then exit
+    -P, --prereqs                    display the tasks and dependencies, then exit
+    -T, --tasks [PATTERN]            display the tasks (matching optional PATTERN) with descriptions, then exit
+    -t, --trace                      turn on invoke/execute tracing, enable full backtrace
 
 common options:
     -h, --help                       show this message
         --version                    show version
 </pre>
 
+The @webby@ program is actually a smart wrapper around "Rake":http://docs.rubyrake.org/. It is used to run the tasks that will create new pages, build the output products, and deploy the site to a server. The list of available tasks can be seen by typing the following command in a Webby site folder:
+
+pre. webby -T
 
-The day to day tasks of working with a webiste - creating pages, building the website, deploying changes to the server - are handled by the "Rake":http://docs.rubyrake.org/ application, a Ruby version of the more famous *make* program. Several rake tasks are provided by default. You are free to create others to make developing and deploying your website easier. To see the current list of rake tasks type in @rake -T@.
+The second program, @webby-gen@, is used less often but it is no less important. This is the *generate* command, and it is used to create a new Webby site folder and files. Type @webby-gen --help@ on the command line to see how the program is used.
 
 <pre>
-$ rake -T
-
-rake autobuild          # Continuously build the website
-rake build              # Build the website
-rake clobber            # Delete the website
-rake create:page        # Create a new page
-rake create:partial     # Create a new partial
-rake deploy             # deploy the website to Rubyforge
-rake deploy:rsync       # Deploy to the server using rsync
-rake deploy:ssh         # Deploy to the server using ssh
-rake growl              # Send log events to Growl (Mac OS X only)
-rake heel:start         # Start the heel server to view website (not for Windows)
-rake heel:stop          # Stop the heel server
-rake rebuild            # Rebuild the website
-rake validate           # Alias to validate:internal
-rake validate:external  # Validate hyperlinks (include external sites)
-rake validate:internal  # Validate hyperlinks (exclude exteranl sites)
+webby-gen --help
+
+Usage: webby-gen [options] template site
+
+    -f, --force                      overwrite files that already exist
+    -s, --skip                       skip files that already exist
+    -u, --update                     update rake tasks for the site
+    -p, --pretend                    run but do not make any changes
+
+    -t, --templates                  list available templates
+
+common options:
+    -h, --help                       show this message
+        --version                    show version
 </pre>
 
+The Webby generate command will create a new site folder (or update an existing site folder) using files from the desired template type. Each template is a collection of files that can be used as the starting point for a Webby project. You can see the list of available templates:
+
+pre. webby-gen --templates
+
 h2. Working With Resources
 
 A resource is any file that is found in the _content_ or _layouts_ folders. Resources are either copied to the output folder or they are processed through the Webby filter engine to generate an output file. Resources fall into one of three types:
@@ -144,7 +147,7 @@ vestibulum libero. Aenean vitae justo. Nam eget tellus. Etiam convallis, est eu
 lobortis mattis, lectus tellus tempus felis, a ultricies erat ipsum at metus.
 </pre>
 
-The page meta-data is contained in the first section  --  it is located between the two @---@ lines. The page meta-data will not be present in the generated HTML file. Only the page content (the text below the second @---@ line) will be rendered into the final HTML file. The meta-data defines a collection of attributes that (1) are made available to the various Webby filters and (2) provide instructions to the Webby filter engine itself.
+The page meta-data is contained in the first section. It is located between the two @---@ lines. The page meta-data will not be present in the generated HTML file. Only the page content (the text below the second @---@ line) will be rendered into the final HTML file. The meta-data defines a collection of attributes that (1) are made available to the various Webby filters and (2) provide instructions to the Webby filter engine itself.
 
 Three attributes are defined in the above example: @title@, @created_at@, and @filter@. The first attribute, @title@, is associated with the value "Lorem Ipsum". This attribute is used in the first line of the page content to render the title using a combination of the ERB and Textile filters (more can be read in the "Filters":#filters section of this manual). The example page above will result in the following snippet of HTML code.
 
@@ -156,7 +159,7 @@ vestibulum libero. Aenean vitae justo. Nam eget tellus. Etiam convallis, est eu
 lobortis mattis, lectus tellus tempus felis, a ultricies erat ipsum at metus.</p>
 </pre>
 
-You can see that the value of the @title@ attribute was substituted for the ERB snippet <code><%= @page.title %></code>. All page attributes can be accessed using the <code>@page.attribute</code> syntax within an ERB block. This will be discussed in greater detail in the "ERB Filter":#erbfilter section.
+You can see that the value of the @title@ attribute was substituted for the ERB snippet @<%%= @page.title %>@. All page attributes can be accessed using the @@page.attribute@ syntax within an ERB block. This will be discussed in greater detail in the "ERB Filter":#erbfilter section.
 
 The last attribute in the meta-data section is the @filter@ attribute. The value for this attribute is a list of filters that will be applied to the page contents. The filters will be applied in the order they are specified. For the example page this would be the ERB filter followed by the Textile filter.
 
@@ -238,11 +241,11 @@ h3(#erbfilter). ERB
 
 "ERB":http://ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html provides an easy to use but powerful templating system for Ruby. Using ERB, Ruby code can be added to any plain text document for the purposes of generating document information details and/or flow control. Much of the functionality Webby has to offer is made available through the erb filter. ERB does not place any limitations on the content of the page, so it is recommended to use the erb filter with another filter that simplifies the HTML markup  --  Textile is my favorite, but Markdown and HAML support are provided in Webby, as well. Chose the markup language that suits your style.
 
-Some examples of ERB have already been seen in the "pages":#pages section of this document. Ruby code is placed between ERB delimiters, <code><notextile>&lt;%= ruby code %&gt;</notextile></code> somewhere in the content section of your page or layout. The erb filter executes that code and inserts the results into the page. Webby provides quite a few features that are accessed via ERB. Page attributes are one feature, and "helper methods":#helpermethods are another that are discussed elsewhere in this manual.
+Some examples of ERB have already been seen in the "pages":#pages section of this document. Ruby code is placed between ERB delimiters, @<%%= ruby code %>@ somewhere in the content section of your page or layout. The erb filter executes that code and inserts the results into the page. Webby provides quite a few features that are accessed via ERB. Page attributes are one feature, and "helper methods":#helpermethods are another that are discussed elsewhere in this manual.
 
-<pre><notextile>
-The title of this page is "&lt;%= @page.title" %&gt;".
-</notextile></pre>
+<pre>
+The title of this page is "<%%= @page.title" %>".
+</pre>
 
 <pre>
 The title of this page is "<%= @page.title %>".
@@ -269,7 +272,7 @@ h3. Textile
 
 A complete textile reference is beyond the scope of this document. Please refer to the "Textile reference":http://hobix.com/textile/ compiled by _why the luck stiff_ <sup><a href="#fn1">1</a></sup>.
 
-The textile filter will operate on all the contents of a page or layout. Given that fact, it should be one of the last filters applied to the page. You can prevent a section of the page from being processed by the textile filter by surrounding it with <code><notextile>&lt;notextile&gt;...&lt;/notextile&gt;</notextile></code> tags.
+The textile filter will operate on all the contents of a page or layout. Given that fact, it should be one of the last filters applied to the page. You can prevent a section of the page from being processed by the textile filter by surrounding it with @<notextile>...</notextile>@ tags.
 
 <div class="label">Usage</div>
 <div class="desc">
@@ -308,7 +311,7 @@ none
 
 <div class="label">Require</div>
 <div class="desc">
-The *BlueCloth* gem must be installed on your system in order to use the markdown filter.
+The *rdiscount* gem must be installed on your system in order to use the markdown filter.
 </div>
 
 h3. HAML & SASS
@@ -335,7 +338,7 @@ p(last). Options are passed to the sass filter by setting the "sass_options" in
 
 <div class="label">Require</div>
 <div class="desc">
-The @haml@ gem must be installed on your system in order to use the haml filter or the sass filter.
+The *haml* gem must be installed on your system in order to use the haml filter or the sass filter.
 </div>
 
 h3. Outline
@@ -364,7 +367,7 @@ The basepath filter only works on HTML/XHTML text, and therefore, it should be o
 Include "basepath" in the filter list of your layout(s). Specify the new base path to use either as a command line argument or as an option configured in the _Rakefile_. The base path specified on the command line takes precedence over the base path specified in the Rakefile.
 
 <pre style="margin-bottom:0">
-$ rake rebuild BASE='http://your.website.com/path/to/your/site'
+$ webby rebuild BASE='http://your.website.com/path/to/your/site'
 </pre>
 </div>
 

data/examples/webby/layouts/{default.rhtml → default.txt}

@@ -3,7 +3,6 @@ extension: html
 filter:
   - erb
   - basepath
-  - tidy
 ---
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
@@ -26,26 +25,20 @@ filter:
 
 <div class="container">
 
-   <div class="column span-20 prepend-1 append-3 first last" id="header">
-      <h1>Webby &#9775; <%= h(@page.title) %></h1>
-   </div>
-
-   <div class="column span-4 prepend-1 first" id="navigation">
+   <div class="column span-17 prepend-4 append-3 first last" id="header">
       <ul
-        ><li><%= link_to_page_unless_current 'Home' %></li
-        ><li><%= link_to_page_unless_current 'Tutorial' %></li
-        ><li><%= link_to_page_unless_current 'Manual' %></li
-        ><li><%= link_to_page_unless_current 'Reference' %></li
-        ><li><%= link_to_page_unless_current 'Tips & Tricks' %></li
-        ><li><a href="http://groups.google.com/group/webby-forum">Forum</a></li
-        ></ul>
+         ><li><%= link_to_page('Learn') %></li
+         ><li><%= link_to_page('Communicate') %></a></li
+      ></ul>
+      <h1><a href="/">Webby</a></h1>
+      <p>- ascii alchemy</p>
    </div>
 
-   <div class="column span-16 append-3 last">
+   <div class="column span-17 prepend-4 append-3 last">
       <%= @content %>
    </div>
 
-   <div class="column span-20 prepend-1 append-3 first last" id="footer">
+   <div class="column span-21 prepend-2 append-1 first last" id="footer">
      <hr />
      <p>This website was created with <a href="http://webby.rubyforge.org">Webby</a><br />
      Webby is released under the MIT license</p>

data/examples/webby/templates/page.erb

@@ -5,6 +5,6 @@ filter:
   - erb
   - textile
 ---
-p(title). <%%= h(@page.title) %>
+h1. <%%= h(@page.title) %>
 
 You can read more about textile "here":http://whytheluckystiff.net/ruby/redcloth/

data/examples/website/Sitefile

@@ -0,0 +1,7 @@
+
+task :default => :build
+
+desc 'deploy the site to the webserver'
+task :deploy => [:build, 'deploy:rsync']
+
+# EOF

data/{data → examples/website}/content/index.txt

@@ -1,5 +1,6 @@
 ---
-title:  Home Page
+title:       Home Page
+created_at:  2008-08-02 14:06:40.000000 -06:00
 filter:
   - erb
   - textile

data/{data/layouts/default.rhtml → examples/website/layouts/default.txt}

@@ -3,7 +3,7 @@ extension: html
 filter:    erb
 ---
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-    "DTD/xhtml1-strict.dtd">
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en-us">
 <head>

data/lib/webby/apps/generator.rb

@@ -0,0 +1,283 @@
+require 'fileutils'
+require 'optparse'
+
+module Webby::Apps
+
+# webby gen template site  => creates the tmplate
+# webby gen -h / --help
+# webby gen       => same as --help
+#
+
+class Generator
+
+  # Create a new Generator instance and run the +webby+ application given the
+  # command line _args_.
+  #
+  def self.run( args )
+    self.new.run args
+  end
+
+  attr_accessor :template, :site
+  attr_reader :options
+
+  # Initialize a new generator object.
+  #
+  def initialize
+    @options = {}
+    @site = @template = nil
+    @stdout, @stdin = $stdout, $stdin
+  end
+
+  # Run the generator executing the commands specified by the user on the
+  # command line.
+  #
+  def run( args )
+    parse args
+    create_site
+  end
+
+  # Parse out the command line options found in the args array.
+  #
+  def parse( args )
+    opts = OptionParser.new
+    opts.banner = 'Usage: webby-gen [options] template site'
+
+    opts.separator ''
+    opts.separator 'The webby-gen command is used to generate a site from a standard template.'
+    opts.separator 'A new site can be created, or an existing site can be added to or updated.'
+
+    opts.separator ''
+    opts.on('-f', '--force',
+            'overwrite files that already exist') {options[:collision] = :force}
+    opts.on('-s', '--skip',
+            'skip files that already exist') {options[:collision] = :skip}
+    opts.on('-u', '--update',
+            'update rake tasks for the site') {options[:update] = true}
+    opts.on('-p', '--pretend',
+            'run but do not make any changes') {options[:pretend] = true}
+
+    opts.separator ''
+    opts.on('-t', '--templates', 'list available templates') {
+      ary = templates.map {|t| ::File.basename(t)}
+      ary.delete 'webby'
+      @stdout.puts "\nAvailable Templates"
+      @stdout.puts "    #{ary.join(', ')}"
+      @stdout.puts
+      exit
+    }
+
+    opts.separator ''
+    opts.separator 'common options:'
+
+    opts.on( '-h', '--help', 'show this message' ) {@stdout.puts opts; exit}
+    opts.on( '--version', 'show version' ) do
+      @stdout.puts "Webby #{::Webby::VERSION}"
+      exit
+    end
+
+    # parse the command line arguments
+    opts.parse! args
+    tmpl, @site = args
+
+    # if no site was given, see if there is a Sitefile in the current
+    # directory
+    if site.nil?
+      self.site = '.' if test(?f, 'Sitefile')
+    end
+
+    # exit if comand line args are missing
+    if site.nil? or tmpl.nil?
+      @stdout.puts opts
+      exit 1
+    end
+
+    templates.each {|t| self.template = t if t =~ %r/\/#{tmpl}$/}
+    if template.nil?
+      @stdout.puts opts
+      abort "Could not find template '#{tmpl}'"
+    end
+
+    nil
+  end
+
+  # Returns +true+ if we are only going to pretend to do something. All the
+  # output messages will be written, but no changes will be made on the
+  # disc.
+  #
+  def pretend?
+    options[:pretend] == true
+  end
+
+  # Returns an array of available site templates.
+  #
+  def templates
+    Dir.glob(::Webby.path('examples') / '*').sort
+  end
+
+  # Create the site from the template specified by the user.
+  #
+  def create_site
+    files = site_files
+
+    # in update mode we only want to update the tasks directory
+    if options[:update]
+      FileUtils.mkdir_p site unless pretend?
+      mkdir 'tasks'
+      files['tasks'].sort.each {|file| cp file}
+    else
+      dirs = files.keys.concat %w[content layouts lib tasks templates]
+      dirs.sort!
+      dirs.uniq!
+
+      # create the directories first
+      dirs.each do |dir|
+        next if dir =~ %r/^output\/.*$/
+        mkdir dir
+      end
+
+      # and the create the files under each directory
+      dirs.each do |dir|
+        next if dir =~ %r/^output(\/.*)?$/
+        files[dir].sort.each {|file| cp file}
+      end
+    end
+  end
+
+  # Make a directory in the user specified site location. A message will be
+  # displayed to the screen indicating tha the directory is being created.
+  #
+  def mkdir( dir )
+    dir = dir.empty? ? site : site / dir
+    if test ?d, dir
+      exists dir
+    else
+      create dir
+      FileUtils.mkdir_p dir unless pretend?
+    end
+  end
+
+  # Copy a file from the template location to the user specified site
+  # location. A message will be displayed to the screen indicating tha the
+  # file is being created.
+  #
+  def cp( file )
+    src = template / file
+    dst = site / file
+
+    if test(?e, dst) 
+      if identical?(src, dst)
+        identical(dst)
+        return
+      end
+
+      choice = case options[:collision]
+        when :force then :force
+        when :skip  then :skip
+        else force_file_collision?( dst ) end
+
+      case choice
+        when :force then force(dst)
+        when :skip  then skip(dst); return
+        else raise "Invalid collision choice: #{choice.inspect}" end
+    else
+      create(dst)
+    end
+    return if pretend?
+
+    if WINDOWS then win_line_endings(src, dst)
+    else FileUtils.cp(src, dst) end
+  end
+
+  # Copy the file from the _src_ location to the _dst_ location and
+  # transform the line endings to the windows "\r\n" format.
+  #
+  def win_line_endings( src, dst )
+    case ::File.extname(src)
+    when *%w[.png .gif .jpg .jpeg]
+      FileUtils.cp src, dst
+    else
+      ::File.open(dst,'w') do |fd|
+        ::File.foreach(src, "\n") do |line|
+          line.tr!("\r\n",'')
+          fd.puts line
+        end
+      end
+    end
+  end
+
+  %w[exists create force skip identical].each do |m|
+    class_eval "def #{m}( msg ) message('#{m}', msg); end"
+  end
+
+  # Print the given message and message type to stdout.
+  #
+  def message( type, msg )
+    msg = msg.sub(%r/#{site}\/?/, '')
+    return if msg.empty?
+    @stdout.puts "%13s  %s" % [type, msg]
+  end
+
+  # Prints an abort message to the screen and then exits the Ruby
+  # interpreter. A non-zero return code is used to indicate an error.
+  #
+  def abort( msg )
+    @stdout.puts "\nAborting!"
+    @stdout.puts "    #{msg}"
+    @stdout.puts
+    exit 1
+  end
+
+  # Iterates over all the files in the template directory and stores them in
+  # a hash.
+  #
+  def site_files
+    exclude = %r/tmp$|bak$|~$|CVS|\.svn/o
+
+    rgxp = %r/\A#{template}\/?/o
+    paths = Hash.new {|h,k| h[k] = []}
+
+    Find.find(template) do |p|
+      next if exclude =~ p
+
+      if test(?d, p)
+        paths[p.sub(rgxp, '')]
+        next
+      end
+      dir = ::File.dirname(p).sub(rgxp, '')
+      paths[dir] << p.sub(rgxp, '')
+    end
+
+    paths
+  end
+
+  # Returns +true+ if the source file is identical to the destination file.
+  # Returns +false+ if this is not the case.
+  #
+  def identical?( src, dst )
+    # FIXME: this most likely won't work on windows machines
+    #        because the line endings are modified when the site is gnerated
+    source      = IO.read(src)
+    destination = IO.read(dst)
+    source == destination
+  end
+
+  # Ask the user what to do about the file collision.
+  #
+  def force_file_collision?( dst )
+    dst = dst.sub(%r/#{site}\/?/, '')
+    @stdout.print "overwrite #{dst}? [(Y)es (n)o (q)uit] "
+    @stdout.flush
+    case @stdin.gets
+      when %r/q/i  then abort 'user asked to quit'
+      when %r/n/i  then :skip
+      when %r/y/i  then :force
+      when %r/\s*/ then :force
+      else force_file_collision?(dst) end
+  rescue
+    retry
+  end
+
+end  # class Generator
+end  # module Webby::Apps
+
+# EOF