inochi(1)

inochi(1)
Version 2.0.0
inochi(1)

NAME

inochi - Gives life to Ruby projects

ABOUT

Inochi is an infrastructure for Ruby projects that helps you test, document, package, publish, and announce your projects. It encourages great documentation and reduces project administrivia.

Features

Provides a comprehensive help manual that is written in eRuby over Markdown and is rendered into a Web page and a UNIX manual page.
Announces project releases on RAA, ruby-talk, and via RSS feed.
Stores project information in a single Ruby source file.

Resources

Issue tracker (report bugs, request features, get help): http://github.com/sunaku/inochi/issues
Source code (browse online or obtain with Git): http://github.com/sunaku/inochi
API documentation: http://snk.tuxfamily.org/lib/inochi/api/
Announcements feed: http://snk.tuxfamily.org/lib/inochi/ann.xml
Official website: http://snk.tuxfamily.org/lib/ember/

Setup

Prerequisites:

Ruby 1.8.6 or newer.
RubyGems 1.3.6 or newer.
Lynx 2.8.6 or newer.

Installing:

gem install inochi

Upgrading:

gem update inochi

Removing:

gem uninstall inochi

SYNOPSIS

inochi [OPTIONS] TASK [RAKE_OPTIONS]

DESCRIPTION

Runs TASK using rake(1), to which RAKE_OPTIONS (see rake --help output) are passed. The following tasks are available for running:

ann: Build all release announcements.
ann:feed: Build RSS feed announcement.
ann:html: Build HTML announcement.
ann:text: Build plain text announcement.
api: Build API documentation.
clean: Remove any temporary products.
clobber: Remove any generated file.
gem: Build release package for RubyGems.
init: Instill Inochi into current directory.
man: Build the help manual.
pub: Publish a release of this project.
pub:ann: Announce release on all news outlets.
pub:ann:raa: Announce release on RAA (Ruby Application Archive).
pub:ann:ruby-talk: Announce release on ruby-talk mailing list.
pub:gem: Publish gem release package to RubyGems.org.
pub:web: Publish help manual, API docs, and RSS feed to project website.

OPTIONS

-h, --help: Display this manual and exit.
-v, --version: Print version number and exit.

inochi init

Instill Inochi into current directory.

SYNOPSIS

inochi init project=PROJECT [package=PACKAGE] [merger=MERGER]

DESCRIPTION

Installs the Inochi infrastructure for the project (see PROJECTS below) named PROJECT into the current working directory, or upgrades a previous installation thereof.

Pre-existing files are not overwritten. Instead, it is your responsibility to merge changes (hopefully with the aid of an automated text merging tool; see MERGER below) between pre-existing and newly generated files.

PARAMETERS

PROJECT: Name of the project. This will be normalized into the name of a Ruby module that will serve as a namespace for all code in the project.
PACKAGE: Name of the project's package directory, shell command, and basename of the project library file.
MERGER: Command that invokes a text merging tool with three arguments: (1) old file, (2) new file, (3) output file. The command should direct the result of merging the old file and the new file to the output file. In addition, the command must not modify the old file or the new file.

TIP: Instead of merging files by hand, you can transfer wanted changes between files semi-automatically using a text merging tool such as meld, kdiff3, or tkdiff as follows:
1. Create a file named merge2 containing the following text:
```
#!/bin/sh
old=$1; new=$2; out=$3;
# meld "$new" "$out"                            # use meld
# kdiff3 --merge "$old" "$new" --output "$out"  # use kdiff3
# tkdiff "$old" "$new" -o "$out"                # use tkdiff
```
2. Uncomment the line corresponding to the tool you wish to use.
3. Make the file executable:
```
chmod +x merge2
```
4. Pass the file's path as the value of MERGER:
```
inochi init merger=path/to/merge2
```
Now your chosen text merging tool will be launched to help you transfer your changes. When you are finished, save the merged file and exit the merging tool. If you do not want to transfer any changes, then simply exit the merging tool without saving any changes to the merged file!

NOTIFICATIONS

create FILE: A file is being created because it does not exist.
skip FILE: A file is being skipped because it is already up to date.
update FILE: A file is being updated because it is out of date. A text merging tool (see the merger parameter above) will be launched to transfer content from the old file (*.old) and the new file (*.new) to the out of date file. If a text merging tool is not specified, then you will have to do the merging by hand.

inochi api

Builds API documentation for the project's Ruby library using YARD. Ruby constructs marked with @private are omitted from the API documentation.

inochi man

Renders the help manual's source files (see Help manual below) into:

