rant 0.3.8 → 0.4.0

data/NEWS

@@ -1,6 +1,25 @@
 
 = Rant NEWS
 
+== Rant 0.4.0
+
+Unless you extended Rant with a custom generator, you can upgrade from
+0.3.8 without changing any dependent code.
+
+Incompatible changes:
+* _Internal_: A generator has to respond to +rant_gen+ instead of
+  +rant_generate+.
+
+New features:
+* Creating zip and gzipped tar archives on all supported platforms
+  without installing extra software. Seamless integration with
+  rant-import.
+  Read doc/package.rdoc[link:files/doc/package_rdoc.html].
+* The standard RubyPackage tasks create zip and gzipped tar archives
+  (and optional gem packages) on all platforms, including Windows,
+  now.
+* rant-import recognizes the new directives +uncomment+ and +remove+.
+
 == Rant 0.3.8
 
 This version should be fully backwards compatible to 0.3.6.

data/README

@@ -12,13 +12,15 @@ Rant currently features:
 * Defining custom tasks
 * Automated packaging, testing and RDoc generation for Ruby
   applications and libraries.
+* The <em>rant-import</em> command creates a monolithic rant script,
+  so you don't depend on an rant installation anymore.
+* Creating gzipped tar and zip archives -- without installing
+  additional software.
 * Primitive support for compiling C# sources portably with csc, cscc
   and mcs.
 * Dependency checking for C/C++ source files.
 * A _configure_ plugin for easy environment and build-parameter
   checking (but not like autoconf!) which saves data in a yaml file.
-* The <em>rant-import</em> command creates a monolithic rant script,
-  so you don't depend on an rant installation anymore.
 
 As programmers usually want to see code, here is a short and very
 basic example of rant usage:
@@ -37,7 +39,7 @@ Running rant in the directory of this file:
 will ensure that the "data" file in the "backup" directory is up to
 date.
 
-This document was written for version 0.3.8 of Rant. Most things
+This document was written for version 0.4.0 of Rant. Most things
 described here will work for older/newer versions of Rant, but look at
 the README file in the Rant distribution you've installed for exact
 documentation of your Rant version.
@@ -70,6 +72,8 @@ Independent from Rant? The <tt>rant-import</tt> command::
     read doc/rant-import.rdoc[link:files/doc/rant-import_rdoc.html]
 Advanced Rantfiles::
     read doc/advanced.rdoc[link:files/doc/advanced_rdoc.html]
+Packaging (creating zip/tgz archives)::
+    read doc/package.rdoc[link:files/doc/package_rdoc.html]
 Compiling C/C++::
     read doc/c.rdoc[link:files/doc/c_rdoc.html]
 Using the Configure plugin::
@@ -148,38 +152,38 @@ The file COPYING[link:../../COPYING] in the Rant package contains a
 copy of the LGPL. Of course your Rantfiles don't need to be licenced
 under the terms of the LGPL.
 
-== Other info
-
-Rant was started in February 2005. It has been written and is
-maintained by Stefan Lang (mailto:langstefan@gmx.at).
+---
 
-=== Why did you write another build tool?
+The file <tt>lib/rant/archive/minitar.rb</tt> is Copyright  2004
+Mauricio Julio Fernandez Pradier and Austin Ziegler. It is licensed
+under the GNU General Public Licence or Ruby's licence.
 
-Because I wasn't satisfied by any other build tool. Before I started
-Rant, I had to write a program in C#. The program had to run under
-Windows, but I wanted to develop under Linux. Also I decided to write
-the documentation in Docbook.
+The file <tt>lib/rant/archive/rubyzip.rb</tt> and the files in the
+<tt>lib/rant/archive/rubyzip</tt> directory were written by Thomas
+Sondergaard. They are distributed under the same license as ruby. See
+http://www.ruby-lang.org/en/LICENSE.txt.
 
-So there where quite a few problems arising:
-* I had to compile with cscc on Linux.
-* compile with csc on Windows.
-* automate PDF and HTML generation from Docbook
+== Other info
 
-_Nant_ would have been ok to compile the C# sources. But it isn't
-suited for more general tasks as clueing togheter other programs
-(needed for Docbook processing).
+Rant was started in February 2005. It has been written and is
+maintained by Stefan Lang (mailto:langstefan@gmx.at).
 
