diff --git a/doc/ChangeLog b/doc/ChangeLog
index 7d0a96f..0bd9cc2 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -9,6 +9,11 @@
 	path delimiters, though. Also deleted all pretense of supporting 
 	multiline command strings in !system or %magic commands. Thanks to
 	Jerry McRae for suggestions.
+	
+	* doc/build_doc_instructions.txt added. Documentation on how to use
+	doc/update_manual.py, added yesterday. Both files contributed by
+	Jörgen Stenarson <jorgen.stenarson@bostream.nu>. This slates
+	doc/*.sh for deprecation at a later date.
 
 2006-01-12  Fernando Perez  <Fernando.Perez@colorado.edu>
 
diff --git a/doc/build_doc_instruction.txt b/doc/build_doc_instruction.txt
new file mode 100644
index 0000000..b546509
--- /dev/null
+++ b/doc/build_doc_instruction.txt
@@ -0,0 +1,28 @@
+How to generate IPython documentation
+=====================================
+
+The doc is written using lyx http://www.lyx.org, which is a gui for latex
+documents. LyX also requires a latex installation.
+
+The file manual_base.lyx is the template file that should be edited if you
+want to do changes to the docs.
+
+A final version is generated by running 
+
+./update_manual.py
+
+or 
+
+ipython update_manual.py
+
+(note that "python update_manual.py" won't work, it's an ipython script!)
+
+The script update_manual.py will insert the current version number into the
+template and also generate magic.tex, a file containing documentation for
+the doc strings of the magic commands.
+
+The script creates manual.lyx which can be opened by lyx to generate pdf or
+postscript versions of the docs.
+
+update_magic.sh and update_version.sh work too, but are slated for
+deprecation.
diff --git a/doc/update_manual.py b/doc/update_manual.py
index 9f5a885..5a58814 100644
--- a/doc/update_manual.py
+++ b/doc/update_manual.py
@@ -1,13 +1,13 @@
+#!/usr/bin/env ipython
 """ Must be launched via ipython not normal python 
 
-in ipython prompt do
-
-> %run update_manual.py
+Run by:
+    
+    ipython update_manual.py
 """
 
 import sys,IPython,re
 
-
 fil=open("magic.tex","w")
 oldout=sys.stdout
 sys.stdout=fil
@@ -23,4 +23,6 @@ manualtext=re.sub("__version__",IPython.__version__,txt)
 fil=open("manual.lyx","w")
 fil.write(manualtext)
 fil.close()
-print "Manual (magic.tex, manual.lyx) succesfully updated!"
+print "Manual (magic.tex, manual.lyx) succesfully updated, exiting..."
+import os
+os.abort()