-- docs for external config, labels

9 files changed, 110 insertions, 84 deletions

diff --git a/Makefile b/Makefile
index 6e77d63..c0a9e7e 100644
--- a/Makefile
+++ b/Makefile
@@ -6,8 +6,8 @@ tgit:
 	xclip -i git-demo
 	echo "ready to paste ..."
 
-WEB_DESTDIR ?= /tmp/html
-ASCIIDOC ?= asciidoc
+WEB_DESTDIR ?= /tmp/localweb
+ASCIIDOC ?= asciidoc --unsafe
 
 
 show: localweb
diff --git a/README b/README
index b624ac2..82786d5 100644
--- a/README
+++ b/README
@@ -1,48 +1,4 @@
 GIT Prompt for BASH
 
-    Screenshots and docs at: http://volnitsky.com/project/git-prompt
+Screenshots and docs at: http://volnitsky.com/project/git-prompt
 
-
-INSTALL
-
-	Put following command in our profile in interactive section:
-
-		. /path/to/git-prompt.sh
-
-	If there are no interactivity test, then above command should be:
-
-		[[ $- == *i* ]] && . /path/to/git-prompt.sh
-
-
-DEPENDENCY
-
-	Most of dependencies (except git and svn) are probably already installed on your host. 
-
-	bash	(tested with v3.2.33) 
-	git	(optional)
-	svn	(optional)
-	sed
-	tput	(terminfo)
-	tty	(core utils)
-	grep	
-	locale	(glibc)
-	id 	(core utils)
-
-
-TODO
-	- git locked state if .git/index.lock exist
-	- external config at /etc/git-prompt.conf  and ~/.git-prompt.conf
-	- avoid wrapping to 2nd line if file list is too long - check current terminal width
-	- new mail (howto at: http://kikhome.net/?p=11)
-	- ^Z subshell indicator
-	- wiki/screenshots for labels and svn module
-	- VIM module needs to be moved out of GIT module
-	- make module (to show generated, stale files)
-	- How detect current merge?  (current method through .git/MERGE_HEAD not always works)
-DONE
-	- TO FIX: when file list is too long, git-prompt truncates it.  Sometimes this truncation can be on color escape sequence.  
-	- limit number of files displayed
-        
-
-leonid@volnitsky.com
-http://github.com/lvv/git-prompt/tree/master
diff --git a/git-prompt.conf b/git-prompt.conf
index 3b29beb..64c158a 100644
--- a/git-prompt.conf
+++ b/git-prompt.conf
@@ -1,43 +1,55 @@
-# git-prompt.sh config
-# 
-# commented-out variales are default values
 
+###  GIT-PROMPT.SH CONFIG
+###
+###    lines commented-out with single '#' are default values
+###    lines commented-out with double '##' are examples
 
-#####  MODULES
-#git_module=on
-#svn_module=off
-#vim_module=on
 
+############################################################   MODULES
 
-###  Default objects are not displayed 
-#default_user=lvv 		
-#default_host="ahp"     		# remote host is always shown
-#default_domain="lvvnet"	
+# git_module=on
+# svn_module=off
+# vim_module=on
 
+# max_file_list_length=100	# in characters
 
-#####  dir, exit code, root color 
-#if [ 0`tput colors` -ge 8 ];  then		#  if terminal supports colors
+###########################################################   DEFAULT OBJECTS
+
+###  Default objects are not displayed.  Example:
+
+## default_user=lvv 		
+## default_host="ahp"     		# remote host is always shown
+## default_domain="lvvnet"	
+
+
+###########################################################   COLOR 
+
+###  directory, exit code, root color 
+
+# if [ 0`tput colors` -ge 8 ];  then		#  if terminal supports colors
 	#	dir_color=CYAN
 	#	rc_color=red
 	#	root_id_color=magenta
-#else						#  B/W terminal
+# else						#  B/W terminal
 	#	dir_color=bw_bold
 	#	rc_color=bw_bold
-#fi
+# fi
+
+
+#####  Per host color.  If not set, color derived from host-name  checksum)
+
+### variable name is uppercase-short-hostname with appended "_host_color"
+### Per host color.  If not set, color derived from host-name  checksum)
+### Example per-host-color config:  
 
-#####  Per host color  .If not set, color derived from host-name  checksum)
-## variable name is uppercase-short-hostname with appended "_host_color"
-## Per host color.  If not set, color derived from host-name  checksum)
-## Example per-host-color config:  
-##
 ##	    TASHA_host_color=cyan
 ##	       AL_host_color=green
 ##	      LVV_host_color=blue
 ##	      AHP_host_color=white
 
 
+#####  VCS (version control system)  state colors
 
-#####  VCS state colors
 #		 init_vcs_color=WHITE     # initial
 #		clean_vcs_color=blue      # nothing to commit (working directory clean)
 #	     modified_vcs_color=red       # Changed but not updated:
@@ -47,7 +59,5 @@
 #		   op_vcs_color=MAGENTA
 #	     detached_vcs_color=RED
 
-#	max_file_list_length=100
-
 
 : vim:ft=sh:
diff --git a/index.txt b/index.txt
index 8445141..c905463 100644
--- a/index.txt
+++ b/index.txt
@@ -1,6 +1,6 @@
-= GIT Prompt - there is a lot more than a branch-name
+= GIT Prompt
 
-//  To see HTML rendered web page go to:   http://volnitsky.com/project/lopti
+//  To see HTML rendered web page go to:  http://volnitsky.com/project/git-prompt
 
 :v-p:		http://volnitsky.com/project
 :compact-option: compact
@@ -17,7 +17,7 @@ Digit [red]*1* on 3rd line is `false(1)` exit code.
 
 Branch and files are colored according to state. "M" stands for master. 
 
-image:screenshot-prompt-git.png[git module]
+image:screenshot-prompt-git.png[git module screenshot]
 
 .Branch and Files Colors
 [cols="^3,^3,12",frame="topbot",options="header"]
@@ -31,12 +31,49 @@ image:screenshot-prompt-git.png[git module]
 | [magenta]#magenta#       |                          | In middle of doing something 
 |================================================================
 
+
 ==  Subversion
-...
+image:screenshot-svn.png[svn module screenshot]
+
+SVN module disabled by default because even on moderate sized working
+directories there is noticeable delay for prompt display.  SVN is slower then
+GIT.  Enable if needed in <<config,config>> 
+
 
 == Labels
 
-...
+Labels are very much like xterm-title and serve purpose of being  visual cues to help figure out what is
+running what command.
+
+They are displayed in terminal titles, terminal tabs, `screen(1)` status
+line and some other places.
+
+image:screenshot-labels.png["labels screenshot", width="300", link="screenshot-labels.png"]
+
+The `screen(1)` status line at bottom of smaller gnome-terminal is displayed with
+following `~/.screenrc` line:
+
+---------
+caption always "%{= kw}%-w%{= bw}%n %t%{-}%+w %-= @%H - %LD %d %LM - %c"
+---------
+
+We don't need to do any thing for something like `cd` or `ssh` (if you have
+git-prompt on remote host).
+For external command we need set label before it is executed.
+It would be simple if `bash` set command name to some variable before execution,
+but it does not do this. So we have to use not elegant wrappers.
+We can not write wrapper for every command. 
+I use wrapper only for `vim` and `man` in my `~/.bashrc`
+
+-------------------------
+vi() {  set_shell_title "vi $@"; /usr/bin/vim -p "$@"; };  export -f vi
+man() { set_shell_title "man $@"; /usr/bin/man "$@";  }; export -f man
+----------------------------
+
+Note that vim sets xterm title itself, but we still use wrapper to set `screen` labels.
+Function `set_shell_title` defined in `git-prompt.sh`.
+
+
 
 == Install
 Download  link:git-prompt.sh[] or get it with GIT:
