mirror of
https://github.com/fish-shell/fish-shell
synced 2025-01-12 21:18:53 +00:00
Add an FAQ section to the documentation, and remove a few seactions of the manual containing introductory material on fish which was no longer accurate
darcs-hash:20060224011446-ac50b-e9246e23dbf725a3e2488f7831b1c7420cdd42db.gz
This commit is contained in:
axel
parent
22bfa6638a
commit
e29f5c5474
2 changed files with 74 additions and 206 deletions
274
doc_src/doc.hdr
274
doc_src/doc.hdr
|
|
@ -1352,208 +1352,6 @@ Examples:
|
|||
- 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 about About fish
|
||||
|
||||
|
||||
\section about-program About the program
|
||||
|
||||
\c fish is meant to be used for interactive shell tasks on a modern
|
||||
UNIX-like workstation. It is much more important for me to keep the
|
||||
code maintainable, readable and bug free than to support esoteric old
|
||||
hardware, software or wetware. As such, the program is often wildly
|
||||
inefficient in its use of memory and CPU cycles. On my system, \c fish
|
||||
uses a little less than half a megabyte of memory, a number that could
|
||||
be significantly reduced with a little effort. \c fish performs a lot
|
||||
of linear searches of things that could be done in logarithmic time,
|
||||
does not usually cache file system data or other search result, and
|
||||
uses the fork() call promiscuosly. None of these things matter because
|
||||
\c fish is still fast enough to be perceived as instantaneous on a
|
||||
semi-modern computer thanks to the miracles of copy-on-write, OS-level
|
||||
caching and Moores law, and it only uses a fraction of the memory used
|
||||
by most terminal emulators to display it. If this program was anything
|
||||
other than an amusing hobby for me, I would of course feel otherwise,
|
||||
but since my time is limited, this is the way it must be.
|
||||
|
||||
|
||||
\section about-code About the source code
|
||||
|
||||
Fish is written using the ellemtel indentation style, using four space
|
||||
tabs. \c fish regularly performs a large set of sanity checks to make
|
||||
sure it is in a sane state. If not, the program will terminate before
|
||||
it can do any harm.
|
||||
|
||||
Do not edit the file builtin_help.c, it is automatically generated.
|
||||
|
||||
|
||||
\section about-documentation About the documentation
|
||||
|
||||
The documentation for \c fish is written for Doxygen. All header files
|
||||
are pretty heavily commented.
|
||||
|
||||
Since it was desirable to use the same text files for producing the
|
||||
HTML documentation as for producing the internal help output, some
|
||||
rather ugly kludges had to be used for writing the documentation for
|
||||
the builtin commands.
|
||||
|
||||
The directory doc_src contains a file called doc.hdr, containing
|
||||
various general documentation for \c fish, and a large number of .txt
|
||||
files. Each txt file contains the documentation for one \c fish
|
||||
builtin. When creating the main doxygen documentation, all these files
|
||||
are concatenated into one file, called doc.h. When creating the
|
||||
internal documentation, each of the .txt files is converted to a .h
|
||||
file by supplying a doxygen header/footer. These headers are then
|
||||
converted into man style manuals, which in turn are converted to C
|
||||
code by a script called gen_hdr.sh. The resulting C-file,
|
||||
builtin_help.c, can then by linked into \c fish. This method is probably
|
||||
not the most robust, elegant or clever method for generating
|
||||
documentation. If someone has a suggestion of how to do i better,
|
||||
please notify me.
|
||||
*/
|
||||
/** \page difference Why fish?
|
||||
\section difference-overview What is different about fish?
|
||||
|
||||
This page is a summary of differences between \c fish and other shells.
|
||||
|
||||
\subsection difference-completion Tab completion features
|
||||
|
||||
\c fish, like many other shells, performs tab completion, i.e. the shell
|
||||
tries to guess what the user is typing and complete the users
|
||||
sentences whenever the user presses the tab key. If the shell finds
|
||||
more than one possible completion, a list of all completions is
|
||||
displayed when the users double taps on tab. \c fish extends tab
|
||||
completion functionality in several ways:
|
||||
|
||||
- \c fish performs file completion on strings containing wildcards
|
||||
- When showing a list of possible completions, \c fish adds a
|
||||
description to each completion. For files this description is a
|
||||
description of the format or filetype, like 'C source code',
|
||||
'Character device' or 'Executable'. For variables, if the
|
||||
value is short enough, the variable value will be displayed. For
|
||||
commands, if there is room and few enough commands, the whatis
|
||||
description of the command is used.
|
||||
- \c fish has extensive command specific completions, including
|
||||
completion of specific options. This is very powerful in combination
|
||||
with completion descriptions, as the user can see what each option does
|
||||
without consulting the manual. Simply type the command you wish to use,
|
||||
type a dash and double tab TAB, and the screen will fill with a list of
|
||||
the commands options and a description of what they do.
|
||||
- \c fish uses a decent pager when the results won't fit on one
|
||||
screen. The pager can scroll up and down, both one row and one page at
|
||||
a time, and if any non movement key is pressed the pager exits without
|
||||
consuming the character. Therefore, there is no need to press
|
||||
'q' to exit before typing your completion.
|
||||
|
||||
Some examples of the completions performed by \c fish
|
||||
|
||||
- When completing an argument for the man command, the whatis
|
||||
database is searched for manual pages as completions.
|
||||
- When completing a command name, the whatis database is searched
|
||||
for each possible command, and the description returned is used
|
||||
as the description of the command.
|
||||
- When completing an argument for the make command, the Makefile
|
||||
in the current directory is searched for targets.
|
||||
|
||||
\subsection difference-killring X-Windows Copy and paste
|
||||
|
||||
\c fish supports using the X-Windows clipboard for storing copy and
|
||||
paste information. This feature is automatically enabled if the
|
||||
DISPLAY environment variable is set. For more information on how to
|
||||
use copy and paste in \c fish, read <a href="index.html#killring">
|
||||
this section</a>. This means you can easily share commands and strings
|
||||
between different shell sessions and applications.
|
||||
|
||||
\subsection difference-open Simple launching of default applications
|
||||
|
||||
The open command uses the mimetype database (Also used by both Gnome
|
||||
or KDE) to launch the default application for a file. Just type
|
||||
<code>open *.html</code> and all the HTML files in your current directory
|
||||
will be opened in your default browser. No longer will you have to
|
||||
convert your filenames to URLS, remember clunky Open Office command
|
||||
names, worry about absolute paths or any the other common pitfalls when
|
||||
opening files from the commandline.
|
||||
|
||||
\subsection difference-help Help
|
||||
|
||||
\c fish is heavily commented. Both the source code and the
|
||||
program in general features a great deal of easily accessible
|
||||
documentation. The <code>help</code> command is used to display HTML-based
|
||||
help files. Just type <code>help</code> and a subject, and the help system
|
||||
will try to fill your needs. To view the page you are reading right
|
||||
now, you could simply type <code>help difference</code>. <code>help</code>
|
||||
also works great together with tab completion. Write \c help and
|
||||
double tap on tab, a list of all help sections will be displayed, with
|
||||
a description of the content of each section.
|
||||
|
||||
Also, all builtin commands have a help option. Passing '-h' or
|
||||
'--help' to any builtin will give you the same help as the help
|
||||
command, but formated for output on screen.
|
||||
|
||||
\subsection difference-highlighting Syntax highlighting
|
||||
|
||||
\c fish performs syntax highlighting of commands as they're
|
||||
entered. Pretty colors may look nice (or awful, depending on your
|
||||
taste), but the real advantage is error flagging. The syntax
|
||||
highlighting function does extensive error cheching and will flag many
|
||||
common errors such as misspelling a command or option, or reading from a
|
||||
non-existent file.
|
||||
|
||||
\c fish also highlights matching quotes and parenthesis as the cursor
|
||||
moves over them. This is very useful when typing long, complex
|
||||
commands.
|
||||
|
||||
\subsection difference-terminal Terminal handling
|
||||
|
||||
\c fish knows it's terminal. \c fish uses the terminfo database
|
||||
to get more information on the current terminal. Some of the terminal
|
||||
handling features of \c fish are:
|
||||
|
||||
- Backspace and delete work more often in \c fish thanks to the use of
|
||||
terminfo. If you've been bitten by this, you'll know what this means.
|
||||
- If the screen has been written to when \c fish was in the foreground,
|
||||
this is detected and the command line is redrawn.
|
||||
- Process notifications, like jobs ending or being stopped by signals,
|
||||
are printed to the screen at once, not whenever the user presses the enter key.
|
||||
|
||||
\c fish uses wide character strings internally, including double width
|
||||
characters, so it should be ready for all your Unicode needs.
|
||||
|
||||
\subsection difference-history Smart history
|
||||
|
||||
\c fish features an intelligent history that automatically removes any
|
||||
duplicate items. Searching is performed by entering a search string
|
||||
and using the up/down arrow keys to go to the next/previous match. On
|
||||
exit, \c fish performs a merge between the history on file and the
|
||||
history in memory history, thus making sure that multiple copies of \c
|
||||
fish running concurrently will not erase each others history
|
||||
information.
|
||||
|
||||
\subsection difference-simple Simplicity
|
||||
|
||||
\c fish has a simple syntax. There is only one form of
|
||||
alias/function/whatever, accessed through the <code>function</code>
|
||||
builtin. The are very few builtins, \c fish relies on normal commands
|
||||
like <code>echo</code>, <code>kill</code>, <code>printf</code> and <code>time</code>
|
||||
instead of reimplementing them as builtins.
|
||||
|
||||
Token separation is performed before variable expansion. This means
|
||||
that even if a variable contains spaces, it will never be separated
|
||||
into multiple arguments. If you want to tokenize a string, you can use
|
||||
the <a href="commands.html#tokenize">tokenize</a> command.
|
||||
|
||||
Command substitution is specified using parenthesis, as in <code>set name (whoami)</code>.
|
||||
|
||||
There is no math mode, use bc.
|
||||
|
||||
The POSIX way of setting variables is <i>lame</i>. Whitespace
|
||||
sensitive languages are awful. "foo=bar" and "foo = bar" should not
|
||||
mean different things. \c fish uses a builtin, <code>set</code> to set and
|
||||
remove environment variables. While this may seem a bit obscure, this
|
||||
makes for a very consistent language. In fish, everything, including
|
||||
the loops, assignments and switch/case statements is a command.
|
||||
|
||||
In \c fish, all block types end with the \c end command.
|
||||
|
||||
*/
|
||||
/** \page license Licenses
|
||||
|
||||
|
|
@ -2539,4 +2337,76 @@ DAMAGES.
|
|||
|
||||
|
||||
*/
|
||||
/** \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>
|
||||
|
||||
<hr>
|
||||
|
||||
\section faq-cwd-symlink Why does cd, pwd and other fish commands always resolve symlinked directories to their canonical path?
|
||||
<i>
|
||||
For example if I have the directory ~/images which is a symlink to
|
||||
~/Documents,/Images if I write 'cd doc', 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 possible completions. In fish, if you specify a
|
||||
relative directory to the cd command, i.e. any path that does not
|
||||
start with '.' or '/', the environment variable CD_PATH will be
|
||||
examined, and any directories in this path is used as a base
|
||||
direcotry. To disable this feature, use <code>set CD_PATH .</code> to
|
||||
only use the current directory for searches.
|
||||
|
||||
<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.
|
||||
|
||||
|
||||
*/
|
||||
|
|
@ -13,14 +13,12 @@
|
|||
|
|
||||
<a class="qindex" href="design.html">Design document</a>
|
||||
|
|
||||
<a class="qindex" href="about.html">About fish</a>
|
||||
|
|
||||
<a class="qindex" href="commands.html">External commands</a>
|
||||
|
|
||||
<a class="qindex" href="difference.html">How fish differs from other shells</a>
|
||||
|
|
||||
<a class="qindex" href="builtins.html">Builtin commands</a>
|
||||
|
|
||||
<a class="qindex" href="faq.html">FAQ</a>
|
||||
|
|
||||
<a class="qindex" href="license.html">License</a>
|
||||
|
||||
</div>
|
||||
|
|
|
|||
Loading…
Reference in a new issue