github-mirror/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2024-11-23 10:43:32 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
c6fa2ec82f
fish-shell/doc_src/index.rst

146 lines
4.9 KiB
ReStructuredText
Raw Normal View History

Switch to fish_indent based syntax highlighting in sphinx docs
2019-03-15 04:52:25 +08:00
.. highlight:: fish-docs-samples
docs: Fix remaining references Fixes #5775.
2019-03-31 17:32:40 +08:00
.. _intro:
Initial sphinx file import
2018-12-16 08:23:36 +08:00
Migrate index.rst to reStructuredText
2018-12-16 10:45:16 +08:00
Introduction
Split up documentation This breaks apart the massive "index" document into 1. An "index" document that explains how to install and set up fish and links to the other documents 2. A "fish-language" document that describes the syntax and semantics of the language 3. A "fish-interactive" document that describes how to use fish interactively No change to the content has been made, only the parts have been moved from index and some of the formatting (links and header levels) were fixed. See #7348.
2021-03-04 03:30:35 +08:00
************
Initial sphinx file import
2018-12-16 08:23:36 +08:00
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
This is the documentation for :command:`fish`, the **f**\ riendly **i**\ nteractive **sh**\ ell.
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
Revise through "Quotes" section
2020-12-27 05:45:48 +08:00
A shell is a program that helps you operate your computer by starting other programs. fish offers a command-line interface focused on usability and interactive use.
docs: Streamline some of the introductory parts of index.rst Really "what is a shell" is covered by the part where it says it offers a commandline interface.
2019-12-10 03:44:57 +08:00
docs: improve introduction section Work on review comments in #5312.
2019-09-11 12:16:19 +08:00
Some of the special features of fish are:
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
Split up documentation This breaks apart the massive "index" document into 1. An "index" document that explains how to install and set up fish and links to the other documents 2. A "fish-language" document that describes the syntax and semantics of the language 3. A "fish-interactive" document that describes how to use fish interactively No change to the content has been made, only the parts have been moved from index and some of the formatting (links and header levels) were fixed. See #7348.
2021-03-04 03:30:35 +08:00
- **Extensive UI**: :ref:`Syntax highlighting <color>`, :ref:`autosuggestions`, :ref:`tab completion <tab-completion>` and selection lists that can be navigated and filtered.
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
docs: improve introduction section Work on review comments in #5312.
2019-09-11 12:16:19 +08:00
- **No configuration needed**: fish is designed to be ready to use immediately, without requiring extensive configuration.
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
docs: Explicity link a few more sections This makes it easier to move them around.
2021-02-06 02:50:05 +08:00
- **Easy scripting**: New :ref:`functions <syntax-function>` can be added on the fly. The syntax is easy to learn and use.
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
Split up documentation This breaks apart the massive "index" document into 1. An "index" document that explains how to install and set up fish and links to the other documents 2. A "fish-language" document that describes the syntax and semantics of the language 3. A "fish-interactive" document that describes how to use fish interactively No change to the content has been made, only the parts have been moved from index and some of the formatting (links and header levels) were fixed. See #7348.
2021-03-04 03:30:35 +08:00
This page explains how to install and set up fish and where to get more information.
docs: Move configuration section to language Instead leave a simple "use config.fish" bit in-place. Also some minor rewording.
2021-10-23 23:13:36 +08:00
Where to go?
============
docs: Split off links to other pages into its own section This is an attempt to make these more visible - the intro section explains what this is, and then we mention where to go, and after that we go into installation and stuff. I don't think putting "where to go" *after* the installation instruction is correct, but maybe it is? For the time being, we keep the order as it is.
2021-05-19 04:51:28 +08:00
Split up documentation This breaks apart the massive "index" document into 1. An "index" document that explains how to install and set up fish and links to the other documents 2. A "fish-language" document that describes the syntax and semantics of the language 3. A "fish-interactive" document that describes how to use fish interactively No change to the content has been made, only the parts have been moved from index and some of the formatting (links and header levels) were fixed. See #7348.
2021-03-04 03:30:35 +08:00
If this is your first time using fish, see the :ref:`tutorial <tutorial>`.
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
Fish for bash users: Fix missing word and link it from index
2021-01-22 23:23:09 +08:00
If you are already familiar with other shells like bash and want to see the scripting differences, see :ref:`Fish For Bash Users <fish_for_bash_users>`.
Split up documentation This breaks apart the massive "index" document into 1. An "index" document that explains how to install and set up fish and links to the other documents 2. A "fish-language" document that describes the syntax and semantics of the language 3. A "fish-interactive" document that describes how to use fish interactively No change to the content has been made, only the parts have been moved from index and some of the formatting (links and header levels) were fixed. See #7348.
2021-03-04 03:30:35 +08:00
For a comprehensive overview of fish's scripting language, see :ref:`The Fish Language <language>`.
For information on using fish interactively, see :ref:`Interactive use <interactive>`.
docs: Move configuration section to language Instead leave a simple "use config.fish" bit in-place. Also some minor rewording.
2021-10-23 23:13:36 +08:00
If you need to install fish first, read on, the rest of this document will tell you how to get, install and configure fish.
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
Installation
============
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
This section describes how to install, uninstall, start, and exit :command:`fish`. It also explains how to make fish the default shell.
Reorder setup instructions First tell them how to install (though we don't actually do that right now), then tell them how to start it, and only *then* tell them how to make it the default or uninstall it. Just seems sensible to try it first then delete it.
2019-12-11 01:35:25 +08:00
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
Installation
------------
docs: fix formatting of name of shells Work on review comments in #5312. [ci skip]
2019-09-11 12:18:27 +08:00
Up-to-date instructions for installing the latest version of fish are on the `fish homepage <https://fishshell.com/>`_.
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
Revise through "Quotes" section
2020-12-27 05:45:48 +08:00
To install the development version of fish, see the instructions on the `project's GitHub page <https://github.com/fish-shell/fish-shell>`_.
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
Starting and Exiting
--------------------
docs: fix formatting of name of shells Work on review comments in #5312. [ci skip]
2019-09-11 12:18:27 +08:00
Once fish has been installed, open a terminal. If fish is not the default shell:
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
- Type :command:`fish` to start a shell::
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
> fish
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
- Type :command:`exit` to end the session::
Incorporate sabine's index changes into sphinx docs Adds: f6974e5a7676d0cd5c4b32300688eb669fe8992b 20c51b7da9cf468fd74af3056dceb0701fe60e63
2019-02-25 07:46:10 +08:00
> exit
Reorder setup instructions First tell them how to install (though we don't actually do that right now), then tell them how to start it, and only *then* tell them how to make it the default or uninstall it. Just seems sensible to try it first then delete it.
2019-12-11 01:35:25 +08:00
Default Shell
-------------
Revise through "Quotes" section
2020-12-27 05:45:48 +08:00
To make fish your default shell:
docs: default shell formatting
2020-07-15 13:58:57 +08:00
docs: Remove broken footnote Oops!
2021-01-28 01:25:46 +08:00
- Add the line ``/usr/local/bin/fish`` to ``/etc/shells``.
Revise through "Quotes" section
2020-12-27 05:45:48 +08:00
- Change your default shell with ``chsh -s /usr/local/bin/fish``.
Reorder setup instructions First tell them how to install (though we don't actually do that right now), then tell them how to start it, and only *then* tell them how to make it the default or uninstall it. Just seems sensible to try it first then delete it.
2019-12-11 01:35:25 +08:00
docs: default shell formatting
2020-07-15 13:58:57 +08:00
For detailed instructions see :ref:`Switching to fish <switching-to-fish>`.
Reorder setup instructions First tell them how to install (though we don't actually do that right now), then tell them how to start it, and only *then* tell them how to make it the default or uninstall it. Just seems sensible to try it first then delete it.
2019-12-11 01:35:25 +08:00
Uninstalling
------------
For uninstalling fish: see :ref:`FAQ: Uninstalling fish <faq-uninstalling>`.
docs: Restructure introduction Some more sections here were duplicated or not all that useful, and it's weird to start with "Commands versus Functions". Let's explain to people how to start fish, then let's get going.
2019-12-11 01:29:57 +08:00
Shebang Line
------------
Revise through "Quotes" section
2020-12-27 05:45:48 +08:00
Because shell scripts are written in many different languages, they need to carry information about which interpreter should be used to execute them. For this, they are expected to have a first line, the shebang line, which names the interpreter executable.
docs: Restructure introduction Some more sections here were duplicated or not all that useful, and it's weird to start with "Commands versus Functions". Let's explain to people how to start fish, then let's get going.
2019-12-11 01:29:57 +08:00
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
A script written in :command:`bash` would need a first line like this:
Remove Copyright sectionf from doc pages, and a couple missing bits ... from fish.rst
2021-11-05 04:26:54 +08:00
::
docs: Restructure introduction Some more sections here were duplicated or not all that useful, and it's weird to start with "Commands versus Functions". Let's explain to people how to start fish, then let's get going.
2019-12-11 01:29:57 +08:00
#!/bin/bash
docs: Some adjustments Rewordings, :ref: links, typos
2021-01-27 23:58:12 +08:00
When the shell tells the kernel to execute the file, it will use the interpreter ``/bin/bash``.
docs: Restructure introduction Some more sections here were duplicated or not all that useful, and it's weird to start with "Commands versus Functions". Let's explain to people how to start fish, then let's get going.
2019-12-11 01:29:57 +08:00
docs: Some adjustments Rewordings, :ref: links, typos
2021-01-27 23:58:12 +08:00
For a script written in another language, just replace ``/bin/bash`` with the interpreter for that language (for example: ``/usr/bin/python`` for a python script, or ``/usr/local/bin/fish`` for a fish script).
docs: Restructure introduction Some more sections here were duplicated or not all that useful, and it's weird to start with "Commands versus Functions". Let's explain to people how to start fish, then let's get going.
2019-12-11 01:29:57 +08:00
Revise through "Quotes" section
2020-12-27 05:45:48 +08:00
This line is only needed when scripts are executed without specifying the interpreter. For functions inside fish or when executing a script with ``fish /path/to/script``, a shebang is not required (but it doesn't hurt!).
docs: Restructure introduction Some more sections here were duplicated or not all that useful, and it's weird to start with "Commands versus Functions". Let's explain to people how to start fish, then let's get going.
2019-12-11 01:29:57 +08:00
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
Configuration
=============
Initial sphinx file import
2018-12-16 08:23:36 +08:00
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
To store configuration write it to a file called ``~/.config/fish/config.fish``.
Initial sphinx file import
2018-12-16 08:23:36 +08:00
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
``.fish`` scripts in ``~/.config/fish/conf.d/`` are also automatically executed before ``config.fish``.
Initial sphinx file import
2018-12-16 08:23:36 +08:00
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
These files are read on the startup of every shell, whether interactive and/or if they're login shells. Use ``status --is-interactive`` and ``status --is-login`` to discriminate.
Initial sphinx file import
2018-12-16 08:23:36 +08:00
Examples:
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
---------
Initial sphinx file import
2018-12-16 08:23:36 +08:00
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
To add ``~/linux/bin`` to PATH variable when using a login shell, add this to ``~/.config/fish/config.fish`` file::
Initial sphinx file import
2018-12-16 08:23:36 +08:00
Migrate index.rst to reStructuredText
2018-12-16 10:45:16 +08:00
if status --is-login
docs: Point away from `set -x` This is a common anti-pattern, we should try to get people to do `set -gx`.
2021-02-02 01:12:24 +08:00
set -gx PATH $PATH ~/linux/bin
Migrate index.rst to reStructuredText
2018-12-16 10:45:16 +08:00
end
Initial sphinx file import
2018-12-16 08:23:36 +08:00
Fix typos in documentation
2021-11-12 14:42:31 +08:00
This is just an example; using :ref:`fish_add_path <cmd-fish_add_path>` e.g. ``fish_add_path ~/linux/bin`` which only adds the path if it isn't included yet is easier.
Initial sphinx file import
2018-12-16 08:23:36 +08:00
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
To run commands on exit, use an :ref:`event handler <event>` that is triggered by the exit of the shell::
Migrate index.rst to reStructuredText
2018-12-16 10:45:16 +08:00
function on_exit --on-event fish_exit
echo fish is now exiting
end
.. _more-help:
index.rst: copy-edit Try to improve the quality of this writing. Evict a paragraph about running Bash from our documentation front page.
2021-11-06 07:50:19 +08:00
Resources
=========
Initial sphinx file import
2018-12-16 08:23:36 +08:00
docs: Misc changes Some formatting improvements, an explanation of $PWD, and some updates - --on-process-exit is gone, the fish_command_not_found event is gone, nobody has sent enhancements via the mailing list in years. [ci skip]
2020-09-18 23:19:44 +08:00
- The `GitHub page <https://github.com/fish-shell/fish-shell/>`_
Initial sphinx file import
2018-12-16 08:23:36 +08:00
docs: Misc changes Some formatting improvements, an explanation of $PWD, and some updates - --on-process-exit is gone, the fish_command_not_found event is gone, nobody has sent enhancements via the mailing list in years. [ci skip]
2020-09-18 23:19:44 +08:00
- The official `Gitter channel <https://gitter.im/fish-shell/fish-shell>`_
Initial sphinx file import
2018-12-16 08:23:36 +08:00
docs: Misc changes Some formatting improvements, an explanation of $PWD, and some updates - --on-process-exit is gone, the fish_command_not_found event is gone, nobody has sent enhancements via the mailing list in years. [ci skip]
2020-09-18 23:19:44 +08:00
- The official mailing list at `fish-users@lists.sourceforge.net <https://lists.sourceforge.net/lists/listinfo/fish-users>`_
Initial sphinx file import
2018-12-16 08:23:36 +08:00
docs: Misc changes Some formatting improvements, an explanation of $PWD, and some updates - --on-process-exit is gone, the fish_command_not_found event is gone, nobody has sent enhancements via the mailing list in years. [ci skip]
2020-09-18 23:19:44 +08:00
If you have an improvement for fish, you can submit it via the GitHub page.
docs: Add toctree back Apparently there must indeed be a toctree somewhere in the document to get the links to the other docs to show up. Even a ":hidden:" toctree doesn't help - that just leads to an empty toc in the sidebar (no idea yet where that's defined!). I've added it to the end so it's not that weird "Commands" section in the middle. [ci skip]
2019-03-30 02:08:25 +08:00
.. _other_pages:
docs: Remove lAtEx thing again Now it's screaming in the man builder. Honestly, some parts of sphinx aren't very well thought out.
2021-07-14 22:57:22 +08:00
Other help pages
================
.. toctree::
:maxdepth: 1
faq
interactive
language
commands
fish_for_bash_users
tutorial
completions
design
relnotes
license
Reference in New Issue Copy Permalink