hello 0.0.0 → 0.0.1

data/CHANGELOG

@@ -1,5 +1,15 @@
+= Version 0.0.1
+=== Sat May 12 15:56:51 CEST 2007
+* rubygem doesn't play nice with Version 0.0.0 ...
 
 = Version 0.0
+=== Wed Oct  4 22:31:04 CEST 2006
+* split up README into several smaller files.
+* added inline docs to hello.rb
+=== Sat Sep 16 20:00:00 CEST 2006
+* added some notes about Rubyforge and rdoc.
+* added THANKS
+* added Rake Task to upload generated docs to Rubyforge.
 === Wed Sep 13 23:37:13 CEST 2006
 * added gem task
 *       clean
@@ -7,3 +17,5 @@
 
 * Started development
 * Directory structure, README and CHANGELOG
+
+back[link:files/README.html]

data/README

@@ -4,12 +4,20 @@
 This package contains a hello project which is meant to provide
 suggestions concerning how to structure and package ruby projects.
 
-* how to structure project directories
-* which auxilliary files to include in a distribution (README,
-  CHANGELOG, etc)
-* providing source code documentation using +rdoc+
-* approriate unit test using +runit+
-* build support using +rake+
+* How to structure[link:files/doc/files_and_directories_rdoc.html]
+  project directories, which auxilliary files to
+  include in a distribution (README, CHANGELOG, etc)
+* providing source code documentation[link:files/doc/rdoc_rdoc.html] 
+  using +rdoc+ approriate unit test
+* {Automating tasks}[link:files/doc/rake_rdoc.html] using +rake+
+* {Functional testing}[link:files/doc/functional_testing_rdoc.html] 
+  using +Test+::+Unit+ build support using +rake+
+* {Packaging and distributing}[link:files/doc/rubygems_rdoc.html] your project using +rubygems+.
+* {Configuration}[link:files/doc/config_rdoc.html] and resource files.
+* Internationalizing[link:files/doc/i18n_rdoc.html] your application or library.
+* Providing (and parsing) proper {command line options}[link:files/doc/commandline_rdoc.html]
+* Handling {plattform specific}[link:files/doc/plattform_rdoc.html] issues.
+* {Distributing and promoting}[link:files/doc/dist_rdoc.html] your project.
 
 None of the suggestions here are set in stone, so feel free to do things
 diffrently if you feel it makes more sense. (I prefer to indent using
@@ -17,105 +25,43 @@ tabs not spaces, which is the 'norm' in ruby). Consider this project to
 be a template that might help you through the tedium of setting up a
 project infrastructure to help you get coding real stuff quicker.
 
