Added a little "Developers Guide"

2 files changed, 66 insertions, 5 deletions

diff --git a/README.md b/README.md
index dc8798fe..76b98ea7 100644
--- a/README.md
+++ b/README.md
@@ -256,3 +256,55 @@ Please submit your contribution as a Github pull-request.
 If you would like to contact me directly, you can find my e-mail address on my
 [Github profile page](https://github.com/bhilburn).
 
+#### Developers Guide
+
+The theme has grown a lot lately, so I think a little explanation would be 
+helpful.
+
+##### Basic Knowledge
+
+Our main entry point are the `PROMPT` and `RPROMPT` variables, which are 
+interpreted by zsh itself. All that this (and any other) theme does is
+filling these two variables with control instructions (like defining 
+colors, etc.) and ready-to-use data. So within this theme we collect a
+whole bunch of information to put in that variables. You can find 
+`PROMPT` and `RPROMPT` at the very end of the `powerlevel9k.zsh-theme`.
+
+This simple diagram may explain the invoking order better:
+
+```
++-----+    +---------+
+| Zsh |--->| $PROMPT |
++-----+    +---------+
+                |
+                V
+    +---------------------+    +------------+  +---------------------+
+    | build_left_prompt() |--->| prompt_*() |->| $1_prompt_segment() |
+    +---------------------+    +------------+  +---------------------+
+```
+
+##### Adding Segments
+
+Feel free to add your own segments. Every segment gets called with an
+orientation as first parameter (`left` or `right`), so we can figure
+out on which side we should draw the segment. This information is 
+used at the time we call the actual segment-drawing function:
+`$1_prompt_segment`. To make the magic color-overwrite mechanism to
+work, we have to pass our function name as first argument. Usually
+this is just `$0`. Second parameter is a default background color,
+third the default foreground color. And finally we pass our content
+to the function. So our function could look somewhat like this:
+
+```zsh
+    prompt_echo() {
+        local content='Hello World!'
+        $1_prompt_segment $0 blue red $content
+    }
+```
+
+At this point we can overwrite our blue-on-red segment by putting 
+    
+    POWERLEVEL9K_ECHO_FOREGROUND="200"
+    POWERLEVEL9K_ECHO_BACKGROUND="040"
+
+in our `~/.zshrc`. We now have a pink-on-green segment. Yay!
diff --git a/powerlevel9k.zsh-theme b/powerlevel9k.zsh-theme
index f65143a1..726ccbb9 100644
--- a/powerlevel9k.zsh-theme
+++ b/powerlevel9k.zsh-theme
@@ -135,8 +135,13 @@ fi
 ################################################################
 
 # Begin a left prompt segment
-# Takes two arguments, background and foreground. Both can be omitted,
-# rendering default background/foreground.
+# Takes four arguments:
+#   * $1: Name of the function that was orginally invoked (mandatory).
+#         Necessary, to make the dynamic color-overwrite mechanism work.
+#   * $2: Background color
+#   * $3: Foreground color
+#   * $4: The segment content
+# The latter three can be omitted,
 left_prompt_segment() {
   # Overwrite given background-color by user defined variable for this segment.
   # We get as first Parameter the function name, which called this function. 
@@ -177,9 +182,13 @@ left_prompt_end() {
 }
 
 # Begin a right prompt segment
-# Takes two arguments, background and foreground. Both can be omitted,
-# rendering default background/foreground. No ending for the right prompt
-# segment is needed (unlike the left prompt, above).
+# Takes four arguments:
+#   * $1: Name of the function that was orginally invoked (mandatory).
+#         Necessary, to make the dynamic color-overwrite mechanism work.
+#   * $2: Background color
+#   * $3: Foreground color
+#   * $4: The segment content
+# No ending for the right prompt segment is needed (unlike the left prompt, above).
 right_prompt_segment() {
   # Overwrite given background-color by user defined variable for this segment.
   local BACKGROUND_USER_VARIABLE=POWERLEVEL9K_${(U)1#prompt_}_BACKGROUND