# HG changeset patch
# User Steve Losh <steve@stevelosh.com>
# Date 1245460931 14400
# Node ID e549425b0dbbd4c6e4a0328a3da1f9579e08dcce
# Parent  753a78ff7a171d10dc23711dd658c72c0fb6ba36
Add some documentation.

diff -r 753a78ff7a17 -r e549425b0dbb prompt.py
--- a/prompt.py	Fri Jun 19 20:50:08 2009 -0400
+++ b/prompt.py	Fri Jun 19 21:22:11 2009 -0400
@@ -1,10 +1,11 @@
 #!/usr/bin/env python
 
-'''prompt
+'''get repository information for use in a shell prompt
 
-Take a format string, parse any template variables inside, and output
-the result.  Useful for putting information about the current repository into
-a bash prompt.
+Take a string, parse any special variables inside, and output the result.
+
+Useful mostly for putting information about the current repository into
+a shell prompt.
 '''
 
 import re
@@ -18,7 +19,38 @@
                                   g[1][1:]  if g[1] else '')    
 
 def prompt(ui, repo, fs):
-    """Take a format string, parse any variables, and output the result."""
+    '''get repository information for use in a shell prompt
+    
+    Take a string and output it for use in a shell prompt. You can use 
+    keywords in curly braces:
+    
+        $ hg prompt "currently on {branch}"
+        currently on default
+    
+    You can also use an extended form of any keyword:
+    
+        {optional text here{keyword}more optional text}
+    
+    This will expand the inner {keyword} and output it along with the extra
+    text only if the {keyword} expands successfully.  This is useful if a
+    keyword that may not always apply to the current state and you have some
+    text that you would like to see only if it is appropriate:
+    
+        $ hg prompt "currently at {bookmark}"
+        currently at 
+        $ hg prompt "{currently at {bookmark}}"
+        $ hg bookmark my-bookmark
+        $ hg prompt "{currently at {bookmark}}"
+        currently at my-bookmark
+    
+    The following keywords are available:
+    
+    - bookmark: the current bookmark
+    - branch: the current branch
+    - status: "!" if the current repository contains files that have been
+        modified, added, removed, or deleted, otherwise "?" if it contains
+        untracked (and not ignored) files, otherwise nothing.
+    '''
     
     def _branch(m):
         branch = repo[-1].branch()
@@ -49,5 +81,5 @@
     ui.status(fs)
 
 cmdtable = {
-    "prompt": (prompt, [], 'hg prompt "FORMATSTRING"')
+    "prompt": (prompt, [], 'hg prompt STRING')
 }
\ No newline at end of file