new version of the ikiwiki vim plugin. docs upgraded. new forum post

[ikiwiki.git] / doc / tips / inside_dot_ikiwiki.mdwn

diff --git a/doc/tips/inside_dot_ikiwiki.mdwn b/doc/tips/inside_dot_ikiwiki.mdwn
index 69083a9a544b8c2891ee26d4e5af259ebf9e4f89..a74d00f473416b28512b769fa3239e0f551ea02e 100644 (file)
--- a/doc/tips/inside_dot_ikiwiki.mdwn
+++ b/doc/tips/inside_dot_ikiwiki.mdwn
@@ -1,4 +1,4 @@
-[[meta title="inside .ikiwiki"]]
+[[!meta title="inside .ikiwiki"]]
 
 The `.ikiwiki` directory contains ikiwiki's internal state. Normally,
 you don't need to look in it, but here's some tips for how to do so if
@@ -6,9 +6,10 @@ you need/want to.
 
 ## the index
 
-`.ikiwiki/indexdb` contains a cache of information about pages, as well
-as all persisitant state about pages. It used to be a (semi) human-readable
-text file, but is not anymore.
+`.ikiwiki/indexdb` contains a cache of information about pages.
+This information can always be recalculated by rebuilding the wiki.
+(So the file is safe to delete and need not be backed up.)
+It used to be a (semi) human-readable text file, but is not anymore.
 
 To dump the contents of the file, enter a perl command like this.
 
@@ -51,15 +52,40 @@ To dump the entire database contents:
                                                  'email' => 'joey@kitenet.net',
        [...]
 
-Editing values is simply a matter of changing values and calling Storable::nstore().
-So to change a user's password:
+Editing values is simply a matter of changing values and calling `Storable::nstore()`.
+So to change a user's email address:
 
-       joey@kodama:~/src/joeywiki/.ikiwiki> perl -le 'use Storable; my $userinfo=Storable::retrieve("userdb"); $userinfo->{"foo"}->{email}=q{foo@bar}; Storable::lock_nstore($userinfo, "underdb")'
+       joey@kodama:~/src/joeywiki/.ikiwiki> perl -le 'use Storable; my $userinfo=Storable::retrieve("userdb"); $userinfo->{"foo"}->{email}=q{foo@bar}; Storable::lock_nstore($userinfo, "userdb")'
 
 To remove that user:
        
-       joey@kodama:~/src/joeywiki/.ikiwiki> perl -le 'use Storable; my $userinfo=Storable::retrieve("userdb"); delete $userinfo->{"foo"}; Storable::lock_nstore($userinfo, "underdb")'
+       joey@kodama:~/src/joeywiki/.ikiwiki> perl -le 'use Storable; my $userinfo=Storable::retrieve("userdb"); delete $userinfo->{"foo"}; Storable::lock_nstore($userinfo, "userdb")'
 
 I've not written actual utilities to do this yet because I've only needed
 to do it rarely, and the data I've wanted has been different each time.
 --[[Joey]]
+
+## the session database
+
+`.ikiwiki/sessions.db` is the session database. See the [[!cpan CGI::Session]]
+documentation for more details.
+
+## lockfiles
+
+In case you're curious, here's what the various lock files do.
+
+* `.ikiwiki/lockfile` is the master ikiwiki lock file. Ikiwiki takes this 
+  lock before reading/writing state.
+* `.ikiwiki/commitlock` is locked as a semophore, to disable the commit hook
+  from doing anything.
+* `.ikiwiki/cgilock` is locked by the cgi wrapper, to ensure that only 
+  one ikiwiki process is run at a time to handle cgi requests.
+
+## plugin state files
+
+Some plugins create other files to store their state. 
+
+* `.ikiwiki/aggregate` is a plain text database used by the aggregate plugin
+  to record feeds and known posts.
+* `.ikiwiki/xapian/` is created by the search plugin, and contains xapian-omega
+  configuration and the xapian database.