diff --git a/README b/README
index b2147f8..d23f7fb 100644
--- a/README
+++ b/README
@@ -1,3 +1,34 @@
 Collected scripts from dokuwiki tips page.
 
 http://www.dokuwiki.org/tips:moinmoin2doku
+
+moin2doku.py
+
+A script for converting MoinMoin version 1.3+ wiki data to DokuWiki format.
+Call with the name of the directory containing the MoinMoin pages and that
+of the directory to receive the DokuWiki pages on the command line:
+
+You need to run this on host where MoinMoin is configured and DokuWiki is
+configured, it will use current configuration from both wikis.
+
+Edit doku.php if your DokuWiki installation is other than /usr/share/dokuwiki
+
+$ ./moin2doku.py ./moin/data/pages/
+
+after conversion be sure to fix ownership (www-data:www-data being your uid/gid
+webserver runs):
+# chown -R www-data:www-data /var/lib/dokuwiki/pages/*
+# chown -R www-data:www-data /var/lib/dokuwiki/media/*
+
+This script doesn't do all the work, and some of the work it does is
+wrong. For instance attachment links end up with the trailing "|}}"
+on the line following the link. This works, but doesn't look good.
+The script interprets a "/" in a pagename as a namespace delimiter and
+creates and fills namespace subdirectories accordingly.
+
+History:
+version 0.1  2010-02  Slim Gaillard, based on the "extended python"
+                      convert.py script here:
+                      http://www.dokuwiki.org/tips:moinmoin2doku
+version 0.2  2011     Elan Ruusamäe, moved to github, track history there
+                      https://github.com/glensc/moin2doku
diff --git a/doku.php b/doku.php
index ccdbef1..41ae830 100755
--- a/doku.php
+++ b/doku.php
@@ -2,8 +2,10 @@
 <?php
 # -*- coding: utf-8 -*-
 # Setup VIM: ex: et ts=2 sw=2 :
-# Bridge for Python code to invoke DokuWiki functions.
-# 
+#
+# PHP side Bridge of accessing DokuWiki functions from Python.
+# See README for details.
+#
 # Author: Elan Ruusamäe <glen@pld-linux.org>
 #
 # You should probably adjust path to DOKU_INC.
diff --git a/doku.py b/doku.py
index 2f65207..9b898ed 100644
--- a/doku.py
+++ b/doku.py
@@ -1,8 +1,10 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 # Setup VIM: ex: noet ts=2 sw=2 :
-# Bridge for Python code to invoke DokuWiki functions.
-# 
+#
+# Python side Bridge of accessing DokuWiki functions from Python.
+# See README for details.
+#
 # Author: Elan Ruusamäe <glen@pld-linux.org>
 
 import sys
diff --git a/moin2doku.py b/moin2doku.py
index efcb567..4e3fb59 100755
--- a/moin2doku.py
+++ b/moin2doku.py
@@ -2,32 +2,11 @@
 # -*- coding: utf-8 -*-
 # Setup VIM: ex: et ts=2 sw=2 :
 #
-# moin2doku.py
-#
-# A script for converting MoinMoin version 1.3+ wiki data to DokuWiki format.
-# Call with the name of the directory containing the MoinMoin pages and that
-# of the directory to receive the DokuWiki pages on the command line:
-#
-# You need to run this on host where MoinMoin is configured and DokuWiki is
-# configured, it will use current configuration from both wikis.
-#
-# python moin2doku.py ./moin/data/pages/
-#
-# set ownership: chown -R www-data:www-data /var/lib/dokuwiki/pages/*
-# chown -R www-data:www-data /var/lib/dokuwiki/media/*
-#
-# This script doesn't do all the work, and some of the work it does is
-# wrong. For instance attachment links end up with the trailing "|}}"
-# on the line following the link. This works, but doesn't look good.
-# The script interprets a "/" in a pagename as a namespace delimiter and
-# creates and fills namespace subdirectories accordingly.
-#
-# version 0.1  02.2010  Slim Gaillard, based on the "extended python"
-#                       convert.py script here:
-#                       http://www.dokuwiki.org/tips:moinmoin2doku
-# version 0.2 Elan Ruusamäe, moved to github, track history there
-#                       https://github.com/glensc/moin2doku
+# Main Script doing the conversion.
+# See README for details.
 #
+# Author: Elan Ruusamäe <glen@pld-linux.org>
+
 import sys, os, os.path, re
 import getopt
 from shutil import copyfile, copystat