-Then I tried to use _Rake_ and it was the other way round. I liked the
-basic concept and syntax of Rake and of course I could have written
-code for Rake (e.g. with a so called _Tasklib_) to support portable C#
-compilation. But it was a bit quirky and because I like to work with
-Ruby, I decided to write my own build tool.
+=== Credits
 
 Rant has taken the basic syntax of a _task_ and some other concepts
 from Rake.
 So thanks to Jim Weirich, the author of
 Rake[http://rubyforge.org/projects/rake].
 
+Rant comes with parts of archive-tar-minitar to create (gzipped) tar
+archives on platforms where no +tar+ command is available.
+archive-tar-minitar is developed by Mauricio Julio Fernandez Pradier
+and Austin Ziegler.
+
+Rant comes with parts of rubyzip to create zip archives on platforms
+where no +zip+ command is available. rubyzip is developed by Thomas
+Sondergaard.
+
 === Goals of Rant
 
 * Most important is to be a very *flexible* build tool. This currently
@@ -212,3 +216,26 @@ know...
 
 If you encounter problems with Rant on any platform (with Ruby 1.8.1
 or higher) please write a bugreport!
+
+=== Why did you write another build tool?
+
+Because I wasn't satisfied by any other build tool. Before I started
+Rant, I had to write a program in C#. The program had to run under
+Windows, but I wanted to develop under Linux. Also I decided to write
+the documentation in Docbook.
+
+So there where quite a few problems arising:
+* I had to compile with cscc on Linux.
+* compile with csc on Windows.
+* automate PDF and HTML generation from Docbook
+
+_Nant_ would have been ok to compile the C# sources. But it isn't
+suited for more general tasks as clueing togheter other programs
+(needed for Docbook processing).
+
+Then I tried to use _Rake_ and it was the other way round. I liked the
+basic concept and syntax of Rake and of course I could have written
+code for Rake (e.g. with a so called _Tasklib_) to support portable C#
+compilation. But it was a bit quirky and because I like to work with
+Ruby, I decided to write my own build tool.
+

data/Rantfile

@@ -5,10 +5,9 @@ import %w(rubytest rubydoc rubypackage autoclean win32/rubycmdwrapper)
 
 task :default => :test
 
-lib_files = sys["lib/**/*.rb"]
-dist_files = sys["{bin,lib,test,doc}/**/*"].shun("html", "coverage") +
-	sys["*"].no_dir.exclude("InstalledFiles", "Session.vim")
-bin_files = sys["bin/*"]
+dist_files = sys["{bin,lib,test,doc,misc}/**/*"]
+dist_files.shun("html", "coverage")
+dist_files += sys["*"].no_dir.exclude("InstalledFiles", "Session.vim")
 rdoc_opts = %w(-S -c UTF-8 --title Rant --main README)
 
 gen RubyPackage, "rant" do |t|
@@ -103,7 +102,6 @@ gen RubyTest, :tall do |g|
     g.libs << "test"
     g.test_files = sys["test/**/test_*.rb"]
 end
-task :testall => %w(test testp1 testp2 testrb1 testplugins)
 
 desc "Remove autogenerated files."
 gen AutoClean, :clean
@@ -126,10 +124,11 @@ task "to-win" => :package do
     win_dir = "/mnt/data_fat/stefan/Ruby"
     Dir["pkg/*"].each { |f|
 	target = File.join(win_dir, File.basename(f))
-	(file target => f do |t|
+	file target => f do |t|
 	    sys.rm_rf target if test(?e, target)
 	    sys.cp_r f, t.name
-	end).invoke
+	end
+        rac.make target
     }
 end
 
@@ -142,4 +141,4 @@ if Env.on_windows?
     enhance :install => (gen Win32::RubyCmdWrapper, sys["bin/*"])
 end
 
-# vim:ft=ruby:
+# vim:ft=ruby

data/doc/advanced.rdoc

@@ -101,7 +101,7 @@ Use the +Clean+ generator in your Rantfiles:
 === Let Rant cleanup for you
 
 Use the +AutoClean+ generator which will remove all files generated by
-any filetask (include those created by rules):
+any filetask (including those created by rules):
 
     import "autoclean"
 
@@ -285,5 +285,7 @@ Rantfile basics::
     doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html]
 Support for C/C++::
     doc/c.rdoc[link:files/doc/c_rdoc.html]
