web commit by http://jeremie.koenig.myopenid.com/: precision

[ikiwiki.git] / doc / setup.mdwn

diff --git a/doc/setup.mdwn b/doc/setup.mdwn
index 41c42a723be161810d7cbfb381722f6ba1386311..8e5653442e21265e75beca467ad1cd3dd8504b25 100644 (file)
--- a/doc/setup.mdwn
+++ b/doc/setup.mdwn
@@ -1,11 +1,13 @@
 This tutorial will walk you through setting up a wiki with ikiwiki.
 
-1. [[Install]] ikiwiki. See [[download]] for where to get it.
+1. [[Download]] and [[install]] ikiwiki.
 
 2. Decide where your wiki's files will go.
 
-   As a wiki compiler, ikiwiki builds a wiki from files in a source
-   directory, and outputs the files to a destination directory.
+   As a wiki compiler, ikiwiki builds a wiki from files in a source directory,
+   and outputs the files to a destination directory.  If you keep your wiki in
+   a version control system, the source directory will contain a working copy
+   checked out from the version control system.
 
    For the purposes of this tutorial, we'll set shell variables
    for these locations, and use those variables in the commands that follow.
@@ -13,6 +15,9 @@ This tutorial will walk you through setting up a wiki with ikiwiki.
                        SRCDIR=~/wikiwc
                        DESTDIR=~/public_html/wiki/
 
+   Note that ikiwiki owns the working copy directory; do not perform your own
+   edits in ikiwiki's working copy.
+
 3. Create the beginnings of your wiki.
 
    This will create a simple main page for the wiki.
@@ -29,18 +34,18 @@ This tutorial will walk you through setting up a wiki with ikiwiki.
                        All wikis are supposed to have a [[SandBox]],
                        so this one does too.
                        ----
-                       This wiki is powered by [ikiwiki](http://ikiwiki.kitenet.net).
+                       This wiki is powered by [ikiwiki](http://ikiwiki.info).
    """]]
    
    See [[HelpOnFormatting]] for details about the markup language.
 
-   Note that several standard wiki pages will be added to your wiki, from
-   files in `/usr/share/ikiwiki/basewiki/`, so your wiki will automatically
-   get a [[SandBox]], and some other useful pages.
+   Note that several [[standard_wiki_pages|basewiki]] will be added to your
+   wiki, from files in `/usr/share/ikiwiki/basewiki/`, so your wiki will
+   automatically get a [[SandBox]], and some other useful pages.
 
 4. Build your wiki for the first time.
 
-                       ikiwiki --verbose $SRCDIR $DESTDIR --url=http://host/~you/wiki/
+                       ikiwiki --verbose $SRCDIR $DESTDIR --url=http://example.org/~you/wiki/
 
    Replace the url with the real url to your wiki. You should now
    be able to visit the url and see your wiki.
@@ -61,7 +66,9 @@ This tutorial will walk you through setting up a wiki with ikiwiki.
    introduce setup files.
    
    A sample setup file is [[ikiwiki.setup]]. Download it (or copy it from
-   `doc/ikiwiki.setup` in the ikiwiki sources), and edit it.
+   `doc/ikiwiki.setup` in the ikiwiki sources), and edit it. Note that this
+   file should *not* be put in your wiki's directory with the rest of the
+   files. A good place to put it is in a ~/.ikiwiki/ subdirectory.
    
    Most of the options, like `wikiname` in the setup file are the same as
    ikiwiki's command line options (documented in [[usage]]. `srcdir` and
@@ -147,6 +154,32 @@ This tutorial will walk you through setting up a wiki with ikiwiki.
                        hg commit -m "initial import"
    """]]
 
+   [[toggle id=monotone text="Monotone"]]
+   [[toggleable id=montone text="""
+                       # These instructions are standard instructions to import a directory into monotone
+                       # and set it up so that you don't need any passwords to use it
+                       REPOSITORY=~/.ikiwiki/mtn.db
+                       BRANCH=com.company.wikiname
+                       # remember the password you use in the next step and
+                       # substitute it for 'wikiKeyPass' in the get_passphrase() hook below
+                       # note the you should never generate two monotone keys with the same name
+                       mtn genkey web@machine.company.com
+                       mtn db init --db=$REPOSITORY
+                       mv $SRCDIR $SRCDIR-old
+                       cd $SRCDIR-old
+                       echo ".ikiwiki" > $SRCDIR-old/.mtn-ignore
+                       mtn --db=$REPOSITORY --branch=$BRANCH import . -m "initial import"
+                       cd ..
+                       mtn --db=$REPOSITORY --branch=$BRANCH checkout $SRCDIR
+                       mv $SRCDIR-old/.ikiwiki $SRCDIR
+                       cat << EOF > $SRCDIR/_MTN/monotonerc
+                       function get_passphrase (branchname)
+                           return "wikiKeyPass"
+                       end
+                       EOF
+                       rm -r $SRCDIR-old
+   """]]
+
 9. Configure ikiwiki to use revision control.
 
    Once your wiki is checked in to the revision control system,
@@ -163,4 +196,5 @@ This tutorial will walk you through setting up a wiki with ikiwiki.
    And in the web interface, RecentChanges should work, and files changed
    by web users will also be committed using revision control.
 
-10. Enjoy your new wiki! Add yourself to [[IkiWikiUsers]].
+10. Enjoy your new wiki! Add yourself to [[IkiWikiUsers]]. And check out
+    [[tips]] to find out how to get more out of ikiwiki.