add doc wiki

12 files changed, 116 insertions, 56 deletions

diff --git a/Makefile b/Makefile
index d1fcbbeee..87c725efe 100644
--- a/Makefile
+++ b/Makefile
@@ -8,5 +8,17 @@ install:
 
 clean:
 	rm -rf build git-annex
+	rm -rf doc/.ikiwiki html
+
+# Build static html docs suitable for being shipped in the software
+# package. This depends on ikiwiki being installed to build the docs.
+ifeq ($(shell which ikiwiki),)
+IKIWIKI=echo "** ikiwiki not found" >&2 ; echo ikiwiki
+else
+IKIWIKI=ikiwiki
+endif
+
+docs:
+	$(IKIWIKI) doc html -v --wikiname git-annex --plugin=goodstuff
 
 .PHONY: git-annex
diff --git a/debian/control b/debian/control
index e58f55af9..846844c32 100644
--- a/debian/control
+++ b/debian/control
@@ -1,7 +1,7 @@
 Source: git-annex
 Section: utils
 Priority: optional
-Build-Depends: debhelper (>= 7.0.50), ghc6, libghc6-missingh-dev, libghc6-sha-dev
+Build-Depends: debhelper (>= 7.0.50), ghc6, libghc6-missingh-dev, libghc6-sha-dev, ikiwiki
 Maintainer: Joey Hess <joeyh@debian.org>
 Standards-Version: 3.9.1
 Vcs-Git: git://git.kitenet.net/git-annex
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 000000000..f2c4d8e54
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,15 @@
+# Build static html docs suitable for being shipped in the software
+# package. This depends on ikiwiki being installed to build the docs.
+
+ifeq ($(shell which ikiwiki),)
+IKIWIKI=echo "** ikiwiki not found" >&2 ; echo ikiwiki
+else
+IKIWIKI=ikiwiki
+endif
+
+all:
+	$(IKIWIKI) `pwd` html -v --wikiname FooBar --plugin=goodstuff \
+		--exclude=html --exclude=Makefile
+
+clean:
+	rm -rf .ikiwiki html
diff --git a/doc/bugs.mdwn b/doc/bugs.mdwn
new file mode 100644
index 000000000..dd2a9b403
--- /dev/null
+++ b/doc/bugs.mdwn
@@ -0,0 +1,4 @@
+This is git-annex's bug list. Link bugs to [[bugs/done]] when done.
+
+[[!inline pages="./bugs/* and !./bugs/done and !link(done) 
+and !*/Discussion" actions=yes postform=yes show=0]]
diff --git a/doc/bugs/branching.mdwn b/doc/bugs/branching.mdwn
new file mode 100644
index 000000000..21996ecc0
--- /dev/null
+++ b/doc/bugs/branching.mdwn
@@ -0,0 +1,36 @@
+The use of `.git-annex` to store logs means that if a repo has branches 
+and the user switched between them, git-annex will see different logs in
+the different branches, and so may miss info about what remotes have which
+files (though it can re-learn). 
+
+An alternative would be to store the log data directly in the git repo
+as `pristine-tar` does. Problem with that approach is that git won't merge
+conflicting changes to log files if they are not in the currently checked
+out branch.
+
+It would be possible to use a branch with a tree like this, to avoid
+conflicts:
+
+key/uuid/time/status
+
+As long as new files are only added, and old timestamped files deleted,
+there would be no conflicts.
+
+A related problem though is the size of the tree objects git needs to
+commit. Having the logs in a separate branch doesn't help with that.
+As more keys are added, the tree object size will increase, and git will
+take longer and longer to commit, and use more space. One way to deal with
+this is simply by splitting the logs amoung subdirectories. Git then can
+reuse trees for most directories. (Check: Does it still have to build
+dup trees in memory?)
+
+Another approach would be to have git-annex *delete* old logs. Keep logs
+for the currently available files, or something like that. If other log
+info is needed, look back through history to find the first occurance of a
+log. Maybe even look at other branches -- so if the logs were on master,
+a new empty branch could be made and git-annex would still know where to
+get keys in that branch. 
+
+Would have to be careful about conflicts when deleting and bringing back
+files with the same name. And would need to avoid expensive searching thru
+all history to try to find an old log file.
diff --git a/doc/bugs/done.mdwn b/doc/bugs/done.mdwn
new file mode 100644
index 000000000..ad332e2a2
--- /dev/null
+++ b/doc/bugs/done.mdwn
@@ -0,0 +1,3 @@
+recently fixed [[bugs]]
+
+[[!inline pages="./* and link(./done) and !*/Discussion" sort=mtime show=10]]
diff --git a/doc/bugs/free_space_checking.mdwn b/doc/bugs/free_space_checking.mdwn
new file mode 100644
index 000000000..34528a7b3
--- /dev/null
+++ b/doc/bugs/free_space_checking.mdwn
@@ -0,0 +1,8 @@
+Should check that there is enough free space before trying to copy a
+file around.
+
+* Need a way to tell how much free space is available on the disk containing
+  a given repository.
+
+* And, need a way to tell the size of a file before copying it from
+  a remote, to check local disk space.
diff --git a/doc/contact.mdwn b/doc/contact.mdwn
new file mode 100644
index 000000000..1238ca040
--- /dev/null
+++ b/doc/contact.mdwn
@@ -0,0 +1,4 @@
+Joey Hess <joey@kitenet.net> is the author of git-annex.
+
+The [VCS-home mailing list](http://lists.madduck.net/listinfo/vcs-home)
+is a good place to discuss it.
diff --git a/doc/download.mdwn b/doc/download.mdwn
new file mode 100644
index 000000000..2ceb73193
--- /dev/null
+++ b/doc/download.mdwn
@@ -0,0 +1,5 @@
+The main git repository for git-annex is `git://git.kitenet.net/git-annex`
+[[gitweb](http://git.kitenet.net/?p=git-annex;a=summary)]
+
+There are no binary packages yet, but you can build Debian packages from
+the source tree with `dpkg-buildpackage`.
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 4c85a03b6..eb5fa9ced 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -176,61 +176,6 @@ when it's run from a git hook and do the necessary fixups.
 * `remote.<name>.annex-uuid` -- git-annex caches UUIDs of repositories
   here.
 
-## issues
-
-### free space determination
-
-Need a way to tell how much free space is available on the disk containing
-a given repository. The repository may be remote, so ssh may need to be
-used.
-
-Similarly, need a way to tell the size of a file before copying it from
-a remote, to check local disk space.
-
-### auto-drop on rm
-
-When git-rm removed a file, its key should get dropped too. Of course, it
-may not be dropped right away, depending on number of copies available.
-
-### branching
-
-The use of `.git-annex` to store logs means that if a repo has branches 
-and the user switched between them, git-annex will see different logs in
-the different branches, and so may miss info about what remotes have which
-files (though it can re-learn). 
-
-An alternative would be to store the log data directly in the git repo
-as `pristine-tar` does. Problem with that approach is that git won't merge
-conflicting changes to log files if they are not in the currently checked
-out branch.
-
-It would be possible to use a branch with a tree like this, to avoid
-conflicts:
-
-key/uuid/time/status
-
-As long as new files are only added, and old timestamped files deleted,
-there would be no conflicts.
-
-A related problem though is the size of the tree objects git needs to
-commit. Having the logs in a separate branch doesn't help with that.
-As more keys are added, the tree object size will increase, and git will
-take longer and longer to commit, and use more space. One way to deal with
-this is simply by splitting the logs amoung subdirectories. Git then can
-reuse trees for most directories. (Check: Does it still have to build
-dup trees in memory?)
-
-Another approach would be to have git-annex *delete* old logs. Keep logs
-for the currently available files, or something like that. If other log
-info is needed, look back through history to find the first occurance of a
-log. Maybe even look at other branches -- so if the logs were on master,
-a new empty branch could be made and git-annex would still know where to
-get keys in that branch. 
-
-Would have to be careful about conflicts when deleting and bringing back
-files with the same name. And would need to avoid expensive searching thru
-all history to try to find an old log file.
-
 ## contact
 
 Joey Hess <joey@kitenet.net>
diff --git a/doc/index.mdwn b/doc/index.mdwn
new file mode 100644
index 000000000..8d2cb1ef5
--- /dev/null
+++ b/doc/index.mdwn
@@ -0,0 +1,23 @@
+git-annex allows managing files with git, without checking the file
+contents into git. While that may seem paradoxical, it is useful when
+dealing with files larger than git can currently easily handle, whether due
+to limitations in memory, checksumming time, or disk space.
+
+Even without file content tracking, being able to manage files with git,
+move files around and delete files with versioned directory trees, and use
+branches and distributed clones, are all very handy reasons to use git. And
+annexed files can co-exist in the same git repository with regularly
+versioned files, which is convenient for maintaining documents, Makefiles,
+etc that are associated with annexed files but that benefit from full
+revision control.
+
+* [[man page|git-annex]]
+* **[[download]]**
+* [[news]]
+* [[bugs]]
+* [[contact]]
+
+----
+
+git-annex's wiki is powered by [Ikiwiki](http://ikiwiki.info/) and
+hosted by [Branchable](http://branchable.com/).
diff --git a/doc/news.mdwn b/doc/news.mdwn
new file mode 100644
index 000000000..d0ff1ca2c
--- /dev/null
+++ b/doc/news.mdwn
@@ -0,0 +1,5 @@
+This is where announcements of new releases, features, and other news is
+posted. git-annex users are recommended to subscribe to this page's RSS
+feed.
+
+[[!inline pages="./news/* and !*/Discussion" rootpage="news" show="30"]]