+Packaging::
+    doc/package.rdoc[link:files/doc/package_rdoc.html]
 Rant Overview::
     README[link:files/README.html]

data/doc/package.rdoc

@@ -0,0 +1,280 @@
+
+== Packaging
+
+Usually you want to create some archive file(s) to distribute your
+software. Rant supports creation of zip and gzipped tar archives. The
+good news is that you don't have to install any extra software because
+Rant integrates parts of Mauricio Julio Fernandez Pradier and Austin
+Ziegler's archive-tar-minitar and Thomas Sondergaard's rubyzip.
+
+Rant provides two techniques, which will be described in the following
+sections.
+
+=== The Package::* generators
+
+The Package namespace provides two generators, namely
+<tt>Package::Tgz</tt> and <tt>Package::Zip</tt>. Let's look at some
+examples to create gzipped tar archives:
+
+Put this into your Rantfile:
+
+    import "package/tgz"
+    gen Package::Tgz, "foo", :files => sys["{bin,lib,test}/**/*"]
+
+This creates a file task called <tt>foo.tgz</tt>. If you run it with
+
+    % rant foo.tgz
+
+rant will create a directory called <tt>foo</tt>, link all selected
+files (in this case all files under bin/, lib/, test/ and all their
+subdirectories, recursively) to foo/ and then create the archive
+<tt>foo.tgz</tt> from the <tt>foo</tt> directory. This means that the
+archive contains exactly one toplevel directory (<tt>foo</tt>) which
+in turn contains the selected files. Most Open Source software is
+packaged up this way. Also usual is to add a version number to the
+package name:
+
+    import "package/tgz"
+    gen Package::Tgz, "foo", :version => "1.0.1", :files => sys["{bin,lib,test}/**/*"]
+
+Now the created file task (and thus the archive file) is called
+<tt>foo-1.0.1.tgz</tt>, and the toplevel directory in the archive is
+called <tt>foo-1.0.1</tt>.
+
+TAKE CARE:: If the directory <tt>foo</tt> or whatever the name
+            of the package is, exists, it will be removed if
+            you invoke the package task!
+
+To avoid such clashes, you can tell Rant to place the package in a
+subdirectory, e.g. <tt>pkg</tt>:
+
+    import "package/tgz"
+    gen Package::Tgz, "pkg/foo", :version => "1.0.1", :files => sys["{bin,lib,test}/**/*"]
+
+Now the task is called <tt>pkg/foo-1.0.1.tgz</tt>. Rant automatically
+creates the pkg/ directory when required. Behind the scenes, Rant
+defines a <tt>Directory</tt> task for the pkg/ directory.
+
+=== Cleaning up with AutoClean
+
+The AutoClean generator knows which files/directories have been
+created by our packaging tasks. Just put this lines into the Rantfile:
+
+    import "package/tgz", "autoclean"
+
+    gen Package::Tgz, "pkg/foo", :version => "1.0.1", :files => sys["{bin,lib,test}/**/*"]
+
+    gen AutoClean
+
+If you invoke rant with <tt>autoclean</tt> as argument now:
+    % rant autoclean
+it will recursively remove the +pkg+ and the <tt>foo-1.0.1</tt>
+directories. This could be a problem if you have source files (or
+other precious files) in the pkg/ directory. In this case change the
+syntax to:
+
+    import "package/tgz", "autoclean"
+
+    gen Package::Tgz, "pkg", "foo", :version => "1.0.1", :files => sys["{bin,lib,test}/**/*"]
+
+    gen AutoClean
+
+The file name for the package is still <tt>pkg/foo-1.0.1.tgz</tt> like
+in the previous example, but now rant assumes that the +pkg+ directory
+belongs to your source base and doesn't create a Directory task for
+it. If you invoke the +autoclean+ task now, it won't remove the +pkg+
+directory, just the <tt>pkg/foo-1.0.1.tgz</tt> archive and the
+<tt>pkg/foo-1.0.1</tt> directory.
+
+<b>If you intend to use AutoClean, you should definitely read
+doc/advanced.rdoc[link:files/doc/advanced_rdoc.html].</b>
+
+=== Writing a MANIFEST
+
+Rant can automatically write a +MANIFEST+ file where it lists all
+files which come into the package. Just give the <tt>:manifest</tt>
+flag:
+
+    import "package/tgz"
+    gen Package::Tgz, "pkg/foo", :manifest,
+        :version => "1.0.1",
+        :files => sys["{bin,lib,test}/**/*"]
+
+Now Rant will write/update a file called +MANIFEST+ whenever the
+package task (<tt>pkg/foo-1.0.1.tgz</tt>) is invoked. +MANIFEST+ will
+then contain a list of all files (each path on a separate line, as
+usual). Of course the +MANIFEST+ file will also be in the archive.
+
+You can use another name instead of +MANIFEST+. In the following
+example we use +contents+:
+
+    import "package/tgz"
+    gen Package::Tgz, "pkg/foo",
+        :manifest => "contents",
+        :version => "1.0.1",
+        :files => sys["{bin,lib,test}/**/*"]
+
+=== Reading a MANIFEST
+
+If you manually maintain a MANIFEST file with all files which belong
+to your software package, you can tell Rant to read it:
+
+    import "package/tgz"
+    gen Package::Tgz, "pkg/foo", :manifest, :version => "1.0.1"
+
+Because we didn't specify the list of files to package with the
+<tt>:files</tt> option, but gave the <tt>:manifest</tt> flag, Rant
+will read the list of files to package from a file called +MANIFEST+.
+
+=== Giving a non-standard file extension
+
+If you want another file extension than the default <tt>.tgz</tt> or
+<tt>.zip</tt> you can specify it with the <tt>:extension</tt> option:
+    
+    import "package/tgz"
+    gen Package::Tgz, "pkg/foo", :manifest,
+        :version => "1.0.1",
+        :extension => ".tar.gz"
+
+=== Creating zip packages
+
+To create a zip package, use exactly the same syntax and options as
+for tgz packages. Just <tt>import "package/zip"</tt> and use the
+<tt>Pakage::Zip</tt> generator:
+
+    import "package/zip"
+    gen Package::Zip, "foo", :files => sys["{bin,lib,test}/**/*"]
+
+This has the same effect as our first example, with the only
+difference that a <tt>foo.zip</tt> archive will be created. As already
+mentioned, you can give the same options and flags as to the
+<tt>Package::Tgz</tt> generator and or course you can use both in the
+same Rantfile:
+
+    import "package/zip", "package/tgz"
+    gen Package::Zip, "foo", :files => sys["{bin,lib,test}/**/*"]
+    gen Package::Tgz, "foo", :files => sys["{bin,lib,test}/**/*"]
+
+=== The Archive::* generators
+
+Like the <tt>Package::</tt> namespace, the <tt>Archive::</tt>
+namespace also provides two generators, namely <tt>Archive::Tgz</tt>
+and <tt>Archive::Zip</tt>. They require the same syntax and recognize
+the same options. So what's the difference? The <tt>Archive::*</tt>
+generators don't move the selected files into a toplevel directory.
+Let's look at an example:
+
+    import "archive/tgz", "package/tgz"
+    gen Package::Tgz, "foo", :files => sys["{bin,lib,test}/**/*"]
+    gen Archive::Tgz, "bar", :files => sys["{bin,lib,test}/**/*"]
+
+This creates a file task <tt>foo.tgz</tt> and a file task
+<tt>bar.tgz</tt>. The difference is, that <tt>foo.tgz</tt> contains a
+toplevel directory +foo+ which in turn contains the +bin+, +lib+ and
++test+ directories, but <tt>bar.tgz</tt> directly contains the +bin+,
++lib+ and +test+ directories:
+
+Created with <tt>Package::Tgz</tt>:
+    foo.tgz
+        foo/
+            bin/
+                .
+                .
+            lib/
+                .
+                .
+            test/
+                .
+                .
+
+Created with <tt>Archive::Tgz</tt>:
+    bar.tgz
+        bin/
+            .
+            .
+        lib/
+            .
+            .
+        test/
+
+Of course the same difference is between the <tt>Package::Zip</tt> and
+<tt>Archive::Zip</tt> generators.
+
+=== Creating a shortcut, dependencies
+
+Imagine you have a package task which creates a tgz package and a task
+which should upload the package to a server. This means that the
+upload task depends on the package task. You could do this like in the
+following Rantfile:
+
+    import "package/tgz"
+    
+    gen Package::Tgz, "pkg", "foo", :version => "1.0.1", :files => sys["{bin,lib,test}/**/*"]
+
+    task :upload => "pkg/foo-1.0.1.tgz" do |t|
+        sys "<some command to upload the archive file>"
+    end
+
+That's not very convinient and it's tedious to always update the
+dependency when you change the version number. But the package
+generator returns an object with information about the created package
+tasks:
+
+    import "package/tgz"
+    
+    pkg =
+    gen Package::Tgz, "pkg", "foo", :version => "1.0.1", :files => sys["{bin,lib,test}/**/*"]
+
+    task :upload => pkg.path do |t|
+        sys "<some command to upload the archive file>"
+    end
+
+Here we assign this object to the +pkg+ variable. The
+<tt>pkg.path</tt> method returns the path to our tgz archive.
+
+Another handy use case is to create a shortcut:
+
+    import "package/tgz"
+    
+    pkg =
+    gen Package::Tgz, "pkg", "foo", :version => "1.0.1", :files => sys["{bin,lib,test}/**/*"]
+
+    desc "Create package for distribution."
+    task :package => pkg.path
+
+Now you can invoke the package task from the commandline:
+
+    % rant -T
+    rant package    # Create package for distribution.
+    % rant package
+    <messages about tgz creation>
+
+
+=== Some random notes
+
+* Symbolic links are always dereferenced, i.e. the file/directory the
+  link points to will be in the archive, not the symbolic link. Rant
+  will probably provide an option to store the symbolic links in the
+  future.
+* Directories are not included recursively:
+        gen Package::Tgz, "foo", :files => sys["lib"]
+  Assuming +lib+ is a directory, <tt>foo.tgz</tt> will contain only
+  the empty directory <tt>foo/lib</tt>, no matter how many
+  files/subdirectories +lib+ contains. If you want to package +lib+
+  with all subdirectories and files it contains, use the following
+  pattern:
+        gen Package::Tgz, "foo", :files => sys["lib/**/*"]
+* Consider the directory where all files are linked to by the
+  Package::* generators as byproducts and don't rely on their
+  creation.
+
+== See also
+
+Rantfile basics::
+    doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html]
+Advanced Rantfiles::
+    doc/advanced.rdoc[link:files/doc/advanced_rdoc.html]
+Support for C/C++::
+    doc/c.rdoc[link:files/doc/c_rdoc.html]
+Rant Overview::
+    README[link:files/README.html]