-
-== Files and Directories
-
-Providing the typical distribution files and directory structure that a
-programmer expects make it easier for others to work with a freshly
-unpacked package. Just imagine a world where everyhting is where you
-expect it. Birds chirping peacefully be the stream, a README containing
-all the information you need, and not long winded musings ...
-
-* +README+ first stop for users of the package. Should contain
-  general information what the project is about, how to install, where
-  to get help.
- 
-* +CHANGELOG+ contains information about what changed between diffrent
-  revisions of the software. Some packages like to call this file
-  +RELEASES+.
-
-* +LICENSE+ should contain information about the license
-  that the software is provided under. This file is sometimes called
-  +COPYING+, especially if it contains the GPL.
-
-* +AUTHORS+ lists contributors to the project, a short description of
-  their contribution and how they can be reached.
-
-* +TODO+ things left laying around. Stuff you never get around doing.
-  Boring crap.
-
-* +Rakefile+ just like a +Makefile+, only for ruby. If you don't know what
-  either +make+ or +rake+ is: they're tools to automate tedious
-  repetitive stuff (called tasks) that need to be done during certain
-  stages of your project, like creating packages, uploading stuff to
-  repositories and to figure out if all dependancies for the task at
-  hand are met. But you either already knew that or if not most likely
-  still don't understand what +rake+ is about, so look around
-  here[http://rake.rubyforge.org/].  Actually that probably wouldn't
-  help much either, maybe try
-  this[http://jimweirich.umlcoop.net/index.cgi/Tech/Rake/Tutorial/RakeTutorialIntroduction.rdoc]
-  or this[http://docs.rubyrake.org/] or google around a little bit.
-
-* +gemspec+ the specification for the +gem+ packaging is sometimes
-  maintained in a seperate file, but it's easiest to just pack it into
-  the +Rakefile+.
-  
 == Installing
 
-TODO: installing per gem.
-
-Currently, there's really nothing to install. In future, you should be
-able to install this via:
+Having a "Installing" section is a bit of a chicken or egg question.
+Someone reading the README has, in all likelyhood already installed your
+package. On the other hand, in case your project has a more involved
+build process, it might be worthwhile to consider describing it in a
+seperate INSTALL file.
 
-	gem install hello
+It can't hurt to provide canonical instructions for installation,
+though. You can install the +hello+ package by executing:
 
-but that won't work until we get things sorted out. If you're reading
-this, chances are you've already downloaded the package
-here[http://www.kuriositaet.de/ruby/hello].
+	gem install hello -r
 
-	
+alternatively, you can download +.tar.gz+ or +.zip+ archives from 
+Rubyforge[http://rubyforge.org/frs/?group_id=2203].
 
-== Tools
 
-=== Documentation using +rdoc+
+== Mailing List
 
-Ruby source code is typically documented with the +rdoc+ tool. +rdoc+ is
-included with Ruby distributions and can generate documenation directly
-from the sources and the included comments. +Markup+ may be used to format
-comments just like in the file. More information about +rdoc+ and
-+markup+ can be found
-here[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/classes/RDoc.html].
-
-=== Unit Testing using +runit+
+In case you discover bugs, spelling errors, offer suggestions for
+improvements or would like to help out with the project, you can contact
+me directly (tim@kuriositaet.de) or through the mailing list
+(hello-talk@rubyforge.org).
+	
 
-=== Build Support using +rake+
 
-+rake+ belongs to the defacto standard toolset for ruby. It's basically
-the ruby equivalent of +make+ in that it's a tool for dealing with
-dependancies and automating routine tasks. The tasks typically expected
-to be in a +Rakefile+ are:
 
-* clean - remove all temporary, intermediary and generated files
-* rdoc - generate +rdoc+ documentation 
-* test - run the packages test suite
-* package - assemble all the necessary files into a package for
-  distribution
 
 
 
 
-=== Packaging using +rubygems+
 
 
 
-== Commandline usage
 
-== Plattform Specific Issues
 
-== Distributing and Promoting the Project
 
-=== rubygems
-=== rubyforge sourceforge
-=== Ruby Application Archive
 
 
+=

data/Rakefile

@@ -1,8 +1,20 @@
 require "rake/rdoctask"
 require "rake/gempackagetask"
+require "rake/testtask"
 require "rake/clean"
 require "rubygems"
 
+# Some definitions that you'll need to edit in case you reuse this
+# Rakefile for your own project.
+
+SHORTNAME	='hello'	# this should be the rubyforge project name
+DESC		='An example Ruby project'
+PKG_VERSION 	='0.0.1'
+LONG_DESC	= <<END_DESC
+	This is a short project description.
+END_DESC
+RUBYFORGE_USER	='a2800276'
+
 # Specifies the default task to execute. This is often the "test" task
 # and we'll change things around as soon as we have some tests.
 
@@ -32,12 +44,12 @@ Rake::RDocTask.new do |rd|
 	# documenation from.
 	rd.rdoc_files.include(	"README", "AUTHORS", "LICENSE", "TODO",
 				"CHANGELOG", "bin/**/*", "lib/**/*.rb", 
-				"examples/**/*rb","test/**/*.rb")
+				"examples/**/*rb","test/**/*.rb", "doc/*.rdoc")
 	# This one specifies the output directory ...
 	rd.rdoc_dir 	= "doc/html"
 
 	# Or the HTML title of the generated documentation set.
-	rd.title 	= "hello: Exemplary Documenation"
+	rd.title 	= "#{SHORTNAME}: #{DESC}"
 
 	# These are options specifiying how source code inlined in the
 	# documentation should be formatted.
@@ -56,30 +68,57 @@ end
 
 # First you'll need to assemble a gemspec
 
-PKG_VERSION 	= "0.0.0"
 PKG_FILES 	= FileList['lib/**/*.rb', 'bin/**/*', 'examples/**/*', '[A-Z]*', 'test/**/*'].to_a
 
 spec = Gem::Specification.new do |s|
 	s.platform = Gem::Platform::RUBY
-	s.summary = "hello: an exemplary ruby project."
-	s.name = 'hello'
+	s.summary = "#{SHORTNAME}: #{DESC}"
+	s.name = SHORTNAME
 	s.version = PKG_VERSION
 	s.files = PKG_FILES
 	s.requirements << "none"
 	s.require_path = 'lib'
-	s.description = <<END_DESC
-This is a short description
-END_DESC
+	s.description = LONG_DESC
 end
 
-
+# Adding a new GemPackageTask adds a task named `package`, which generates
+# packages as gems, tarball and zip archives.
 Rake::GemPackageTask.new(spec) do |pkg|
 	pkg.need_zip = true
 	pkg.need_tar_gz = true
 end
 
-task :test do 
-	puts "hello"
+
+# This task is used to demonstrate how to upload files to Rubyforge.
+# Calling `upload_page` creates a current version of the +rdoc+
+# documentation and uploads it to the Rubyforge homepage of the project,
+# assuming it's hosted there and naming conventions haven't changed.
+#
+# This task uses `sh` to call the `scp` binary, which is plattform
+# dependant and may not be installed on your computer if you're using
+# Windows. I'm currently not aware of any pure ruby way to do scp
+# transfers.
+
+RubyForgeProject=SHORTNAME
+
+desc "Upload the web pages to the web."
+task :upload_pages => ["rdoc"] do
+  if RubyForgeProject then
+    path = "/var/www/gforge-projects/#{RubyForgeProject}"
+    sh "scp -r doc/html/* #{RUBYFORGE_USER}@rubyforge.org:#{path}"
+    sh "scp doc/images/*.png #{RUBYFORGE_USER}@rubyforge.org:#{path}/images"
+  end
 end
 
+# This task will run the unit tests provided in files called
+# `test/test*.rb`. The task itself can be run with a call to `rake test`
+
+Rake::TestTask.new do |t| 
+	t.libs << "test" 
+	t.libs << "lib" 
+	t.test_files = FileList['test/*.rb'] 
+	t.verbose = true 
+end
+
+
 

data/THANKS

@@ -0,0 +1,4 @@
+
+John Gabriele <jmg3000@gmail.com> provided general input, especially
+concerning Rubyforge.
+James Britt <jbritt@ruby-doc.org> general input and encouragement.

data/TODO

@@ -1,8 +1,23 @@
-There's so much left to do that I don't even know where to start.
+There's so much left to do that I don't even know where to start. These are
+just notes.
 
 * Rakefile task for submitting to rubyforge. 
-* Dealing with Verison Control, automating tagging etc. in Rakefile
+  xforge vs. rubyforge (...)
+* Dealing with Version Control, automating tagging etc. in Rakefile
 
 * source code commenting
 * command line arguments
 * dealing with c extensions
+
+* unit testing (runit rcov)
+* template for project structure.
+
+* dealing with `data` files (e.g. ZIP code data)
+* dealing with non ruby bits (sql, c)
+
+* i18n figure out how to link between documentation files without silly
+* link notation
+* Release checklist (rubyforge stuff, packaging, updated documentation,
+  announcements: mailing lists/RAA/other listings) 
+ 
+

data/lib/hello.rb

@@ -0,0 +1,57 @@
+#-- 
+# hello.rb: provide proper boilerplate docs in all sourcefiles
+# specifing the author, license, and possibly some quick info about the
+# file. You can surround the boilplate comments with '--' and '++' like
+# we've done here to make sure it doesn't get included in the generated
+# documentation.
+#
+#
+# Copyright (c) 2006 by Tim Becker (tim@kuriositaet.de) All rights
+# Reserved.
+#
+# This is free software.  You may modify and redistribute this freely
+# under your choice of the GNU General Public License or the Ruby
+# License.
+#
+# See LICENSE for details
+#
+# BTW: The above does not constitute legal advice concerning how to
+# handle code licensing issues.
+#++
+
+
+# Ruby Modules may be nested in order to provided namespaces.
+module Well
+# Each nested module can have it's own documenation.
+module Tempered
+# Lowest level of module nesting.
+module Application
+
+# Comments providing general descriptions of constructs like modules and
+# classes should be provided where these are defined. The class Hello
+# provides basically no functionality. It's only here to contain some
+# demonstration code and in order for me to document it. 
+class Hello
+	# the constructor of the Hello class
+	#
+	def intialize name=nil
+		@name=name
+	end
+
+	# the namesake of the Hello class. Provides the well loved
+	# +helloworld+ functionality.
+	def hello
+		puts "Hello #{name?', ':''}#{@name}!"	
+	end
+
+
+end
+
+# some function that does nothing. Located outside of the Hello class.
+def some_function
+
+end
+
+end # module Application
+end # module Tempered
+end # module Well

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.8.11
+rubygems_version: 0.9.2
 specification_version: 1
 name: hello
 version: !ruby/object:Gem::Version 
-  version: 0.0.0
-date: 2006-09-14 00:00:00 +02:00
-summary: "hello: an exemplary ruby project."
+  version: 0.0.1
+date: 2007-05-12 00:00:00 +02:00
+summary: "hello: An example Ruby project"
 require_paths: 
 - lib
 email: 
 homepage: 
 rubyforge_project: 
-description: This is a short description
+description: This is a short project description.
 autorequire: 
 default_executable: 
 bindir: bin
@@ -25,17 +25,19 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 signing_key: 
 cert_chain: 
+post_install_message: 
 authors: []
 
 files: 
 - lib/hello.rb
+- AUTHORS
 - CHANGELOG
+- COPYING
 - LICENSE
 - Rakefile
-- AUTHORS
-- TODO
-- COPYING
 - README
+- THANKS
+- TODO
 test_files: []
 
 rdoc_options: []