man.ronn: Ronn format, rendered by Ember.
man.html: HTML (Web page) format, rendered by Ronn.
man/man1/PACKAGE.1.gz: Roff (UNIX manual page) format, rendered by Ronn.

inochi gem

Builds a release package in RubyGems format (plainly known as a gem):

PACKAGE-VERSION.gem: The gem itself.
PACKAGE-VERSION.gemspec: Ruby representation of the gem's specification.

The gem specification is pre-initialized with information from the project's Ruby library and help manual. In particular:

gem.description

Plain text version of all content between the ABOUT heading and any subsequent heading.

gem.authors

Plain text version of all content between the AUTHORS or CREDITS heading (whichever comes first) and any subsequent heading.

gem.files

Only contains the project's LICENSE and CREDITS files, rendered help manual, Ruby library, shell command, and C extension.

All other files (such as the test suite and help manual source files) are omitted (1) to reduce the gem file size and (2) because they are really only needed during development.

The gem specification can be further customized through the :gem_spec_logic parameter defined in the project's options file (see Options file below).

inochi ann

Builds release announcements which can be edited by hand before publishing:

ann.html: Web page version of the release announcement.
ann.txt: Plain text version of the release announcement; converted from the Web page version by Lynx.
ann.xml: RSS feed version of the release announcement.

inochi pub:ann:ruby-talk

Announces the release on the ruby-talk mailing list.

It is recommended that you build, review, and edit the ann.txt file by hand before running this command because (1) the body of that file is published directly as the announcement message and (2) HTML to plain text conversion is not perfect.

inochi pub:web

Publishes the help manual, API documentation, and RSS feed to project website using rsync(1) according to the :pub_web_* parameters defined in the project's options file (see Options file below).

PROJECTS

A project instilled with Inochi is composed of an options file, a license, source code, documentation, and a Web presence; which are all explained below.

Options file

A project's options file is a YAML document named inochi.opts that defines the following optional parameters for the various inochi(1) sub-commands:

:pub_web_target

Location where inochi pub:web will upload files. This value can use any local/remote/protocol syntax supported by rsync(1).

:pub_web_options

Options for rsync(1), which uploads files for inochi pub:web.

:pub_web_extras

Additional files for inochi pub:web to upload. The values listed here can use any local/remote/protocol syntax supported by rsync(1).

Example:

:pub_web_extras:
  - some/file
  - some_user@some_host:some/path

:gem_spec_logic

Arbitrary Ruby code that will configure this project's RubyGem before it is built by inochi gem. This code has access to a local variable named gem which holds a Gem::Specification object representing this project.

Example:

:gem_spec_logic: |
  # show the Inochi-provided specification for this project's gem
  puts gem.to_ruby

  # add files that are outside this project directory to the gem
  gem.files += ['some', 'files', 'in', 'this', 'directory']

  # omit some added files in this project's directory from the gem
  gem.files -= ['lib/top_secret.rb', 'bin/more_top_secret_stuff']

  # and so on...  anything is possible!  use your imagination!

License file

A project's license defines the legal conditions under which the project is developed and distributed. It is stored in a file named LICENSE at the root of the project directory.

Ruby library

A project's Ruby library is composed of the following files:

lib/PACKAGE.rb: Defines the project's namespace (Ruby module or class) and registers sub-libraries to be automatically loaded on demand (Kernel#autoload).
lib/PACKAGE/inochi.rb: Defines project information in Ruby constants within the project's namespace (Ruby module or class). Also defines a require class method on the project's namespace that loads the correct version (as defined by the project's dependency information) of a given gem if RubyGems is available.

Test suite

A project's test suite is composed of the following files:

test/runner: Executable Ruby script that hides the details of running the test suite.
test/test_helper.rb: Ruby source file that prepares the testing environment by loading a testing library and defining common knowledge and utility logic shared by the actual tests.
test/**/*_test.rb: Part of the test suite. Performs the actual testing.

Shell command

A project's shell command is an executable Ruby source file that serves as a gateway into the project's Ruby library from the command line:

bin/PACKAGE: Expects the project's lib/ directory to be on Ruby's $LOAD_PATH (see HACKING below). This requirement is automatically met when a user installs the project using RubyGems.

Help manual

A project's help manual is a monolithic eRuby template that is (1) processed by Ember with its shorthand notation, hierarchical unindentation, and missing <% end %> inference features enabled, and (2) composed of the following source files:

MANUAL: Primary source file of the help manual that (1) defines common knowledge and utility logic and (2) divides its content into the following files for easier editing and maintenance.
README: Introduces the project, its Web presence, and gives setup instructions.
USAGE: Explains how to use the project's shell command.
EXAMPLES: Illustrates how to perform common tasks with the project's shell command and Ruby library, respectively.
HACKING: Instructs fellow software developers on running, testing, and hacking the project's source code.
HISTORY: Records notes about current and past releases of the project in terms of incompatible changes, new features, bug fixes, and housekeeping activities.
CREDITS: Attributes all developers and contributors whose efforts have made the project what it is today.
FURTHER: Refers to related commands, help manuals, and topics beyond this project.

Web presence

A project's a Web presence is composed, at minimum, of the following:

Code repository: Where fellow software developers can obtain the latest source code.
Issue tracker: Where users and contributors can submit patches, request features, and get help.
Official website: Where the help manual, API documentation, and announcements RSS feed can be accessed (hopefully) permanently.

You may choose to omit some or all of these components by simply not mentioning them in the Resources section of the help manual's README source file.

HACKING

This section is meant for people who want to develop Inochi's source code.

Prerequisites

Install Ruby libraries necessary for development:

gem install inochi --development

Infrastructure

Inochi serves as the project infrastructure for Inochi. It handles tasks such as building this help manual and API documentation, and packaging, announcing, and publishing new releases. See its help manual and list of tasks to get started:

inochi --help     # display help manual
inochi --tasks    # list available tasks

$LOAD_PATH setup

Ensure that the lib/ directory is listed in Ruby's $LOAD_PATH before you use any libraries therein or run any executables in the bin/ directory.

This can be achieved by passing an option to Ruby:

ruby -Ilib bin/inochi
irb -Ilib -r inochi

Or by setting the $RUBYLIB environment variable:

export RUBYLIB=lib   # bash, ksh, zsh
setenv RUBYLIB lib   # csh
set -x RUBYLIB lib   # fish

ruby bin/inochi
irb -r inochi

Or by installing the ruby-wrapper tool.

RubyGems setup

If you use Ruby 1.8 or older, then ensure that RubyGems is activated before you use any libraries in the lib/ directory or run any executables in the bin/ directory.

This can be achieved by passing an option to Ruby:

ruby -rubygems bin/inochi
irb -rubygems -r inochi

Or by setting the $RUBYOPT environment variable:

export RUBYOPT=-rubygems   # bash, ksh, zsh
setenv RUBYOPT -rubygems   # csh
set -x RUBYOPT -rubygems   # fish

Running tests

Simply execute the included test runner, which sets up Ruby's $LOAD_PATH for testing, loads the included test/test_helper.rb file, and then evaluates all test/**/*_test.rb files:

test/runner

Its exit status will indicate whether all tests have passed. It may also print additional pass/fail information depending on the testing library used in the test/test_helper.rb file.

Contributing

Fork this project on GitHub (see Resources above) and send a pull request.

VERSIONS

This section contains release notes of current and past releases.

Version 2.0.0 (2010-04-24)

This release makes Inochi a development-time dependency only, documents nearly everything in the help manual, renders the help manual as a UNIX manual page, simplifies the project infrastructure it provides, and removes needless cruft.

Incompatible changes:

Inochi is no longer a runtime dependency (gem or otherwise) for projects that use it. It also no longer runs tests, creates project namespaces, or provides libraries for internationalization, combinatorics, command-line parsing, utility logic, or Rakefiles.

See PROJECTS to learn about the new Inochi infrastructure.
The help manual is now processed by Ronn instead of ERBook. As a result, you may only use plain Markdown and eRuby when writing it.
Announcement publishing tasks no longer read login information from the ~/.config/inochi/logins.yaml file and prompt you to enter that information manually instead. As a result, the forementioned file is no longer recognized or used by Inochi so you may safely delete it.

New features:

The help manual is now available as a UNIX manual page (thanks to Ronn) and is now divided into smaller files that can be read directly without needing a special viewer, and are named according to open-source packaging conventions (such as README, HACKING, and LICENSE) so that they draw the attention of users unaccustomed to the organization of your project.
A require class method is now added to the project's namespace. This method verifies that the library or gem being required meets the dependency version constraints defined by the project.
A test/runner script is now generated. It provides a fast, self-contained way to run your project's test suite.
Inochi is now a Rake application. A Rakefile is not necessary.

Housekeeping:

Many KISS and YAGNI fueled iterations later, this is it! :-)
Nearly every aspect of Inochi is now meticulously documented in the help manual to the best of my ability. If I missed something important, please notify me or contribute the correction yourself!

Version 1.1.1 (2009-10-03)