data/doc/rantfile.rdoc

@@ -170,20 +170,6 @@ explain it a little bit. The +sys+ function can be used in three ways:
 	sys.ruby "arg1", "arg2", ... # invoke the ruby interpreter
 	sys.safe_ln "src", "dest"    # create a hardlink or fall back to
 				     # copying
-   If you're tired of typing <tt>sys.</tt> all the time, you can include
-   the Rant::Sys module in your Rantfile (though it is not recommended
-   to do this):
-	include Rant::Sys
-	task :clean do
-	    rm_f "myprog"
-	end
-Then you can invoke these methods without the <tt>sys</tt> function.
-Note::	You are highly encouraged to not <tt>include Rant::Sys</tt>
-	into your Rantfile as this introduces many methods in the
-	global namespace, which can cause name clashes with other
-	libraries.  Of course if you have just some tasks to remove
-	backup files in your home directory and do not use other Ruby
-	libraries in your Rantfile, it is no problem.
 
 2. <b>Running external commands</b>
 
@@ -206,8 +192,8 @@ Note::	You are highly encouraged to not <tt>include Rant::Sys</tt>
    read the ri docs to get an overview:
 	ri Dir::glob
 
-   From now on we'll call <tt>sys[...]</tt> the <it>glob
-   operator</it>.
+   From now on we'll call <tt>sys[...]</tt> the <em>glob
+   operator</em>.
 
    You can give more patterns:
 	c_files = sys["**/*.h", "**/*.c"]
