[Rake-devel] Plea for documentation, resource aggregation, and help with rules

Gavin Sinclair gsinclair at soyabean.com.au
Wed Oct 6 10:33:53 EDT 2004

Hi Jim,

Just petitioning for a collection of all Rake resources in one place.
I visit rake.rubyforge.org to examine the documentation so often it's
ridiculous.  But there are other resources as well: the example on the
Wiki, and the slides from RubyConf2003 (which, believe it or not, I've
just hunted down and found helpful).  It would be nice to see all the
resources gathered in one place.

How about:

    index.html   -- link to wiki, api doc, and presentation
    doc/index.html -- some new documentation :)

Anyway, I've been struggling to get a rule working, and have given up.
I'm converting Textile into HTML.  Here's what I've boiled my Rakefile
down to:

  # Building the web pages (source: etc/doc/*.textile; target: build/www/*.html)
  # I should be able to name the targets, generated from the sources, and have a rule that
  # generates HTML from Textile.  This rule should take account of timestamps, and keep in mind
  # that a change in the CSS or generate.rb requires regeneration throughout.

  directory 'build/www'
  directory 'build/www/api'

  desc "Build the Textile documentation"
  task :textile => ['build/www', 'etc/doc/textile.css', 'etc/doc/generate.rb']

  Dir['etc/doc/*.textile'].each do |source|
    target = source.sub('etc/doc', 'build/www').sub('.textile', '.html')
      # Set the file task, so Rake knows about it.
    file target => source do
      require 'etc/doc/generate'
      generate_document source, 'build/www'
      # Collect the targets, so the 'textile' task can aggregate them all.
    task :textile => target

There are 4 textile source files.  That means I'm creating four
explicit file tasks.  It's all working, and I'm thrilled that it saves
time by only regenerating when necessary.  But I did want to create a
rule instead of duplicating explicit tasks.

Jim, can you look at the Rakefile snippet above and try to factor out
a rule which I can try?  I can provide more information as needed.

Rules are the hardest things for me to understand in Rake.  But it's
part of a general problem: I'd really like to see a manual that spells
out what Rake can and can't do, and how to get it to do that.  The API
documentation is quite good, but I too often have to resort to trial
and error, and source code browsing, to get the result I'm after.


More information about the Rake-devel mailing list