This release improves Ruby 1.9 support and upgrades gem dependencies.

Bug fixes:

require() was unable to find project library in Ruby 1.9.2dev.
Ruby 1.9 warning about "shadowing outer variable".
Ruby 1.9 error about "incompatible encoding regexp match".

Housekeeping:

The "spicycode-rcov" project was officially renamed to "relevance-rcov".
Upgrade to RubyForge 2.x library for publishing gems.

Version 1.1.0 (2009-09-06)

This release improves the user manual and scaffold generator output, injects more metadata into gems, adds support for Microsoft web browsers, and fixes some bugs.

New features:

Add instructions for building gems without Inochi as a runtime dependency.
Put release notes in "description" field of gemspec, as suggested by Eric Hodel, so that subscribers of the RubyForge gems feed are aware of the changes in a published gem.
Set the "date" field in gemspec to project release date.
Change file extension of generated user manuals from .xhtml to .html to accomodate Microsoft web browsers' inability to process the application/xhtml+xml mime type.

Bug fixes:

The sdoc library was necessary to run 'rake test'.
Forgot to add :develop option to scaffold generator output.
Make "rake lang:dump" unconditionally overwrite the dump file.
Fix gem not being built and prevent Maruku errors for the dummy "WordCount" project in the user manual.
Use /usr/bin/env instead of /usr/bin/ruby to launch Ruby for better portability.

Housekeeping:

Use simpler Copyright reminder at the top of every file.
Open source is for fun, so be nice: speak of "related works" instead of "competitors".
Rename "Tutorial" to "General walkthrough" in user manual and add a "Specific topics" section for housing uncommon use cases.
Remove "logistics" section and redistribute its contents in more suitable locations in the user manual.

Version 1.0.0 (2009-05-03)

This release allows your gems to not depend on Inochi, lets you choose which unit testing library to use, adds new utility libraries and rake tasks, and fixes some bugs.

Incompatible changes:

Your program is no longer halted by Inochi.init() and Inochi.rake() if gem dependencies are not satified. A warning is issued instead.
The project_summary and project_history nodes, which are provided by Inochi.book() to the user manual, have been renamed to project and history respectively.
ERBook 7.1.0 is now used for generating the user manual. This is a major step up from the previous version, and so it has incompatible changes. See its release notes for details.
SDoc is now used to generate API documentation instead of YARD. If you link to particular classes or methods in the generated API documentation, be sure to update your link addresses!
Minitest is no longer the default testing library. You must specify which testing library you want to use via the :test_with option of the Inochi.rake() method. See the "Test execution" section for details.
The "pak" rake task, which is provided by Inochi.rake(), has been renamed to "gem".

New features:

Add :inochi_consumer and :inochi_producer options to Inochi.rake() which allows you to avoid having Inochi as a runtime and development dependency, respectively, for your project's gem.

This is useful if you just want to use Inochi facilities for building a gem for a pure Ruby library that does not have any need for Inochi's runtime convenience facilities.
Add :develop option for Inochi.init() which lets you specify RubyGems as development dependencies in the same way as the :require option.
Add "lint" rake task which reports code quality statistics.
Add "test:cov" rake task which reports code coverage statistics.
Add "test:ruby" task which runs all tests with multiruby.
Add 'rake opts=' environment variable, which lets you specify command-line arguments directly to the Ruby interpreter, for all test* rake tasks.
Add inochi/util/combo combinatorics library for enumerations, permutations, and combinations which are all useful in exhaustive brute-force unit testing.
Add inochi/util/tempdir library which really should be in the Ruby standard library.

Bug fixes:

The "enable email notification" checkbox was not activated properly when posting announcement to ruby-talk mailing list via Ruby-Forum.
Mark gems needed by Inochi.rake() as development dependencies.

Users must now run gem install Inochi --development to install these dependencies. This also solves the recursive dependency problem between Inochi and ERBook.
Set executable in gem specification only if it exists.
Fix parsing of stack trace in Ruby 1.9.

Housekeeping:

Write contributor names in CREDITS file instead of in the user manual.
Use completely lowercase name for Rakefile.
Add copyright statement at the top of every source file.

Version 0.3.0 (2009-02-12)

This release adds support for language translations, improves the user interface, and fixes a show-stopper bug for Windows users.

New features:

Add support for language translations of phrases used in a project.
- Add "lang:dump" Rake task for extracting language phrases from project.
- Add "lang:conv" Rake task for translating dumped phrases into various languages using the BabelFish translation service.
- Add --locale option to a project's main executable for setting user's preferred language in spite of the user's locale environment.
Notify user when attempting to publish announcements in the "pub" Rake tasks.

