o Adding a man page on internals.

7 files changed, 62 insertions, 199 deletions

diff --git a/Makefile b/Makefile
index 49a1896..edf76c8 100644
--- a/Makefile
+++ b/Makefile
@@ -18,11 +18,11 @@ test: $(TESTS)
 .PHONY: test
 
 clean:
-	@make -C docs clean
+	@make -s -C docs clean
 .PHONY: clean
 
 docs:
-	@make -C docs
+	@make -s -C docs
 .PHONY: docs
 
 define set_header
diff --git a/README.md b/README.md
index c4a83e9..f36feea 100644
--- a/README.md
+++ b/README.md
@@ -1,166 +1,2 @@
-Installation
-------------
-
-    git clone http://.../app.sh.git
-
-    mkdir /opt/apps
-    cd /opt/apps
-    ln -s .../app.sh.git/app.sh app.sh
-
-NOTE: The bash completion is not perfect yet.
-
-    echo 'source .../app.sh.git/app_completion' >> ~/.bashrc
-
-Or was it `~/.bash_profile`? hmm
-
-TODOs
------
-
-* Support installation-wide settings. Useful for shared environment
-  settings etc (PATH).
-
-* Add support for hooks in .app/hooks. Example hooks:
-    * Diff config. Save a backup of the config on installtaion.
-    * Copy the configuration from the previous installation.
-
-* Support changing current version.
-
-* Document app.sh
-    * Concept: config. group, key and value.
-    * Scriptable
-
-* init.d support - register the application under /etc/init.d on
-  installation. Should probably be a plugin.
-
-* Support -h for all applicable methods to show the help/usage.
-
-* Rename "scripts/" to handlers or something similar. Perhaps just
-  remove it entirely.
-
-* Document how the operate method (custom pid-method stuff) can see
-  its own output for debugging.
-
-Commands
---------
-
-### `instance`
-
-#### `install`
-
-#### `upgrade`
-
-Tries to upgrade all instances where the version doesn't match the resolved version.
-
-#### `list`
-
-#### `list-versions`
-
-#### `set-current`
-
-#### `remove`
-
-Not implemented
-
-### `conf`
-
-#### `get`
-
-    ./app -n $n -i $i conf get
-
-#### `set`
-
-    ./app -n $n -i $i conf set group.key value
-
-#### `delete`
-
-    ./app -n $n -i $i conf delete group.key
-
-### `operate`
-
-The operate sub-methods are provided by the application.
-
-#### Supported methods by `pid-method`
-
-#### `start`
-
-#### `stop`
-
-TODO: support -f flag that doesn't exit with 1 if the app is not running.
-
-#### `status`
-
-### `foreach`
-
-Runs the given command for each of the selected instances.
-
-Method Contract
----------------
-
-### Environment variables you can depend on
-
-* `APPSH_NAME`
-* `APPSH_INSTANCE`
-* `APPSH_METHOD`
-
-Unclassified:
-
-* `APPSH_HOME`
-* `APPSH_APPS`
-
-Directory Hierarchy
--------------------
-
-### Current
-
-App.sh is installed through cloning the git repository and/or
-unpacking a tarball from the git repository. The directory that
-contains the app.sh libraries is known as `$APPSH_HOME`.
-
-App.sh related:
-
-    ./         The root of an application set. Known as $APPSH_APPS
-    ./app      The app script, symlinked from your git clone directory
-    ./.app/lib bash libraries used by app.sh and methods
-    ./.app/var runtime data
-
-Applications:
-
-    ./<name>/<instance>/  - Known as $APPSH_INSTANCE_HOME
-        current ->        - symlink to the currently installed app
-        versions/         - collection with all installed versions
-          1.0/            - A installed version. The zip file is unzipped here.
-            root/         - The current directory when executing methods and scripts
-            scripts/
-          1.1/
-          2.0/
-
-Creating Apps
--------------
-
-"App bundles" are basically just zip file with a specific layout. It
-has to contain at least a `root/` directory which contains your
-application. It can contain anything. The `current` symlink will point
-to this directory.
-
-The bundle can also contain a special `scripts` directory which
-contains scripts that's run durtion package operations. Only
-`postinstall` is currently supported.
-
-Zip File Tree
-=============
-
-    root/
-        bin/
-            myapp
-        etc/
-            config
-    scripts/
-        postinstall
-
-Managing Apps
--------------
-
-Setting Environment Variables
------------------------------
-
-    app -n .. -i .. conf
+See docs/app.txt. Run `make docs` to generate a HTML version if you
+have asciidoc installed.
diff --git a/docs/Makefile b/docs/Makefile
index 2a62f18..f340323 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,6 +1,8 @@
 TXT=$(wildcard *.txt)
