ratch 0.3.0 → 0.4.0

data/doc/siteparts/tutorial.red

@@ -1,578 +0,0 @@
-p(rev){float: right}. rev. 9
-
-h1(top). Ratch Tutorial
-
-p(copy). Copyright © 2006 7rans. All Rights Reserved.
-
-p(important). IMPORTANT
-Ratch is still in it's infancy as a project. While mostly functional
-in its present state, it is still under going a good bit of design
-considerations, so methods and certain aspects of functionality may
-change. Likewise, documentation is not 100% current.
-
-
-
-h1. Introduction
-
-Ratch is a Ruby-based batch file system specially designed for handling
-project support and build tasks.
-
-The creation of support and build tools for a project enatils the
-question of whether to simply use shell scripts or rely on a specialized
-build system. The later is almost always the prefered choice. Why?
-Two reasons in particular stand out. First, and perhaps most importantly,
-shell scripts are generally not cross-platform. A shell script on a Linux
-machine may well fail on a Mac X system, and will certainly fail on a Windows
-system. Second, shell scripting lacks dedicated support for the creation of
-build tasks. This is the reason we have tools like Make --a build tool built
-on top of the Unix shell commands.
-
-Ratch solves these two issues by providing a cross-platform shell scripting
-DSL based on Ruby. Ratch scripts are really just Ruby scripts. What sets them
-apart from plain Ruby is the convenient Domain Specific Language (DSL) that
-Ratch provides geared specifically toward the needs of project task and
-build task scripting. With Ratch, scripting becomes a viable option again.
-
-Individual task scripts have some clear advantages over monolithic build systems:
-
-* Tasks are clearly enumerable and can be viewed like any other file-system folder.
-* And like any system script, permissions can be restricted --per individual task.
-* Individual tasks can be easily edited w/o sorting through large "Makefiles".
-* Shell-based tools and scripts written in other languages easily coexist.
-
-The only signifficant disadvantage to the script appraoch is the focus on _tasks_
-rather than _builds_. In other words one can't ask that a particular file be built
-unless some task provides an interface for doing so.
-
-But Ratch provides some
-
-
-h2. Getting Started
-
-If you haven't already done so, you'll first need to install Ratch.
-The process is straight-forward with RubyGems.
-
-      $ gem install ratch
-
-Alternatively you can install from source. Simply, download the package file,
-decompress it, 'cd' into the package directory and run @task/setup@.
-
-      $ tar -xvzf ratch-1.0.0.gzip
-      $ cd ratch-1.0.0
-      $ sudo task/setup
-
-Once installed, you can immediately start using Ratch. However, to make life even
-easier, two other tools augment Ratch very nicely. So we recommend that you also
-install "Box":http://reap.rubyforge.org/box and "Mint":http://reap.rubyforge.org/mint.
-Box is meta-packaging system and Mint is managed copy tool. They are optional,
-but parts of this tutorial will also cover their use in relation to Ratch.
-
-
-!{float: right; width: 150px;}images/toolbox.jpg!
-
-h1. Task Creation
-
-
-h2. Creating Your First Task
-
-Let jump right in by creating a Ratch script so you can see just how easy it is.
-First create a faux project dirctory in which to conduct our tutorial. We'll call it
-@myproject/@.
-
-    $ mkdir myproject
-
-Now @cd@ into it and create a directory to store your ratch scripts. The name of the directory
-can be anything you like. Ratch doesn't require that it have a special name. For the purposes
-of this tutorial we will call it @task/@.
-
-    $ cd myproject
-    $ mkdir task
-
-Now lets create a ratch script.
-
-    $ vi task/list
-
-This example uses @vi@. You can use your favorite editor, of course. Now, edit the file to read:
-
-<pre class="script">
-    #!/usr/bin/env ratch
-
-    # List project files
-
-    puts glob('**/*')
-</pre>
-
-Save the file. If you are using a Unix-based operating system, also change the file's
-mode to be user executable[2].
-
-    $ chmod u+x task/list
-
-Now run it like you might any executable file on your system:
-
-    $ task/list
-
-fn2. On Windows systems you do this a little differntly. Instead you need to run the task
-via either of the @ruby@ command. Ie. @ruby task/list@. You'll need to keep
-that in mind throughout this tutorial.
-
-And, as you might have expected, our first task printed a listing of every file in our
-project directory. Pretty simple. Yet there are a few things to notice about this example.
-
-First, the @glob@ command. @glob@ is not a standard main method in Ruby. So this method
-comes instead from the Ratch DSL. In normal Ruby you'd have to use @Dir.glob@ to do the same
-thing. Wile a minor difference, this is a simple example of how Ratch makes building project
-tasks easier than just using normal Ruby scripts. There are many more methods provided by
-Ratch's DSL, and we will cover many of them later in this tutorial.
-
-The other thing to notice is that we executed our script like we would any local command,
-and we did so _from the project's root directory_. This is very important. <i>The task will
-act on the directory from which it is called</i>. This can be useful if a task provides
-behavior effective relative to the call location, but it also means we must remain aware
-this versitility, and use our task accordinginly. However, often a task is designed to be
-run only from the project's root directory, as we did in our example. In those cases it
-is not uncommon for the task to perform _sanity_ checks to make sure that's indeed were a
-task is being run. One thing you should not do though, but may at first be tempted to do,
-is @cd@ down into that task directory and run the tasks from there. Do not do that.
-It won't work!!!
-
-h2. Task and System Calls
-
-Okay, that's our first teeny tiny example. Now's its time to dig a little deeper into the
-Ratch DSL.
-
-One of more unique aspects of Ratch scripts is the way in polymophizes internal method calls,
-external task calls and external command calls. To demonstrate lets define a second task
-called 'list2'.
-
-    $ vi task/list2
-
-Make it read:
-
-<pre class="script">
-    #!/usr/bin/env ratch
-
-    # List project files
-
-    puts "How many lists?"
-    list
-    list
-    list
-</pre>
-
-Be sure to change the mode to user executable, then run it.
-
-    $ task/list2
-
-You will notice that calling @list2@, in turn, calls our first script, @list@. But it didn't generate
-a list three times, as you may have expected, but only once. That's because tasks, by definition, are
-only supposed to run once in a given run session. Internally, task results are cached to facilitate this.
-
-Now lets try another example. First, rename @last2@ to @rdoc@
-
-    $ mv task/list2 task/rdoc
-
-Then edit it to read:
-
-<pre class="script">
-    #!/usr/bin/env ratch
-
-    # Generate RDocs
-
-    rdoc "README", 'm' => true, 'op' => 'doc'
-</pre>
-
-For this example to work we'll need to create a @README@ file in project's root directory.
-Anything content will do:
-
-    $ echo "= Welcome" > README
-
-Now, rather than run the task outright, let's see what it would do without actually running the task.
-Ratch provieds a --dryrun global flag that allows you to check/debug scripts easily.
-
-    $ task/rdoc --dryrun
-    rdoc -m --op doc lib
-
-Ratch prints out the command that would have been run without the --dryrun flag. Notice how
-Ratch interpreted the Ruby-esque method call as a commandline tool. It knew this b/c
-1) there were no methods defined with then name 'rdoc', 2) there were not other local tasks
-with the name rdoc (the task's own filename does not count), and 3) it looked up the
-systems list of executable files and found 'rdoc' listed. It then interprets the arguments
-accordingly, the main trick being that any trailing keyword arguments will be truned into
-flag options of the command. However sometimes an external command will have an argument
-usage that Ratch can't handle. In thos cases simple trail along argument text. For instance
-the above #rdoc call could have been written in any number of ways:
-
-<pre>
-    rdoc "-m --op doc "README"
-    rdoc "-m --op doc", "README"
-    rdoc "-m", "--op doc", "README"
-</pre>
-
-Occasionally, there may be a name conflict bwetween a method and an external task
-or command you wish to use. In those cases you can invoke the task or command using
-either the @target@ or @system@ reference object, respectively. For instance the above
-could have also been written:
-
-    system.rdoc "README", 'm' => true, 'op' => 'doc'
-
-The two forms are completely equivalent. The former is simply using @system@
-behined the scenes.
-
-h2. Integrated Build Tools
-
-Well Ratch wouldn't be much a build tool if it didn't facilitate the defintion
-of file creation tasks, beyond simply running shell commands on demand. Ratch
-provides a DSL method, @file@, just for this purpose. With it we can rewrite
-the above RDoc task more robustly as:
-
-<pre class="script">
-    #!/usr/bin/env ratch
-
-    # Generate RDocs
-
-    file 'doc' => ['README'] do
-      rdoc "README", 'm' => true, 'op' => 'doc'
-    end
-
-    target 'doc'
-</pre>
-
-If you are familiar with Rake or Rant what this does is clear. It says that the
-construction of a target file, in this case a directory called 'doc', depends on
-a file 'README'. What this does in practice is compare the modification times
-of the target and it's dependsencies. If _any_ of the dependencies
-have a modification time _after_ the target file's, then the target clearly
-needs to be regenerated and so the task will execute. But if _none_ of the
-the dependecies have a last modification time _after_ the targets, the the
-target is considered upto date, and will not be rebuilt.
-
-Note the last line @target :doc@, which invokes an _internal target_,
-as opposed to external target which is another task script.
-
-
-h2. Task Configuration
-
-Often a task proves useful enough to be reused in other projects, but to do this requires
-some level of generalization and configurability. Ratch makes this easy to do via the
-#config_load method. With it you can load a set of configuration options tied to a specific
-name. The information can then be an entry in a central @config.yaml@ file in your task
-directory, or it can be in a file by that name, ie. @_name_.yaml@.
-
-For example, a @config.yaml@ file might look something like:
-
-<pre class="script">
-      ---
-
-      rdoc:
-        dir      : 'doc/rdoc'
-        main     : README
-
-      publish:
-        target   : rubyforge
-        type     : web
-        host     : rubyforge.org
-        username : transami
-        dir      : web
-
-      release:
-        host     : rubyforge.org
-        username : transami
-        project  : reap
-        groupid  : 811
-        package  : ratch
-        dir      : pkg
-</pre>
-
-In a script one can access this information easily. With it we can define our rdoc task
-like so:
-
-<pre class="script">
-    #!/usr/bin/env ratch
-
-    # Generate RDocs
-
-    config = load_config('rdoc')
-
-    output  = config['dir']
-    include = config['include'] || ['README']
-
-    file ouput => include do
-      rdoc include, 'm' => true, 'op' => output
-    end
-
-    target 'doc'
-</pre>
-
-Now our rdoc task is perfectly general (albiet a bit simplistic), we can reuse the same
-task in any project. We only need to change the config.yaml settings per project instead
-of having to make isolated changes to the task itself. In turn this makes it possible to
-readily share task with other project developers.
-
-
-h2. Project Info via Box
-
-!{float: left; width: 100px;}images/box.jpg!
-
-Notice the reference to 'info'. This is an OpenStruct-like interface to the project information.
-
-It's a good idea to take some time and learn all the standard properties of a project's information file
-which you can draw on for your own tools. Looking at the RDoc API documentation will elucidate most of them.
-And, of course you can also invent your own if needed.
-
-
-
-As you can see this creates a <i>project information file</i> called <code>ProjectInfo</code>.
-Another, and perhaps better way to create a ProjectInfo file is to copy one from some
-other project and modify it to suit your needs. That makes it easier to learn how to fill
-them out. But if you don't have that option or you are already familiar with the layout,
-then you can use <code>mint</code> to copy a new template.
-
-The name of the project information file has some flexibility. Capitalization, for
-instance, is insignifficant; <code>projectinfo</code> would do just as well. Also
-a few alternative namings are supported, namely, <code>project.yaml</code> or just
-<code>PROJECT</code> (again capitalization doesn't matter). For simplicity sake we will refer
-to this file as the ProjectInfo file throughout the documentation. Just remember that you
-can substitue any of these other supported names in it's place to suit your personal preference.
-If you prefer one of the alternate names when creating the file, you can specify it as
-a parameter of the <code>--info</code> option.
-
-    $ project new --info project.yaml
-
-Rather then 'ProjectInfo', the file will be called 'project.yaml'. Ratchets will let you know
-if you pick a name it does not recognize.
-
-Once you have edited the ProjectInfo file (more on this in the next section), subsequnelty running
-<code>project new</code> will create the same project layout as before, but it will add
-enhanced details to further ease the creation of the new project. For instance, the lib
-directory will already have subdirectory named appropriately and if you use the --web option,
-the index.html page will be suitably labeled. And so on.
-
-<div class="special"><b>NOTE</b> The enhanced information scaffolding is barely
-implemented as of yet. But will continue to improve with future releases.</div>
-
-Of course, if you already have a project with which you wish to use Ratchets, rather than
-create a whole new project layout you will probably just want to add the <code><i>ProjectInfo</i></code>
-file to it. In that case you simply run <code>project new --info</code>. The project information file
-will be added and the rest of your project will be undisturbed. Running <code>project new</code> on
-a pre-existing project will have no effect. It will simply report an error that your project
-already has content.
-
-The project file is of central importance to Ratchets and the <code>project</code> command.
-The file is a YAML-formatted file storing shared information from which Ratchets' tools gather
-default information on how to perform their actions. Most subsequent activity will largely
-depend on the content of this file. So lets now turn our attention squarely to it.
-
-The structure of the ProjectInfo file is fairly self-explanitory. The header is devoted to
-common information. This is generally followed by deafult tool settings. And lastly
-a <i>tasks</i> section is used to define user tasks. Each task entry is a YAML map where the
-key represent the task name followed by a private type (!!) which identifies the tool
-it invokes. The next line begins the indented attributes the tool needs to do the job.
-To a detailed list of parameters each tool accepts have a look at the  RDoc API.
-
-Example ProjectInfo File
-
-<pre class="script">
-    --- %YAML:1.0
-
-    title    : Reap
-    name     : reap
-
-    version  : 6.0.0
-    status   : 'beta'
-
-    author   : Thomas Sawyer
-    created  : '2004-04-01'
-    email    : transfirz@zmail.com
-    homepage : "http://reap.rubyforge.org"
-
-    summary  : A Ruby Project Management Assistant
-
-    description: >
-      Reap comprises a set of tasks commonly needed by
-      Ruby package developers/deployers, such as testing,
-      packaging, releasing, etc. You can also use Reap
-      to create your own custom tasks. Reap utilizes a
-      YAML configuration file to harvest common project
-      information, significantly simplifying these chores.
-
-    rubyforge:
-      project  : reap
-      username : transami
-
-    revision:
-      tool: darcs
-      exclude:
-        - doc/api
-
-    executables : [ reap, rubytest ]
-
-    dependencies:
-      - [ facets, '> 1.5' ]
-
-    exclude:
-      - snip
-      - doc/api
-</pre>
-
-As you can the top portion is fairly self-explainitory. After that we see entries related to
-specific Ratchet tools like package. This entry specifies default parameters to use for any
-subsequent call of the package tool. We will cover this in more detail in the
-<a href="tool.html">Tool Utilization</a> documention.
-
-Following this is the tasks section with which we can define our own user-defined
-tasks. Typically these are specializtions of the buil-in tools,
-but as you can see by our "silly example" arbitary tasks can be written as well. We will
-cover this in more detail in the <a href="task.html">Task Management</a> documentation.
-
-
-h2. Verifying Project Information
-
-When Ratchets searches for a ProjectInfo file it will move up the
-directory hierarchy from the current working directory until it finds a ProjectInfo file
-and will assume the location of that file is your project's source directory unless the file
-itself specifes that another directory is the source root.
-
-Project has one other subcommand that can be used to verify the project information: <code>info</code>.
-This simply dumps the parsed  contents of the ProjectInfo file to stdout.
-
-  $ box --dump
-
-This may seem trivial, but it can be sometimes be useful to quicky insure information
-is correct and that you are calling <code>project</code> from an appropriate location. [ed-
-the order of information is arbitrary, so it looks a bit messy. This will be improved
-in a future release.]
-
-
-h2. On Your Own
-
-The rest of building a task is just a matter of writing the code to have
-it do what you want. If you develop any nice tasks, be sure to pass them along!
-
-
-
-
-
-
-
-
-!{float: right;  width: 128px;}images/clipboard.jpg!
-
-h1. Task Management
-
-
-h2. Listings Tasks
-
-Of course, it's not enough to just create tasks and run them willy-nilly. A good build tool
-will let us see what tasks we have available and what they do. It's eay enough to use @ls@
-or @dir@ to list the targets in the task directory.
-
-      $ ls task/
-      list
-
-But that only tells us the names of avaialble tasks. What about what the tasks do? Ratch
-comes with a command line tool to faciltiate this called @lt@. It works much like @ls@.
-Try it:
-
-      $ lt task/
-      [/home/me/projects/foo]
-      task/list     # List project files
-
-So now we know waht the task does as well. Didi you notice where lt got that information?
-It's form the first comment line of the ratch script. @lt@ is enven a bit smater than
-this. If you give it an actual script, it will output full help-details, if the script
-provides it. In our case, the @list@ task doesn't have further details (it doesn't
-really need them), but ew can add some for sample sake.
-
-Edit the @list@ file to look like:
-
-<pre class="script">
-    #!/usr/bin/env ratch
-
-    # List project files
-
-    # This task simply prints out a list
-    # of all the files in the project.
-
-    puts glob('**/*')
-</pre>
-
-Now try:
-
-<pre>
-    $ lt task/list
-
-    List project files
-
-    This task simply prints out a list
-    of all the files in the project.
-</pre>
-
-As you can see, in the mode, @lt@ outputs all the comments line at the top of script.
-It stops at the first non-blank, non-commnet line.
-
-
-h2. Lookup and Do
-
-What if I want to run a task script, but I'm currently way down in the
-project's directory tree. I dont want to <code>cd</code> all the way up or type
-<code>../</code> a bunch of times.
-
-Sake provides a utility called <code>ludo</code> which stands for
-<i>lookup and do</i>. Just prepend that command to your invocation and it
-will find the executable and execute it.
-
-    % ludo task/list
-
-By the way, the <code>ludo</code> command can be used anywhere you like, it is
-not dependent on Sake to work. Albeit you should exercise some caution when doing
-so since <code>ludo</code> actively searches up the directory tree for a script
-to execute.
-
-Sometimes, you may want to lookup and run a command but rather than change directories to
-the where the command match was made you want the task will be run from the current
-directory. You can do that with the --here switch (or -h for short).
-
-  $ ludo -h task/list
-
-This will list all the files relative to the current directory.
-
-
-!{float: right;}images/mints.png!
-
-h2. Task Trading via Mint
-
-Mint is another ProUtil, like Ratch, taht is extermely useful for distributing and resusing Ratch tasks.
-In fact Racth comes with a dozen or so general purpose tasks that you can install to you're projects
-right aay using @mint@.
-
-  $ mint -s ratch/setup
-
-
-
-!images/appendix.png!
-
-h1. Appendix
-
-
-h2. License
-
-<p>
-Ratcehts<br/>
-Copyright &copy; 2006 Thomas Sawyer</br>
-</p>
-
-Ruby/GPL License
-
-This program is free software; you can redistribute it and/or modify
-it under the terms of the Ruby License or GNU General Public License
-as published by the Free Software Foundation; either version 2 of the
-License, or (at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program; if not, write to the Free Software
-Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA

data/doc/style.css

@@ -1,112 +0,0 @@
-
-body {
-  padding: 0; margin: 5px;
-  background: silver;
-  font-size: 1em;
-  font-family: microsoft sans-serif, sans-serif, helvetica;
-  text-align: center;
-}
-
-h1 {
-  margin-top: 25px;
-  font-size: 2.5em;
-}
-
-h1.top {
-  margin-top: -10px;
-}
-
-h2 {
-  margin-top: 25px;
-}
-
-p {
-  font-size: 1em;
-  line-height: 16pt;
-}
-
-pre {
-  padding: 10px 10px 10px 10px;
-  font-size: 0.9em;
-  background-color: black;
-  color: #00FF00;
-  font-weight: bold;
-}
-
-a { text-decoration: none; color: #CC0000; }
-a:hover { text-decoration: underline; }
-
-pre.script { background-color: #DDFFDD; color: black; }
-
-.promenu { font-weight: bold; color: #CC1133; padding-bottom: 5px; }
-.promenu a { color: white; }
-
-.container {
-  margin: 0 auto;
-  width: 740px;
-  border: 2px solid #999999;
-}
-
-.banner {
-  padding: 36px 0px 36px 20px;
-  background: transparent;
-  text-align: left;
-  color: white;
-  font-size: 76px;
-  font-weight: bold;
-  background: url(images/ratch2.png) 300px -10px no-repeat #666666;
-}
-
-.menu {
-  background: white;
-  border-bottom: 1px solid #aaaaaa;
-  font-size: 1.2em;
-  text-align: left;
-  padding-left: 20px;
-  line-height: 40px;
-}
-
-.menu a {
-  color: black;
-  text-decoration: none;
-  padding: 5px;
-}
-
-.menu a:hover {
-  color: #CC0000;
-  text-decoration: underline;
-}
-
-.ad {
-  background: white;
-  padding-top: 10px;
-}
-
-.content {
-  padding: 30px;
-  text-align: left;
-  background: white;
-}
-
-.date {
-  float:right; color:gray; margin: 0;
-}
-
-.copyright {
-  text-align: center;
-  color: white;
-  margin: 0 auto;
-  font-size: 0.9em;
-  font-weight: bold;
-  padding: 30px;
-  background: url(images/ratch2.png) -300px -20px no-repeat #666666;
-}
-
-.copyright a {
-  color: pink;
-}
-
-.important {
-  color: #FF0033;
-  font-weight: bold;
-}