@@ -215,7 +201,7 @@ Note::	You are highly encouraged to not <tt>include Rant::Sys</tt>
    directory and all subdirectories.
 
    The object returned by the glob operator _behaves_ like a list of
-   string, so it is possible to pass it to methods expecting an array.
+   strings, so it is possible to pass it to methods expecting an array.
    If you're getting errors or experience strange behaviour convert
    the list explicetely to an array:
 	sys.touch c_files.to_a
@@ -423,7 +409,11 @@ because it refers to a main Rantfile.
 
 Advanced Rantfiles::
     doc/advanced.rdoc[link:files/doc/advanced_rdoc.html]
-Rant Overview::
-    README[link:files/README.html]
+Support for C/C++::
+    doc/c.rdoc[link:files/doc/c_rdoc.html]
+Packaging::
+    doc/package.rdoc[link:files/doc/package_rdoc.html]
 Ruby project howto::
     doc/rubyproject.rdoc[link:files/doc/rubyproject_rdoc.html]
+Rant Overview::
+    README[link:files/README.html]

data/doc/rubyproject.rdoc

@@ -17,10 +17,10 @@ You can find this little project in test/project_rb1 directory of the
 Rant package. You'll probably have more files in your project, but we
 will try to write our Rantfile as generic as possible:
 
