%#--
%# Copyright protects this work.
%# See LICENSE file for details.
%#++

%|chapter "Setup"


  %|section "Requirements"

    Your system needs the following software to run <%= $project %>.

    %|table
      %|thead
        %|tr
          %|th
            Software
          %|th
            Description
          %|th
            Notes
      %|tbody
        %|tr
          %|td
            [Ruby](http://ruby-lang.org)
          %|td
            Ruby language interpreter
          %|td
            Version 1.8.7 and 1.9.1 have been tested successfully.
        %|tr
          %|td
            [RubyGems](http://rubygems.org)
          %|td
            Ruby packaging system
          %|td
            Version 1.3.5 or newer is required.


  %|section "Installation"

    You can install <%= $project %> by running this command:

        gem install <%= $program %>

    To check whether the installation was sucessful, run this command:

        <%= $program %> --version

    If the installation was successful, you will see output like this:

    %|text
      %= verbatim `ruby bin/#{$program} --version`

    If you do not see such output, you may
    %= xref "License", "ask the author(s)"
    for help.


  %|section "Package contents"

    You will see the following items inside <%= $project %>'s installation
    directory, whose path you can determine by running this command:

        <%= $program %> --version

    * <tt>bin/</tt>

      * <tt><%= $program %></tt> --- the main <%= $project %> executable.

    * <tt>fmt/</tt> --- contains the predefined set of <%= xref "SpecFile", "format specification files" %>. If you ever need to install your custom format specification file globally, then put it inside this directory.

      %|ERBook::FORMAT_FILES.each do |file|
        %= '  * <tt>%s</tt> --- %s' % [File.basename(file), YAML.load_file(file)['desc']]

    * <tt>lib/</tt>

      * <tt><%= $program %>.rb</tt> --- the main <%= $project %> library.

      * <tt><%= $program %>/</tt>

        * <tt>to_xhtml.rb</tt> --- implements <%= xref "Text to XHTML conversion" %> methods for the <%= xref "xhtml" %> format.

        * <tt>rdoc.rb</tt> --- provides RDoc parse trees to Ruby code.

    * <tt>doc/</tt>

      * <tt>api/</tt> --- API reference documentation.

      * <tt><%= $program %>.svg</tt> --- source file of the <%= $project %> logo.

      * <tt>index.erb</tt> --- source file of this manual.

    * <tt>LICENSE</tt> --- copyright notice and legal conditions.

    * <tt>CREDITS</tt> --- attribution of project contributors.


  %|section "Version numbers"

    <%= $project %> releases are numbered in *major.minor.patch*
    form according to the [RubyGems rational versioning
    policy](http://www.rubygems.org/read/chapter/7), which
    can be summarized as follows:

    %|table
      %|thead
        %|tr
          %|td :rowspan => 2
            What increased in the version number?
          %|td :colspan => 3
            The increase indicates that the release:
        %|tr
          %|th
            Is backward compatible?
          %|th
            Has new features?
          %|th
            Has bug fixes?
      %|tbody
        %|tr
          %|th
            major
          %|td :style => "background-color: #FFE4E1;"
            No
          %|td
            Yes
          %|td
            Yes
        %|tr
          %|th
            minor
          %|td
            Yes
          %|td
            Yes
          %|td
            Yes
        %|tr
          %|th
            patch
          %|td
            Yes
          %|td :style => "background-color: #FFE4E1;"
            No
          %|td
            Yes