Rewrite "usage" section in README to better meet the users’ needs

Author: codener

README.md

@@ -4,14 +4,13 @@ Generating a Rails 5.1.4 app on Ruby 2.5.0.
 <img src="katapult.png" width="200px" align="right" />
 
 
-Katapult is a kickstart generator for Rails applications. It creates new Rails
-applications with [lots of pre-configuration](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)
+Katapult is a kickstart generator for Rails. It prepares a new
+application with [lots of pre-configuration](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)
 and offers [makandra-flavored](https://leanpub.com/growing-rails) code
-generation from an application model. These two features significally speed up
-the initial phase of a Rails project by doing in minutes what otherwise would
-cost you weeks.
-After modeling your application, which takes about an hour, you can instantly
-start implementing the meat of your application.
+generation from an application model. This significantly speeds up the initial
+phase of Rails development by doing in minutes what would cost you weeks. When
+Katapult has finished, you can instantly start implementing the interesting
+parts of your application.
 
 
 ## Prerequisites
@@ -23,77 +22,104 @@ Also, it drops the Rails asset pipeline in favor of *Webpacker*, so you'll need
 The required *Ruby* version is 2.5.0. You'll need the *Bundler* and *Rake* gems,
 which are probably already installed on your system.
 
+When you're using the `katapult` binary (you should), you'll also need *Git*.
 
-## Installation
 
-Install the `katapult` gem with
+## Installation
 
     gem install katapult
 
-If you intend to extend an existing application, add it to the development group
-in your Gemfile.
-
 
 ## Usage
 
-Katapult does two distinct things for you:
+There are two usage scenarios for Katapult:
 
-1. It creates a new Rails application, prepared with gems, snippets,
-   configuration, databases, testing libraries etc.
-2. It generates code from an application model, i.e. it generates models and
-   views, controllers, styles etc. 
+1. Starting a fresh Rails application
+2. Extending an existing Rails application
 
-You may use both or only one of them. Read on for details.
+Choose your use case and read on below.
 
 
-## 1) Creating a new Rails application
+## Starting a fresh Rails application
 
-To get started, run the following command:
+To create a new Rails application with Katapult, run the following command:
 
     katapult new $APPLICATION_NAME
 
-This will create a new Rails application and prepare it in more than 20 steps.
-Read the [BasicsGenerator](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)
-for details: Its methods are executed one-by-one, while the method names are a
-description of what they do.
+This will create a new Rails application, prepared and configured: bundled,
+database set up, RSpec, Cucumber and Capistrano installed and much more.
+Please read the [BasicsGenerator](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)
+for details (its methods are executed one-by-one from top to bottom).
 
-#### Alternative: Using Katapult in an existing Rails application
-Katapult generates a fresh application. If you have an existing Rails
-application, you *may* use Katapult to configure it.
-Be warned: it is not designed to respect existing files, although it will usually
-ask before overwriting something.
+When Katapult is done, you will find a default application model in
+`lib/katapult/application_model.rb`. It contains a full example of Katapult's
+DSL that you can use as an inspiration for creating your own application model.
 
-After adding it to the Gemfile, invoke the basics generator manually:
+Next, check the templates in `lib/templates/katapult`. They will be used
+to generate the corresponding files, e.g. HAML views. Please modify the templates
+to match your requirements. (Actually, you can customize much more templates.
+Each template in Katapult's `lib/generators/katapult/<generator>/templates/` can
+be overridden with a file at `lib/templates/katapult/<generator>/` in your
+application.)
 
-    bin/rails generate katapult:basics
+When your application model and the templates are ready, let Katapult generate
+your code:
 
+    katapult fire
 
-## 2) Generating code from an application model
+This will create models, migrations, views, styles, controllers, routes,
+Cucumber features, specs, factories and more. It will also commit the results
+and migrate the database.
 
-After running `katapult new`, you will find a default application model in
- `lib/katapult/application_model.rb`. It contains a full example of Katapult's
-features that you can use as an inspiration for creating _your_ application model.
+When this is done, your application is ready to use! Start a development
+server and try it out.
 
-When your application model is ready, transform it using:
 
-    katapult fire [path/to/application_model]
+## Extending an existing Rails application
 
-The path is optional and defaults to the generated application model. If you
-later want to extend your application, you may create a second application model
-and invoke `katapult fire` with its path.
+You can use Katapult for code generation in an existing application as well.
 
-Below you find an overview of the application model DSL. The respective sections
-hold examples of what options are available to each element. For details, dive
-into `lib/generators/katapult` where all generators are stored. The method names
-of a generator tell what it does.
+First, add Katapult to the development group in your Gemfile:
+```
+  gem 'katapult'
+```
 
-### Generic DSL syntax example
-The DSL consists of _elements_, e.g. `Model` or `WebUI`. Each Katapult element
-has the following syntax, taking a name, options, and a block:
+Next, generate the default application model:
 
-    element_type 'name', options: 'example' do |element|
-      element.some_method
-    end
+```
+bundle exec rails generate katapult:app_model
+```
+
+You'll find the application model at `lib/katapult/application_model.rb`. It
+contains a full example of Katapult's features: Use it as an inspiration for
+modeling your own application. (When you're used to the application model DSL,
+you don't need to generate the default model. Just create a Ruby file and start
+modeling.)
+
+Next, copy Katapult's template files to your application:
+
+```
+katapult templates
+```
+
+This will copy some of Katapult's file templates to `lib/templates/katapult`.
+Modify them, especially the view templates, to match the current state of your
+application. You can customize even more templates, see the "Starting …" section
+above.
+
+When model and templates are ready, trigger code generation with:
+
+```
+katapult fire path/to/your_model.rb
+```
+
+
+## DSL reference
+
+Below you find an overview of the application model DSL. The respective sections
+hold examples of what options are available to each element. For details, dive
+into the respective generator at `lib/generators/katapult/*/*_generator.rb`. The
+method names of a generator tell what it does.
 
 ### Crud
 Shortcut for creating a model together with a WebUI with CRUD actions. The block
@@ -121,7 +147,7 @@ needed.
     # Default type :string
     model.attr :name
 
-    # Inferred type :email (when attr name matches /email/)
+    # Inferred type :email (attribute name matches /email/)
     model.attr :email
 
     # Inferred type :password. Password fields are rendered as password_field in
@@ -207,7 +233,7 @@ Rails, including Clearance mails like password reset requests.
 ### Getting started
 `Katapult` is tested with [RSpec](http://rspec.info/) and
 [Cucumber](https://cucumber.io/) + [Aruba](https://github.com/cucumber/aruba)
-([API-Doc](http://www.rubydoc.info/github/cucumber/aruba/master/)).
+([API documentation](http://www.rubydoc.info/github/cucumber/aruba/master/)).
 
 For its full-stack integration tests, Katapult requires a PostgreSQL account.
 Create a dedicated account on your local PostgreSQL server:
@@ -228,22 +254,24 @@ included in the `katapult` gem.
 
 The generators of Katapult extend the `rails/generators` you probably know
 from generating migration files or scaffolds. However, Katapult lifts them on a
-new level by invoking them programmatically with a model object instead
+higher level by passing them a model object instead
 of plain text arguments. This way, the Katapult generators can explore the whole
-application model and are not restricted to a few string's they've been given.
-
-There are three Rails generators that are intended for invocation from bash.
-They can be considered the next-lower level API of Katapult:
-
-- `katapult:basics` generator: Enhances a pristine Rails app with all of the basic
-  configuration Katapult brings.
-- `katapult:app_model` generator: Installs a boilerplate application model that serves as
-  a starting point for modeling your own application.
-- `katapult:transform` generator: Parses the application model into an internal
+application model and are not restricted to a few strings they've been given.
+
+There are a few "public" Rails generators. They can be considered the next API
+level after the `katapult` binary:
+
+- `katapult:basics`: Enhances a pristine Rails app with all of the
+  basic configuration.
+- `katapult:app_model`: Installs a boilerplate application model that
+  serves as a starting point for modeling an application.
+- `katapult:templates`: Copies some generator templates to the target
+  application.
+- `katapult:transform`: Parses the application model into an internal
   representation, which will be turned into code by all the other generators.
 
-Note that the `katapult` binary is the only Rails-independent part of Katapult;
-everything else runs in the context of the Rails application.
+Note that the `katapult` binary is the only Rails-independent part of Katapult.
+Everything else runs in the context of the Rails application.
 
 ### Suggested workflow
 When adding a feature to Katapult, it will usually take you some time to
@@ -255,11 +283,12 @@ Here's a process for building larger code generation features:
 1) **Start with a test:** Create a Cucumber scenario that creates and transforms
    an application model. Also, write a first draft of the code that generates
    what you expect.
-2) Run your scenario.
+2) Run your scenario. This will transform your test application model.
 3) Make a commit inside the generated test application, so you'll have a clean
    working directory: `script/kta git add --all && script/kta git commit -m 'x'`
-4) **Tune the generated code to meet your expectations.** Boot a development
-   server with `script/kta rails s` if you like.
+4) **Modify the generated code** inside the generated test application until it
+   meets your expectations. If you like, boot a development server with
+   `script/kta rails s`.
 5) **Finish your test:** Once you've figured how the generated code should look
    like, it's time to write steps that test it. For this purpose, tag your
    scenario with @no-clobber and comment out the model transformation step. This
