start a more complete readme
authorJoerg Jaspert <joerg@ganneff.de>
Fri, 22 Mar 2013 13:38:59 +0000 (14:38 +0100)
committerJoerg Jaspert <joerg@ganneff.de>
Fri, 22 Mar 2013 13:38:59 +0000 (14:38 +0100)
.zsh/README

index 80df1c8..abc6c16 100644 (file)
-########################################################################
-# To correctly use this fileset for zsh, you need to understand the
-# order in which stuff is loaded by zsh.
-#
-# Wherever $ZDOTDIR is unset, $HOME is used instead
-# 
-# 1. /etc/zsh/zshenv             This is not overridable and not affected by the
-#                                RCS/GLOBAL_RCS variables explained below!
-# 2. $ZDOTDIR/.zshenv            
-#
-# If the shell is a login shell, it continues with
-# 3. /etc/zsh/zprofile
-# 4. $ZDOTDIR/.zprofile
-#
-# If the shell is interactive, it continues with
-# 5. /etc/zsh/zshrc
-# 6. $ZDOTDIR/.zshrc
-#
-# If the shell is a login shell, it continues with
-# 7. /etc/zsh/zlogin
-# 8. $ZDOTDIR/zlogin
-########################################################################
-
-########################################################################
-# On logout it is easier: If the shell exits (not due to exec'ing another
-# process, but logout/exit), it reads
-#
-# 1. $ZDOTDIR/.zlogout
-# 2. /etc/zsh/zlogout
-########################################################################
-
-########################################################################
-# There are 2 variables affecting the above ordering.
-#
-# RCS         If this is unset, none of the (remaining) startup files
-#             are sourced.
-# GLOBAL_RCS  If this is unset, none of the startup files in /etc/zsh
-#             are sourced.
-#
-# Note: These variables do NOT affect /etc/zsh/zshenv, which is
-#       ALWAYS read!
+* ZSH configuration "framework"
+
+This is my zsh configuration. Well, more a framework of it.
+It is setting quite a lot of defaults, but at the same time
+tries to be as user configurable as makes sense. So most of the
+settings should be easy (enough) to adjust.
+
+** The boring stuff, license / copyright
+
+It is hard to say what exact license applies: It consists of a lot of
+snippets taken from a lot of places all over the net, many of which I
+don't remember anymore. Also, many of which are probably small enough
+that no copyright would apply.
+
+Where I still remember where it is from, I tried to mark them as such,
+giving credit where its due. If you find something in here thats from
+you and want to be mentioned, just mail me.
+
+For stuff that is from me, use the following license terms:
+
+Copyright (C) 2013, Joerg Jaspert <joerg@ganneff.de>
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+* Usage
+** Basics
+To correctly use this fileset for zsh, you need to understand the
+order in which things are loaded by zsh.
+
+Note: Wherever $ZDOTDIR is unset, $HOME is used instead
+
+- Always
+  1. /etc/zsh/zshenv  This is not overridable and not affected by the
+                      RCS/GLOBAL_RCS variables explained below!
+  2. $ZDOTDIR/.zshenv
+
+- If the shell is a *login* shell, it continues with
+  3. /etc/zsh/zprofile
+  4. $ZDOTDIR/.zprofile
+
+- If the shell is *interactive*, it continues with
+  5. /etc/zsh/zshrc
+  6. $ZDOTDIR/.zshrc
+
+- If the shell is a *login* shell, it continues with
+  7. /etc/zsh/zlogin
+  8. $ZDOTDIR/zlogin
+
+
+On logout it is easier: If the shell exits (not due to exec'ing another
+process, but logout/exit), it reads
+
+1. $ZDOTDIR/.zlogout
+2. /etc/zsh/zlogout
+
+There are 2 variables affecting the above ordering.
+
+- RCS :: If this is unset, none of the (remaining) startup files
+         are sourced.
+- GLOBAL_RCS :: If this is unset, none of the startup files in /etc/zsh
+                are sourced.
+
+Note: These variables do NOT affect /etc/zsh/zshenv, which is
+      ALWAYS read!
+** Howto
+For the impatient:
+#+BEGIN_SRC shell
+
+#+END_SRC
+
+* Sources
+** Prompt
+The prompt i use is based on various others.
+- The "design" is taken from Phil!'s ZSH prompt, as found on
+  http://aperiodic.net/phil/prompt/
+
+- The tech using zstyle is inspired by the prompt as used by
+  the grml-live system <http://grml.org>, see
+  http://git.grml.org/?p=grml-etc-core.git;a=summary for details
+  on theirs.
+  A good number of their support functions are also taken, though
+  they got renamed from grml_* to ganneff_* to have a single namespace
+  here. (And to direct flames about the bugs to me... :) )
+
+- The winch function as seen in the prompt theme "bart", delivered
+  with zsh