From c13e6d795f235afeee4cd38ed5117272dcd5be58 Mon Sep 17 00:00:00 2001
From: nojhan <nojhan@gmail.com>
Date: Thu, 19 Jul 2012 14:17:32 +0200
Subject: [PATCH] explanations about liquidprompt

---
 README.md         | 70 +++++++++++++++++++++++++++++++++++++++++++++++
 liquidprompt.bash | 10 +++++--
 2 files changed, 77 insertions(+), 3 deletions(-)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ca3bb8c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,70 @@
+Liquid prompt -- A useful adaptive Bash prompt
+==============================================
+
+Liquid prompt is a smart prompt for the "Bourne-Again" Unix shell (bash).
+
+The basic idea of the liquid prompt is to nicely display useful informations on
+the shell prompt, only when they are needed. It adds carefuly chosen colors to
+draw your attention on what differs from the normal context. Thus, you will
+notice what changes, when it changes, because you do not become accommodated to
+informations that are always displayed in the same way.
+
+
+## FEATURES
+
+If there is nothing special in the current context, the liquid prompt is close
+to a default prompt:
+
+`[user:~] $ `
+
+If you have ran one command in background that is still running and that you are
+in a git repository, on branch "myb":
+
+`1r [user@server:~/liquidprompt] myb ± `
+
+A liquid prompt displaying everything may look like this:
+
+`25% 12.5 1s/1r [user@server:~/liquidprompt] master(3) 125 ± `
+
+It displays:
+
+* the average of the batteries remaining power, if it is under a given
+threshold, with a colormap too;
+* the average of the processors load, if it is over a given limit, with a
+colormap that became more and more noticeable with increasing load;
+* the number of attached sleeping jobs (when you interrupt a command with Ctrl-Z
+and bring it back with `fg`), if there is any;
+* the number of attached running jobs (commands started with a `&`), if there is
+any;
+* the current user, in bold yellow if it is root;
+* the current host, if you are connected via an SSH or telnet connection, with
+different colors for each case;
+* the current directory in bold;
+* the name of the current branch if you are in a version control repository
+(git, mercurial or subversion), in green if everything is up to date, in red if
+there is changes, in yellow if there is pending commits to push;
+* the number of pending commits, if any;
+* the error code of the last command, if it has failed in some way;
+* a smart mark: ± for VCS directories, $ for simple user, a red # for root.
+
+
+## USAGE
+
+Include the file in your bash configuration, for example in your `.bashrc`:
+
+`source liquidpromt.bash`
+
+
+## PUT THE PROMPT IN A DIFFERENT ORDER
+
+Most of the display is prepared in the `__set_bash_prompt` function, apart from
+features that needs several colors (such as the load colormap). You can sort
+what you want to see by editing the PS1 variable.
+
+
+## KNOWN LIMITATIONS AND BUGS
+
+* Does not display the number of commits to be pushed in Mercurial repositories.
+* Subversion repository cannot display commits to be pushed, this is a
+limitation of the Subversion versionning model.
+
diff --git a/liquidprompt.bash b/liquidprompt.bash
index 30bbef1..f2064eb 100644
--- a/liquidprompt.bash
+++ b/liquidprompt.bash
@@ -405,7 +405,7 @@ __smart_mark()
     fi
 }
 
-# space right
+# insert a space on the right
 __sr()
 {
     if [ ! -z "$1" ] ; then
@@ -413,7 +413,7 @@ __sr()
     fi
 }
 
-# space left
+# insert a space on the left
 __sl()
 {
     if [ ! -z "$1" ] ; then
@@ -421,7 +421,7 @@ __sl()
     fi
 }
 
-# space both
+# insert two space, before and after
 __sb()
 {
     if [ ! -z "$1" ] ; then
@@ -455,13 +455,17 @@ __set_bash_prompt()
     # end of the prompt line: double spaces
     __MARK=$(__sb "`__smart_mark`")
 
+    # add jobs, load and battery
     PS1="${__BATT}${__LOAD}${__JOBS}"
+
+    # if not root
     if [ "$EUID" -ne "0" ]
     then
         PS1="${PS1}[${LIGHT_GREY}\u${NO_COL}${__HOST}:${WHITE}\w${NO_COL}]"
         PS1="${PS1}${__GIT}${__HG}${__SVN}"
     else
         PS1="${PS1}[${LIGHT_YELLOW}\u${__HOST}${NO_COL}:${YELLOW}\w${NO_COL}]"
+        # do not add VCS infos
     fi
     PS1="${PS1}${PURPLE}${__RET}${NO_COL}${__MARK}"