Remove stray period

[ikiwiki-bootstrap] / README

diff --git a/README b/README
index c2589e09e3a4de914304b96c5105ef4d5455681c..8ec1f7cf2e422bcdcd3f06f8eba5a365f53ba14c 100644 (file)
--- a/README
+++ b/README
@@ -1,14 +1,18 @@
 This is a simple set of files for bootstrapping a git-backed instance
 of ikiwiki.
 
 This is a simple set of files for bootstrapping a git-backed instance
 of ikiwiki.
 

-I put this together to make it easier to get started with ikiwiki than
-following the standad instructions:
+I put this together to make it easier for people who are already
+comfortable with git to start using ikiwiki with git. If you're not
+already comfortable with git, then you're probably much better off
+learning to use ikiwiki from its standard instructions:

 
        http://ikiwiki.info/setup/
 
 Features
 ========
 
        http://ikiwiki.info/setup/
 
 Features
 ========

-Here are some of the key features of what I've got setup:
+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).

 
 1. Self-contained.
 
 
 1. Self-contained.
 


@@ -23,26 +27,86 @@ Here are some of the key features of what I've got setup:
 
 3. Pre-configured for git
 
 
 3. Pre-configured for git
 

-       Most of the git-specific settings you need are already setup
-       in ikiwiki.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
+       edit post-update to call ikiwiki-post-update, (perhaps in
+       addition to anything else you want to do in post-update). See
+       below.

 
 Usage
 =====
 
 Usage
 =====

-To start choose where the bare git repository will exist on your web
+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
 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).

 
 

-Next, follow these steps to setup gitrepo along with a nested checkout
-inside of it that ikiwiki will use:
+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. 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
        git clone $gitrepo ikiwiki-checkout

+       cd ikiwiki-checkout
+       ikiwiki --setup ikiwiki.setup
+
+[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
+shouldn't touch. If you think this is too creepy, you could put it
+anywhere else, and configure ikiwiki.setup to point to it there.]
+
+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
+
+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
+========
+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:

 
 

-Finally, push this repository out to $gitrepo, then start adding
-content in files under src.
+       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>