Bug fixes:

In Windows, ENV['USERPROFILE'] gives the path to the user's home directory and ENV['HOME'] is not defined.
The only real solution to the circular gem dependency problem is:
```
gem install --force
```
You should update the "Setup" section in your projects' user manuals accordingly.

Housekeeping:

Break the huge lib/inochi/inochi.rb library into smaller files.
Instead of adding methods to singleton classes directly, define modules and extend to them so that YARDoc documents the methods appropriately.
List all project contributors globally in the "Credits" section.
Remove "Contributor kudos" paragraph in release notes in favor of crediting contributors inline with each item in the release notes.
Mention that the project license is ISC for the reader's convenience.

Version 0.2.0 (2009-01-25)

This release adds support for unit testing, improves the portability of Inochi and configurability of your projects, adds new content to the user manual, and fixes some bugs.

New features:

Added support for unit testing via the minitest library.
- The scaffold generator now emits a default unit test for the main project library.
Added optional ProgramName parameter to the scaffold generator. This allows you to specify reasonable program names when your project module has a strange capitalization:
```
$ inochi ERBook
create er_book/LICENSE

$ inochi ERBook erbook
create erbook/LICENSE

$ inochi ERBook foobar
create foobar/LICENSE
```
Allow project authors to be specified via Inochi.init :YourProject, :authors => [['name', 'mail']] (thanks to Florian Gilcher)

Bug fixes:

Run on both JRuby and normal Ruby in multiple versions and with different executable names on Windows. (thanks to Florian Gilcher)
Use Gem::RubyGemsVersion instead of a shell command to determine rubygems version for generation of setup.erb. (thanks to Florian Gilcher)
Add blank lines between all list items, not just multi-line ones, in the plain-text version of the release announcement for improved readability.
Omit LaTeX-style heading numbers from release announcements. They caused confusion, especially in plain-text announcements, when trying to determine which version of a project was released.

Housekeeping:

Added unit tests for utility methods provided by the Inochi module: project name calculation and CamelCase to snake_case conversion.

Version 0.1.0 (2009-01-13)

This release reattempts to fix the circular dependency problem that occurred when installing either Inochi or ERBook.

New features:

Inochi.init() now adds #major(), #series(), and #requirement() instance methods to a project's VERSION constant.

Bug fixes:

Solved circular dependency problem by making inochi gem not dependent on erbook gem. However, ERBook is still required during runtime and is supplied on the gem install command for Inochi.

The "Installing" section has been updated accordingly.
Add forgotten Rake dependency for Inochi gem.

Version 0.0.1 (2009-01-13)

This release fixes some show-stopper bugs.

Bug fixes:

The name of the project library was being determined incorrectly. (thanks to Florian Gilcher)
There was a circular dependency problem when installing the Inochi gem. (thanks to Florian Gilcher)

The solution is to specify the --force option when installing the gem. The "Installing" section has been updated accordingly.
Generated project scaffolds now check against the major version of the Inochi gem, to avoid runtime version conflicts.

Housekeeping:

Only add project libraries to $LOAD_PATH if not already there.

Version 0.0.0 (2009-01-13)

This is the first release of Inochi. Enjoy!

CREDITS

Suraj N. Kurapati, Peileppe Production, Florian Gilcher

Logo

The "inochi.png" image and its "inochi.svg" source utilize the "3 flowers" graphic, which was created and released into the public domain by Peileppe Production on June 25, 2008.

LICENSE

(the ISC license)

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

inochi(1)

NAME

ABOUT

Features

Resources

Setup

SYNOPSIS

DESCRIPTION

OPTIONS

inochi init

SYNOPSIS

DESCRIPTION

PARAMETERS

NOTIFICATIONS

inochi api

inochi man

inochi gem

inochi ann

inochi pub:ann:ruby-talk

inochi pub:web

PROJECTS

Options file

License file

Ruby library

Test suite

Shell command

Help manual

Web presence

HACKING

Prerequisites

Infrastructure

$LOAD_PATH setup

RubyGems setup

Running tests

Contributing

VERSIONS

Version 2.0.0 (2010-04-24)

Version 1.1.1 (2009-10-03)

Version 1.1.0 (2009-09-06)

Version 1.0.0 (2009-05-03)

Version 0.3.0 (2009-02-12)

Version 0.2.0 (2009-01-25)

Version 0.1.0 (2009-01-13)

Version 0.0.1 (2009-01-13)

Version 0.0.0 (2009-01-13)

CREDITS

Logo

LICENSE

SEE ALSO