@@ -269,7 +298,7 @@ Here's a process for building larger code generation features:
    see your changes.
 6) **Write code:** When you've completed your scenario, write the code that
    generates what is needed to satisfy the test.
-7) Remove the @no-clobber tag and comment in the transformation step. Stop the
+7) Remove the @no-clobber tag and uncomment the transformation step. Stop the
    development server if you've started one.
 8) Run your scenario normally and iterate over your code generation code until
    your scenario is green.
@@ -280,19 +309,19 @@ Please respect the following guidelines during development:
 - The application model should be order-agnostic. There is a #prepare_render
   method in `ApplicationModel` for things that need to happen between parsing
   and rendering the application model.
-- The application model should be idempotent, meaning it should be possible to
-  generate it over and over again without breaking code.
+- Transformation should be idempotent: it should be possible to generate the
+  application model over and over again without crashing or breaking things.
 
 ### Debugging
-Add the `@announce-output` tag to Katapult features in order to have any output
+Add the `@announce-output` tag to Katapult scenarios in order to have output
 logged to your terminal. Note that each step will print all output to date, so
 you will see things multiple times.
 
 To precisely debug errors occurring _inside_ the generated application, use
 `script/kta`. It is a helper script that will execute whatever command you pass
 it, but in the directory of the generated application. While you could cd to the
 test app and run your command there, you'd need to `cd ../../aruba/katapult_test_app`
-after each test run, because the tmp/aruba directory gets wiped before each test.
+between test runs, because the tmp/aruba directory gets wiped before each test.
 
 When fixing issues in the generated app, make a commit in the app first. When
 you've fixed it, the diff will show you what you need to port back to katapult.

Rakefile

@@ -19,7 +19,7 @@ task :update_readme do
 
   readme = File.read readme_path
   readme.sub! /\A# Katapult.*\nGenerating.*\n/, '# ' + `bin/katapult version`
-  readme.sub! /(required Ruby version is )[\d\.]+\d/, "\\1#{Katapult::RUBY_VERSION}"
+  readme.sub! /(required .Ruby. version is )[\d\.]+\d/, "\\1#{Katapult::RUBY_VERSION}"
 
   File.open readme_path, 'w' do |f|
     f.write readme