X-Git-Url: https://git.cworth.org/git?p=ikiwiki-bootstrap;a=blobdiff_plain;f=README;h=8ec1f7cf2e422bcdcd3f06f8eba5a365f53ba14c;hp=27d04a5eeaae90fdc8d6cc5903313d9641c21dee;hb=HEAD;hpb=b0afdc29c02147822a454304750938b40f44a88f

diff --git a/README b/README
index 27d04a5..8ec1f7c 100644
--- a/README
+++ b/README
@@ -10,7 +10,7 @@ learning to use ikiwiki from its standard instructions:
 
 Features
 ========
-Here are some of the key features of what I've got setup, (and that
+Here are some of the key features of what I've got set up, (and that
 are different than following the standard instruction for integrating
 ikiwiki with git).
 
@@ -27,7 +27,7 @@ ikiwiki with git).
 
 3. Pre-configured for git
 
-	Most of the git-specific settings you need are already setup
+	Most of the git-specific settings you need are already set up
 	in ikiwiki.setup. One that is not is that the generated
 	wrapper is placed into ikiwiki-post-update rather than going
 	directly into git's post-update---so you will have to manually
@@ -39,24 +39,30 @@ Usage
 =====
 To start, choose where the bare git repository will exist on your web
 server and where you'd like the HTML results to be published to. Edit
-ikiwiki.setup and fill these in for gitrepo and destdir.
+ikiwiki.setup and fill these in for gitrepo and destdir. Commit these
+changes, (git commit -a).
 
-Then use the following commands to setup everything you'll need on the
-server:
+Then use the following commands on the server to set up the bare git
+repository there:
 
 	mkdir -p $gitrepo
 	cd $gitrepo
 	GIT_DIR=. git init-db
 
-Then, push the contents of this repository out to $gitrepo and
-continue with the following commands (still with $gitrepo as the
-current working directory):
+Then, push the contents of this repository out to $gitrepo. To do
+this, you'll probably want to edit .git/config to point origin at the
+repository you just setup on your web server at $gitrepo. Then do:
+
+	git push origin master:refs/heads/master
+
+Then, back on the server, (and still with $gitrepo as the current
+working directory) do:
 
 	git clone $gitrepo ikiwiki-checkout
 	cd ikiwiki-checkout
 	ikiwiki --setup ikiwiki.setup
 
-[And yes, if you're paying attention there, we just cloned from the
+[And yes, if you're paying attention there, you just cloned from the
 bare repository into a directory that is also inside that same
 repository. I found this a neat place to hide away the
 clone-with-working-tree that ikiwiki needs to edit but that you
@@ -67,14 +73,40 @@ And finally, edit $gitrepo/hooks/post-update to call the new
 $gitrepo/hooks/ikiwiki-post-update program and also don't forget to
 actually enable the hook with:
 
-	chmod a+x $gitrepo/hooks/post-update .
+	chmod a+x $gitrepo/hooks/post-update
+
+Now, you're finally ready to go. You should be able to just start
+adding content under the src directory. You can give files a .mdwn
+extension to use markdown syntax to turn the contents into HTML. Here
+are some hints on doing that:
 
-Now, you're finally ready to go, and you should be able to just start
-adding content under the src directory and use "git push" to publish
-them. To preview things locally, just run "ikiwiki --setup
-ikiwiki.setup", (and ensure the destination paths exist on the local
-machine as well).
+	http://ikiwiki.info/helponformatting/
+
+To preview things locally, you can run "ikiwiki --setup
+ikiwiki.setup", (and ensure the destdir path exists on the local
+machine). When you're ready to publish to your server, it should be as
+simple as "git push".
+
+Problems
+========
+Here is a useful, (self explanatory), command-line options for
+debugging ikiwiki problems:
+
+	ikiwiki --verbose --setup ikiwiki.setup
+
+	ikiwiki --verbose --rebuild --setup ikiwiki.setup
+
+I've had occasions where the hook-based update fails for one reason or
+another, (for example, once when I moved the location of $gitrepo, but
+the compiled hook still had the old location). The basic recipe for
+unwedging things in this case was as simple as running the following
+on the server:
+
+	cd $gitrepo/ikiwiki-checkout
+	git pull
+	ikiwiki --setup ikiwiki.setup
 
-Let me know if you have any problems or questions,
+I hope that's all helpful, and please feel free to let me know if you
+have any problems or questions,
 
 Carl Worth <cworth@cworth.org>