-    import %w(rubytest rubydoc rubypackage)
+    import %w(rubytest rubydoc rubypackage clean)
 
-    lib_files = Dir["lib/**/*.rb"]
-    dist_files = lib_files + %w(rantfile.rb README) + Dir["{test,bin}/*"]
+    lib_files = sys["lib/**/*.rb"]
+    dist_files = lib_files + %w(rantfile.rb README) + sys["{test,bin}/*"]
 
     desc "Run unit tests."
     gen RubyTest do |t|
@@ -34,7 +34,7 @@ will try to write our Rantfile as generic as possible:
     end
 
     desc "Create packages."
-    gen RubyPackage, :wgrep do |t|
+    gen RubyPackage, "wgrep" do |t|
 	t.version = "1.0.0"
 	t.summary = "Simple grep program."
 	t.files = dist_files
@@ -43,15 +43,16 @@ will try to write our Rantfile as generic as possible:
 	t.package_task
     end
 
-    task :clean do
-	sys.rm_rf %w(doc pkg)
-    end
+    desc "Remove autogenerated and backup files."
+    gen Clean
+    var[:clean].include "doc", "pkg", "*~"
 
 To verify how our tasks are named:
     % rant -T
     rant test     # Run unit tests.
     rant doc      # Generate html documentation.
     rant package  # Create packages.
+    rant clean    # Remove autogenerated and backup files.
 
 Let's examine the code by running the tasks:
     % rant test
@@ -109,25 +110,30 @@ The most interesting task is the +package+ task:
       Version: 1.0.0
       File: wgrep-1.0.0.gem
     mv wgrep-1.0.0.gem pkg
-This is what it does on my machine:
+This is what it does:
 1. Link all package files to the new folder <tt>pkg/wgrep-1.0.0</tt>.
-2. Create a tar.gz file in the +pkg+ directory with the tar command.
-3. Create a .zip file in the +pkg+ directory with the zip command.
+2. Create a tar.gz file in the +pkg+ directory.
+3. Create a .zip file in the +pkg+ directory.
 4. Create a RubyGem in +pkg+.
-The .zip file will only be created if the +zip+ command is available.
-The .tar.gz file will only be created if the +tar+ command is
-available. And the RubyGem will only be created if RubyGems is
-available on your system.
+The RubyGem will only be created if RubyGems is available on your
+system.
 
 The gem specification also contains the RDoc options we have given to
 the +RubyDoc+ generator and the +has_rdoc+ attribute is set to true.
 No need to duplicate this information in our Rantfile.
 
+And if we want to remove all autogenerated files (and backup files) we
+run the +clean+ task:
+    % rant clean
+    rm -rf doc
+    rm -rf pkg
+    rm -f README~
+
 === More about the RubyPackage generator
 
 The argument given to the RubyPackage generator is used as package
-name (here "wgrep") and may be a symbol or string:
-    gen RubyPackage, :wgrep do |t|
+name (here "wgrep"):
+    gen RubyPackage, "wgrep" do |t|
 
 The line which actually creates the package task(s) is this one:
     t.package_task
@@ -234,3 +240,5 @@ Rant Overview::
     README[link:files/README.html]
 Writing an Rantfile::
     doc/rantfile.rdoc[link:files/doc/rantfile_rdoc.html]
+Advanced Rantfiles::
+    doc/advanced.rdoc[link:files/doc/advanced_rdoc.html]