--- a/contrib/hgk
+++ b/contrib/hgk
@@ -4,6 +4,8 @@
 # This program is free software; it may be used, copied, modified
 # and distributed under the terms of the GNU General Public Licence,
 # either version 2, or (at your option) any later version.
+#
+# See hgk.py for extension usage and configuration.
 
 
 # Modified version of Tip 171:

--- a/hgext/hgk.py
+++ b/hgext/hgk.py
@@ -4,6 +4,46 @@
 #
 # This software may be used and distributed according to the terms
 # of the GNU General Public License, incorporated herein by reference.
+#
+# The hgk extension allows browsing the history of a repository in a
+# graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is
+# not distributed with Mercurial.)
+#
+# hgk consists of two parts: a Tcl script that does the displaying and
+# querying of information, and an extension to mercurial named hgk.py,
+# which provides hooks for hgk to get information. hgk can be found in
+# the contrib directory, and hgk.py can be found in the hgext
+# directory.  
+#
+# To load the hgext.py extension, add it to your .hgrc file (you have
+# to use your global $HOME/.hgrc file, not one in a repository). You
+# can specify an absolute path:
+#
+#   [extensions]
+#   hgk=/usr/local/lib/hgk.py
+#
+# Mercurial can also scan the default python library path for a file
+# named 'hgk.py' if you set hgk empty:
+#
+#   [extensions]
+#   hgk=
+#
+# The hg view command will launch the hgk Tcl script. For this command
+# to work, hgk must be in your search path. Alternately, you can
+# specify the path to hgk in your .hgrc file:
+#
+#   [hgk]
+#   path=/location/of/hgk
+#
+# hgk can make use of the extdiff extension to visualize
+# revisions. Assuming you had already configured extdiff vdiff
+# command, just add:
+#
+#   [hgk]
+#   vdiff=vdiff
+#
+# Revisions context menu will now display additional entries to fire
+# vdiff on hovered and selected revisions.
 
 import sys, os
 from mercurial import hg, fancyopts, commands, ui, util, patch, revlog