Update README with several additions.

[ikiwiki-bootstrap] / README

diff --git a/README b/README
index 27d04a5eeaae90fdc8d6cc5903313d9641c21dee..a2222324beb2c0aba92a52acf5283aed8ab2e10d 100644 (file)
--- a/README
+++ b/README
@@ -10,7 +10,7 @@ learning to use ikiwiki from its standard instructions:
 
 Features
 ========
 
 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).
 
 are different than following the standard instruction for integrating
 ikiwiki with git).
 


@@ -27,7 +27,7 @@ ikiwiki with git).
 
 3. Pre-configured for 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
        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
 =====
 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
 
 
        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
 
 
        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
 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 .
 
 
        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>
 
 Carl Worth <cworth@cworth.org>