1 files changed, 56 insertions, 0 deletions
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..e71b44a
--- /dev/null
+++ b/README.org
@@ -0,0 +1,56 @@
+* Steeplejack
+A generic scaffolding system.
+** About
+#+begin_quote
+A steeplejack is a craftsman who scales buildings, chimneys, and
+church steeples to carry out repairs or maintenance.
+
+Steeplejacks erect ladders on church spires, industrial chimneys,
+cooling towers, bell towers, clock towers, or any other high
+structure.
+#+end_quote
+
+Like a steeplejack, ~steeplejack~ is a diligent worker that can erect
+scaffolding for any project you need.
+** Usage
+~steeplejack~ can be taught how to erect scaffolding by setting the
+=STEEPLEJACK_DIR= (defaults to ~~/.steeplejack~)environment variable and
+putting template directories there.  A template directory contains a
+~_scaffold.yml~ and various ~.erb~ files.  ~_scaffold.yml~ should at least
+contain a =params= or =parameters= property.  It should be a list of
+property names.  Each parameter will be read when the scaffold is
+erected.  ~_scaffold.yml~ can also contain an =erb_options= parameter
+that, when present, is used to set the =trim_mode= for ERB.  See the [[https://docs.ruby-lang.org/en/master/ERB.html][ERB
+documentation]] for details.
+
+When the scaffold is erected, each ~.erb~ file in the scaffold’s
+directory is evaluated, and the output is written to the corresponding
+file in the target directory.  For example, let’s take a scaffold
+directory ~scaf~.  We will deploy it to ~targ~.  Let’s say that ~scaf~ has
+three files in it:
++ ~scaf/_scaffold.yml~
++ ~scaf/a.erb~
++ ~scaf/b.erb~
+Let’s also say that ~_scaffold.yml~ contains the text
+#+begin_src yaml
+  properties:
+    - foo
+    - bar
+#+end_src
+When deploying ~scaf~ to ~targ~, you will be prompted for =foo= and =bar=.
+Then ~scaf/a.erb~ and ~scaf/b.erb~ will be evaluated, and the results
+written to ~targ/a~ and ~targ/b~.
+** Configuration
+When ~steeplejack~ starts up, it loads ~$STEEPLEJACK_DIR/init.rb~.  The
+most notable thing to have ~init.rb~ is ~add_alias~.  An example:
+#+begin_src ruby
+  add_alias sc: :scaffold,
+            ls: :list,
+            i: :info
+#+end_src
+
+Note that ~add_alias~ is not the same as ~alias~.  ~alias~ is a built-in
+Ruby feature, whereas ~add_alias~ is ~steeplejack~-specific; using ~alias~
+will not make the alias available as a ~steeplejack~ subcommand.
+** License
+~steeplejack~ is published under the [[http://gnu.org/licenses/gpl-3.0.html][GPLv3]] (or any later version).