+# Expand target section from heading of each page
+MAN=$(shell ls *.txt|xargs -n 1 head -n 1|sed "s,\(.*\)(\([0-9]\)),\1.\2,")
 HTML=$(patsubst %.txt,%.html,$(TXT))
-MAN=$(patsubst %.txt,%.1,$(TXT))
+
 all: $(HTML) $(MAN)
 
 %.html: %.txt
@@ -8,8 +10,15 @@ all: $(HTML) $(MAN)
 	@asciidoc -f asciidoc.conf --backend=html5 $<
 
 %.1: %.txt
-	@echo a2x $<
-	@a2x --format manpage $<
+	$(call man,$<)
+
+%.7: %.txt
+	$(call man,$<)
+
+define man
+	@echo a2x $(1)
+	@a2x --format manpage $(1)
+endef
 
 clean:
-	rm -rf $(wildcard *.html) $(wildcard *.1)
+	rm -rf $(wildcard *.html) $(wildcard *.1) $(wildcard *.7)
diff --git a/docs/app-cat-conf.txt b/docs/app-cat-conf.txt
index ec2c4f9..0b4f83a 100644
--- a/docs/app-cat-conf.txt
+++ b/docs/app-cat-conf.txt
@@ -45,6 +45,14 @@ LOCATIONS AND DEFAULT FILES
 
 * '.app/config'
 
+TODOs
+-----
+
+Support comments::
+  1) ignore comments (lines that start with #), 2) add a flag (-C) to
+  include comments in the output but still filter the lines. (2) is
+  required for app-conf set to work. (1) can be done first.
+
 SEE ALSO
 --------
 
diff --git a/docs/app.txt b/docs/app.txt
index fb77174..c0d92f6 100644
--- a/docs/app.txt
+++ b/docs/app.txt
@@ -55,30 +55,6 @@ CHANGING VERSION OF AN APPLICATION
 `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.
 
-INTERNALS
----------
-
-Concepts:
-
-resolver::
-    Something that takes a version and resolves it to a specific
-    version. Makes it possible to depend on a development version
-    which is resolved later on.
-
-Configuration properties:
-
-`app.version`::
-    The unresolved version of the application. Configured when the
-    application is installed.
-
-`app.resolved_version`::
-    The resolved version of the application. Is updated by the
-    resolved configured for the project.
-
-`app.installed_version`::
-    The installed version of the application. Is updated by
-    `app-set-version`.
-
 TODOs
 -----
 
@@ -92,6 +68,7 @@ TODOs
 SEE ALSO
 --------
 
-linkman:app-conf[1]
+linkman:app-conf[1],
+linkman:appinternals[1],
 
 // vim: set ft=asciidoc:
diff --git a/docs/appinternals.txt b/docs/appinternals.txt
new file mode 100644
index 0000000..743cb03
--- /dev/null
+++ b/docs/appinternals.txt
@@ -0,0 +1,33 @@
+appinternals(7)
+===============
+
+NAME
+----
+appinternals - Appsh internals
+
+DESCRIPTION
+-----------
+
+Concepts:
+
+resolver::
+    Something that takes a version and resolves it to a specific
+    version. Makes it possible to depend on a development version
+    which is resolved later on.
+
+Configuration properties:
+
+`app.version`::
+    The unresolved version of the application. Configured when the
+    application is installed.
+
+`app.resolved_version`::
+    The resolved version of the application. Is updated by the
+    resolved configured for the project.
+
+`app.installed_version`::
+    The installed version of the application. Is updated by
+    `app-set-version`.
+
+
+// vim: set ft=asciidoc:
diff --git a/docs/asciidoc.conf b/docs/asciidoc.conf
index 8622db4..724524a 100644
--- a/docs/asciidoc.conf
+++ b/docs/asciidoc.conf
@@ -11,8 +11,8 @@ endif::backend-docbook[]
 
 ifdef::backend-html5[]
 
-#[attributes]
-#relative-ext=.html
+[attributes]
+relative-ext=.html
 
 [linkman-inlinemacro]
 <a href="{target}.html">{target}{0?({0})}</a>