o Removing all old code (X files).

o Making sure APPSH_HOME is 1) exported and, 2) always prepended to
  $PATH.
o More documentation on what a zip file actually looks like and how to
  create hooks.

1 files changed, 51 insertions, 16 deletions

diff --git a/docs/app.txt b/docs/app.txt
index 9ab0ba7..487c9cd 100644
--- a/docs/app.txt
+++ b/docs/app.txt
@@ -16,31 +16,31 @@ DOCUMENTATION
 QUICK START
 ~~~~~~~~~~~
 
-------------------------------------------------------------------------
+---------------------------------------------------------------------
 $ app init -d my-app maven org.example:my-app:1.0-SNAPSHOT
 $ cd my-app
 $ app start
 $ app conf set app.version 1.0
 $ app upgrade
 $ app restart
-------------------------------------------------------------------------
+---------------------------------------------------------------------
 
 INSTALLING AN APPLICATION
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This resolved and downloads an appliaction from a Maven repository:
 
-------------------------------------------------------------------------
+---------------------------------------------------------------------
 $ app init -d my-app maven org.example:my-app:1.0-SNAPSHOT
-------------------------------------------------------------------------
+---------------------------------------------------------------------
 
 By default it will download from the central repository, but this is
 not always what you want. To get it to use another repository give the
 `-r` option:
 
-------------------------------------------------------------------------
+---------------------------------------------------------------------
 $ app init -d my-app maven -f http://repo.example.org/snapshots org.example:my-app:1.0-SNAPSHOT
-------------------------------------------------------------------------
+---------------------------------------------------------------------
 
 UPGRADING AN APPLICATION
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -49,9 +49,9 @@ If your application is configured with the Maven resolver and the
 version is a SNAPSHOT version, you can use this to upgrade your
 application through a cron job:
 
-------------------------------------------------------------------------
+---------------------------------------------------------------------
 $ app upgrade
-------------------------------------------------------------------------
+---------------------------------------------------------------------
 
 With the resolver will try to resolve `app.version` to the latest
 version. If it's change it will automatically download and install the
@@ -60,10 +60,10 @@ latest version.
 CHANGING VERSION OF AN APPLICATION
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-------------------------------------------------------------------------
+---------------------------------------------------------------------
 $ app conf set app.version 1.0
 $ app sync-version
-------------------------------------------------------------------------
+---------------------------------------------------------------------
 
 `app-sync-version` will first run the resolver to resolve the version
 and if that has changed, it will download and install the new version.
@@ -71,10 +71,33 @@ and if that has changed, it will download and install the new version.
 CREATING APPS
 -------------
 
-TODO
-
-CREATING HOOKS
-~~~~~~~~~~~~~~
+An "app" is in itself nothing more than a zip archive with a particular
+layout. In the root of the zip archive there must be a directory called
+`root`. You can also place a file called `app.config` at the root. The
+config file will be imported into the app's configuration. It is also
+possible to run appliations before and after appliations are installed
+through hooks. These are placed in a `hooks` directory, also at the
+root of the archive.
+
+To summarize, this is what an application zip archive looks like:
+
+---------------------------------------------------------------------
+/app.conf
+/root
+/root/bin
+/root/bin/my-app
+/root/repo/
+/root/repo/io
+/root/repo/io/trygvis/
+/root/repo/io/trygvis/...
+/hooks/
+/hooks/post-install
+---------------------------------------------------------------------
+
+If this looks familiar to RPMs, Debs or Pkg files, you're right.
+
+HOOKS
+~~~~~
 
 TODO
 
@@ -83,10 +106,22 @@ CREATING LAUNCHERS
 
 Trick when you don't know why your app won't start:
 
-------------------------------------------------------------------------
+---------------------------------------------------------------------
 exec 1>/tmp/myapp.out
 exec 2>/tmp/myapp.err
-------------------------------------------------------------------------
+---------------------------------------------------------------------
+
+Make sure you _always_ use `exec` when spawning the actual app. This
+makes sure that the pid operator records the correct PID. If you don't
+do this the application will run, but will be reported as crashed when
+you run 'app status'.
+
+If you can't use `exec` or the application demands to deamonize itself
+(like Apache Httpd), you have to set the configuration option
+`app.pid_management=launcher`. Then the launcher is responsible for
+creating the PID file under $APP_HOME/.app/pid. You can create a
+symlink to the actual PID file if you can't customize where the app
+places the file.
 
 TODOs
 -----