README.md in klipp-0.2.2.4 vs README.md in klipp-0.2.2.5
- old
+ new
@@ -1,35 +1,56 @@
# Klipp [](https://travis-ci.org/epologee/klipp) [](https://coveralls.io/r/epologee/klipp)
## Code templates for the rest of us.
-Klipp is a ruby gem with a command line interface for creating new programming projects from existing templates. It was originally designed to create Xcode projects. However, there are no Apple or Xcode specific features in Klipp, so you can use it for pretty much any textfile-and-directory-based template.
-When compared to Xcode's plist-based templating system, Klipp takes an existing Xcode project and creates a new project by copying and modifying an existing template project by your own specifications.
+Klipp is a Ruby gem that you can use to replicate folder structures, while doing extensive search-and-replace operations on filenames, directory names and file contents.
+I developed Klipp as an alternative to the templating system of Apple's Xcode, to use while developing iOS projects. However, there are no Apple or Xcode specific features in Klipp, so you can use it for pretty much any textfile-and-directory-based template.
+
## Installation
Install Klipp with RubyGems:
$ gem install klipp
+
+Then run Klipp from the command line and read the instructions:
-Execute and read the usage instructions:
-
$ klipp
+
+## Templates a.k.a. Specs
-## CLI under construction ...
+When you execute `klipp` the first time, it will create a `.klipp` folder in your home directory, where it will search for template directories. Each template has one `.klippspec` file. Upon first use however, you will not have any specs. For starters you might try my personal specs by executing:
-Klipp is still in the early development stage. When 0.1 ships, the CLI will feature:
+ $ git clone https://github.com/epologee/klipp-specs.git ~/.klipp/epologee
+
+After that, you can call `klipp template list` to see the specs it includes.
-* `klipp repo add <repo-name> [<repo-url>]` - git init [or clone] template repositories in the `~/.klipp` directory
-* `klipp template spec <template-name>` - creates a new template specificiation called `<template-name>.klippspec`, for you to configure your template's properties.
-* `klipp template push <repo-name>` - push a new template to one of your template repositories.
-* `klipp template list [<repo-name>]` - list all available templates on your machine [per repository]
-* `klipp prepare <template-name>` - prepare the creation of files from a new template, by authoring a `Klippfile`
-* `klipp create [<template-name>]` - create files based on the prepared `Klippfile` [or interactively from the terminal].
+## Inspiration
-## Contributing
+I've borrowed some of the terminology of Klipp from the RubyGem and CocoaPods community, which is why you see things like this:
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
++ `.klippspec` files defining the structure of a template (compare to `.gemspec` and `.podspec`)
++ `Klippfile` files used to setup a new project from an existing template (compare to `Gemfile` and `Podfile`)
++ The `~/.klipp` folder containing your templates (compare to `~/.cocoapods`)
+
+## Usage
+
+You use klipp from the terminal, as a command line tool. For example, if you have a template setup in the `~/.klipp/` folder called `iPhoneProject`, you can call commands like:
+
++ `klipp template list` to list your templates
++ `klipp create iPhoneProject` interactively prompts you to enter the values required for the template. This works well with very small templates, like creating a new class.
++ `klipp prepare iPhoneProject` to create a new `Klippfile` for the `iPhoneProject` template. You edit the Klippfiles by hand to supply it with strings, numbers and booleans. This is easier for templates with more required values.
++ `klipp create` to create a new project from a `Klippfile`, relative to your current directory.
++ `klipp create -f` to re-create the project, overwriting the existing one.
+
+You can always just start by running `klipp` and have the terminal tell you what commands to add to get your desired result.
+
+## Contribute
+
+The gem in its current state is very usable. It's got decent rspec coverage (96%+) and I personally use the publicly available gem build for all my templating needs. There are however areas in which I would love the project to evolve more:
+
++ Better terminal output during the creation process.
++ The ability to update an existing `Klippfile` when the corresponding `project.klippspec` is updated underneath.
++ Better feedback when something is missing, like token values or terminal commands.
++ A setup to share your templates, like the specs from CocoaPods and RubyGems projects.
+
+So if you're willing to help, feel free to fork and send those pull requests!
\ No newline at end of file