From f6974e5a7676d0cd5c4b32300688eb669fe8992b Mon Sep 17 00:00:00 2001 From: Sabine Maennel Date: Sat, 4 Aug 2018 20:42:26 +0200 Subject: [PATCH] documentation Start issue 740 - changed introduction section - added installation section - added what is a shell section --- doc_src/index.hdr.in | 196 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 195 insertions(+), 1 deletion(-) diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in index 5bce40c54..b1e853637 100644 --- a/doc_src/index.hdr.in +++ b/doc_src/index.hdr.in @@ -17,7 +17,201 @@ \section introduction Introduction -This is the documentation for `fish`, the friendly interactive shell. `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 `fish`, please visit the `fish` homepage. +This is the documentation for *fish* the f riendly i nteractive sh ell. + +A shell is a commandline interpreter. It reads text input from the commandline and interpretes it as commands to operating system, see: What is a Shell. + +So shells serve as user-interface between applications and the operating system. There are many different shells. They differ on how this interface is implemented. *fish* specializes in the following ways: + +- Extensive UI: *fish* supports the user with syntax highlighting, autosuggestions, tab completions and selections lists, that can be navigated and filtered, see: Autosuggestions and Tab Completions. + +- No further configuration is needed: *fish* comes preconfigured so that it will be an efficient helper on the commandline out of the box. + +- Add new commands easily: in *fish* new commands can be added on the fly. The syntax is easy to learn and there is no administrative overhead, see: Functions. + +- Interactive shell: *fish* focuses on commands that will be run in an interactive session: While it supports job control for external commands, its own commands share the process of the shell, that started them. + +<-
+ + +\section install Installation and Start + +This section is on how to install, uninstall, start and exit a *fish* shell and on how to make *fish* the default shell: + +- Install: How to install *fish* +- Default Shell: How to switch to *fish* as the default shell +- Starting and Exiting: How to start and exit a *fish* shell +- Uninstall: How to uninstall *fish* +- Executing Bash: How to execute *bash* commands in *fish* + +\subsection installation Installation + +Instructions for installing fish are on the fish homepage. Search that page for "Go fish". + +To install the development version of *fish* see the instructions at the project's GitHub page. + +\subsection default-shell Default Shell + +You can make *fish* your default shell by adding *fish*'s executable in two places: +- add `/usr/local/bin/fish` to `/etc/shells` +- change your default shell with `chsh -s` to `/usr/local/bin/fish` + +For for detailed instructions see Switching to *fish*. + +\subsection uninstall Uninstalling + +For uninstalling *fish*: see FAQ: Uninstalling *fish* + +\subsection start Starting and Exiting + +Once *fish* has been installed, open a terminal. If *fish* is not the default shell: + +- Enter `fish` to start a *fish* shell: + +\fish +>fish +\endfish + +- Enter `exit` to exit a *fish* shell: + +\fish +>exit +\endfish + +\subsection bash Executing Bash + +If *fish* is your default shell you can still execute *bash* commands in case you need to: + +- a single command can be executed with: + +\fish +>bash -c SomeBashCommand +\endfish + +- or a *bash* shell can be opened with: + +\fish +>/bin/bash +\endfish + +This might be useful, when copying complicated *bash* commands from a website. Translating them into *fish* syntax can be avoided that way. + +<-
+ +\section shell What is a Shell + +This section is about the basics of shells. *fish* is a shell and shells have a lot in common: + +- Shell Standards: Why shells adjust to standards +- Manual Pages: Commands usually come with a standardized manual page +- Command Syntax: Shell commands have a standard syntax +- Commands versus Programs: Commands differ from normal programs +- Shebang Line: How the shell knows the language of a script + +\subsection shell-standards Shell Standards + +A shell is an interface to the operating system that reads from the commandline of a terminal. A shell's task is to identify and interpret commands. The commands can come from different applications and can be written in different programming languages. + +This can only work smoothly if shells adapt to some common standards. For shells there is the POSIX standard, see Command-line interpreters. `fish` tries to satisfy the POSIX standard wherever it does not get into the way of its own design principles, see `fish` Design. + +\subsection man-page Manual Pages + +There is a common standard on how to receive help on shell commands: applications provide a manual page to their commands that can be opened with the `man` command: + +\fish +>man COMMAND +\endfish + +This convention helps to make sure help can be found on commands no matter where they originate from. *fish*'s internal commands all come with a manual page. + +\subsection shell-syntax Command Syntax + +Shell commands also have some syntax in common, no matter where they originate from: + +Commands consist of three parts: + +\fish +COMMAND [OPTIONS] ARGUMENTS +\endfish + +- `COMMAND`: the name of the executeable + +- `[OPTIONS]`: options can change the behaviour of a command + +- `ARGUMENTS`: input to the command + +For external commands the executable is usually stored on file and the file path must be included in the variable `$PATH`, so that the file can be found: see Special Variables. + +Options come in two forms: a short name, that is a hyphen with a single letter; or a long name, consisting of two hyphens with words connected by hyphens. Example: `-h` and `--help` are common options for opening the manual page of a command. Options are a fixed set, described in the manual pages of the command, see Manual Pages + +Arguments are the arbitrary input part of a command: often it is a file or directory name, sometimes it is a string or a list. + +Example: + +\fish +>echo -s Hallo World! +HalloWorld! +\endfish + +- both `Hallo` and `World!` are arguments to the echo command +- `-s` is an option that suppresses spaces in the output of the command + +\subsection shell-programming Commands versus Programs + +Shell commands differ from other programs in the following way: + +- they cannot return variables + +Instead: + +- They transform an input stream into an output stream. Both of these streams are usually the terminal, but they can be redirected. + +- They return an exit code: this exit code is 0 when the command executes normally and between 1 and 255 otherwise. + +This leads to another way of programming for shell commands: they can directly return variables, but they can pass on content to other commands in following ways: + +Commands can pass on content as a stream: one command takes the output stream of another command as its input stream: + +Example: + +\fish +>ls -l | grep "my topic" +\endfish + +- every line of the `ls` command is immediatelly passed on to the `grep` command and treated separately. + +In this case the two commands execute in parallel. This is called piping, see Piping. + +Commands can pass on all of their output stream as a chunk: + +Example: +\fish +>echo (ls a*) +\endfish + +- the `echo` command takes the output of the `ls` command as a chunk and prints it to the terminal. The `echo` command waits for the `ls` command to finish, before it executes. + +In this case one command waits for the other command to finish, before it executes. This is called command substitution, see Command Substitution. + +\subsection shebang-line Shebang Line + +Since script for shell commands can be written in many different languages, they need to carry information about what interpreter is needed to execute them: For this they are expected to have a first line, the shebang line, which names an executable for this purpose: + +Example: + +A scripts written in `bash` it would need a first line like this: + +``` +#!/bin/bash +``` + +- this line tells the shell to execute the file with the *bash* interpreter, that is located at the path `/bin/bash`. + +For a script, written in another language, just replace the interpreter `/bin/bash` with the language interpreter of that other language (for example `/bin/python` for a `python` script) + +This line is only needed when scripts are executed by another interpreter, so for *fish* internal commands, that are executed by *fish* the shebang line is not necessary. + +<-
\section syntax Syntax overview