@@ -51,12 +88,41 @@ Put following command in our profile in interactive section:
   . /path/to/git-prompt.sh
 ---------------------
 
-If there are no interactivity test in your profile, then above command should be:
+If there are no interactivity test in your profile or you don't know what it
+is, then above command should be:
 
 --------------------
   [[ $- == *i* ]] && . /etc/git-prompt.sh
 ---------------------
 
+
+== Config 
+[[config]]
+
+Git-prompt sources two config file if they are present:
+
+- `/etc/git-prompt.conf`
+- `~/.git-prompt.conf`
+
+Copy example config `git-prompt.conf` 
+to any of above locations and customize as needed.
+
+
+== Limitations
+
+- cd-ing into something like linux kernel git working directory for the 1st
+  time (with cold cache) will take about 10 seconds (that is how long `git status` executes).
+- Because you will be always reminded about not checking-in files, you will
+  be more disciplined about maintaining clean working
+  directory.  And you probably will better maintain `.gitignore` and commit more often.
+- If you have terminal with limited width, you might want to disable
+  file list display (`max_file_list_length=0`).
+- When prompt is longer then screen-width it wraps to second line. Because of
+  bug in `gnome-terminal` (or `readline`?) some color escape codes can be
+  visible on second line.  I've reported gnome-terminal bug.
+  Again, you can disable file list display or limit length (`max_file_list_length`).
+
+
 == DEPENDENCY
 
 Most of dependencies (except git and svn) are probably already installed on your host. 
@@ -67,23 +133,17 @@ Most of dependencies (except git and svn) are probably already installed on your
 - sed
 - tput  (terminfo)
 - tty  (core utils)
-- grep  
+- grep
 - locale  (glibc)
 - id   (core utils)
 
-include::../volnitsky.com/project/howto-submit-patch.txt[]
 
 == TODO
 
-- external config at `/etc/git-prompt.conf` and `~/.git-prompt.conf`
-- always display remote hostname if login is through sshd (how to detect this?)
 - new mail (howto at: `http://kikhome.net/?p=11` )
 - ctrl-Z subshell indicator
-- screenshots for labels and svn module
 - VIM module needs to be moved out of GIT module
 - make module (to show generated, stale files)
 - How detect current merge?  (current method through .git/MERGE_HEAD not always works)
 
-== DONE
-- different host color even if they are not in config
-- TO FIX: when file list is too long, git-prompt truncates it. Sometimes this truncation can be on color escape sequence.
+include::../volnitsky.com/project/howto-submit-patch.txt[]
diff --git a/labels-screenshot.png b/labels-screenshot.png
deleted file mode 100644
index 273c552..0000000
--- a/labels-screenshot.png
+++ /dev/null
diff --git a/screenshot-labels.png b/screenshot-labels.png
new file mode 100644
index 0000000..71f3513
--- /dev/null
+++ b/screenshot-labels.png
diff --git a/screenshot-labels.xcf b/screenshot-labels.xcf
new file mode 100644
index 0000000..b0f482c
--- /dev/null
+++ b/screenshot-labels.xcf
diff --git a/screenshot-svn.png b/screenshot-svn.png
new file mode 100644
index 0000000..6b9dec7
--- /dev/null
+++ b/screenshot-svn.png
diff --git a/svn-screenshot.png b/svn-screenshot.png
deleted file mode 100644
index da76080..0000000
--- a/svn-screenshot.png
+++ /dev/null