diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in index b1e853637..5defee884 100644 --- a/doc_src/index.hdr.in +++ b/doc_src/index.hdr.in @@ -34,6 +34,123 @@ So shells serve as user-interface between applications and the operating system. <-
+\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 + +Shells also support some common syntax for executing commands. That way a command can be started in the same way, regardless of the application, where it comes from, and the shell, where it is executed in. + +The pattern below is a basic pattern: + +\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 often used to print a help message. 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 + +Programs in other languages can often be regarded as black boxes: they get complex input and return complex output. Sometimes they produce side effects such as writing to a file or reporting an error, but the emphasis is on: arguments in and return values out: + +Arguments → |Program| → Return Values + +Shell commands are different: + +- the side effects take the center of the stage: they transform an input stream of data into an output stream of data. Both of these streams are usually the terminal, but they can be redirected. +- the arguments become options or switches paired with data: the switches influence the behaviour of the command +- the return value shrinks to an exit code: this exit code is 0 when the command executes normally and between 1 and 255 otherwise. + + +
Input Stream ⇒|Shell Command|⇒ Output Stream +
switch and data as arguments →→ exit code +
+ +This leads to another way of programming and especially of combining commands: + +There are two ways to combine shell commands: + +- Commands can pass on their streams to each other: one command takes the output stream of another command as its input stream and the two commands execute in parallel. This is called piping, see Piping. + +Example: + +\fish +# Every line of the `ls` command is immediatelly passed on to the `grep` command +>ls -l | grep "my topic" +\endfish + +- Commands can pass on all their output as a chunk: the output stream of one command is bundled and taken as data argument for the second command. This is called command substitution, see Command Substitution. + +Example: +\fish +# the output of the inner `ls` command is taken as the input argument for the outer `echo` command +>echo (ls a*) +\endfish + +\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 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: @@ -80,139 +197,20 @@ Once *fish* has been installed, open a terminal. If *fish* is not the default sh \subsection bash Executing Bash -If *fish* is your default shell you can still execute *bash* commands in case you need to: +If *fish* is your default shell and you want to copy commands from the internet, that are written in a different shell language, *bash* for example, you can proceed in the following way: -- a single command can be executed with: +Consider, that `bash` is also a command. With `man bash` you can see that there are two ways to do this: + +- `bash` has a switch `-c` to read from a string: \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. +- or `bash` without a switch, opens a *bash* shell that you can use and `exit` afterwards. <-
-\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