rote 0.1.2 → 0.1.6

data/README

@@ -10,41 +10,7 @@ Markdown, and embedded Ruby code with RedCloth [http://redcloth.rubyforge.org/]
 and ERB [http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html]), 
 layout, and general documentation / website build tasks.
 
-== Should I download it?
-
-I don't know. Rote offers the following major features:
-
-* Simple set-up based on page templates and sections.
-* ERB, Textile, and Markdown supported out of the box.
-* Multiple configurable layouts apply boilerplate to your pages.
-* 'Scoped' Ruby code support allows fine-grained control of data available across 
-  all documentation, a subset, or individual pages.
-* Can be used standalone (from the command-line) or from within Rake [http://rake.rubyforge.org]
-  as a custom task library.
-* Supports any (text-based) format, while providing utilities and helpers for
-  common formats (HTML at present).
-	  
-So, should you?
-  
-== Why 'Rote'
-
-The name? I tried to come up with a combination of 'Ruby Site', but couldn't
-get past 'Rite' (it's already taken ;)). So, I changed a letter. I'm short on
-imagination you know. Oh, you mean why the system? Well, to make it easier 
-for me to manage roscopeco.co.uk now that I've dumped all the dynamic (JEE) 
-stuff and gone back to good old Apache sans CGI. I want something that lets 
-me do the disconnected page rendering and some of the 'dynamic' stuff, 
-without the dynamic stuff.
-
-If you really need a better explanation for the name, I've come up with these
-alternatives:
-
-* Something about 'the docs I rote'
-* 'Rake-Oriented Template Extensions'
-* 'Rote Only Talks Erb'
-* 'Really? Ordinary Template Enhancements?'
-
-== What else do I need?
+== Prerequisites
 
 Rote uses the following (versions are as per my development environment,
 you may find you can use older versions, you may not).
@@ -53,17 +19,21 @@ you may find you can use older versions, you may not).
 * Rake 0.6.2 ('gem install rake')
 * RedCloth 3.0.4 ('gem install RedCloth')
 
-RubyGems (http://rubyforge.org/frs/?group_id=126) is *highly recommended*,
+RubyGems [http://rubyforge.org/frs/?group_id=126] is *highly recommended*,
 and makes for not only an easier install but a cleaner library path.
 Rote is tested with Gems 0.8.11.
 
-== How do I install it ... 
+Please note that Rote is written and tested on Linux - I have no facilities
+to test with, e.g. Windows, and would like to hear about any issues that affect
+usage with other OSes.
+
+== Installation ... 
 
 === ... with RubyGems?
 
 If you have RubyGems, you can install Rote by simply issuing the command:
 
-	gem install rote 
+	gem install -r rote 
 	
 Which should download the latest version and install it, including
 the 'rote' wrapper script and man pages.	If you experience problems,
@@ -71,7 +41,11 @@ or wish to perform an offline installation, then simply download the
 .gem file from the FRS, and execute the gem command from within the same
 directory.
 
-=== ... using install.rb?
+*Note* that the gem install currently doesn't install the man pages.
+You will need to copy them to the appropriate location manually if using
+this method.
+
+=== ... with install.rb?
 
 If you don't have RubyGems, you can install from one of the tarball or zip
 packages, using the following command:
@@ -79,7 +53,7 @@ packages, using the following command:
 	ruby install.rb
 	
 from the unpacked root directory. This will copy the libaries to the 
-appropriate	place, and set up the rote wrapper script and so on.
+appropriate	place, and set up the rote wrapper script, manpages, and so on.
 
 === ... in my own way?
 
@@ -100,203 +74,40 @@ the version number of your Rote installation.
  
 == How do I use it?
 
-=== From the command-line
-
-If you are generating a standalone documentation set (i.e. not as part of 
-some wider build) then you don't need to worry about writing a +Rakefile+ -
-you can use the built-in build via the +rote+ command. This works with
-a standard directory layout, and wraps invocation of +rake+ to handle
-setting up library dependencies and generation of appropriate tasks.
-
-You'll need something like the following directory layout:
-  
-  somesite ( <- root, this can be called whatever you like)
-  |--> [publish.rf]
-  |
-  |--> doc
-  |    |--> [COMMON.rb]
-  |    |
-  |    |--> res
-  |    |    |--> (resources)
-  |    |
-  |    |--> layouts
-  |    |    |--> one.rhtml
-  |    |    |--> two.rhtml
-  |    | 
-  |    |--> pages
-  |    |    |--> [COMMON.rb]
-  |    |    |--> apage.txt
-  |    |    |--> [apage.rb]
-  |    |    |--> adir
-  |    |    |    |--> [COMMON.rb]
-  |    |    |    |--> bpage.html
-  |    |    |    |--> [bpage.rb]   
-
-Template sources under the 'pages' directory may have any extension (except
-+rb+), and will be rendered to that same name under the output directory. 
-See the section on Layouts below for details on layout name resolution.
-Set up a simple test site following the above layout, and then run:
-
-	rote
-	
-from the top-level directory (+somesite+), you should get a 'target' directory
-created with the (transformed) templates.
-
-Now try:
-
-	rote --tasks
-	
-to get a list of valid tasks, or:
-	
-	rote --usage
-	
-for further option information.
-
-=== From your +Rakefile+
-
-If you are wanting to build documentation as part of a larger build process, or
-commandline setup, then you'll want to get started on integrating Rote with 
-your own (existing) +Rakefile+. Fortunately, this is very easy to do. Try 
-something like:
-
-	# Rakefile
-	require 'rote'
-	
-	ws = Rote::DocTask.new(:doc) { |site| 
-	  site.site_dir = 'html'
-	  site.layout_dir = 'doc/layouts'
-	
-	  site.pages.dir = 'doc/pages'
-	  site.pages.include('**/*')  
-		  
-	  site.res.dir = 'doc/res/'
-	  site.res.include('**/*.png')
-	  site.res.include('**/*.gif')
-	  site.res.include('**/*.jpg')
-	  site.res.include('**/*.css')
-	}
-	
-Save this as +Rakefile+, and fire up:
-
-	rake --libdir=$ROTE_HOME/lib doc
-
-If all goes well, you should see each command and transformation output to your
-console as Rote runs. 
-
-*Note* that it's safe to include '**/*' in the +pages+ list, since +rb+ 
-files are implicitly excluded.
-
-== Creating templates
-
-As mentioned, templates are simply text files in the doc/pages directory. The
-layout below that directory is retained when transforming pages, and is
-also used to provide simple hierarchical structure to the common page code.
-By default, any file with an extension other than +rb+ will be processed
-as a page template (with it's associated ruby source). The output will have
-the same filename and path, relative to the output directory.
+Please see the user guide for usage information. The latest version can be
+found online at http://rote.rubyforge.org/guide/ , and documentation source for
+a specific release is included in the release package. 
 
-=== Template code and ERB
+See above for instructions on building the documentation set.
 
-All templates may contain embedded Ruby code (ERB), delimited by the standard
-<% ... %> (for executed code) and <%= ... %> (for output) tags. Any (valid) 
-Ruby code may be placed in the templates, and variables may be defined to
-allow information to be passed into templates. There are four places where 
-you might define such variables. The following is in order of evaluation:
+=== A note about version numbers
 
-* This directory's COMMON.rb, or the parent directory's COMMON.rb if
-  +inherit_common+ is used.
-* This page's ruby code, _basename_.rb
-* In a block passed to Page.new
-* In the template itself
+Rote uses odd/even numbers for development/release versions. When the final
+version component is odd, the package is an 'unofficial' build - generally
+this means built manually from source, during development. These will never
+be distributed, and there's no guarantee that any two packages with the same
+development version will actually be the same. These packages will have no
+corresponding CVS tag.
 
-When a Rote::Page instance is created, Rote looks for these, and 
-evaluates them, in order, in the same binding as the template is later rendered
-in (i.e. the +Page+ instance binding). Therefore, you can define
-instance variables to pass data around, or even helper methods if you wish.
+Even numbers always denote 'official' releases, which are released on 
+RubyForge and tagged as such in CVS. These packages can be trusted to exhibit
+version consistency.
 
-=== Text to HTML formatting
+If you are bundling Rote with your product, please ensure you use an official
+release version whenever possible. If you must use a developmental version,
+please modify the package version to reflect the fact that it is a custom
+build (e.g. 0.1.3-mycompany-20051021) to prevent inconsistent development
+packages from escaping into the wild.
 
-Rote uses RedCloth (http://redcloth.rubyforge.org) to provide text to HTML 
-formatting, supporting both Textile and Markdown. The formatting applied to a
-given page is controlled by that page's +format_opts+ array. Both are disabled
-by default - to enable formatting you must add something like the following
-somewhere appropriate:
+=== Further information
 
-	format_opts << :textile << :markdown
-	
-Although you can directly assign to +format_opts+, this isn't recommended since
-Ruby often interprets it as a local variable set rather than method call, 
-resulting in much head scratching as to why your options are being ignored.
-
-Formatting is applied _after_	any ERB has been evaluated.
-
-*Note* that the options you supply are passed directly to RedCloth, so you can
-exercise much more control over the formatting by using the feature-specific
-symbols defined by RedCloth, rather than the blanket :textile and :markdown
-symbols.
+Rote is developed by Ross Bamford (ross <at> roscopeco.co.uk). Flame him if
+it breaks your day ;P
 
-=== Layout
-
-Layouts are stored under the doc/layouts directory (by default). They may
-be organised into subdirectories, but this hierarchy is not connected to
-the hierarchy in +pages+. To apply a layout to a page, simply call the
-Rote::Page.layout method from code applied to that page, passing the
-base-name (and path, relative to +layouts+, if used). If no extension is
-specified, then the same extension as the page itself is assumed. Examples:
-
-	layout 'one'
-	layout 'main/wide'
-	layout 'dark.txt'
-	<% layout 'my' %>
-	
-With that done, Rote would first render the template text (including textile)
-and set the Page instance variable @content_for_layout before rendering 
-the layout (in which textile is currently not supported). The layout is
-responsible for inserting the rendered template where appropriate, with
-e.g.:
+* Homepage - http://rote.rubyforge.org/
+* Project - http://rubyforge.org/projects/rote
+* Issues - http://rubyforge.org/tracker/?group_id=1120
+* List - rote-devel@rubyforge.org
 
-	<%= @content_for_layout %>
-	
-This pattern shouldn't be unfamiliar. Again, note that Rote doesn't mandate 
-HTML, despite the appearance from the ERB tags - any (textual) format can
-be templated and laid out.
-
-== Resources
-
-Of course, you're likely to have resources for your site (images, sounds, etc)
-and you'll need to copy them over to the target too. Such resources should be
-placed under 'res' (with the commandline setup) or in your specified +res+
-directory, and will be copied directly to the output directory after page
-rendering.
-
-Of course, the directory layout beneath +res+ should mirror that of the 
-output, and will be preserved during the copy.
-
-== Publishing
-
-Rote does not provide any direct support for publishing your site at present,
-relying on you to configure an appropriate publish task if required, using
-the publishers supplied with Rake (in rake/contrib). This allows maximum 
-flexibility, and allows Rote to concentrate on creating your documents.
-
-The command-line build will automatically look for a file in the top-level
-directory (above +doc+) named publish.rf. If found, this file will be 
-evaluated by Rake, making any tasks defined within it available to your
-build. The most likely use case is to define task that uses an SSH directory
-publisher to publish via SCP.
-
-== A final note about command-line mode
-
-Currently, there isn't enough checking involved on source resources when
-building pages from the command-line wrapper - Basically, only templates are
-considered when Rake decides what to update. If you change layouts, code or 
-resources you'll need to run:
-	
-	rote clean
-		
-to make sure everything gets updated. It's recommended to always run upload
-as:
-	
-	rote clean upload
-		
-Please note that this isn't Rake's limitation - it's mine.	
+As you may have guessed, Rote's hosting and development services are provided
+by http://RubyForge.org .

data/Rakefile

@@ -6,7 +6,7 @@
 # This Rakefile is heavily based on Rake's own Rakefile.
 # Portions copyright (c)2003, 2004 Jim Weirich (jim <AT> weirichhouse.org)
 #
-# $Id: Rakefile,v 1.4 2005/11/26 01:36:52 roscopeco Exp $
+# $Id: Rakefile,v 1.6 2005/11/27 15:57:45 roscopeco Exp $
 #
 
 begin
@@ -20,7 +20,10 @@ require 'rake/clean'
 require 'rake/testtask'
 require 'rake/rdoctask'
 
-$: << 'lib'
+# This needs to go at the front of the libpath
+# Otherwise, any pre-installed rote gets found,
+# and used from there.
+$:[0,1] = 'lib'
 require 'rote'
 
 CLEAN.include('testdata')
@@ -172,9 +175,6 @@ else
 
     s.files = PKG_FILES.to_a
 
-    #### Install Manpages (abuse C extension feature a bit)
-    #s.extensions << "post-install.rb"
-
     #### Load-time details: library and application (you will need one or both).
 
     s.require_path = 'lib'                         # Use these for libraries.
@@ -208,6 +208,15 @@ else
 #       s.cert_chain  = [File.join(ENV['CERT_DIR'], 'gem-public_cert.pem')]
 #     end
   end
+  
+  # Quick fix for Ruby 1.8.3 / YAML bug
+  if (RUBY_VERSION == '1.8.3')
+    def spec.to_yaml
+      out = super
+      out = '--- ' + out unless out =~ /^---/
+      out
+    end  
+  end
 
   package_task = Rake::GemPackageTask.new(spec) do |pkg|
     pkg.need_zip = true

data/TODO

@@ -6,7 +6,10 @@ Send any suggestions (or test-driven patches) to:
   rosco <at> roscopeco <dot> co <dot> uk
 
 * More flexible markup rendering
+* Nested layouts
 * Integration with test reports
 * Automatic navigation / TOC
+* Ability to have multiple views of a section, e.g. user guide (separate
+  pages) and user guide (one page) generated from same source.
 * Index and glossary support
 * statistics

data/doc/layouts/page.html

@@ -32,6 +32,10 @@
 	</table>	
 	
 	<div class='main' background='#c0a0c0'>
+		<% if @page_title %>
+			<h2><%= @page_title %></h2>
+		<% end %>
+		
 		<%= @content_for_layout %>	
 	</div>
 	

data/doc/pages/COMMON.rb

@@ -1,3 +1,14 @@
+# Common code for every page.
+#
+# Instead of being executed once (as you might expect), this is evaluated
+# for each Page's binding as the instance is created.
+#
+# At the moment, COMMON.rb code isn't automatically inherited from
+# parent directories - you have to use the 'inherit_common' hack provided
+# by Page to inherit from the immediate parent directory ONLY (setting
+# up chains of COMMONs if you have deep nesting - Ugh!). This limitation
+# will be removed very soon.
+
 @site_title = 'Rote'
 @base_url = 'http://rote.rubyforge.org/'
 
@@ -5,16 +16,23 @@
 layout 'page'
 format_opts << :textile
 
-# this is used to construct the navbar and frontpage.
+# this is used to construct the navbar and frontpage. Note that we use absolute
+# (root-relative) URLs here, and fix them from each page with 'link_rel'.
 @navigation = [
 					{:title => 'Home',
 					 :url => '/index.html'},
 					{:title => 'Download',
 					 :url => 'http://rubyforge.org/frs/?group_id=1120'},					 
+					{:title => 'User guide',
+					 :url => '/guide/'},					 
 					{:title => 'RDoc',
-					 :url => 'rdoc/'},					 
+					 :url => '/rdoc/'},
+					{:title => 'Issue tracker',
+					 :url => 'http://rubyforge.org/tracker/?group_id=1120'},
 					{:title => 'Project home',
 					 :url => 'http://rubyforge.org/projects/rote'},					 
 					{:title => 'Browse CVS',
-					 :url => 'http://rubyforge.org/cgi-bin/viewcvs.cgi/?cvsroot=rote'}					 
+					 :url => 'http://rubyforge.org/cgi-bin/viewcvs.cgi/?cvsroot=rote'},
+					{:title => 'License',
+					 :url => '/license.html'}					 
 					]

data/doc/pages/guide/COMMON.rb

@@ -0,0 +1,7 @@
+# This is a hack that exists currently to inherit COMMON.rb
+# from above. Of course, we can still define extra stuff
+# here. 
+#
+# This will be made implicit soon.
+
+inherit_common

data/doc/pages/guide/index.html

@@ -0,0 +1,311 @@
+<% @page_title = 'User guide' %>
+
+*This guide is still very much under construction!*
+
+It is assumed that you have installed Rote already. If not, please
+consult the <a href="<%= link_rel '/rdoc/files/README.html' %>">README</a> 
+for installation instructions.
+
+<a name='top'/>
+h3. Contents
+
+  * "Getting started with Rote":#getting_started
+  ** "From the command-line":#getting_started_command_line
+  ** "From your Rakefile":#getting_started_rakefile
+  * "Creating templates":#create_templates
+  ** "Basics":#create_templates_basics
+  ** "Formatting":#create_templates_formatting
+  ** "Template code & ERB":create_templates_erb
+  ** "Applying layout":create_templates_layout
+  * "Resources":#resources
+  * "Publishing":#publishing
+  
+<a name='getting_started'/>
+h3. Getting started with Rote
+
+h4. Setting up a project
+
+To get started quickly, we'll use the standard Rote directory layout, which
+can be used immediately with the command-line wrapper, and fits well with
+Rakefile usage too. Basically, Rote expects your documentation source to
+be laid out as follows:
+
+<code><pre>  
+  project_root ( <- root, this can be called whatever you like)
+  |
+  |--> [publish.rf]
+  |
+  |--> doc
+  |    |--> [COMMON.rb]
+  |    |
+  |    |--> res
+  |    |    |--> (resources)
+  |    |
+  |    |--> layouts
+  |    |    |--> one.txt
+  |    |    |--> two.html
+  |    | 
+  |    |--> pages
+  |    |    |--> [COMMON.rb]
+  |    |    |--> apage.txt
+  |    |    |--> [apage.rb]
+  |    |    |--> adir
+  |    |    |    |--> [COMMON.rb]
+  |    |    |    |--> bpage.html
+  |    |    |    |--> [bpage.rb]   
+			  
+</code></pre>
+
+Template sources under the 'pages' directory may have any extension (except
+=rb=), and will be rendered to that same name under the output directory. 
+See the section on Layouts below for details on layout name resolution.
+
+Ruby source is optional, and allows you to define instance variables and 
+methods on a Page instance. COMMON.rb is applied to all pages in a given
+directory. See "the section on templates":#create_templates for more
+information on the specifics.
+
+If you've downloaded Rote, then you can see the canonical example site by
+looking in the =doc/= directory (where you'll find the source for this
+site).
+
+["top":#top]
+
+<a name='getting_started_command_line'/>
+h4. From the command-line
+
+If you are generating a standalone documentation set (i.e. not as part of 
+some wider build) then you don't need to worry about writing a =Rakefile= -
+you can use the built-in build via the +rote+ command. This works with
+a standard directory layout, and wraps invocation of +rake+ to handle
+setting up library dependencies and generation of appropriate tasks.
+
+The command-line wrapper expects the above layout, and requires no direct
+configuration. To generate an entire documentation set, simply run:
+
+<pre><code>        rote</code></pre>
+	
+from the top-level directory (=project= in the example above), you should get
+a 'html' directory created with the (transformed) templates, and any 
+resources should be copied as necessary. 
+
+Being based on Rake, Rote supports last-modified checking, and provides an
+individual file task for each page in your doc set. For example, running 
+the 'rote' command again with no options will cause it to exit almost
+immediately, since all output is up to date. If you change a file, and run
+rote again, then just that file will be updated. There are a few caveats
+with this (see "the notes section":#final_notes).
+
+The file tasks are named for the target files, so for example to generate
+just the top-level index.html (regardless of whether it's been modified)
+you'd run:
+
+<pre><code>        rote html/index.html</code></pre>
+
+The =clean= task supports deleting all output files to start from scratch:
+
+<pre><code>        rote clean</code></pre>
+
+Of course, multiple file or task names (or a mixture) can be specified.
+You can get a list of valid tasks in the current context with:
+
+<pre><code>        rote --tasks</code></pre>
+	
+Further command-line usage information is available with:
+	
+<pre><code>        rote --usage</code></pre>
+	
+and Unix installations performed with =install.rb= should also make a
+manpage available for the =rote= command.
+
+["top":#top]
+
+<a name='getting_started_rakefile'/>
+h4. From your +Rakefile+
+
+If you are wanting to build documentation as part of a larger build process, or
+commandline setup, then you'll want to get started on integrating Rote with 
+your own (existing) +Rakefile+. Fortunately, this is very easy to do. Try 
+something like:
+
+<pre><code>
+	# Rakefile
+	require 'rote'
+	
+	ws = Rote::DocTask.new(:doc) { |site| 
+	  site.site_dir = 'html'
+	  site.layout_dir = 'doc/layouts'
+	
+	  site.pages.dir = 'doc/pages'
+	  site.pages.include('**/*')  
+		  
+	  site.res.dir = 'doc/res/'
+	  site.res.include('**/*.png')
+	  site.res.include('**/*.gif')
+	  site.res.include('**/*.jpg')
+	  site.res.include('**/*.css')
+	}
+	
+</code></pre>
+	
+Save this as =Rakefile=, and fire up:
+
+<pre><code>        rake doc</code></pre>
+
+If all goes well, you should see each command and transformation output to your
+console as Rote runs. 
+
+*Note* that it's safe to include '**/*' in the +pages+ list, since +rb+ 
+files are implicitly excluded.
+
+["top":#top]
+
+<a name='create_templates'/>
+h3. Creating templates
+
+<a name='create_templates_basics'/>
+h4. The basics
+
+As mentioned, templates are simply text files in the =doc/pages= directory. The
+layout below that directory is retained when transforming pages, and is
+also used to provide simple hierarchical structure to the common page code.
+
+By default, any file with an extension other than =rb= will be processed
+as a page template (with it's associated ruby source). The output will have
+the same filename and path, relative to the output directory.
+
+["top":#top]
+
+<a name='create_templates_formatting'/>
+h4. Applying formatting
+
+If you're generating HTML, you'll probably want to use some plaintext 
+formatting, rather than writing HTML by hand. Rote uses 
+"RedCloth":http://redcloth.rubyforge.org to provide text to HTML formatting, 
+supporting both Textile and Markdown. The formatting applied to a given page is
+controlled by that page's +format_opts+ array. Both are disabled by default - to 
+enable formatting you must add something like the following somewhere appropriate:
+
+<pre><code>        format_opts << :textile << :markdown</code></pre>
+	
+This can be done in page code, COMMON.rb, or even inside the template itself.
+See "the section on template code":#create_templates_erb for more information
+on adding code to your templates.
+	
+*Some additional notes on formatting*
+
+  * Although you can directly assign to +format_opts+, this isn't recommended 
+    since Ruby often interprets it as a local variable set rather than method call, 
+    resulting in much head scratching as to why your options are being ignored.
+    
+  * Note that *Formatting is applied _after_ any ERB has been evaluated.*
+
+  * that the options you supply are passed directly to RedCloth, so you can
+    exercise much more control over the formatting by using the feature-specific
+    symbols defined by RedCloth, rather than the blanket :textile and :markdown
+    symbols.
+
+["top":#top]
+
+<a name='create_templates_erb'/>
+h4. Template code and ERB
+
+All templates may contain embedded Ruby code (ERB), delimited by the standard
+&lt;% ... %&gt; (for executed code) and &lt;%= ... %&gt; (for output) tags. Any 
+(valid) Ruby code may be placed in the templates, and variables may be defined to
+allow information to be passed into templates. There are four places where 
+you might define such variables. The following is in order of evaluation:
+
+* This directory's COMMON.rb, or the parent directory's COMMON.rb if
+  =inherit_common= is used.
+* This page's ruby code, _basename_.rb
+* In a block passed to Page.new
+* In the template itself
+
+When a =Rote::Page= instance is created, Rote looks for these, and if found
+evaluates them, in order, in the same binding as the template is later rendered
+in (i.e. the =Page= instance binding). Therefore, you can define
+instance variables to pass data around, or even helper methods if you wish.
+
+["top":#top]
+
+<a name='create_templates_layout'/>
+h4. Layout
+
+Layouts are stored under the =doc/layouts= directory (by default). They may
+be organised into subdirectories, but this hierarchy is not connected to
+the hierarchy in =pages=. To apply a layout to a page, simply call the
+=Rote::Page.layout= method from code applied to that page, passing the
+base-name (and path, relative to =layouts=, if used). If no extension is
+specified, then the same extension as the page itself is assumed. Examples:
+
+<code><pre>
+	layout 'one'
+	layout 'main/wide'
+	layout 'dark.txt'
+	&lt;% layout 'my' %&gt;
+</code></pre>	
+
+With that done, Rote would first render the template text (including textile)
+and set the Page instance variable =@content_for_layout= before rendering 
+the layout (in which textile is currently not supported). The layout is
+responsible for inserting the rendered template where appropriate, with
+e.g.:
+
+<code><pre>        &lt;%= @content_for_layout %&gt;</code></pre>
+
+This pattern shouldn't be unfamiliar. Again, note that Rote doesn't mandate 
+HTML, despite the appearance from the ERB tags - any (textual) format can
+be templated and laid out.
+
+["top":#top]
+
+<a name='resources'/>
+h3. Resources
+
+Of course, you're likely to have resources for your site (images, sounds, etc)
+and you'll need to copy them over to the target too. Such resources should be
+placed under 'res' (with the commandline setup) or in your specified +res+
+directory, and will be copied directly to the output directory after page
+rendering.
+
+As you'd expect, the directory layout beneath =res= should mirror that of the 
+output, and will be preserved during the copy.
+
+["top":#top]
+
+<a name='publishing'/>
+h3. Publishing
+
+Rote does not provide any direct support for publishing your site at present,
+relying on you to configure an appropriate publish task if required, using
+the publishers supplied with Rake (in =rake/contrib=), or your own. This 
+allows maximum flexibility, and allows Rote to concentrate on creating your 
+documents.
+
+The command-line build will automatically look for a file in the top-level
+directory (above =doc=) named =publish.rf=. If found, this file will be 
+evaluated by Rake, making any tasks defined within it available to your
+build. The most likely use case is to define a task that uses an SSH directory
+publisher to publish via SCP.
+
+["top":#top]
+
+<a name='final_notes'/>
+h3. Final notes
+
+Currently, there isn't enough checking involved on source resources when
+building pages - Basically, only templates are considered when Rake decides
+what to update. If you change layouts, code or resources you'll need to run:
+	
+<pre><code>        rote clean</code></pre>
+		
+to make sure everything gets updated. It's recommended to always run upload
+as:
+	
+<pre><code>        rote clean upload</code></pre>
+	
+Please note that this isn't Rake's limitation - it's mine. It will be fixed
+in a later version of Rote.
+
+["top":#top]

data/doc/pages/index.html

@@ -1,5 +1,3 @@
-h2. Rote - A static website build tool for Ruby
-
 *Rote is a simple page-based template system that was written to make it 
 easier to author and maintain non-dynamic websites and 
 offline documentation.* Rote provides a simple commandline or 
@@ -9,12 +7,6 @@ rendering (optionally supporting Textile and Markdown with
 "ERB":http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html), layout,
 and general documentation / website build tasks.
 
-Rote is somewhat similar to (though simpler than) 
-"WebGen":http://webgen.rubyforge.org , which provides a richer environment
-geared more toward websites and content publishing (whereas Rote's
-implementation as an extension to Rake reflects a bias toward software 
-documentation).
-
 h3. Features
 
 Rote offers the following major features:
@@ -29,44 +21,31 @@ Rote offers the following major features:
 	* Supports any (text-based) format, while providing utilities and helpers for
 	  common formats (HTML at present).
 
-h3. So where is it?
+Rote is somewhat similar to (though simpler than) 
+"WebGen":http://webgen.rubyforge.org , which provides a richer environment
+geared more toward websites and content publishing (whereas Rote's
+implementation as an extension to Rake reflects a bias toward software 
+documentation).
+
+See the "User guide":<%= link_rel '/guide' %> and "RDoc":<%= link_rel '/rdoc' %> for usage information.
 
-The first release of Rote can be downloaded from "Our FRS on RubyForge":http://rubyforge.org/frs/?group_id=1120 .
-It should be also available as a RubyGem (rote-0.1.0) in the usual way.
-The "README":rdoc/files/README.html has the most comprehensive user guide at the moment.  Obviously, this
-site is still under construction too.
+h3. Download?
 
-You can also grab the latest code from "CVS":http://rubyforge.org/cgi-bin/viewcvs.cgi/?cvsroot=rote. 
+You can get Rote via "RubyGems":http://rubyforge.org/projects/rubygems if you have it:
 
-Please note that Rote is still pretty new, and while this first release is fairly functional, it's
-also still shiny and new, and liable to break down, destroy data, and run away with your spouse if
-given half a chance. Check out the "Project page on Rubyforge":http://rubyforge.org/projects/rote 
-for everything you need to get going with the CVS version.
+	* <strong><code>gem install -r rote</code></strong>
+
+Alternatively, you can download tarball / zip packages from: 
 
-h3. Licence
+  * <strong>"http://rubyforge.org/frs/?group_id=1120":http://rubyforge.org/frs/?group_id=1120</strong>
 
-<ul>
-<pre>
-<code>
-Copyright (c) 2005 Ross Bamford (and contributors)
+You can also grab the latest code from "CVS":http://rubyforge.org/cgi-bin/viewcvs.cgi/?cvsroot=rote. 
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in 
-the Software without restriction, including without limitation the rights to 
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
-of the Software, and to permit persons to whom the Software is furnished to do
-so, subject to the following conditions:
+h4. From CVS 
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+A link to the latest stable release can be found from the "project page":http://rubyforge.org/projects/rote .
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-</code>
-</pre>
-</ul>
+Please note that Rote is still pretty new, and while currently fairly functional, it's
+also still shiny and new, and liable to break down, destroy data, and run away with your spouse if
+given half a chance. Sound like fun? Then check out the "Project page on Rubyforge":http://rubyforge.org/projects/rote 
+for everything you need to get going with the CVS version!

data/doc/pages/index.rb

@@ -1,4 +1,8 @@
-# the default
-#layout 'page'
-
-@page_title = 'Welcome!'
+# Page code for 'index.html'
+#
+# In practice, for something this simple you'd usually go with setting
+# the var directly in the template, e.g.
+#
+#   <% @page_title = 'Welcome!' %>
+#
+@page_title = 'Welcome!'

data/doc/pages/license.html

@@ -0,0 +1,27 @@
+<% @page_title = 'Licence' %>
+
+<ul>
+<pre>
+<code>
+Copyright (c) 2005 Ross Bamford (and contributors)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in 
+the Software without restriction, including without limitation the rights to 
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+</code>
+</pre>
+</ul>

data/install.rb

@@ -85,5 +85,27 @@ for fn in files
   File::install(File.join('lib', fn), File.join($sitedir, fn), 0644, true)
 end
 
+$mandir = CONFIG['mandir']
+unless (!$mandir || CONFIG["target_os"] =~ /mswin/i)   # manpages not doable on windows?
+  files = Dir.chdir('doc/man') { Dir['*.gz'] }
+  for fn in files
+    # maybe in locale dir
+    fdn = File.dirname(fn)    
+    target_dir = $mandir
+    target_dir = File.join(target_dir, fdn) unless fdn == '.'
+    
+    fbn = File.basename(fn)    
+    if (fbn =~ /\.([0-9]*)(\.gz)?$/)
+      target_dir = File.join(target_dir,"man#{$~[1]}")
+    end      
+    
+    if ! File.exist?(target_dir)
+      File.makedirs(target_dir)
+    end
+    
+    File::install(File.join('doc/man', fn), File.join(target_dir, fbn), 0644, true)
+  end  
+end
+
 # and the executable
 installBIN("bin/rote", "rote")

data/lib/rote.rb

@@ -28,7 +28,7 @@ require_gem 'rake'
 require 'rote/rotetasks'
 
 # Master Rote version. Manage this from the Rake release support.
-ROTEVERSION = '0.1.2'
+ROTEVERSION = '0.1.6'
 
 #####
 ## *Rote* is a Rake (http://rake.rubyforge.org) based build tool for page-based

data/lib/rote/dirfilelist.rb

@@ -1,5 +1,9 @@
 module Rote
 
+
+# TODO untested
+
+
   # An extension to the Rake +FileList+ class that allows a root
   # directory to be specified.
   class DirectoryFileList < FileList  
@@ -8,17 +12,17 @@ module Rote
     # patterns. You may also pass a block to perform additional
     # configuration (e.g. if you have a lot of includes/excludes
     # or just don't like arguments for whatever reason).
-    def initialize(basedir = '.', *patterns)
-      dir=(basedir)
+    def initialize(basedir = '.', *patterns)      
       super(*patterns)
+      self.dir = basedir
     end
   
     # The root directory from which this filelist matches. All patterns
     # are considered relative to this directory.
-    attr_accessor :dir        
+    attr_reader :dir        
     def dir=(newdir)
       newdir = newdir.sub(/\/$/,'')
-      sub!(/^#{@dir}/,newdir)
+      self.sub!(/^#{@dir}/,newdir) unless self.empty?
       @dir = newdir    
     end
    

data/lib/rote/page.rb

@@ -33,7 +33,7 @@ module Rote
     # The default is [], which means 'No formatting'. This setting
     # does not affect ERB rendering (which is always performed, before
     # any formatting).
-    attr_accessor :format_opts
+    attr_reader :format_opts
     def format_opts=(opts)
       if !opts.nil? && opts.respond_to?(:to_ary)
         @format_opts = opts

data/lib/rote/rotetasks.rb

@@ -91,8 +91,10 @@ module Rote
     def define_page_tasks
     
       # define a task for each page
+      realpages = FileList[]
       pages.each { |fn| 
         unless File.directory?(fn)    # make dirs only as needed
+          realpages << fn
           tfn = fn.sub(/#{pages.dir}/, output_dir)
           
           desc "#{fn} => #{tfn}" if show_page_tasks?
@@ -109,7 +111,7 @@ module Rote
       
       # this is pretty convenient ;]
       desc "Render all documentation pages"
-      task "#{name}-pages" => pages.sub(/#{pages.dir}/, output_dir)
+      task "#{name}-pages" => realpages.sub(/#{pages.dir}/, output_dir)
     end
     
     def define_main_tasks

metadata

@@ -1,10 +1,10 @@
-!ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification 
 rubygems_version: 0.8.11
 specification_version: 1
 name: rote
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
-date: 2005-11-26 00:00:00 +00:00
+  version: 0.1.6
+date: 2005-11-28 00:00:00 +00:00
 summary: Adds template-based doc support to Rake.
 require_paths: 
 - lib
@@ -61,6 +61,7 @@ files:
 - doc/res
 - doc/jamis.rb
 - doc/pages
+- doc/man
 - doc/layouts
 - doc/res/images
 - doc/res/stylesheets
@@ -78,7 +79,12 @@ files:
 - doc/res/stylesheets/normal.css
 - doc/pages/COMMON.rb
 - doc/pages/index.html
+- doc/pages/guide
+- doc/pages/license.html
 - doc/pages/index.rb
+- doc/pages/guide/COMMON.rb
+- doc/pages/guide/index.html
+- doc/man/rote.1.gz
 - doc/layouts/page.html
 test_files: []