fish-shell/doc_src/doc.hdr

/** \mainpage Fish user documentation

\section introduction The friendly interactive shell

This is the documentation for \c fish, the friendly interactive
shell. \c fish is a user friendly commandline shell intended
mostly for interactive use. A shell is a program used to execute other
programs. For the latest information on \c fish, please visit the <a
href="http://roo.no-ip.org/fish/"><code>fish</code> homepage</a>.

\section syntax Syntax overview

Shells like fish are used by giving them commands. Every \c fish
command follows the same simple syntax.

A command is executed by writing the name of the command followed by
any arguments.

Example:

<code>echo hello world</code>

calls the \c echo command. \c echo is a command which will write its
arguments to the screen. In the example above, the output will be
'hello world'. Everything in fish is done with commands. There are
commands for performing a set of commands multiple times, commands for
assigning variables, commands for treating a group of commands as a
single command, etc.. And every single command follows the same simple
syntax.

If you wish to find out more about the echo command used above, read
the manual page for the echo command by writing:

<code>man echo</code>

\c man is a command for displaying a manual page on a given topic. The
man command takes the name of the manual page to display as an
argument. There are manual pages for almost every command on most
computers. There are also manual pages for many other things, such as
system libraries and important files.

Every program on your computer can be used as a command in \c fish. If
the program file is located in one of the directories in the <a
href="#variables-special">PATH</a>, it is sufficient to type the name
of the program to use it. Otherwise the whole filename, including the
directory (like \c /home/me/code/checkers/checkers or \c ../checkers)
has to be used.

Here is a list of some useful commands:

- \c cd, change the current directory
- \c ls, list files and directories
- \c man, display a manual page on the screen
- \c mv, move (rename) files
- \c cp, copy files
- \c open, open files with the default application associated with each filetype
- \c less, list the contents of files 

Commands and parameters are separated by the space character
(&nbsp;). Every command ends with either a newline (i.e. by pressing
the return key) or a semicolon (;). More than one command can be
written on the same line by separating them with semicolons.

A switch is a very common special type of argument. Switches almost
always start with one or more hyphens (-) and alter the way a command
operates. For example, the \c ls command usually lists all the files
and directories in the current working directory, but by using the \c
-l switch, the behaviour of ls is changed to not only display the
filename, but also the size, permissions, owner and modification time
of each file. Switches differ between commands and are documented in
the manual page for each command. Some switches are common to most
command though, for example '--help' will usually display a help text,
'-i' will often turn on interactive prompting before taking action,
while '-f' will turn it off.

\subsection quotes Quotes

Sometimes features such as <a href="#globbing">parameter expansion</a>
and <a href="#escapes">character escapes</a> get in the way. When that
happens, the user can write a parameter within quotes, either '
(single quote) or " (double quote). There is one important difference
between single quoted and double quoted strings: When using double
quoted string, <a href='#expand-variable'>variable expansion</a> still
takes place. Other than that, a quoted parameter will not be parameter
expanded, may contain spaces, and escape sequences are ignored. The
only backslash escape accepted within single quotes is \\', which
escapes a single quote and \\\\, which escapes the backslash
symbol. The only backslash escapes accepted within double quotes are
\\", which escapes a double quote, \\$, which escapes a dollar
character, and \\\\, which escapes the backslash symbol. Single quotes
have no special meaning withing double quotes and vice versa.

Example:

<code>rm "cumbersome filename.txt"</code>

Will remove the file 'cumbersome filename.txt', while

<code>rm cumbersome filename.txt</code>

would remove the two files 'cumbersome' and 'filename.txt'.

\subsection escapes Escaping characters

Some characters can not be written directly on the command line. For
these characters, so called escape sequences are provided. These are:

- <code>'\\n'</code>, escapes a newline character
- <code>'\\t'</code>, escapes the tab character
- <code>'\\b'</code>, escapes the backspace character
- <code>'\\r'</code>, escapes the carriage return character
- <code>'\\e'</code>, escapes the escape character
- <code>'\\ '</code>, escapes the space character
- <code>'\\$'</code>, escapes the dollar character
- <code>'\\\\'</code>, escapes the backslash character
- <code>'\\*'</code>, escapes the star character
- <code>'\\?'</code>, escapes the question mark character
- <code>'\\~'</code>, escapes the tilde character
- <code>'\\%'</code>, escapes the percent character
- <code>'\\#'</code>, escapes the hash character
- <code>'\\('</code>, escapes the left parenthesis character
- <code>'\\)'</code>, escapes the right parenthesis character
- <code>'\\{'</code>, escapes the left curly bracket character
- <code>'\\}'</code>, escapes the right curly bracket character
- <code>'\\['</code>, escapes the left bracket character
- <code>'\\]'</code>, escapes the right bracket character
- <code>'\\\<'</code>, escapes the less than character
- <code>'\\\>'</code>, escapes the more than character
- <code>'\\^'</code>, escapes the circumflex character
- <code>'\\x<i>xx</i>'</code>, where <code><i>xx</i></code> is a hexadecimal number, escapes the ascii character with the specified value
- <code>'\\X<i>xx</i>'</code>, where <code><i>xx</i></code> is a hexadecimal number, escapes a byte of data with the specified value. If you are using a mutibyte encoding, this can be used to enter invalid strings. Only use this if you know what you are doing.
- <code>'\\<i>ooo</i>'</code>, where <code><i>ooo</i></code> is an octal number, escapes the ascii character with the specified value
- <code>'\\u<i>xxxx</i>'</code>, where <code><i>xxxx</i></code> is a hexadecimal number, escapes the 16-bit unicode character with the specified value
- <code>'\\U<i>xxxxxxxx</i>'</code>, where <code><i>xxxxxxxx</i></code> is a hexadecimal number, escapes the 32-bit unicode character with the specified value

\subsection redirects IO redirection

Most program use three types of input/output (IO), each represented by
a number called a file descriptor (FD). These are:

- Standard input, FD 0, for reading, defaults to reading from the keyboard. 
- Standard output, FD 1, for writing, defaults to writing to the screen.
- Standard error, FD 2, for writing errors and warnings, defaults to writing to the screen.

The reason for providing for two output file descriptors is to allow
separation of errors and warnings from regular program output.

Any file descriptor can be directed to a different output than its
default through a simple mechanism called a redirection.

An example of a file redirection is <code> echo hello \>output.txt</code>,
which directs the output of the echo command to the file error.txt.

- To redirect standard input, write <code>\<SOURCE_FILE</code> 
- To redirect standard output, write <code>\>DESTINATION</code> 
- To redirect standard error, write <code>^DESTINATION</code> 
- To redirect standard output to a file which will be appended, write <code>\>\>DESTINATION_FILE</code>
- To redirect standard error to a file which will be appended, write <code>^^DESTINATION_FILE</code> 

<code>DESTINATION</code> can be one of the following: 

- A filename. The output will be written to the specified file.
- An ampersand (\&) followed by the number of another file descriptor. The file descriptor will be a duplicate of the specified file descriptor.
- An ampersand followed by a minus sign (\&-). The file descriptor will be closed.

Example:

To redirect both standard output and standard error to the file
all_output.txt, you can write <code>echo Hello \>all_output.txt
^\&1</code>.

Any FD can be redirected in an arbitrary way by prefixing the
redirection with the number of the FD.

- To redirect input of FD number N, write <code>N\<DESTINATION</code>
- To redirect output of FD number N, write <code>N\>DESTINATION</code> 
- To redirect output of FD number N to a file which will be appended, write <code>N\>\>DESTINATION_FILE</code>

Example: <code>echo Hello 2\>-</code> and <code>echo Hello ^-</code> are
equivalent.

\subsection piping Piping

The user can string together multiple commands into a so called
pipeline. This means that the standard output of one command will be read
in as standard input into the next command. This is done by separating
the commands by the pipe character (|). For example

<code>cat foo.txt | head</code>

will call the 'cat' program with the parameter 'foo.txt', which will
print the contents of the file 'foo.txt'. The contents of foo.txt will
then be filtered through the program 'head', which will pass on the
first ten lines of the file to the screen. For more information on how
to combine commands through pipes, read the manual pages of the
commands you want to use using the 'man' command. If you want to find
out more about the 'cat' program, type <code>man cat</code>.

Pipes usually connect file descriptor 1 (standard output) of the first
process to file descriptor 0 (standard input) of the second
process. It is possible use a different output file descriptor by
prepending the desired FD number and then output redirect symbol to
the pipe. For example:

<code>make fish 2>|less</code>

will attempt to build the fish program, and any errors will be shown
using the less pager.

\subsection syntax-background Background jobs

When you start a job in \c fish, \c fish itself will pause, and give
control of the terminal to the program just started. Sometimes, you
want to continue using the commandline, and have the job run in the
background. To create a background job, append a \& (ampersand) to
your command. This will tell fish to run the job in the
background. Background jobs are very useful when running programs that
have a graphical user interface.

Example:

<code>emacs \&</code>

will start the emacs text editor in the background. 

\subsection syntax-job-control Job control

Most programs allow you to suspend the programs execution and return
control to \c fish by Pressing ^Z (Press and hold the Control key and
press 'z'). Once back at the \c fish commandline, you can start other
programs and do anything you want. If you then want to go back to the
suspended command by using the <a href="builtins.html#fg">fg</a>
command.

If you instead want to put a suspended job into the background, use
the <a href="builtins.html#bg">bg</a> command.

To get a listing of all currently started jobs, use the <a
href="builtins.html#jobs">jobs</a> command.

\subsection syntax-function Shellscript functions

Functions are used to group together commands and arguments using a
single name. It can also be used to start a specific command with
additional arguments. For example, the following is a function
definition that calls the command 'ls -l' to print a detailed listing
of the contents of the current directory:

<pre>
function ll
	ls -l $argv
end
</pre>

The first line tells fish that a function by the name of ll is to be
defined. To use it, simply write <code>ll</code> on the
commandline. The second line tells fish that the command <code>ls -l
$argv</code> should be called when ll is invoked. $argv is an array
variable, which always contains all arguments sent to the function. In
the example above, these are simply passed on to the ls command. For
more information on functions, see the documentation for the <a
href='builtin.html#function'>function</a> builtin.

Functions can be defined on the commandline or in a configuration
file, but they can also be automatically loaded. Fish automatically
searches through any directories in the array variable
\$fish_function_path, and any functions defined are automatically
loaded when needed. A function definition file must have a filename
consisting of the name of the function plus the suffix '.fish'.  

The default value for \$fish_function_path is ~/.fish.d/functions,
/etc/fish.d/functions /usr/share/fish/functions. The exact path to the
last two of these may be slighly different depending on what install
path prefix was chosen at configuration time. The rationale behind
having three different directories is that the first one is for user
specific functions, the second one is for system-wide additional
functions and the last one is for default fish functions.

\subsection syntax-words Some common words

This is a short explanation of some of the commonly used words in fish.

- argument, a parameter given to a command
- builtin, a command that is implemented in the shell. Builtins are commands that are so closely tied to the shell that it is impossible to implement them as external commands.
- command, a program that the shell can run.
- function, a block of commands and arguments that can be called as if they where a single command. By using functions, it is possible to string together multiple smaller commands into one more advanced command.
- job, a running pipeline or command
- pipeline, a set of commands stringed together so that the output of one command is the input of the next command
- redirection, a operation that changes one of the input/output streams associated with a job
- switch, a special flag sent as an argument to a command that will alter the behavious of the command. A switch almost always begins with one or two hyphens.

\section help Help

\c fish has an extensive help system. Use the <a
href="commands.html#help"><code>help</code></a> command to obtain help on
a specific subject or command. For instance, writing <code>help
syntax</code> displays the <a href="#syntax">syntax section</a> of this
documentation.

Help on a specific builtin can also be obtained with the <code>-h</code>
parameter. For instance, to obtain help on the \c fg builtin, either
type <code>fg -h</code> or <code>help fg</code>.


\section completion Tab completion

Tab completion is one of the most time saving features of any modern
shell. By tapping the tab key, the user asks \c fish to guess the rest
of the command or parameter that the user is currently typing. If \c
fish can only find one possible completion, \c fish will write it
out. If there is more than one completion, \c fish will write out the
longest common prefix that all completions have in common. If all
completions differ on the first character, a list of all possible
completions is printed. The list features descriptions of the
completions and if the list doesn't fit the screen, it is scrollable
by using the arrow keys, the page up/page down keys or the space
bar. Press any other key will exit the list and insert the pressed key
into the command line.

These are the general purpose tab completions that \c fish provides:

- Completion of commands, both builtins, functions and regular programs.
- Completion of environment variable names.
- Completion of usernames for tilde expansion.
- Completion of filenames, even on strings with wildcards such as '*' and '?'.
- Completion of job id, job name and process names for <a href="#expand-process">process expansion</a>.

\c fish provides a large number of program specific completions. Most
of these completions are simple options like the \c -l option for \c
ls, but some are more advanced. The latter include:

- The programs 'man' and 'whatis' show all installed 
manual pages as completions.
- The 'make' program uses all targets in the Makefile in 
the current directory as completions.
- The 'mount' command uses all mount points specified in fstab as completions.
- The 'ssh' command uses all hosts in that are stored 
in the known_hosts file as completions. (see the ssh documentation for more information) 
- The 'su' command uses all users on the system as completions.
- The \c apt-get, \c rpm and \c yum commands use all installed packages as completions.

\subsection completion-own Writing your own completions

Specifying your own completions is not complicated. To specify a
completion, use the \c complete command. \c complete takes
as a parameter the name of the command to specify a completion
for. For example, to add a completion for the program \c myprog, one
would start the completion command with <code>complete -c myprog
...</code>. To provide a list of possible completions for myprog, use
the \c -a switch. If \c myprog accepts the arguments start and stop,
this can be specified as <code>complete -c myprog -a 'start
stop'</code>. The argument to the \c -a switch is always a single
string. At completion time, it will be tokenized on spaces and tabs,
and variable expansion, command substitution and other forms of
parameter expansion will take place. 

Fish has a special syntax to support specifying switches accepted by a
command. The switches \c -s, \c -l and \c -o are used to specify a
short switch (single character, such as -l), a gnu style long switch (such as
--color) and an old-style long switch (like -shuffle),
respectively. If the command 'myprog' has an option '-o' which can
also be written as '--output', and which can take an additional value
of either 'yes' or 'no', this can be specified by writing:

<code>complete -c myprog -s o -l output -a "yes no"</code>

There are also special switches for specifying that a switch requires
an argument, to disable filename completion, to create completions
that are only available in some combinations, etc..  For a complete
description of the various switches accepted by the \c complete
command, see the documentation for the <a
href="builtins.html#complete">complete</a> builtin, or write 'complete
--help' inside the \c fish shell.

For examples of how to write your own complex completions, study the
completions in /usr/share/fish/completions. (The exact path depends on
your chosen installation prefix and may be slightly different)

\subsection completion-path Where to put completions

Completions can be defined on the commandline or in a configuration
file, but they can also be automatically loaded. Fish automatically
searches through any directories in the array variable
\$fish_complete_path, and any completions defined are automatically
loaded when needed. A completion file must have a filename consisting
of the name of the command to complete and the suffix '.fish'.

The default value for \$fish_complete_path is ~/.fish.d/completions,
/etc/fish.d/completions and /usr/share/fish/completions. The exact
path to the last two of these may be slighly different depending on
what install path prefix was chosen at configuration time. If a
suitable file is found in one of these directories, it will be
automatically loaded and the search will be stopped. The rationale
behind having three different directories is that the first one is for
user specific completions, the second one is for system-wide
completions and the last one is for default fish completions.

If you have written new completions for a common
Unix command, please consider sharing your work by sending it to <a
href='mailto: fish-users@lists.sf.net'>the fish mailinglist</a>.


\section expand Parameter expansion (Globbing)

When an argument for a program is given on the commandline, it
undergoes the process of parameter expansion before it is sent on to
the command.  There are many ways in which the user can specify a
parameter to be expanded. These include:

\subsection expand-wildcard Wildcards 

If a star (*) or a question mark (?) is present in the parameter, \c
fish attempts to match the given parameter to any files in such a
way that '?' can match any character except '/' and '*' can match any
string of characters not containing '/'.

Example:
<code>a*</code> matches any files beginning with an 'a' in the current directory.

<code>???</code> matches any file in the current directory whose name is exactly three characters long.

If no matches are found for a specific wildcard, it will expand into
zero arguments, i.e. to nothing. If none of the wildcarded arguments
sent to a command result in any matches, the command will not be
executed. If this happens when using the shell interactively, a
warning will also be printed.

\subsection expand-command-substitution Command substitution

If a parameter contains a set of parenthesis, the text enclosed by the
parenthesis will be interpreted as a list of commands. Om expansion,
this list is executed, and substituted by the output. If the output is
more than one line long, each line will be expanded to a new
parameter.

Example:

The command <code>echo (basename image.jpg .jpg).png</code> will
output 'image.png'.

The command <code>for i in *.jpg; convert $i (basename $i .jpg).png;
end</code> will convert all Jpeg files in the current directory to the
PNG format.


\subsection expand-brace Brace expansion

A comma separated list of characters enclosed in curly braces will be
expanded so each element of the list becomes a new parameter.

Example:

<code>echo input.{c,h,txt}</code> outputs 'input.c input.h input.txt'

The command <code>mv *.{c,h} src/</code> moves all files with the suffix
'.c' or '.h' to the subdirectory src.

\subsection expand-variable Variable expansion

A dollar sign followed by a string of characters is expanded into the
value of the environment variable with the same name. For an
introduction to the concept of environment variables, read the <a
href="#variables"> Environment variables</a> section.

Example:

<code> echo \$HOME</code> prints the home directory of the current
user. 

If you wish to combine environment variables with text, you can
encase the variables within braces to embed a variable inside running
text like <code>echo Konnichiwa {$USER}san</code>, which will print a
personalized Japanese greeting.

The {$USER}san syntax might need a bit of an elaboration.  Posix
shells allow you to specify a variable name using '$VARNAME' or
'${VARNAME}'. Fish supports the former, and has no support whatsoever
for the latter or anything like it. So what is '{$VARNAME}' then?
Well, '{WHATEVER}' is <a href='#brace'>brace expansion</a>, identical
to that supported by Posix shells, i.e.  'a{b,c}d' -> 'abd acd' works
both in bash and on fish. So '{$VARNAME}' is a bracket-expansion with
only a single element, i.e.  it becomes expanded to '$VARNAME', which
will be variable expanded to the value of the variable 'VARNAME'. So
you might think that the brackets don't actually do anything, and that
is nearly the truth. The snag is that there once along the way was a
'}' in there somewhere, and } is not a valid character in a variable
name.  So anything after the otherwise pointless bracket expansion
becomes explicitly NOT a part of the variable name, even if it happens
to be a legal variable name character. That's why '{$USER}san' looks
for the variable '$USER' and not for the variable '$USERsan'. It's
simply a case of one syntax lending itself nicely to solving an
unrelated problem in its spare time.

Variable expansion is the only type of expansion performed on double
quoted strings. There is, however, an important difference in how
variables are expanded when quoted and when unquoted. An unquoted
variable expansion will result in a variable number of arguments. For
example, if the variable $foo has zero elements or is undefined, the
argument $foo will expand to zero elements. If the variable $foo is an
array of five elements, the argument $foo will expand to five
elements. When quoted, like "$foo", a variable expansion will always
result in exactly one argument. Undefined variables will expand to the
empty string, and array variables will be concatenated using the space
character.

There is one further notable feature of fish variable
expansion. Consider the following code snippet:

<pre>
set foo a b c
set a 10; set b 20; set c 30
for i in (seq (count $$foo))
	echo $$foo[$i]
end
# Output is:
# 10
# 20
# 30
</pre>

The above code demonstrates how to use multiple '$' symbols to expand
the value of a variable as a variable name. One can simply think of
the $-symbol as a variable dereference operator. When using this
feature together with array brackets, the brackets will always match
the innermost $ dereference. Thus, $$foo[5] will always mean the fift
element of the foo variable should be dereferenced and never that the fift
element of the doubly dereferenced variable foo. The latter can
instead be expressed as $$foo[1][5].

\subsection expand-home Home directory expansion

The ~ (tilde) character at the beginning of a parameter, followed by a
username, is expanded into the home directory of the specified user. A
lone ~, or a ~ followed by a slash, is expanded into the home
directory of the process owner.

\subsection expand-process Process expansion

The \% (percent) character at the beginning of a parameter followed by
a string is expanded into a process id. The following expansions are
performed:

- If the string is the entire word \c self, the shells pid is the result
- When inside a command substitution, if the string is the entire word \c caller, the job number (not the pid) of the job the created the command substitution is the result
- Otherwise, if the string is the id of a job, the result is the process
group id of the job.
- Otherwise, if any child processes match the specified string, their 
pids are the result of the expansion. 
- Otherwise, if any processes owned by the user match the specified 
string, their pids are the result of the expansion.

This form of expansion is useful for commands like kill and fg, which
take the process ids as an argument.

Example:

<code>fg \%ema</code> will search for a process whose command line begins
with the letters 'ema', such as emacs, and if found, put it in the
foreground.

<code>kill -s SIGINT \%3</code> will send the SIGINT signal to the job
with job id 3.

\subsection  combine Combining different expansions

All of the above expansions can be combined. If several expansions
result in more than one parameter, all possible combinations are
created.

Example:

If the current directory contains the files 'foo' and 'bar', the command
<code>echo a(ls){1,2,3} </code>
will output 'abar1 abar2 abar3 afoo1 afoo2 afoo3'.


\section variables Environment variables

The concept of environment variables are central to any
shell. Environment variables are variables, whose values can be set
and used by the user. For information on how to use the current value
of a variable, see the section on <a href='#expand-variable'>variable
expansion</a>.

To set a variable value, use the <a href="builtins.html#set"> \c set
command</a>.

Example: 

To set the variable \c smurf to the value \c blue, use the command
<code>set smurf blue</code>.

After a variable has been set, you can use the value of a variable in
the shell through <a href="expand-variable">variable expansion</a>.

Example:

To use the value of a the variable \c smurf, write $ (dollar symbol)
followed by the name of the variable, like <code>echo Smurfs are
$smurf</code>, which would print the result 'Smurfs are blue'.

\subsection variables-scope Variable scope

There are three kinds of variables in fish, universal, global and
local variables. Universal variables are shared between all fish
sessions a user is running on one computer. Global variables are
specific to the current fish session, but are not associated with any
specific block scope, and will never be erased unless the user
explicitly requests it using <code>set -e</code>. Local variables are
specific to the current fish session, and associated with a specific
block of commands, and is automatically erased when a specific block
goes out of scope. A block of commands is a series of commands that
begins with one of the commands \c 'for, \c 'while' , \c 'if', \c
'function', \c 'begin' or \c 'switch', and ends with the command \c
'end'. The user can specify that a variable should have either global
or local scope using the \c -g/--global or \c -l/--local switches.

Variables can be explicitly set to be universal with the \c -U or \c
--universal switch, global with the \c -g or \c --global switch, or
local with the \c -l or \c --local switch.  The scoping rules when
creating or updating a variable are:

-# If a variable is explicitly set to either universal, global or local, that setting will be honored. If a variable of the same name exists in a different scope, that variable will not be changed.
-# If a variable is not explicitly set to be either universal, global or local, but has been previously defined, the variable scope is not changed.
-# If a variable is not explicitly set to be either universal, global or local and has never before been defined, the variable will be local to the currently executing functions. If no function is executing, the variable will be global.

There may be many variables with the same name, but different scopes.
When using a variable, the variable scope will be searched from the
inside out, i.e. a local variable will be used rather than a global
variable with the same name, a global variable will be used rather
than a universal variable with the same name.

Example:

The following code will not output anything:
<pre>
begin
	# This is a nice local scope where all variables will die
	set -l pirate 'There be treasure in them thar hills'
end

# This will not output anything, since the pirate was local
echo $pirate
</pre>

\subsection variables-universal More on universal variables

Universal variables are variables that are shared between all the
users fish sessions on the computer. Fish stores many of its
configuration options as universal variables. This means that in order
to change fish settings, all you have to do is change the variable
value once, and it will be automatically updated for all sessions, and
preserved across computer reboots and login/logout.

To see universal variables in action, start two fish sessions side by
side, and issue the following command in one of them <code>set
fish_color_cwd blue</code>. Since \c fish_color_cwd is a universal
variable, the color of the current working directory listing in the
prompt will instantly change to blue on both terminals.

\subsection variables-functions Variable scope for functions

When calling a function, all non-global variables temporarily
disappear. This shadowing of the local scope is needed since the
variable namespace would become cluttered, making it very easy to
accidentally overwrite variables from another function.

For example, the following code will output 'Avast, mateys':

<pre>
function shiver
	set phrase 'Shiver me timbers'
end

function avast
	set phrase 'Avast, mateys'

	# Calling the shiver function here can not change any variables
	# in the local scope
	shiver

	echo $phrase
end

avast
</pre>

\subsection variables-export Exporting variables

Variables in fish can be exported. This means the variable will be
inherited by any commands started by fish. It is convention that
exported variables are in uppercase and unexported variables are in
lowercase.

Variables can be explicitly set to be exported with the \c -x or \c
--export switch, or not exported with the \c -u or \c --unexport
switch.  The exporting rules when creating or updating a variable are
identical to the scoping rules for variables:

-# If a variable is explicitly set to either be exported or not exported, that setting will be honored.
-# If a variable is not explicitly set to be exported or not exported, but has been previously defined, the previous exporting rule for the variable is kept.
-# If a variable is not explicitly set to be either global or local and has never before been defined, the variable will not be exported.


\subsection variables-arrays Arrays

\c fish can store a list of multiple strings inside of a variable. To
access one element of an array, use the index of the element inside of
square brackets, like this:

<pre>
echo $PATH[3]
</pre>

Note that array indices start at 1 in fish, not 0, as is more common
in other languages. This is because many common unix tools like seq
are more suited to such use. 

If you do not use any brackets, all the elements of the array will be
written as separate items. This means you can easily iterate over an
array using this syntax:

<pre>
for i in $PATH; echo $i is in the path; end
</pre>

To create a variable \c smurf, containing the items \c blue and \c
small, simply write:

<pre>
set smurf blue small
</pre>

It is also possible to set or erase individual elements of an array:

<pre>
\#Set smurf to be an array with the elements 'blue' and 'small'
set smurf blue small

\#Change the second element of smurf to 'evil'
set smurf[2] evil

\#Erase the first element
set -e smurf[1]

\#Output 'evil'
echo $smurf
</pre>

If you specify a negative index when expanding or assigning to an
array variable, the index will be calculated from the end of the
array. For example, the index -1 means the last index of an array.

\subsection variables-special Special variables

The user can change the settings of \c fish by changing the values of
certain environment variables.

- \c BROWSER, which is the users preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.
- \c CDPATH, which is an array of directories in which to search for the new directory for the \c cd builtin.
- A large number of variable starting with the prefixes \c fish_color and \c fish_pager_color. See <a href='#variables-color'>Variables for changing highlighting colors</a> for more information.
- \c LANG, \c LC_ALL, \c LC_COLLATE, \c LC_CTYPE, \c LC_MESSAGES, \c LC_MONETARY, \c LC_NUMERIC and \c LC_TIME set the language option for the shell and subprograms. See the section <a href='#variables-locale'>Locale variables</a> for more information.
- \c PATH, which is an array of directories in which to search for commands
- \c umask, which is the current file creation mask. The preferred way to change the umask variable is through the <a href="commands.html#umask">umask shellscript function</a>. An attempt to set umask to an invalid value will always fail.

\c fish also sends additional information to the user through the
values of certain environment variables. The user can not change the
values of most of these variables. 

- \c _, which is the name of the currently running command.
- \c argv, which is an array of arguments to the shell or function. \c argv is only defined when inside a function call, or if fish was invoked with a list of arguments, like 'fish myscript.fish foo bar'. This variable can be changed by the user.
- \c history, which is an array containing the last commands that where entered.
- \c HOME, which is the users home directory. This variable can only be changed by the root user.
- \c PWD, which is the current working directory. 
- \c status, which is the exit status of the last foreground job to exit. If a job contains pipelines, the status of the last command in the pipeline is the status for the job.
- \c USER, which is the username. This variable can only be changed by the root user.

Variables whose name are in uppercase are exported to the commands
started by fish, those in lowercase are not exported. This rule is not
enforced by fish, but it is good coding practice to use casing to
distinguish between exported and unexported variables. \c fish also
uses several variables internally. Such variables are prefixed with
the string __FISH or __fish. These should be ignored by the user.

\subsection variables-color Variables for changing highlighting colors

The colors used by fish for syntax highlighting can be configured by
changing the values of a various variables. The value of these
variables can be one of the colors accepted by the <a
href='commands.html#set_color'>\c set_color</a> command. The \c --bold
or \c -b switches accepted by \c set_color are also accepted.

The following variables are available to change the highligting colors
in fish:

- \c fish_color_normal, the default color
- \c fish_color_command, the color for commands
- \c fish_color_quote, the color for quoted blocks of text
- \c fish_color_redirection, the color for IO redirections
- \c fish_color_end, the color for process separators like ';' and '&'
- \c fish_color_error, the color used to highlight potential errors
- \c fish_color_param, the color for regular command parameters
- \c fish_color_comment, the color used for code comments
- \c fish_color_match, the color used to highlight matching parenthesis
- \c fish_color_search_match, the color used to highlight history search matches
- \c fish_color_operator, the color for parameter expansion operators like '*' and '~'
- \c fish_color_escape, the color used to highlight character escapes like '\\n' and '\\x70'
- \c fish_color_cwd, the color used for the current working directory in the default prompt

Additionally, the following variables are available to change the
highlighting in the completion pager:

- \c fish_pager_color_prefix, the color of the prefix string, i.e. the string that is to be completed
- \c fish_pager_color_completion, the color of the completion itself
- \c fish_pager_color_description, the color of the completion description
- \c fish_pager_color_progress, the color of the progress bar at the bottom left corner

Example:

To make errors highlighted and red, use:

<code>set fish_color_error red --bold</code>D

\subsection variables-locale Locale variables

The most common way to set the locale to use a command like 'set -x
LANG en_GB.utf8', which sets the current locale to be the english
language, as used in Great Britain, using the UTF-8 character set. For
a list of available locales, use 'locale -a'.

\c LANG, \c LC_ALL, \c LC_COLLATE, \c LC_CTYPE, \c LC_MESSAGES, \c
LC_MONETARY, \c LC_NUMERIC and LC_TIME set the language option for the
shell and subprograms. These variables work as follows: \c LC_ALL
forces all the aspects of the locale to the specified value. If LC_ALL
is set, all other locale variables will be ignored. The other LC_
variables set the specified aspect of the locale information. LANG
is a fallback value, it will be used if none of the LC_ variables are
specified.

\section builtin-overview Builtins 

Many other shells have a large library of builtin commands. Most of
these commands are also available as standalone commands, but have
been implemented in the shell anyway for whatever reason. To avoid
code duplication, and to avoid the confusion of subtly differing
versions of the same command, \c fish only implementing builtins for
actions which cannot be performed by a regular command.

\section bundle Commands bundled with fish 

The following commands are distributed with fish. Many of them are
builtins or shellscript functions, and can only be used inside fish.

- <a href="builtins.html#source">.</a>, read and execute the commands in a file 
- <a href="builtins.html#and">and</a>, execute command if previous command suceeded
- <a href="builtins.html#bg">bg</a>, set a command to the background
- <a href="builtins.html#begin">begin</a>, execute a block of commands
- <a href="builtins.html#bind">bind</a>, change keyboard bindings
- <a href="builtins.html#break">break</a>, stop the execution of a loop
- <a href="builtins.html#block">block</a>, Temporarily block delivery of events
- <a href="builtins.html#builtin">builtin</a>, execute a builtin command
- <a href="builtins.html#case">case</a>, conditionally execute a block of commands
- <a href="builtins.html#cd">cd</a>, change the current directory
- <a href="builtins.html#command">command</a>, execute an external program
- <a href="builtins.html#commandline">commandline</a>, set or get the contents of the commandline buffer
- <a href="builtins.html#complete">complete</a>, add and remove completions
- <a href="builtins.html#continue">continue</a>, skip the rest of the current lap of a loop
- <a href="commands.html#count">count</a>, count the number of arguments
- <a href="commands.html#dirh">dirh</a>, view the directory history
- <a href="commands.html#dirs">dirs</a>, view the directory stack
- <a href="builtins.html#end">end</a>, end a block of commands
- <a href="builtins.html#else">else</a>, conditionally execute a block of commands
- <a href="builtins.html#eval">eval</a>, evaluate a string as a command
- <a href="builtins.html#exec">exec</a>, replace the current process image with a new command
- <a href="builtins.html#exit">exit</a>, causes \c fish to quit
- <a href="builtins.html#fg">fg</a>, set a command to the foreground
- <a href="commands.html#fishd">fishd</a>, the universal variable daemon
- <a href="builtins.html#for">for</a>, perform a block of commands once for every element in a list
- <a href="builtins.html#function">function</a>, define a new function
- <a href="builtins.html#functions">functions</a>, print or erase functions
- <a href="commands.html#help">help</a>, show the fish documentation
- <a href="builtins.html#if">if</a>, conditionally execute a block of commands
- <a href="builtins.html#jobs">jobs</a>, print the currently running jobs
- <a href="commands.html#mimedb">mimedb</a>, view mimedata about a file
- <a href="commands.html#nextd">nextd</a>, move forward in the directory history
- <a href="builtins.html#not">not</a>, negates the exit status of any command
- <a href="builtins.html#or">or</a>, execute a command if previous command failed
- <a href="commands.html#popd">popd</a>, move to the topmost directory on the directory stack
- <a href="commands.html#prevd">prevd</a>, move backwards in the direcotry stack
- <a href="commands.html#pushd">pushd</a>, push the surrent directory onto the directory stack
- <a href="builtins.html#random">random</a>, calculate a pseudo-random number
- <a href="builtins.html#return">return</a>, return from a function
- <a href="builtins.html#read">read</a>, read from a stream into an environment variable
- <a href="builtins.html#set">set</a>, set environment variables
- <a href="commands.html#set_color">set_color</a>, change the terminal colors
- <a href="builtins.html#switch">switch</a>, conditionally execute a block of commands
- <a href="commands.html#tokenize">tokenize</a>, split a string up into multiple tokens
- <a href="builtins.html#ulimit">ulimit</a>, set or get the shells resurce usage limits
- <a href="commands.html#umask">umask</a>, set or get the file creation mask
- <a href="builtins.html#while">while</a>, perform a block of commands while a condition is met

For more information about these commands, use the <code>--help</code>
option of the command to display a longer explanation.

\section editor Command Line editor

The \c fish editor features copy and paste, a searchable history and
many editor functions that can be bound to special keyboard
shortcuts. The most important keybinding is probably the tab key, which is bound to the complete function. 
Here are some of the commands available in the editor:

- Tab completes the current token
- Home or Ctrl-a moves to the beginning of the line
- End or Ctrl-e moves to the end of line
- Left and right moves one character left or right
- Alt-left and Alt-right moves one word left or right, or moves forward/backward in the directory history if the commandline is empty
- Up and down search the command history for the previous/next command containing the string that was specified on the commandline before the search was started. If the commandline was empty when the search started, all commands match. See the <a href='#history'>history </a>section for more information on history searching.
- Alt-up and Alt-down search the command history for the previous/next token containing the token under the cursor before the search was started. If the commandline was not on a token when the search started, all tokens match. See the <a href='#history'>history </a>section for more information on history searching.
- Delete and backspace removes one character forwards or backwards
- Ctrl-c delete entire line
- Ctrl-d delete one character to the right of the cursor, unless the buffer is empty, in which case the shell will exit
- Ctrl-k move contents from the cursor to the end of line to the <a href="#killring">killring</a>
- Ctrl-u move contents from the beginning of line to the cursor to the <a href="#killring">killring</a>
- Ctrl-l clear and repaint screen
- Ctrl-w move previous word to the <a href="#killring">killring</a>
- Alt-d move next word to the <a href="#killring">killring</a>
- Alt-w prints a short description of the command under the cursor 
- Alt-l lists the contents of the current directory, unless the cursor is over a directory argument, in which case the contents of that directory will be listed 
- Alt-p adds the string '| less;' to the end of the job under the cursor. The result is that the output of the command will be paged.

You can change these key bindings by making an inputrc file. To do
this, copy the file /etc/fish_inputrc to your home directory and
rename it to '.fish_inputrc'. Now you can edit the file .fish_inputrc,
to change your key bindings. The fileformat of this file is described
in the manual page for readline. Use the command <code>man readline</code>
to read up on this syntax. Please note that the list of key binding
functions in fish is different to that offered by readline. Currently,
the following functions are available:


- \c backward-char, moves one character to the left
- \c backward-delete-char, deletes one character of input to the left of the cursor
- \c backward-kill-line, move everything from the beginning of the line to the cursor to the killring
- \c backward-kill-word, move the word to the left of the cursor to the killring
- \c backward-word, move one word to the left
- \c beginning-of-history, move to the beginning of the history
- \c beginning-of-line, move to the beginning of the line
- \c complete, guess the remainder of the current token
- \c delete-char, delete one character to the right of the cursor
- \c delete-line, delete the entire line
- \c dump-functions, print a list of all key-bindings
- \c end-of-history, move to the end of the history
- \c end-of-line, move to the end of the line
- \c explain, print a description of possible problems with the current command
- \c forward-char, move one character to the right
- \c forward-word, move one word to the right
- \c history-search-backward, search the history for the previous match
- \c history-search-forward, search the history for the next match
- \c kill-line, move everything from the cursor to the end of the line to the killring
- \c kill-whole-line, move the line to the killring
- \c kill-word, move the next word to the killring
- \c yank, insert the latest entry of the killring into the buffer
- \c yank-pop, rotate to the previous entry of the killring

You can also bind a pice of shellscript to a key using the same
syntax. For example, the Alt-p functionality described above is
implemented using the following keybinding.

<pre>"\M-p": if commandline -j|grep -v 'less *$' &gt;/dev/null; commandline -aj "|less;"; end</pre>

\subsection killring Copy and paste (Kill Ring) 

\c fish uses an Emacs style kill ring for copy and paste
functionality. Use Ctrl-K to cut from the current cursor position to
the end of the line. The string that is cut (a.k.a. killed) is
inserted into a linked list of kills, called the kill ring. To paste
the latest value from the kill ring use Ctrl-Y. After pasting, use
Meta-Y to rotate to the previous kill.

If the environment variable DISPLAY is set, \c fish will try to
connect to the X-windows server specified by this variable, and use
the clipboard on the X server for copying and pasting. 

\subsection history Searchable history

After a command has been entered, it is inserted at the end of a
history list. Any duplicate history items are automatically
removed. By pressing the up and down keys, the user can search
forwards and backwards in the history. If the current command line is
not empty when starting a history search, only the commands containing
the string entered into the command line are shown.

By pressing Alt-up and Alt-down, a history search is also performed,
but instead of searching for a complete commandline, each commandline
is tokenized into separate elements just like it would be before
execution, and each such token is matched agains the token under the
cursor when the search began.

History searches can be aborted by pressing the escape key.

The history is stored in the file '.fish_history'. It is automatically
read on startup and merged on program exit.

Example:

To search for previous entries containing the word 'make', type 'make'
in the console and press the up key.

\section job-control Running multiple programs

Normally when \c fish starts a program, this program will be put in
the foreground, meaning it will take control of the terminal and \c
fish will be stopped until the program finishes. Sometimes this is not
desirable. For example, you may wish to start an application with a
graphical user interface from the terminal, and then be able to
continue using the shell. In such cases, there are several ways in
which the user can change <code>fish</code>'s behaviour.

-# By ending a command with the \& (ampersand) symbol, the user tells \c fish to put the specified command into the background. A background process will be run simultaneous with \c fish. \c fish will retain control of the terminal, so the program will not be able to read from the keyboard. 
-# By pressing ^Z, the user stops a currently running foreground  program and returns control to \c fish. Some programs do not support this feature, or remap it to another key. Gnu emacs uses ^X z to stop running.
-# By using the <a href="builtins.html#fg">fg</a> and <a href="builtins.html#bg">bg</a> builtin commands, the user can send any currently running job into the foreground or background.

\section initialization Initialization files

On startup, \c fish evaluates the files /usr/share/fish/fish,
/etc/fish (Or ~/etc/fish if you installed fish in your home directory)
and ~/.fish, in that order. The first file should not be directly
edited, the second one is meant for systemwide configuration and the
last one is meant for user configuration. If you want to run a command
only on starting an interactive shell, use the exit status of the
command 'status --is-interactive' to determine if the shell is
interactive. If you want to run a command only when using a login
shell, use 'status --is-login' instead.

Examples:

If you want to add the directory ~/linux/bin to your PATH variable
when using a login shell, add the following to your ~/.fish file:

<pre>if status --is-login
	set PATH $PATH ~/linux/bin
end</pre>

If you want to run a set of commands when \c fish exits, use an <a
href='#event'>event handler</a> that is triggered by the exit of the
shell:

<pre>function on_exit --on-process \%self
	echo fish is now exiting
end</pre>

<a href="#variables-universal">Universal variables</a> are stored in
the file .fishd.HOSTNAME, where HOSTNAME is the name of your
computer. Do not edit this file directly, edit them through fish
scripts or by using fish interactively instead.

\section other Other features

\subsection color Syntax highlighting

\c fish interprets the command line as it is typed and uses syntax
highlighting to provide feedback to the user. The most important
feedback is the detection of potential errors. By default, errors are
marked red.

Detected errors include:

- Non existing commands.
- Reading from or appending to a non existing file.
- Incorrect use of output redirects
- Mismatched parenthesis

When the cursor is over a parenthesis or a quote, \c fish also
highlights its matching quote or parenthesis.

To customize the syntax highlighting, you can set the environment
variables \c fish_color_normal, \c fish_color_command, \c
fish_color_substitution, \c fish_color_redirection, \c fish_color_end,
\c fish_color_error, \c fish_color_param, \c fish_color_comment, \c
fish_color_match, \c fish_color_search_match, \c fish_color_cwd, \c
fish_pager_color_prefix, \c fish_pager_color_completion, \c
fish_pager_color_description and \c
fish_pager_color_progress. Usually, the value of these variables will
be one of \c black, \c red, \c green, \c brown, \c yellow, \c blue, \c
magenta, \c purple, \c cyan, \c white or \c normal, but they can be an
array containing any color options for the set_color command.

Issuing <code>set fish_color_error black --background=red
--bold</code> will make all commandline errors be written in a black,
bold font, with a red background.

\subsection prompt Programmable prompt

By defining the \c fish_prompt function, the user can choose a custom
prompt. The \c fish_prompt function is executed and the output is used
as a prompt.

Example: 
<p>
The default \c fish prompt is 
</p>
<p>
<pre>
function fish_prompt -d "Write out the prompt"
	printf '\%s\@\%s\%s\%s\%s> ' (whoami) (hostname|cut -d . -f 1) (set_color \$fish_color_cwd) (prompt_pwd) (set_color normal)
end
</pre>

where \c prompt_pwd is a shellscript function that displays a condensed version of the current working direcotry.

</p>


\subsection title Programmable title

When using most virtual terminals, it is possible to set the message
displayed in the titlebar of the terminal window. This can be done
automatically in fish by defining the \c fish_title function. The \c
fish_title function is executed before and after a new command is
executed or put into the foreground and the output is used as a
titlebar message. The $_ environment variable will always contain the
name of the job to be put into the foreground (Or 'fish' if control is
returning to the shell) when the fish_prompt function is called.

Example:
<p>
The default \c fish title is 
</p>
<p>
<pre>
function fish_title
	echo $_ ' '
	pwd
end
</pre>
</p>

\subsection event Event handlers

When defining a new function in fish, it is possible to make it into an
event handler, i.e. a function that is automatically run when a
specific event takes place. Events that can trigger a handler currently are:

* When a signal is delivered
* When a process or job exits
* When the value of a variable is updated

Example:

To specify a signal handler for the WINCH signal, write:

<pre>function --on-signal WINCH my_signal_handler
	echo Got WINCH signal!
end
</pre>

For more information on how to define new event handlers, see the
documentation for the <a href='builtins.html#function'>function</a>
command.

\section issues Common issues with fish

If you install fish in your home directory, fish will not work
correctly for any other user than yourself. This is because fish needs
its initalization files to function properly. To solve this
problem, either copy the initialization files to each fish users home
directory, or install them in /etc.

\section i18n Translating fish to other languages

Fish uses the GNU gettext library to implement translation to multiple
languages. If fish is not available in your language, please consider
making a translation. Currently, only the shell itself can be
translated, a future version of fish should also include translated
manuals.

To make a translation of fish, you will first need the sourcecode,
available from the <a href='http://roo.no-ip.org/fish'>fish
homepage</a>. Download the latest version, and then extract it using a
command like <code>tar -zxf fish-VERSION.tar.gz</code>.

Next, cd into the newly created fish directory using <code>cd
fish-VERSION</code>.

You will now need to configure the sourcecode using the command
<code>./configure</code>. This step might take a while.

Before you continue, you will need to know the ISO 639 language code
of the language you are translating to. These codes can be found <a
href='http://www.w3.org/WAI/ER/IG/ert/iso639.htm'>here</a>. For
example, the language code for Uighur is ug.

Now you have the sourcecode and it is properly configured. Lets start
translating. To do this, first create an empty translation table for
the language you wish to translate to by writing <code>make
po/[LANGUAGE CODE].po</code> in the fish terminal. For example, if you
are translating to Uighur, you should write <code>make
po/ug.po</code>. This should create the file po/ug.po, a template
translation table containing all the strings that need to be
translated.

Now you are all set up to translate fish to a new language. Open the
newly created .po file in your editor of choice, and start
translating. The .po file format is rather simple. It contains pairs
of string in a format like:

<pre>
msgid "%ls: No suitable job\n"
msgstr ""
</pre>

The first line is the english string to translate, the second line
should contain your translation. For example, in swedish the above
might become:

<pre>
msgid "%ls: No suitable job\n"
msgstr "%ls: Inget passande jobb\n"
</pre>

\%s, \%ls, \%d and other tokens beginning with a '\%' are
placeholders. These will be replaced by a value by fish at
runtime. You must always take care to use exactly the same
placeholders in the same order in your translation. (Actually, there
are ways to avoid this, but they are too complicated for this short
introduction. See the full manual for the printf C function for more
information.)

Once you have provided a translation for fish, please send it to <a
href='fish-users@lists.sf.net'>fish-users@lists.sf.net</a>.

\section todo Missing features and bugs

\subsection todo-features Missing features

- Complete vi-mode key bindings
- More completions (for example xterm, vim, 
konsole, gnome-terminal, dcop, cron,
rlogin, telnet, rsync, arch, finger, nice, locate, 
bibtex, aspell, xpdf,
compress, wine, xmms, dig, wine, batch, cron, 
g++, javac, java, gcj, lpr, doxygen, whois, find)
- Undo support
- Check keybinding commands for output - if nothing has happened, don't repaint to reduce flicker
- Syntax highlighting should mark cd to non-existing directories as an error
- wait shellscript
- Support for the screen clipboard


\subsection todo-possible Possible features

- Multiline editing
- tab completion could use smart casing
- Completions could support options beginning with a plus (like xterm
  +fbx) and options without dashes (like top p) Do we really want to
  complicate the code additionally for such a small number of programs?
- mouse support like zsh has with http://stchaz.free.fr/mouse.zsh 
  installed would be awesome
- suggest a completion on unique matches by writing it out in an understated color
- With a bit of tweakage, quite a few of the readline key-binding functions could be implemented in shellscript.
- Highlight beginning/end of block when moving over a block command
- Inclusion guards for the init files to make them evaluate only once, even if the user has installed fish both in /etc and in $HOME
- Do not actually load/parse .fish_history, only mmap it and use some clever string handling. Should save ~150 kB of memory permanently, but is very hard to implement.
- command specific wildcarding (use case * instead of case '*', etc.)
- Map variables. (export only the values. When expanding with no key specified, expand to all values.)
- Descriptions for variables using 'set -d'.
- Parse errors should when possible honor IO redirections
- Support for writing strings like /u/l/b/foo and have them expand to /usr/local/bin/foo - perhaps through tab expansion


\subsection bugs Known bugs

- Completion for gcc -\#\#\# option doesn't work.
- Yanking weird characters from the clipboard prints Unicode escapes
- Suspending and then resuming pipelines containing a builtin is broken. How should this be handled?

If you think you have found a bug not described here, please send a
report to <a href="mailto:axel@liljencrantz.se"> axel@liljencrantz.se
</a>.


\subsection issues Known issues

Older versions of Doxygen has bugs in the man-page generation which
cause the builtin help to render incorrectly. Version 1.2.14 is known
to have this problem.




*/
/** \page design Design document

\section design-overview Design document

\subsection design-overview Overview

This is a description of the design principles that have been used to
design fish. The fish design has three high level goals. These are:

-# Everything that can be done in other shell languages should be
possible to do in fish, though fish may rely on external commands in
doing so. 
-# Fish should be user friendly, but not at the expense of expressiveness. 
Most tradeoffs between power and ease of use can be avoided with careful design.
-# Whenever possible without breaking the above goals, fish should
follow the Posix syntax.

To achive these high-level goals, the fish design relies on a number
of more specific design principles. These are presented below,
together with a rationale and a few examples for each.

\subsection ortho The law of orthogonality

The shell language should have a small set of orthogonal features. Any
situation where two features are related but not identical, one of them
should be removed, and the other should be made powerful and general
enough to handle all common use cases of either feature.

Rationale:

Related features make the language larger, which makes it harder to
learn. It also increases the size of the sourcecode, making the
program harder to maintain and update.

Examples:

- Here documents are too similar to using echo inside of a pipeline.
- Subshells, command substitution and process substitution are strongly related. \c fish only supports command substitution, the others can be achived either using a block or the psub shellscript function. 
- Having both aliases and functions is confusing, especially since both of them have limitations and problems. \c fish functions have none of the drawbacks of either syntax.
- The many Posix quoting styles are silly, especially \$''.


\subsection sep The law of minimalism

The shell should only contain features that cannot be implemented in
a reasonable way outside of the shell. A large performance decrease,
as well as some program complexity increase is acceptable in order to
improve separation.

Rationale:

A modular project is easier to maintain since smaller programs are far
easier to understand than larger ones. A modular project is also more
future proof since the modules can be individually
replaced. Modularity also decreases the severity of bugs, since there
is good hope that a bug, even a serious one, in one module, does not
take the whole system down.

Examples:

- Builtin commands should only be created when it cannot be
avoided. \c echo, \c kill, \c printf and \c time are among the commands 
that fish does not implement internally since they can be provided as 
external commands. Several other commands that are commonly implemented 
as builtins and can not be implemented as external commands,
including \c type, \c vared, \c pushd and \c popd are implemented as shellscript
functions in fish.
- Mathematical calculations, regex matching, generating lists of numbers
and many other funtions can easily be done in external programs. They 
should not be supported internally by the shell.

The law of minimalism does not imply that a large feature set is
bad. So long as a feature is not part of the shell itself, but a
separate command or at least a shellscript function, bloat is fine.

\subsection conf Configurability is the root of all evil

Every configuration option in a program is a place where the program
is too stupid to figure out for itself what the user really wants, and
should be considered a failiure of both the program and the programmer
who implemented it.

Rationale:

Different configuration options are a nightmare to maintain, since the
number of potential bugs caused by specific configuration combinations
quickly becomes an issue. Configuration options often imply
assumptions about the code which change when reimplementing the code,
causing issues with backwards compatibility. But mostly, configuration
options should be avoided since they simply should not exist, as the
program should be smart enough to do what is best, or at least a good
enough approximation of it.

Examples:

- Fish allows the user to set various syntax highlighting colors. This is needed because fish does not know what colors the terminal uses by default, which might make some things unreadable. The proper solution would be for text color preferences to be defined centrally by the user for all programs, and for the terminal emulator to send these color properties to fish.
- Fish does not allow you to set the history filename, the number of history entries, different language substyles or any number of other common shell configuration options.

A special note on the evils of configurability is the long list of
very useful features found in some shells, that are not turned on by
default. Both zsh and bash support command specific completions, but
no such completions are shipped with bash by default, and they are
turned of by default in zsh. Other features that zsh support that are
disabled by default include tab-completion of strings containing
wildcards, a sane completion pager and a history file.

\subsection user The law of user focus

When designing a program, one should first think about how to make a
intuitive and powerful program. Implementation issues should only be
considered once a user interface has been designed.

Rationale:

This design rule is different than the others, since it describes how
one should go about designing new features, not what the features
should be. The problem with focusing on what can be done, and what is
easy to do, is that to much of the implementation is exposed. This
means that the user must know a great deal about the underlying system
to be able to guess how the shell works, it also means that the
language will often be rather low-level.

Examples:

- There should only be one type of input to the shell, lists of commands. Loops, conditionals and variable assignments are all performed through regular commands.
- The differences between builtin commands, shellscript functions and builtin commands should be made as small as possible. Builtins and shellscript functions should have exactly the same types of argument expansion as other commands, should be possible to use in any position in a pipeline, and should support any io redirection.
- Instead of forking when performing command substitution to provide a fake variable scope, all fish commands are performed from the same process, and fish instead supports true scoping
- All blocks end with the \c end builtin

\subsection disc The law of discoverability

A program should be designed to make its features as
easy as possible to discover for the user.

Rationale:

A program whose features are discoverable turns a new user into an
expert in a shorter span of time, since the user will become an expert
on the program simply by using it.

The main benefit of a graphical program over a command line-based
program is discoverability. In a graphical program, one can discover
all the common features by simply looking at the user interface and
guessing what the different buttons, menus and other widgets do. The
traditional way to discover features in commandline programs is
through manual pages. This requires both that the user starts to use a
different program, and the she/he then remembers the new information
until the next time she/he uses the same program.

Examples:

- Everything should be tab-completable, and every tab completion should have a description
- Every syntax error and error in a builtin command should contain an error message describing what went wrong and a relevant help page. Whenever possible, errors should be flagged red by the syntax highlighter.
- The help manual should be easy to read, easily available from the shell, complete and contain many examples
- The language should be uniform, so that once the user understands the command/argument syntax, he will know the whole language, and be able to use tab-completion to discover new featues.

*/
/** \page license Licenses

Fish Copyright (C) 2005 Axel Liljencrantz. Fish is released under the
GNU General Public License, version 2. The license agreement is
included below.

Fish contains code under the BSD license, namely versions of the
two functions strlcat and strlcpy, modified for use with wide
character strings. This code is copyrighted by Todd C. Miller. The
license agreement is included below.

The XSel command, written and copyrighted by Conrad Parker, is
distributed together with, and used by fish. It is released under the MIT
license. The license agreement is included below.

The xdgmime library, written and copyrighted by Red Hat, Inc, is used
by the mimedb command, which is a part of fish. It is released under
the LGPL. The license agreement is included below.

Fish contains code from the glibc library, namely the wcstok
function. This code is licensed under the LGPL. The license agreement
is included below.


<HR>

<H2><A NAME="SEC1" HREF="gpl.html#TOC1">GNU GENERAL PUBLIC LICENSE</A></H2>
<P>
Version 2, June 1991

</P>

<PRE>
Copyright (C) 1989, 1991 Free Software Foundation, Inc.  
59 Temple Place - Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
</PRE>


<H2><A NAME="SEC2" HREF="gpl.html#TOC2">Preamble</A></H2>

<P>
The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

</P>
<P>
When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

</P>
<P>
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

</P>
<P>

For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

</P>
<P>
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

</P>
<P>
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

</P>
<P>
Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

</P>
<P>
The precise terms and conditions for copying, distribution and
modification follow.


</P>


<H2><A NAME="SEC3" HREF="gpl.html#TOC3">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</A></H2>


<P>

<STRONG>0.</STRONG>
This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term "modification".)  Each licensee is addressed as "you".
<P>

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

<P>

<STRONG>1.</STRONG>
You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.
<P>

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.
<P>

<STRONG>2.</STRONG>
You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
<P>

<DL>

<DT>
<DD>
<STRONG>a)</STRONG>
You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
</DD>
</DT>
</DL>
<P>
<DL>
<DT>
<DD>
<STRONG>b)</STRONG>
You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.

</DD>
</DT>
</DL>
<P>
<DL>
<DT>
<DD>
<STRONG>c)</STRONG>
If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License.  (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
</DD>
</DT>
</DL>
<P>

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

<P>

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
<P>

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

<P>

<STRONG>3.</STRONG>
You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:


<!-- we use this doubled UL to get the sub-sections indented, -->
<!-- while making the bullets as unobvious as possible. -->

<DL>
<DT>

<DD>
<STRONG>a)</STRONG>
Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,
</DD>
</DT>
</DL>
<P>
<DL>
<DT>
<DD>
<STRONG>b)</STRONG>
Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
</DD>

</DT>
</DL>
<P>
<DL>
<DT>
<DD>
<STRONG>c)</STRONG>
Accompany it with the information you received as to the offer
to distribute corresponding source code.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
</DD>
</DT>
</DL>
<P>

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.
<P>

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
<P>

<STRONG>4.</STRONG>
You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

<P>

<STRONG>5.</STRONG>
You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

<P>

<STRONG>6.</STRONG>

Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

<P>

<STRONG>7.</STRONG>
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
<P>

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
<P>

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
<P>

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.


<P>

<STRONG>8.</STRONG>
If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

<P>

<STRONG>9.</STRONG>
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
<P>

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

<P>

<STRONG>10.</STRONG>
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.



<P><STRONG>NO WARRANTY</STRONG></P>

<P>

<STRONG>11.</STRONG>
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

<P>

<STRONG>12.</STRONG>

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

<P>

<HR>

<h2>License for wcslcat and wcslcpy</h2>

\c fish also contains small amounts of code under the BSD
license, namely versions of the two functions strlcat and strlcpy,
modified for use with wide character strings. This code is copyrighted
by Todd C. Miller.

Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

<HR>

<h2>License for XSel</h2>

The XSel command, written and copyrighted by Conrad Parker, is
distributed together with \c fish. 


It is Copyright (C) 2001 Conrad Parker <conrad@vergenet.net>

Permission to use, copy, modify, distribute, and sell this software
and its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation. No representations are made about the
suitability of this software for any purpose. It is provided "as is"
without express or implied warranty.


<HR>

<H2><A NAME="SEC1" HREF="#TOC1">GNU LESSER GENERAL PUBLIC LICENSE</A></H2>

<P>
Version 2.1, February 1999

<P>
<PRE>
Copyright (C) 1991, 1999 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

[This is the first released version of the Lesser GPL.  It also counts
 as the successor of the GNU Library Public License, version 2, hence
 the version number 2.1.]
</PRE>


<H2><A NAME="SEC2" HREF="#TOC2">Preamble</A></H2>

<P>
  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.
<P>
  This license, the Lesser General Public License, applies to some
specially designated software packages--typically libraries--of the
Free Software Foundation and other authors who decide to use it.  You
can use it too, but we suggest you first think carefully about whether
this license or the ordinary General Public License is the better
strategy to use in any particular case, based on the explanations below.

<P>
  When we speak of free software, we are referring to freedom of use,
not price.  Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of
it in new free programs; and that you are informed that you can do
these things.
<P>
  To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights.  These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.
<P>
  For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you.  You must make sure that they, too, receive or can get the source
code.  If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it.  And you must show them these terms so they know their rights.
<P>
  We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.
<P>
  To protect each distributor, we want to make it very clear that
there is no warranty for the free library.  Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.
<P>
  Finally, software patents pose a constant threat to the existence of
any free program.  We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder.  Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.

<P>
  Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License.  This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License.  We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.
<P>
  When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library.  The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom.  The Lesser General
Public License permits more lax criteria for linking other code with
the library.
<P>
  We call this license the "Lesser" General Public License because it
does Less to protect the user's freedom than the ordinary General
Public License.  It also provides other free software developers Less
of an advantage over competing non-free programs.  These disadvantages
are the reason we use the ordinary General Public License for many
libraries.  However, the Lesser license provides advantages in certain
special circumstances.
<P>
  For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it becomes
a de-facto standard.  To achieve this, non-free programs must be
allowed to use the library.  A more frequent case is that a free
library does the same job as widely used non-free libraries.  In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.
<P>
  In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software.  For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.
<P>
  Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.

<P>
  The precise terms and conditions for copying, distribution and
modification follow.  Pay close attention to the difference between a
"work based on the library" and a "work that uses the library".  The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.
<P>

<H2><A NAME="SEC3" HREF="#TOC3">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</A></H2>


<P>
<STRONG>0.</STRONG>
This License Agreement applies to any software library or other
program which contains a notice placed by the copyright holder or
other authorized party saying it may be distributed under the terms of
this Lesser General Public License (also called "this License").
Each licensee is addressed as "you".
<P>
  A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.
<P>

  The "Library", below, refers to any such software library or work
which has been distributed under these terms.  A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language.  (Hereinafter, translation is
included without limitation in the term "modification".)
<P>
  "Source code" for a work means the preferred form of the work for
making modifications to it.  For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.
<P>
  Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it).  Whether that is true depends on what the Library does
and what the program that uses the Library does.
<P>
<STRONG>1.</STRONG>
You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.
<P>
  You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.
<P>
<STRONG>2.</STRONG>

You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
<P>
<UL>
  <LI><STRONG>a)</STRONG>
       The modified work must itself be a software library.
  <LI><STRONG>b)</STRONG>
       You must cause the files modified to carry prominent notices
       stating that you changed the files and the date of any change.

  <LI><STRONG>c)</STRONG>
       You must cause the whole of the work to be licensed at no
       charge to all third parties under the terms of this License.

  <LI><STRONG>d)</STRONG>

       If a facility in the modified Library refers to a function or a
       table of data to be supplied by an application program that uses
       the facility, other than as an argument passed when the facility
       is invoked, then you must make a good faith effort to ensure that,
       in the event an application does not supply such function or
       table, the facility still operates, and performs whatever part of
       its purpose remains meaningful.
       <P>
       (For example, a function in a library to compute square roots has
       a purpose that is entirely well-defined independent of the
       application.  Therefore, Subsection 2d requires that any
       application-supplied function or table used by this function must
       be optional: if the application does not supply it, the square
       root function must still compute square roots.)
       <P>
       These requirements apply to the modified work as a whole.  If
       identifiable sections of that work are not derived from the Library,
       and can be reasonably considered independent and separate works in
       themselves, then this License, and its terms, do not apply to those
       sections when you distribute them as separate works.  But when you
       distribute the same sections as part of a whole which is a work based
       on the Library, the distribution of the whole must be on the terms of
       this License, whose permissions for other licensees extend to the
       entire whole, and thus to each and every part regardless of who wrote
       it.
       <P>
       Thus, it is not the intent of this section to claim rights or contest
       your rights to work written entirely by you; rather, the intent is to
       exercise the right to control the distribution of derivative or
       collective works based on the Library.
       <P>
       In addition, mere aggregation of another work not based on the Library
       with the Library (or with a work based on the Library) on a volume of
       a storage or distribution medium does not bring the other work under
       the scope of this License.
</UL>
<P>
<STRONG>3.</STRONG>

You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library.  To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License.  (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.)  Do not make any other change in
these notices.
<P>
  Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.
<P>
  This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
<P>
<STRONG>4.</STRONG>
You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.
<P>
  If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.
<P>
<STRONG>5.</STRONG>

A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library".  Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.
<P>
  However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library".  The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.
<P>
  When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library.  The
threshold for this to be true is not precisely defined by law.
<P>
  If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work.  (Executables containing this object code plus portions of the
Library will still fall under Section 6.)
<P>
  Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.
<P>
<STRONG>6.</STRONG>
As an exception to the Sections above, you may also combine or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.

<P>
  You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License.  You must supply a copy of this License.  If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License.  Also, you must do one
of these things:
<P>
<UL>
    <LI><STRONG>a)</STRONG> Accompany the work with the complete corresponding
    machine-readable source code for the Library including whatever
    changes were used in the work (which must be distributed under
    Sections 1 and 2 above); and, if the work is an executable linked
    with the Library, with the complete machine-readable "work that
    uses the Library", as object code and/or source code, so that the
    user can modify the Library and then relink to produce a modified
    executable containing the modified Library.  (It is understood
    that the user who changes the contents of definitions files in the
    Library will not necessarily be able to recompile the application
    to use the modified definitions.)
	 
    <LI><STRONG>b)</STRONG> Use a suitable shared library mechanism for linking with the
    Library.  A suitable mechanism is one that (1) uses at run time a
    copy of the library already present on the user's computer system,
    rather than copying library functions into the executable, and (2)
    will operate properly with a modified version of the library, if
    the user installs one, as long as the modified version is
    interface-compatible with the version that the work was made with.

    <LI><STRONG>c)</STRONG> Accompany the work with a written offer, valid for at
    least three years, to give the same user the materials
    specified in Subsection 6a, above, for a charge no more
    than the cost of performing this distribution.

    <LI><STRONG>d)</STRONG> If distribution of the work is made by offering access to copy
    from a designated place, offer equivalent access to copy the above
    specified materials from the same place.

    <LI><STRONG>e)</STRONG> Verify that the user has already received a copy of these
    materials or that you have already sent this user a copy.

</UL>
<P>
  For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it.  However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.
<P>
  It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system.  Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.
<P>
<STRONG>7.</STRONG> You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:
<P>
<UL>
    <LI><STRONG>a)</STRONG> Accompany the combined library with a copy of the same work
    based on the Library, uncombined with any other library
    facilities.  This must be distributed under the terms of the
    Sections above.

    <LI><STRONG>b)</STRONG> Give prominent notice with the combined library of the fact
    that part of it is a work based on the Library, and explaining
    where to find the accompanying uncombined form of the same work.

</UL>
<P>
<STRONG>8.</STRONG> You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License.  Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License.  However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
<P>
<STRONG>9.</STRONG>
You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Library or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.
<P>
<STRONG>10.</STRONG>
Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.
<P>
<STRONG>11.</STRONG>
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all.  For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.

<P>
If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.
<P>
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
<P>
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
<P>
<STRONG>12.</STRONG>
If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded.  In such case, this License incorporates the limitation as if
written in the body of this License.
<P>
<STRONG>13.</STRONG>
The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
<P>
Each version is given a distinguishing version number.  If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation.  If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.
<P>

<STRONG>14.</STRONG>
If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission.  For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this.  Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.
<P>
<STRONG>NO WARRANTY</STRONG>
<P>
<STRONG>15.</STRONG>
BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
<P>
<STRONG>16.</STRONG>
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
<P>



*/
/** \page faq Frequently asked questions

- <a href='#faq-cwd-symlink'>Why does cd, pwd and other fish commands always resolve symlinked directories to their canonical path?</a>
- <a href='#faq-cd-autocomplete'>Why does the cd command autocompletion list the subdirectories of my home directory as completions?</a>
- <a href='#faq-cd-implicit'>I accidentally entered a directory path and fish changed directory. What happened?</a>
- <a href='#faq-open'>The open command doesn't work.</a>
- <a href='#faq-default'>How do I make fish my default shell?</a>

<hr>

\section faq-cwd-symlink Why does cd, $PWD and and various fish commands always resolve symlinked directories to their canonical path?

<i>
For example if ~/images is a symlink to ~/Documents/Images, if I write
'cd images', my prompt will say ~/D/Images, not ~/images.
</i>

Because it is impossible to consistently keep symlinked directories
unresolved. It is indeed possible to do this partially, and many other
shells do so. But it was felt there are enough serious corner cases
that this is a bad idea. Most such issues have to do with how '..' is
handled, and are varitations of the following example:

Writing <code>cd images; ls ..</code> given the above directory
structure would list the contents of ~/Documents, not of ~, even
though using <code>cd ..</code> changes the current direcotry to ~,
and the prompt, the pwd builtin and many other directory information
sources suggest that the the current directory is ~/images and it's
parent is ~. This issue is not possible to fix without either making
every single command into a builtin, breaking Unix semantics or
implementing kludges in every single command.

This issue can also be seen when doing IO redirection. 

Another related issue is that many programs that operate on recursive
directory trees, like the find command, silently ignore symlinked
directories. For example, <code>find $PWD -name '*.txt'</code>
silently fails in shells that don't resolve symlinked paths.

<hr>

\section faq-cd-autocomplete Why does the cd command autocompletion list the subdirectories of my home directory as completions?

Because they are completions. In fish, if you specify a relative
directory to the cd command, i.e. any path that does not start with
either './' or '/', the environment variable CDPATH will be examined, and any
directories in this path is used as a base direcotry. To disable this
feature, write <code>set CDPATH .</code> on the commandline.

<hr>

\section faq-cd-implicit I accidentally entered a directory path and fish changed directory. What happened?

If fish is unable to locate a command with a given name, fish will
test if a directory of that name exists. If it does, it is implicitly
assumed that you want to change working directory. For example, the 
fastest way to switch to your home directory is to simply type
<code>~</code>.

<hr>

\section faq-open The open command doesn't work.

The open command uses the mimetype database and the .desktop files
used by Gnome and KDE to identify filetypes and default actions. If
at least one of these two desktops are installed, but the open command is
not working, this probably means that the relevant files are installed
in a nonstandard location. Please contact the <a
href='mailto:fish-users@lists.sf.net'>fish mailing list</a>, and
hopefully this can be resolved.

\section faq-default How do I make fish my default shell?

If you installed fish manually (e.g. by compiling it, not by using a
package manager), you first need to add fish to the list of shells by
executing the following command (assuming you installed fish in
/usr/local) as root:

<code>echo /usr/local/bin/fish >>/etc/shells</code>

If you installed a prepackaged version of fish, the package manager
should have already done this for you.

In order to change your default shell, type:

<code>chsh -s /usr/bin/fish</code>

You may need to adjust the above path to e.g. /usr/local/bin/fish.

You will need to log out and back in again for the change to take
effect.

*/