Renamed README to README.org
[zsh.git] / .zsh / README.org
1 * ZSH configuration "framework"
2
3 This is my zsh configuration. Well, more a framework of it.
4 It is setting quite a lot of defaults, but at the same time
5 tries to be as user configurable as makes sense. So most of the
6 settings should be easy (enough) to adjust.
7
8 ** The boring stuff, license / copyright
9
10 It is hard to say what exact license applies: It consists of a lot of
11 snippets taken from a lot of places all over the net, many of which I
12 don't remember anymore. Also, many of which are probably small enough
13 that no copyright would apply.
14
15 Where I still remember where it is from, I tried to mark them as such,
16 giving credit where its due. Those I know off are also listed at the end
17 of this README file. If you find something in here thats from you and
18 want to be mentioned, just mail me.
19
20 For stuff that is from me, use the following license terms:
21
22 Copyright (C) 2013, Joerg Jaspert <joerg@ganneff.de>
23
24 Permission is hereby granted, free of charge, to any person obtaining a
25 copy of this software and associated documentation files (the
26 "Software"), to deal in the Software without restriction, including
27 without limitation the rights to use, copy, modify, merge, publish,
28 distribute, sublicense, and/or sell copies of the Software, and to
29 permit persons to whom the Software is furnished to do so, subject to
30 the following conditions:
31
32 The above copyright notice and this permission notice shall be included
33 in all copies or substantial portions of the Software.
34
35 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
36 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
37 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
38 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
39 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
40 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
41 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
42 * Usage
43 ** Basics
44 To correctly use this fileset for zsh, you need to understand the
45 order in which things are loaded by zsh.
46
47 Note: Wherever $ZDOTDIR is unset, $HOME is used instead
48
49 - Always
50 1. /etc/zsh/zshenv This is not overridable and not affected by the
51 RCS/GLOBAL_RCS variables explained below!
52 2. $ZDOTDIR/.zshenv
53
54 - If the shell is a *login* shell, it continues with
55 3. /etc/zsh/zprofile
56 4. $ZDOTDIR/.zprofile
57
58 - If the shell is *interactive*, it continues with
59 5. /etc/zsh/zshrc
60 6. $ZDOTDIR/.zshrc
61
62 - If the shell is a *login* shell, it continues with
63 7. /etc/zsh/zlogin
64 8. $ZDOTDIR/zlogin
65
66
67 On logout it is easier: If the shell exits (not due to exec'ing another
68 process, but logout/exit), it reads
69
70 1. $ZDOTDIR/.zlogout
71 2. /etc/zsh/zlogout
72
73 There are 2 variables affecting the above ordering.
74
75 - RCS :: If this is unset, none of the (remaining) startup files
76 are sourced.
77 - GLOBAL_RCS :: If this is unset, none of the startup files in /etc/zsh
78 are sourced.
79
80 Note: These variables do NOT affect /etc/zsh/zshenv, which is
81 ALWAYS read!
82 ** Howto
83 For the impatient:
84 #+BEGIN_SRC shell
85
86 #+END_SRC
87
88 * Sources
89 ** Prompt
90 The prompt i use is based on various others.
91 - The "design" is taken from Phil!'s ZSH prompt, as found on
92 http://aperiodic.net/phil/prompt/
93
94 - The tech using zstyle is inspired by the prompt as used by
95 the grml-live system <http://grml.org>, see
96 http://git.grml.org/?p=grml-etc-core.git;a=summary for details
97 on theirs.
98 A good number of their support functions are also taken, though
99 they got renamed from grml_* to ganneff_* to have a single namespace
100 here. (And to direct flames about the bugs to me... :) )
101
102 - The winch function as seen in the prompt theme "bart", delivered
103 with zsh
104
105 ** Various
106 - The is-{alias,builtin,callable,command,function} and zpgrep function
107 have been taken from "zoppo", see [[https://github.com/zoppo][zoppo]] for more of it, which is
108 licensed "under WTFPL unless otherwise noted".
109
110 - zbell function is Written by Jean-Philippe Ouellet <jpo@vt.edu>
111 and available under the ISC license.