Update README with several additions.

* Explicit instructions on how to do the first push

* Where to find instructions on markdown syntax

* A tip on how to unwedge things

diff --git a/README b/README
index 306d0da3e8b1b9abe00b9ae28d90987ae614b2ea..a2222324beb2c0aba92a52acf5283aed8ab2e10d 100644 (file)
--- a/README
+++ b/README
@@ -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 set up 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
@@ -69,12 +75,31 @@ actually enable the hook with:
 
        chmod a+x $gitrepo/hooks/post-update .
 
-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).
+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:
+
+       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
+========
+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>