diff options
| author |  Konrad Borowski <x.fix@o2.pl> | 2014-09-12 13:36:26 +0200 |
|---|---|---|
| committer | Konrad Borowski <x.fix@o2.pl> | 2014-09-12 13:36:26 +0200 |
| commit | 5c25be51ea9ab623ae55728eee1987d0f16df255 (patch) | |
| tree | c811aaf584199a6e895f994d9a5b62c85a8acf95 | |
| parent | f6da9d4d5d04e9bd4e1e12727c1672e61495f33a (diff) | |
| parent | 6b75a4593bb2f5a4b3b1bdf3333f50ef94c20da5 (diff) | |
Merge pull request #1662 from MarkGriffiths/documentation-update
Documentation update: Fixes issue #1557
90 files changed, 9943 insertions, 5726 deletions
@@ -2,6 +2,7 @@ *~ *.exe +.DS_Store Makefile autom4te.cache/ build/ @@ -35,3 +36,7 @@ tests/foo.txt FISH-BUILD-VERSION-FILE version messages.pot +lexicon.txt +lexicon_filter +lexicon.log + @@ -1,902 +1,1945 @@ -# Doxyfile 1.3.9.1 +# Doxyfile 1.8.7 # This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project +# doxygen (www.doxygen.org) for a project. # -# All text after a hash (#) is considered a comment and will be ignored +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. # The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all text +# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv +# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv +# for the list of possible encodings. +# The default value is: UTF-8. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. PROJECT_NAME = fish -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. +# The PROJECT_NUMBER tag can be used to enter a project or revision number. This +# could be handy for archiving the generated documentation or if some version +# control system is used. PROJECT_NUMBER = 1 -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify an logo or icon that is included in +# the documentation. The maximum height of the logo should not exceed 55 pixels +# and the maximum width should not exceed 200 pixels. Doxygen will copy the logo +# to the output directory. + +PROJECT_LOGO = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path +# into which the generated documentation will be written. If a relative path is +# entered, it will be relative to the location where doxygen was started. If +# left blank the current directory will be used. OUTPUT_DIRECTORY = doc -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of source -# files, where putting all generated files in the same directory would otherwise -# cause performance problems for the file system. +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub- +# directories (in 2 levels) under the output directory of each output format and +# will distribute the generated files over these directories. Enabling this +# option can be useful when feeding doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise causes +# performance problems for the file system. +# The default value is: NO. CREATE_SUBDIRS = NO +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, -# Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese, -# Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian, -# Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, -# Swedish, and Ukrainian. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. +# The default value is: English. OUTPUT_LANGUAGE = English -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. +# If the BRIEF_MEMBER_DESC tag is set to YES doxygen will include brief member +# descriptions after the members that are listed in the file and class +# documentation (similar to Javadoc). Set to NO to disable this. +# The default value is: YES. BRIEF_MEMBER_DESC = YES -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief +# description of a member or function before the detailed description +# +# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. +# The default value is: YES. REPEAT_BRIEF = YES -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is used -# as the annotated text. Otherwise, the brief description is used as-is. If left -# blank, the following values are used ("$name" is automatically replaced with the -# name of the entity): "The $name class" "The $name widget" "The $name file" -# "is" "provides" "specifies" "contains" "represents" "a" "an" "the" +# This tag implements a quasi-intelligent brief description abbreviator that is +# used to form the text in various listings. Each string in this list, if found +# as the leading text of the brief description, will be stripped from the text +# and the result, after processing the whole list, is used as the annotated +# text. Otherwise, the brief description is used as-is. If left blank, the +# following values are used ($name is automatically replaced with the name of +# the entity):The $name class, The $name widget, The $name file, is, provides, +# specifies, contains, represents, a, an and the. ABBREVIATE_BRIEF = YES # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief +# doxygen will generate a detailed section even if there is only a brief # description. +# The default value is: NO. ALWAYS_DETAILED_SEC = NO -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited -# members of a class in the documentation of that class as if those members were -# ordinary class members. Constructors, destructors and assignment operators of -# the base classes will not be shown. +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. +# The default value is: NO. INLINE_INHERITED_MEMB = NO -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. +# If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path +# before files name in the file list and in the header files. If set to NO the +# shortest path that makes the file name unique will be used +# The default value is: YES. FULL_PATH_NAMES = YES -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand +# part of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to +# strip. +# +# Note that you can specify absolute paths here, but also relative paths, which +# will be relative from the directory where doxygen is started. +# This tag requires that the tag FULL_PATH_NAMES is set to YES. STRIP_FROM_PATH = -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the +# path mentioned in the documentation of a class, which tells the reader which +# header file to include in order to use a class. If left blank only the name of +# the header file containing the class definition is used. Otherwise one should +# specify the list of include paths that are normally passed to the compiler +# using the -I flag. STRIP_FROM_INC_PATH = -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but +# less readable) file names. This can be useful is your file systems doesn't +# support long names like on DOS, Mac, or CD-ROM. +# The default value is: NO. SHORT_NAMES = NO -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like the Qt-style comments (thus requiring an -# explicit @brief command for a brief description. +# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the +# first line (until the first dot) of a Javadoc-style comment as the brief +# description. If set to NO, the Javadoc-style will behave just like regular Qt- +# style comments (thus requiring an explicit @brief command for a brief +# description.) +# The default value is: NO. JAVADOC_AUTOBRIEF = YES -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. +# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first +# line (until the first dot) of a Qt-style comment as the brief description. If +# set to NO, the Qt-style will behave just like regular Qt-style comments (thus +# requiring an explicit \brief command for a brief description.) +# The default value is: NO. -MULTILINE_CPP_IS_BRIEF = NO +QT_AUTOBRIEF = NO -# If the DETAILS_AT_TOP tag is set to YES then Doxygen -# will output the detailed description near the top, like JavaDoc. -# If set to NO, the detailed description appears after the member -# documentation. +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# multi-line C++ special comment block (i.e. a block of //! or /// comments) as +# a brief description. This used to be the default behavior. The new default is +# to treat a multi-line C++ comment block as a detailed description. Set this +# tag to YES if you prefer the old behavior instead. +# +# Note that setting this tag to YES also means that rational rose comments are +# not recognized any more. +# The default value is: NO. -DETAILS_AT_TOP = NO +MULTILINE_CPP_IS_BRIEF = NO -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. +# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the +# documentation from any documented member that it re-implements. +# The default value is: YES. INHERIT_DOCS = YES -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce a +# new page for each member. If set to NO, the documentation of a member will be +# part of the file/class/namespace that contains it. +# The default value is: NO. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen +# uses this value to replace tabs by spaces in code fragments. +# Minimum value: 1, maximum value: 16, default value: 4. + +TAB_SIZE = 4 + +# This tag can be used to specify a number of aliases that act as commands in +# the documentation. An alias has the form: +# name=value +# For example adding +# "sideeffect=@par Side Effects:\n" +# will allow you to put the command \sideeffect (or @sideeffect) in the +# documentation, which will result in a user-defined paragraph with heading +# "Side Effects:". You can put \n's in the value part of an alias to insert +# newlines. + +# Simplify Fish output from Doxygen for developer doc pages. (see lexicon_filter.in) + +ALIASES = "key{1}=<b>\1</b>" +ALIASES += "key{2}=<b>\1-\2</b>" +ALIASES += "key{3}=<b>\1-\3</b>" +ALIASES += "cursor_key{2}=<b>\2</b>" + +ALIASES += "fish=<pre>" +ALIASES += "fish{1}=<pre>" +ALIASES += "endfish=</pre>\n" + +ALIASES += "asis{1}=\1" +ALIASES += "outp{1}=\1" +ALIASES += "blah{1}=#\1" +ALIASES += "bltn{1}=\1" +ALIASES += "func{1}=\1" +ALIASES += "cmnd{1}=\1" +ALIASES += "args{1}=\1" +ALIASES += "opts{1}=\1" +ALIASES += "vars{1}=\1" +ALIASES += "optr{1}=\1" +ALIASES += "redr{1}=\1" +ALIASES += "fsfo{1}=\1" +ALIASES += "path{1}=\1" +ALIASES += "clrv{1}=\1" + +ALIASES += "strg{1}=\1" +ALIASES += "sglq{1}='\1'" +ALIASES += "dblq{1}=\"\1\"" + +ALIASES += "prmt=>" +ALIASES += "prmt{1}=\1>" +ALIASES += "sgst{1}=\1" +ALIASES += "mtch{1}=\1" +ALIASES += "smtc{1}=\1" +ALIASES += "eror{1}=\1" +ALIASES += "curs=_" +ALIASES += "curs{1}=\1" + +ALIASES += "bold{1}=\1" +ALIASES += "emph{1}=\1" +ALIASES += "undr{1}=\1" +ALIASES += "span{2}=\2" +ALIASES += "spcl{2}=\2" + +ALIASES += "bksl{1}=\\\1" + +# This tag can be used to specify a number of word-keyword mappings (TCL only). +# A mapping has the form "name=value". For example adding "class=itcl::class" +# will allow you to use the command class in the itcl::class meaning. + +TCL_SUBST = -DISTRIBUTE_GROUP_DOC = NO +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. For +# instance, some of the names that are used will be different. The list of all +# members will be omitted, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_FOR_C = YES + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or +# Python sources only. Doxygen will then generate output that is more tailored +# for that language. For instance, namespaces will be presented as packages, +# qualified scopes will look different, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_JAVA = NO -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources. Doxygen will then generate output that is tailored for Fortran. +# The default value is: NO. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for VHDL. +# The default value is: NO. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, Javascript, +# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: +# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: +# Fortran. In the later case the parser tries to guess whether the code is fixed +# or free formatted code, this is the default for Fortran type files), VHDL. For +# instance to make doxygen treat .inc files as Fortran files (default is PHP), +# and .f files as C (default is Fortran), use: inc=Fortran f=C. +# +# Note For files without extension you can use no_extension as a placeholder. +# +# Note that for custom extensions you also need to set FILE_PATTERNS otherwise +# the files are not read by doxygen. -TAB_SIZE = 8 +EXTENSION_MAPPING = -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. +# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# according to the Markdown format, which allows for more readable +# documentation. See http://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you can +# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# case of backward compatibilities issues. +# The default value is: YES. -ALIASES = +MARKDOWN_SUPPORT = YES -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources -# only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. +# When enabled doxygen tries to link words that correspond to documented +# classes, or namespaces to their corresponding documentation. Such a link can +# be prevented in individual cases by by putting a % sign in front of the word +# or globally by setting AUTOLINK_SUPPORT to NO. +# The default value is: YES. -OPTIMIZE_OUTPUT_FOR_C = YES +AUTOLINK_SUPPORT = YES -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources -# only. Doxygen will then generate output that is more tailored for Java. -# For instance, namespaces will be presented as packages, qualified scopes -# will look different, etc. +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should set this +# tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); +# versus func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. +# The default value is: NO. -OPTIMIZE_OUTPUT_JAVA = NO +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. +# The default value is: NO. -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: +# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen +# will parse them like normal C++ but will assume all classes use public instead +# of private inheritance when no explicit protection keyword is present. +# The default value is: NO. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES will make +# doxygen to replace the get and set methods by a property in the documentation. +# This will only work if the methods are indeed getting or setting a simple +# type. If this is not the case, or you want to show the methods anyway, you +# should set this option to NO. +# The default value is: YES. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. +# The default value is: NO. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES to allow class member groups of the same type +# (for instance a group of public functions) to be put as a subgroup of that +# type (e.g. under the Public Functions section). Set it to NO to prevent +# subgrouping. Alternatively, this can be done per class using the +# \nosubgrouping command. +# The default value is: YES. SUBGROUPING = YES +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions +# are shown inside the group in which they are included (e.g. using \ingroup) +# instead of on a separate page (for HTML and Man pages) or section (for LaTeX +# and RTF). +# +# Note that this feature does not work in combination with +# SEPARATE_MEMBER_PAGES. +# The default value is: NO. + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions +# with only public data fields or simple typedef fields will be shown inline in +# the documentation of the scope in which they are defined (i.e. file, +# namespace, or group documentation), provided this scope is documented. If set +# to NO, structs, classes, and unions are shown on a separate page (for HTML and +# Man pages) or section (for LaTeX and RTF). +# The default value is: NO. + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or +# enum is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically be +# useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. +# The default value is: NO. + +TYPEDEF_HIDES_STRUCT = NO + +# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This +# cache is used to resolve symbols given their name and scope. Since this can be +# an expensive process and often the same symbol appears multiple times in the +# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# doxygen will become slower. If the cache is too large, memory is wasted. The +# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range +# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 +# symbols. At the end of a run doxygen will report the cache usage and suggest +# the optimal cache size from a speed point of view. +# Minimum value: 0, maximum value: 9, default value: 0. + +LOOKUP_CACHE_SIZE = 0 + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES +# documentation are documented, even if no documentation was available. Private +# class members and static file members will be hidden unless the +# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. +# Note: This will also disable the warnings about undocumented members that are +# normally produced when WARNINGS is set to YES. +# The default value is: NO. EXTRACT_ALL = NO -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class will +# be included in the documentation. +# The default value is: NO. EXTRACT_PRIVATE = NO -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. +# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal +# scope will be included in the documentation. +# The default value is: NO. + +EXTRACT_PACKAGE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file will be +# included in the documentation. +# The default value is: NO. EXTRACT_STATIC = YES -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO +# only classes defined in header files are included. Does not have any effect +# for Java sources. +# The default value is: YES. EXTRACT_LOCAL_CLASSES = YES -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. +# This flag is only useful for Objective-C code. When set to YES local methods, +# which are defined in the implementation section but not in the interface are +# included in the documentation. If set to NO only methods in the interface are +# included. +# The default value is: NO. EXTRACT_LOCAL_METHODS = NO -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base name of +# the file that contains the anonymous namespace. By default anonymous namespace +# are hidden. +# The default value is: NO. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# undocumented members inside documented classes or files. If set to NO these +# members will be included in the various overviews, but no documentation +# section is generated. This option has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. HIDE_UNDOC_MEMBERS = NO -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. +# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. If set +# to NO these classes will be included in the various overviews. This option has +# no effect if EXTRACT_ALL is enabled. +# The default value is: NO. HIDE_UNDOC_CLASSES = NO -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# (class|struct|union) declarations. If set to NO these declarations will be +# included in the documentation. +# The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. +# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# documentation blocks found inside the body of a function. If set to NO these +# blocks will be appended to the function's detailed documentation block. +# The default value is: NO. HIDE_IN_BODY_DOCS = NO -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. +# The INTERNAL_DOCS tag determines if documentation that is typed after a +# \internal command is included. If the tag is set to NO then the documentation +# will be excluded. Set it to YES to include the internal documentation. +# The default value is: NO. INTERNAL_DOCS = NO -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also +# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file +# names in lower-case letters. If set to YES upper-case letters are also # allowed. This is useful if you have classes or files whose names only differ # in case and if your file system supports case sensitive file names. Windows # and Mac users are advised to set this option to NO. +# The default value is: system dependent. CASE_SENSE_NAMES = YES -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. +# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# their full class and namespace scopes in the documentation. If set to YES the +# scope will be hidden. +# The default value is: NO. HIDE_SCOPE_NAMES = NO -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. +# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# the files that are included by a file in the documentation of that file. +# The default value is: YES. SHOW_INCLUDE_FILES = YES -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# files with double quotes in the documentation rather than with sharp brackets. +# The default value is: NO. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the +# documentation for inline members. +# The default value is: YES. INLINE_INFO = YES -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. +# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# (detailed) documentation of file and class members alphabetically by member +# name. If set to NO the members will appear in declaration order. +# The default value is: YES. SORT_MEMBER_DOCS = YES -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# descriptions of file, namespace and class members alphabetically by member +# name. If set to NO the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. +# The default value is: NO. SORT_BRIEF_DOCS = NO -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# (brief and detailed) documentation of class members so that constructors and +# destructors are listed first. If set to NO the constructors will appear in the +# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. +# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief +# member documentation. +# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting +# detailed member documentation. +# The default value is: NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# of group names into alphabetical order. If set to NO the group names will +# appear in their defined order. +# The default value is: NO. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by +# fully-qualified names, including namespaces. If set to NO, the class list will +# be sorted only by class name, not including the namespace part. # Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. +# Note: This option applies only to the class list, not to the alphabetical +# list. +# The default value is: NO. SORT_BY_SCOPE_NAME = NO -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# type resolution of all parameters of a function it will reject a match between +# the prototype and the implementation of a member function even if there is +# only one candidate or it is obvious which candidate to choose by doing a +# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# accept a match between prototype and implementation in such cases. +# The default value is: NO. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable ( YES) or disable ( NO) the +# todo list. This list is created by putting \todo commands in the +# documentation. +# The default value is: YES. GENERATE_TODOLIST = YES -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. +# The GENERATE_TESTLIST tag can be used to enable ( YES) or disable ( NO) the +# test list. This list is created by putting \test commands in the +# documentation. +# The default value is: YES. GENERATE_TESTLIST = YES -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. +# The GENERATE_BUGLIST tag can be used to enable ( YES) or disable ( NO) the bug +# list. This list is created by putting \bug commands in the documentation. +# The default value is: YES. GENERATE_BUGLIST = YES -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. +# The GENERATE_DEPRECATEDLIST tag can be used to enable ( YES) or disable ( NO) +# the deprecated list. This list is created by putting \deprecated commands in +# the documentation. +# The default value is: YES. GENERATE_DEPRECATEDLIST= YES -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. +# The ENABLED_SECTIONS tag can be used to enable conditional documentation +# sections, marked by \if <section_label> ... \endif and \cond <section_label> +# ... \endcond blocks. ENABLED_SECTIONS = -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the +# initial value of a variable or macro / define can have for it to appear in the +# documentation. If the initializer consists of more lines than specified here +# it will be hidden. Use a value of 0 to hide initializers completely. The +# appearance of the value of individual variables and macros / defines can be +# controlled using \showinitializer or \hideinitializer command in the +# documentation regardless of this setting. +# Minimum value: 0, maximum value: 10000, default value: 30. MAX_INITIALIZER_LINES = 30 -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at +# the bottom of the documentation of classes and structs. If set to YES the list +# will mention the files that were used to generate the documentation. +# The default value is: YES. SHOW_USED_FILES = YES -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This +# will remove the Files entry from the Quick Index and from the Folder Tree View +# (if specified). +# The default value is: YES. -SHOW_DIRECTORIES = YES +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces +# page. This will remove the Namespaces entry from the Quick Index and from the +# Folder Tree View (if specified). +# The default value is: YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command command input-file, where command is the value of the +# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided +# by doxygen. Whatever the program writes to standard output is used as the file +# version. For an example see the documentation. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. You can +# optionally specify a file name after the option, if omitted DoxygenLayout.xml +# will be used as the name of the layout file. +# +# Note that if you run doxygen from a directory containing a file called +# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# tag is left empty. + +LAYOUT_FILE = + +# The CITE_BIB_FILES tag can be used to specify one or more bib files containing +# the reference definitions. This must be a list of .bib files. The .bib +# extension is automatically appended if omitted. This requires the bibtex tool +# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. +# For LaTeX the style of the bibliography can be controlled using +# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the +# search path. Do not use file names with spaces, bibtex cannot handle them. See +# also \cite for info how to create references. + +CITE_BIB_FILES = #--------------------------------------------------------------------------- -# configuration options related to warning and progress messages +# Configuration options related to warning and progress messages #--------------------------------------------------------------------------- -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. +# The QUIET tag can be used to turn on/off the messages that are generated to +# standard output by doxygen. If QUIET is set to YES this implies that the +# messages are off. +# The default value is: NO. QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. +# generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES +# this implies that the warnings are on. +# +# Tip: Turn warnings on while writing the documentation. +# The default value is: YES. WARNINGS = YES -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. +# If the WARN_IF_UNDOCUMENTED tag is set to YES, then doxygen will generate +# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: YES. WARN_IF_UNDOCUMENTED = YES -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. +# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some parameters +# in a documented function, or documenting parameters that don't exist or using +# markup commands wrongly. +# The default value is: YES. WARN_IF_DOC_ERROR = YES -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. +# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that +# are documented, but have no documentation for their parameters or return +# value. If set to NO doxygen will only warn about wrong or incomplete parameter +# documentation, but not about the absence of documentation. +# The default value is: NO. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# can produce. The string should contain the $file, $line, and $text tags, which +# will be replaced by the file and line number from which the warning originated +# and the warning text. Optionally the format may contain $version, which will +# be replaced by the version of the file (if it could be obtained via +# FILE_VERSION_FILTER) +# The default value is: $file:$line: $text. WARN_FORMAT = "$file:$line: $text" -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. +# The WARN_LOGFILE tag can be used to specify a file to which warning and error +# messages should be written. If left blank the output is written to standard +# error (stderr). WARN_LOGFILE = #--------------------------------------------------------------------------- -# configuration options related to the input files +# Configuration options related to the input files #--------------------------------------------------------------------------- -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. +# The INPUT tag is used to specify the files and/or directories that contain +# documented source files. You may enter file names like myfile.cpp or +# directories like /usr/src/myproject. Separate the files or directories with +# spaces. +# Note: If this tag is empty the current directory is searched. INPUT = +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# libiconv (or the iconv built into libc) for the transcoding. See the libiconv +# documentation (see: http://www.gnu.org/software/libiconv) for the list of +# possible encodings. +# The default value is: UTF-8. + +INPUT_ENCODING = UTF-8 + # If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp -# *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm +# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank the +# following patterns are tested:*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii, +# *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, +# *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, +# *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, +# *.qsf, *.as and *.js. -FILE_PATTERNS = *.h *.c +FILE_PATTERNS = *.h \ + *.c -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. RECURSIVE = NO -# The EXCLUDE tag can be used to specify files and/or directories that should +# The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. - -EXCLUDE = print_help.c xdgmimealias.c xdgmimealias.h xdgmime.c xdgmimeglob.c xdgmimeglob.h xdgmime.h xdgmimeint.c xdgmimeint.h xdgmimemagic.c xdgmimemagic.h xdgmimeparent.c xdgmimeparent.h - - -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories -# that are symbolic links (a Unix filesystem feature) are excluded from the input. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. + +EXCLUDE = print_help.c \ + xdgmimealias.c \ + xdgmimealias.h \ + xdgmime.c \ + xdgmimeglob.c \ + xdgmimeglob.h \ + xdgmime.h \ + xdgmimeint.c \ + xdgmimeint.h \ + xdgmimemagic.c \ + xdgmimemagic.h \ + xdgmimeparent.c \ + xdgmimeparent.h + +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. +# The default value is: NO. EXCLUDE_SYMLINKS = NO # If the value of the INPUT tag contains directories, you can use the # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude # certain files from those directories. +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories for example use the pattern */test/* EXCLUDE_PATTERNS = -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories use the pattern */test/* + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or directories +# that contain example code fragments that are included (see the \include +# command). EXAMPLE_PATH = # If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank all +# files are included. EXAMPLE_PATTERNS = # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. +# searched for input files to be used with the \include or \dontinclude commands +# irrespective of the value of the RECURSIVE tag. +# The default value is: NO. EXAMPLE_RECURSIVE = NO -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). +# The IMAGE_PATH tag can be used to specify one or more files or directories +# that contain images that are to be included in the documentation (see the +# \image command). IMAGE_PATH = # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command <filter> <input-file>, where <filter> -# is the value of the INPUT_FILTER tag, and <input-file> is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. If FILTER_PATTERNS is specified, this tag will be -# ignored. +# by executing (via popen()) the command: +# +# <filter> <input-file> +# +# where <filter> is the value of the INPUT_FILTER tag, and <input-file> is the +# name of an input file. Doxygen will then use the output that the filter +# program writes to standard output. If FILTER_PATTERNS is specified, this tag +# will be ignored. +# +# Note that the filter must not add or remove lines; it is applied before the +# code is scanned, but not when the output code is generated. If lines are added +# or removed, the anchors will not be placed correctly. INPUT_FILTER = # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: pattern=filter +# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how +# filters are used. If the FILTER_PATTERNS tag is empty or if none of the +# patterns match the file name, INPUT_FILTER is applied. FILTER_PATTERNS = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). +# INPUT_FILTER ) will also be used to filter the input files that are used for +# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). +# The default value is: NO. FILTER_SOURCE_FILES = NO +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. + +FILTER_SOURCE_PATTERNS = + +# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that +# is part of the input, its contents will be placed on the main page +# (index.html). This can be useful if you have a project on for instance GitHub +# and want to reuse the introduction page also for the doxygen output. + +USE_MDFILE_AS_MAINPAGE = + #--------------------------------------------------------------------------- -# configuration options related to source browsing +# Configuration options related to source browsing #--------------------------------------------------------------------------- -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. +# If the SOURCE_BROWSER tag is set to YES then a list of source files will be +# generated. Documented entities will be cross-referenced with these sources. +# +# Note: To get rid of all source code in the generated output, make sure that +# also VERBATIM_HEADERS is set to NO. +# The default value is: NO. SOURCE_BROWSER = NO -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. +# Setting the INLINE_SOURCES tag to YES will include the body of functions, +# classes and enums directly into the documentation. +# The default value is: NO. INLINE_SOURCES = NO -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# special comment blocks from generated source code fragments. Normal C, C++ and +# Fortran comments will always remain visible. +# The default value is: YES. STRIP_CODE_COMMENTS = YES -# If the REFERENCED_BY_RELATION tag is set to YES (the default) -# then for each documented function all documented -# functions referencing it will be listed. +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# function all documented functions referencing it will be listed. +# The default value is: NO. REFERENCED_BY_RELATION = YES -# If the REFERENCES_RELATION tag is set to YES (the default) -# then for each documented function all documented entities -# called/used by that function will be listed. +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. REFERENCES_RELATION = YES -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. +# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set +# to YES, then the hyperlinks from functions in REFERENCES_RELATION and +# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will +# link to the documentation. +# The default value is: YES. + +REFERENCES_LINK_SOURCE = YES + +# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the +# source code will show a tooltip with additional information such as prototype, +# brief description and links to the definition and documentation. Since this +# will make the HTML file larger and loading of large files a bit slower, you +# can opt to disable this feature. +# The default value is: YES. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +SOURCE_TOOLTIPS = YES + +# If the USE_HTAGS tag is set to YES then the references to source code will +# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# source browser. The htags tool is part of GNU's global source tagging system +# (see http://www.gnu.org/software/global/global.html). You will need version +# 4.8.6 or higher. +# +# To use it do the following: +# - Install the latest version of global +# - Enable SOURCE_BROWSER and USE_HTAGS in the config file +# - Make sure the INPUT points to the root of the source tree +# - Run doxygen as normal +# +# Doxygen will invoke htags (and that will in turn invoke gtags), so these +# tools must be available from the command line (i.e. in the search path). +# +# The result: instead of the source browser generated by doxygen, the links to +# source code will now point to the output of htags. +# The default value is: NO. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# verbatim copy of the header file for each class for which an include is +# specified. Set to NO to disable this. +# See also: Section \class. +# The default value is: YES. VERBATIM_HEADERS = YES #--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index +# Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all +# compounds will be generated. Enable this if the project contains a lot of +# classes, structs, unions or interfaces. +# The default value is: YES. ALPHABETICAL_INDEX = NO -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) +# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in +# which the alphabetical index list will be split. +# Minimum value: 1, maximum value: 20, default value: 5. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. COLS_IN_ALPHA_INDEX = 5 -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. +# In case all classes in a project start with a common prefix, all classes will +# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag +# can be used to specify a prefix (or a list of prefixes) that should be ignored +# while generating the index headers. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. IGNORE_PREFIX = #--------------------------------------------------------------------------- -# configuration options related to the HTML output +# Configuration options related to the HTML output #--------------------------------------------------------------------------- -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. +# If the GENERATE_HTML tag is set to YES doxygen will generate HTML output +# The default value is: YES. GENERATE_HTML = YES -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: html. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_OUTPUT = html -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each +# generated HTML page (for example: .htm, .php, .asp). +# The default value is: .html. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_FILE_EXTENSION = .html -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a +# The HTML_HEADER tag can be used to specify a user-defined HTML header file for +# each generated HTML page. If the tag is left blank doxygen will generate a # standard header. +# +# To get valid HTML the header file that includes any scripts and style sheets +# that doxygen needs, which is dependent on the configuration options used (e.g. +# the setting GENERATE_TREEVIEW). It is highly recommended to start with a +# default header using +# doxygen -w html new_header.html new_footer.html new_stylesheet.css +# YourConfigFile +# and then modify the file new_header.html. See also section "Doxygen usage" +# for information on how to generate the default header that doxygen normally +# uses. +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. For a description +# of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_HEADER = -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. +# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each +# generated HTML page. If the tag is left blank doxygen will generate a standard +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_FOOTER = -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style +# sheet that is used by each HTML page. It can be used to fine-tune the look of +# the HTML output. If left blank doxygen will generate a default style sheet. +# See also section "Doxygen usage" for information on how to generate the style +# sheet that doxygen normally uses. +# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as +# it is more robust and this tag (HTML_STYLESHEET) will in the future become +# obsolete. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_STYLESHEET = -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) -# of the generated HTML documentation. +# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional user- +# defined cascading style sheet that is included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefor more robust against future updates. +# Doxygen will copy the style sheet file to the output directory. For an example +# see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_STYLESHEET = + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that the +# files will be copied as-is; there are no commands or markers available. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen +# will adjust the colors in the stylesheet and background images according to +# this color. Hue is specified as an angle on a colorwheel, see +# http://en.wikipedia.org/wiki/Hue for more information. For instance the value +# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 +# purple, and 360 is red again. +# Minimum value: 0, maximum value: 359, default value: 220. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors +# in the HTML output. For a value of 0 the output will use grayscales only. A +# value of 255 will produce the most vivid colors. +# Minimum value: 0, maximum value: 255, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the +# luminance component of the colors in the HTML output. Values below 100 +# gradually make the output lighter, whereas values above 100 make the output +# darker. The value divided by 100 is the actual gamma applied, so 80 represents +# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not +# change the gamma. +# Minimum value: 40, maximum value: 240, default value: 80. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting this +# to NO can help when comparing the output of multiple runs. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_TIMESTAMP = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_SECTIONS = NO + +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries +# shown in the various tree structured indices initially; the user can expand +# and collapse entries dynamically later on. Doxygen will expand the tree to +# such a level that at most the specified number of entries are visible (unless +# a fully collapsed tree already exceeds this amount). So setting the number of +# entries 1 will produce a full collapsed tree by default. 0 is a special value +# representing an infinite number of entries and will result in a full expanded +# tree by default. +# Minimum value: 0, maximum value: 9999, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files will be +# generated that can be used as input for Apple's Xcode 3 integrated development +# environment (see: http://developer.apple.com/tools/xcode/), introduced with +# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a +# Makefile in the HTML output directory. Running make will produce the docset in +# that directory and running make install will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at +# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_DOCSET = NO + +# This tag determines the name of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# The default value is: Doxygen generated docs. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# This tag specifies a string that should uniquely identify the documentation +# set bundle. This should be a reverse domain-name style string, e.g. +# com.mycompany.MyDocSet. Doxygen will append .docset to the name. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. +# The default value is: org.doxygen.Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. +# The default value is: Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# additional HTML index files: index.hhp, index.hhc, and index.hhk. The +# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop +# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on +# Windows. +# +# The HTML Help Workshop contains a compiler that can convert all HTML output +# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# files are now used as the Windows 98 help format, and will replace the old +# Windows help format (.hlp) on all Windows platforms in the future. Compressed +# HTML files also contain an index, a table of contents, and you can search for +# words in the documentation. The HTML workshop also contains a viewer for +# compressed HTML files. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_HTMLHELP = NO -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be +# The CHM_FILE tag can be used to specify the file name of the resulting .chm +# file. You can add a path in front of the file if the result should not be # written to the html output directory. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_FILE = -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. +# The HHC_LOCATION tag can be used to specify the location (absolute path +# including file name) of the HTML help compiler ( hhc.exe). If non-empty +# doxygen will try to run the HTML help compiler on the generated index.hhp. +# The file has to be specified with full path. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. HHC_LOCATION = -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). +# The GENERATE_CHI flag controls if a separate .chi index file is generated ( +# YES) or that it should be included in the master .chm file ( NO). +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. GENERATE_CHI = NO -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index ( hhk), content ( hhc) +# and project file content. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_INDEX_ENCODING = + +# The BINARY_TOC flag controls whether a binary table of contents is generated ( +# YES) or a normal table of contents ( NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. BINARY_TOC = NO -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. +# The TOC_EXPAND flag can be set to YES to add extra items for group members to +# the table of contents of the HTML help documentation and to the tree view. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. TOC_EXPAND = NO -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that +# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help +# (.qch) of the generated HTML documentation. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify +# the file name of the resulting .qch file. The path specified is relative to +# the HTML output folder. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help +# Project output. For more information please see Qt Help Project / Namespace +# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt +# Help Project output. For more information please see Qt Help Project / Virtual +# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- +# folders). +# The default value is: doc. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_VIRTUAL_FOLDER = doc + +# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom +# filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's filter section matches. Qt Help Project / Filter Attributes (see: +# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_SECT_FILTER_ATTRS = + +# The QHG_LOCATION tag can be used to specify the location of Qt's +# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the +# generated .qhp file. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be +# generated, together with the HTML files, they form an Eclipse help plugin. To +# install this plugin and make it available under the help contents menu in +# Eclipse, the contents of the directory containing the HTML and XML files needs +# to be copied into the plugins directory of eclipse. The name of the directory +# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. +# After copying Eclipse needs to be restarted before the help appears. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the Eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have this +# name. Each documentation set should have its own identifier. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# If you want full control over the layout of the generated HTML pages it might +# be necessary to disable the index and replace it with your own. The +# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top +# of each HTML page. A value of NO enables the index and the value YES disables +# it. Since the tabs in the index contain the same information as the navigation +# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. DISABLE_INDEX = NO -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. If the tag +# value is set to YES, a side panel will be generated containing a tree-like +# index structure (just like the one that is generated for HTML Help). For this +# to work a browser that supports JavaScript, DHTML, CSS and frames is required +# (i.e. any modern browser). Windows users are probably better off using the +# HTML help feature. Via custom stylesheets (see HTML_EXTRA_STYLESHEET) one can +# further fine-tune the look of the index. As an example, the default style +# sheet generated by doxygen has an example that shows how to put an image at +# the root of the tree instead of the PROJECT_NAME. Since the tree basically has +# the same information as the tab index, you could consider setting +# DISABLE_INDEX to YES when enabling this option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. -ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO -# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be -# generated containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, -# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are -# probably better off using the HTML help feature. +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that +# doxygen will group on one line in the generated HTML documentation. +# +# Note that a value of 0 will completely suppress the enum values from appearing +# in the overview section. +# Minimum value: 0, maximum value: 20, default value: 4. +# This tag requires that the tag GENERATE_HTML is set to YES. -GENERATE_TREEVIEW = NO +ENUM_VALUES_PER_LINE = 4 -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used +# to set the initial width (in pixels) of the frame in which the tree is shown. +# Minimum value: 0, maximum value: 1500, default value: 250. +# This tag requires that the tag GENERATE_HTML is set to YES. TREEVIEW_WIDTH = 250 +# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open links to +# external symbols imported via tag files in a separate window. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of LaTeX formulas included as images in +# the HTML documentation. When you change the font size after a successful +# doxygen run you need to manually remove any form_*.png images from the HTML +# output directory to force them to be regenerated. +# Minimum value: 8, maximum value: 50, default value: 10. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are not +# supported properly for IE 6.0, but are supported on all modern browsers. +# +# Note that when changing this option you need to delete any form_*.png files in +# the HTML output directory before the changes have effect. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_TRANSPARENT = YES + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see +# http://www.mathjax.org) which uses client side Javascript for the rendering +# instead of using prerendered bitmaps. Use this if you do not have LaTeX +# installed or if you want to formulas look prettier in the HTML output. When +# enabled you may also need to install MathJax separately and configure the path +# to it using the MATHJAX_RELPATH option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +USE_MATHJAX = NO + +# When MathJax is enabled you can set the default output format to be used for +# the MathJax output. See the MathJax site (see: +# http://docs.mathjax.org/en/latest/output.html) for more details. +# Possible values are: HTML-CSS (which is slower, but has the best +# compatibility), NativeMML (i.e. MathML) and SVG. +# The default value is: HTML-CSS. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_FORMAT = HTML-CSS + +# When MathJax is enabled you need to specify the location relative to the HTML +# output directory using the MATHJAX_RELPATH option. The destination directory +# should contain the MathJax.js script. For instance, if the mathjax directory +# is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax +# Content Delivery Network so you can quickly see the result without installing +# MathJax. However, it is strongly recommended to install a local copy of +# MathJax from http://www.mathjax.org before deployment. +# The default value is: http://cdn.mathjax.org/mathjax/latest. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest + +# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax +# extension names that should be enabled during MathJax rendering. For example +# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_EXTENSIONS = + +# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# of code that will be used on startup of the MathJax code. See the MathJax site +# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# example see the documentation. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_CODEFILE = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for +# the HTML output. The underlying search engine uses javascript and DHTML and +# should work on any modern browser. Note that when using HTML help +# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) +# there is already a search function so this one should typically be disabled. +# For large projects the javascript based search engine can be slow, then +# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to +# search using the keyboard; to jump to the search box use <access key> + S +# (what the <access key> is depends on the OS and browser, but it is typically +# <CTRL>, <ALT>/<option>, or both). Inside the search box use the <cursor down +# key> to jump into the search results window, the results can be navigated +# using the <cursor keys>. Press <Enter> to select an item or <escape> to cancel +# the search. The filter options can be selected when the cursor is inside the +# search box by pressing <Shift>+<cursor down>. Also here use the <cursor keys> +# to select a filter and <Enter> or <escape> to activate or cancel the filter +# option. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +SEARCHENGINE = NO + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a web server instead of a web client using Javascript. There +# are two flavors of web server based searching depending on the EXTERNAL_SEARCH +# setting. When disabled, doxygen will generate a PHP script for searching and +# an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing +# and searching needs to be provided by external tools. See the section +# "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SERVER_BASED_SEARCH = NO + +# When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP +# script for searching. Instead the search results are written to an XML file +# which needs to be processed by an external indexer. Doxygen will invoke an +# external search engine pointed to by the SEARCHENGINE_URL option to obtain the +# search results. +# +# Doxygen ships with an example indexer ( doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: http://xapian.org/). +# +# See the section "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH = NO + +# The SEARCHENGINE_URL should point to a search engine hosted by a web server +# which will return the search results when EXTERNAL_SEARCH is enabled. +# +# Doxygen ships with an example indexer ( doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: http://xapian.org/). See the section "External Indexing and +# Searching" for details. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHENGINE_URL = + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed +# search data is written to a file for indexing by an external tool. With the +# SEARCHDATA_FILE tag the name of this file can be specified. +# The default file is: searchdata.xml. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHDATA_FILE = searchdata.xml + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the +# EXTERNAL_SEARCH_ID tag can be used as an identifier for the project. This is +# useful in combination with EXTRA_SEARCH_MAPPINGS to search through multiple +# projects and redirect the results back to the right project. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH_ID = + +# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen +# projects other than the one defined by this configuration file, but that are +# all added to the same external search index. Each project needs to have a +# unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id of +# to a relative location where the documentation can be found. The format is: +# EXTRA_SEARCH_MAPPINGS = tagname1=loc1 tagname2=loc2 ... +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTRA_SEARCH_MAPPINGS = + #--------------------------------------------------------------------------- -# configuration options related to the LaTeX output +# Configuration options related to the LaTeX output #--------------------------------------------------------------------------- -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. +# If the GENERATE_LATEX tag is set to YES doxygen will generate LaTeX output. +# The default value is: YES. GENERATE_LATEX = YES -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: latex. +# This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_OUTPUT = latex # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. +# invoked. +# +# Note that when enabling USE_PDFLATEX this option is only used for generating +# bitmaps for formulas in the HTML output, but not in the Makefile that is +# written to the output directory. +# The default file is: latex. +# This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_CMD_NAME = latex -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate +# index for LaTeX. +# The default file is: makeindex. +# This tag requires that the tag GENERATE_LATEX is set to YES. MAKEINDEX_CMD_NAME = makeindex -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. +# If the COMPACT_LATEX tag is set to YES doxygen generates more compact LaTeX +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. COMPACT_LATEX = NO -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and -# executive. If left blank a4wide will be used. +# The PAPER_TYPE tag can be used to set the paper type that is used by the +# printer. +# Possible values are: a4 (210 x 297 mm), letter (8.5 x 11 inches), legal (8.5 x +# 14 inches) and executive (7.25 x 10.5 inches). +# The default value is: a4. +# This tag requires that the tag GENERATE_LATEX is set to YES. PAPER_TYPE = a4wide -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. +# The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names +# that should be included in the LaTeX output. To get the times font for +# instance you can specify +# EXTRA_PACKAGES=times +# If left blank no extra packages will be included. +# This tag requires that the tag GENERATE_LATEX is set to YES. -EXTRA_PACKAGES = +EXTRA_PACKAGES = bookmark -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for the +# generated LaTeX document. The header should contain everything until the first +# chapter. If it is left blank doxygen will generate a standard header. See +# section "Doxygen usage" for information on how to let doxygen write the +# default header to a separate file. +# +# Note: Only use a user-defined header if you know what you are doing! The +# following commands have a special meaning inside the header: $title, +# $datetime, $date, $doxygenversion, $projectname, $projectnumber. Doxygen will +# replace them by respectively the title of the page, the current date and time, +# only the current date, the version number of doxygen, the project name (see +# PROJECT_NAME), or the project number (see PROJECT_NUMBER). +# This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_HEADER = -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. +# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the +# generated LaTeX document. The footer should contain everything after the last +# chapter. If it is left blank doxygen will generate a standard footer. +# +# Note: Only use a user-defined footer if you know what you are doing! +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_FOOTER = + +# The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the LATEX_OUTPUT output +# directory. Note that the files will be copied as-is; there are no commands or +# markers available. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_FILES = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated is +# prepared for conversion to PDF (using ps2pdf or pdflatex). The PDF file will +# contain links (just like the HTML output) instead of page references. This +# makes the output suitable for online browsing using a PDF viewer. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. PDF_HYPERLINKS = YES -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a +# If the LATEX_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate +# the PDF file directly from the LaTeX files. Set this option to YES to get a # higher quality PDF documentation. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. USE_PDFLATEX = YES -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode +# command to the generated LaTeX files. This will instruct LaTeX to keep running +# if errors occur, instead of asking the user for help. This option is also used +# when generating formulas in HTML. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. -LATEX_BATCHMODE = NO +LATEX_BATCHMODE = YES -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. +# If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the +# index chapters (such as File Index, Compound Index, etc.) in the output. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_HIDE_INDICES = NO +# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source +# code with syntax highlighting in the LaTeX output. +# +# Note that which sources are shown also depends on other settings such as +# SOURCE_BROWSER. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_SOURCE_CODE = NO + +# The LATEX_BIB_STYLE tag can be used to specify the style to use for the +# bibliography, e.g. plainnat, or ieeetr. See +# http://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# The default value is: plain. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_BIB_STYLE = plain + #--------------------------------------------------------------------------- -# configuration options related to the RTF output +# Configuration options related to the RTF output #--------------------------------------------------------------------------- -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. +# If the GENERATE_RTF tag is set to YES doxygen will generate RTF output. The +# RTF output is optimized for Word 97 and may not look too pretty with other RTF +# readers/editors. +# The default value is: NO. GENERATE_RTF = NO -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: rtf. +# This tag requires that the tag GENERATE_RTF is set to YES. RTF_OUTPUT = rtf -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. +# If the COMPACT_RTF tag is set to YES doxygen generates more compact RTF +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. COMPACT_RTF = NO -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated will +# contain hyperlink fields. The RTF file will contain links (just like the HTML +# output) instead of page references. This makes the output suitable for online +# browsing using Word or some other Word compatible readers that support those +# fields. +# +# Note: WordPad (write) and others do not support links. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. RTF_HYPERLINKS = NO -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. +# Load stylesheet definitions from file. Syntax is similar to doxygen's config +# file, i.e. a series of assignments. You only have to provide replacements, +# missing definitions are set to their default value. +# +# See also section "Doxygen usage" for information on how to generate the +# default style sheet that doxygen normally uses. +# This tag requires that the tag GENERATE_RTF is set to YES. RTF_STYLESHEET_FILE = -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. +# Set optional variables used in the generation of an RTF document. Syntax is +# similar to doxygen's config file. A template extensions file can be generated +# using doxygen -e rtf extensionFile. +# This tag requires that the tag GENERATE_RTF is set to YES. RTF_EXTENSIONS_FILE = #--------------------------------------------------------------------------- -# configuration options related to the man page output +# Configuration options related to the man page output #--------------------------------------------------------------------------- -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages +# If the GENERATE_MAN tag is set to YES doxygen will generate man pages for +# classes and files. +# The default value is: NO. GENERATE_MAN = NO -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. +# The MAN_OUTPUT tag is used to specify where the man pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. A directory man3 will be created inside the directory specified by +# MAN_OUTPUT. +# The default directory is: man. +# This tag requires that the tag GENERATE_MAN is set to YES. MAN_OUTPUT = man -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) +# The MAN_EXTENSION tag determines the extension that is added to the generated +# man pages. In case the manual section does not start with a number, the number +# 3 is prepended. The dot (.) at the beginning of the MAN_EXTENSION tag is +# optional. +# The default value is: .3. +# This tag requires that the tag GENERATE_MAN is set to YES. MAN_EXTENSION = .3 -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. +# The MAN_SUBDIR tag determines the name of the directory created within +# MAN_OUTPUT in which the man pages are placed. If defaults to man followed by +# MAN_EXTENSION with the initial . removed. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_SUBDIR = + +# If the MAN_LINKS tag is set to YES and doxygen generates man output, then it +# will generate one additional man file for each entity documented in the real +# man page(s). These additional files only source the real man page, but without +# them the man command would be unable to find the correct page. +# The default value is: NO. +# This tag requires that the tag GENERATE_MAN is set to YES. MAN_LINKS = NO #--------------------------------------------------------------------------- -# configuration options related to the XML output +# Configuration options related to the XML output #--------------------------------------------------------------------------- -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. +# If the GENERATE_XML tag is set to YES doxygen will generate an XML file that +# captures the structure of the code including all documentation. +# The default value is: NO. GENERATE_XML = NO -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. +# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: xml. +# This tag requires that the tag GENERATE_XML is set to YES. XML_OUTPUT = xml -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the -# syntax of the XML files. +# If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program +# listings (including syntax highlighting and cross-referencing information) to +# the XML output. Note that enabling this will significantly increase the size +# of the XML output. +# The default value is: YES. +# This tag requires that the tag GENERATE_XML is set to YES. -XML_SCHEMA = +XML_PROGRAMLISTING = YES -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the -# syntax of the XML files. +#--------------------------------------------------------------------------- +# Configuration options related to the DOCBOOK output +#--------------------------------------------------------------------------- -XML_DTD = +# If the GENERATE_DOCBOOK tag is set to YES doxygen will generate Docbook files +# that can be used to generate PDF. +# The default value is: NO. -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. +GENERATE_DOCBOOK = NO -XML_PROGRAMLISTING = YES +# The DOCBOOK_OUTPUT tag is used to specify where the Docbook pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be put in +# front of it. +# The default directory is: docbook. +# This tag requires that the tag GENERATE_DOCBOOK is set to YES. + +DOCBOOK_OUTPUT = docbook #--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output +# Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. +# If the GENERATE_AUTOGEN_DEF tag is set to YES doxygen will generate an AutoGen +# Definitions (see http://autogen.sf.net) file that captures the structure of +# the code including all documentation. Note that this feature is still +# experimental and incomplete at the moment. +# The default value is: NO. GENERATE_AUTOGEN_DEF = NO #--------------------------------------------------------------------------- -# configuration options related to the Perl module output +# Configuration options related to the Perl module output #--------------------------------------------------------------------------- -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. +# If the GENERATE_PERLMOD tag is set to YES doxygen will generate a Perl module +# file that captures the structure of the code including all documentation. +# +# Note that this feature is still experimental and incomplete at the moment. +# The default value is: NO. GENERATE_PERLMOD = NO -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. +# If the PERLMOD_LATEX tag is set to YES doxygen will generate the necessary +# Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI +# output from the Perl module output. +# The default value is: NO. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. PERLMOD_LATEX = NO -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. This is useful -# if you want to understand what is going on. On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be nicely +# formatted so it can be parsed by a human reader. This is useful if you want to +# understand what is going on. On the other hand, if this tag is set to NO the +# size of the Perl module output will be much smaller and Perl will parse it +# just the same. +# The default value is: YES. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. PERLMOD_PRETTY = YES -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. +# The names of the make variables in the generated doxyrules.make file are +# prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. This is useful +# so different doxyrules.make files included by the same Makefile don't +# overwrite each other's variables. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. PERLMOD_MAKEVAR_PREFIX = @@ -904,108 +1947,128 @@ PERLMOD_MAKEVAR_PREFIX = # Configuration options related to the preprocessor #--------------------------------------------------------------------------- -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. +# If the ENABLE_PREPROCESSING tag is set to YES doxygen will evaluate all +# C-preprocessor directives found in the sources and include files. +# The default value is: YES. ENABLE_PREPROCESSING = YES -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. +# If the MACRO_EXPANSION tag is set to YES doxygen will expand all macro names +# in the source code. If set to NO only conditional compilation will be +# performed. Macro expansion can be done in a controlled way by setting +# EXPAND_ONLY_PREDEF to YES. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. MACRO_EXPANSION = NO -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_PREDEFINED tags. +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then +# the macro expansion is limited to the macros specified with the PREDEFINED and +# EXPAND_AS_DEFINED tags. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. EXPAND_ONLY_PREDEF = NO -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# in the INCLUDE_PATH (see below) will be search if a #include is found. +# If the SEARCH_INCLUDES tag is set to YES the includes files in the +# INCLUDE_PATH will be searched if a #include is found. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. SEARCH_INCLUDES = YES # The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. +# contain include files that are not input files but should be processed by the +# preprocessor. +# This tag requires that the tag SEARCH_INCLUDES is set to YES. INCLUDE_PATH = # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. +# directories. If left blank, the patterns specified with FILE_PATTERNS will be +# used. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. INCLUDE_FILE_PATTERNS = -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. +# The PREDEFINED tag can be used to specify one or more macro names that are +# defined before the preprocessor is started (similar to the -D option of e.g. +# gcc). The argument of the tag is a list of macros of the form: name or +# name=definition (no spaces). If the definition and the "=" are omitted, "=1" +# is assumed. To prevent a macro definition from being undefined via #undef or +# recursively expanded use the := operator instead of the = operator. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. PREDEFINED = -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition. +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this +# tag can be used to specify a list of macro names that should be expanded. The +# macro definition that is found in the sources will be used. Use the PREDEFINED +# tag if you want to use a different macro definition that overrules the +# definition found in the source code. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. EXPAND_AS_DEFINED = -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse the -# parser if not removed. +# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will +# remove all references to function-like macros that are alone on a line, have +# an all uppercase name, and do not end with a semicolon. Such function macros +# are typically used for boiler-plate code, and will confuse the parser if not +# removed. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- -# Configuration::additions related to external references +# Configuration options related to external references #--------------------------------------------------------------------------- -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# TAGFILES = file1 file2 ... +# The TAGFILES tag can be used to specify one or more tag files. For each tag +# file the location of the external documentation should be added. The format of +# a tag file without this location is as follows: +# TAGFILES = file1 file2 ... # Adding location for the tag files is done as follows: -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where loc1 and loc2 can be relative or absolute paths or URLs. See the +# section "Linking to external documentation" for more information about the use +# of tag files. +# Note: Each tag file must have a unique name (where the name does NOT include +# the path). If a tag file is not located in the directory in which doxygen is +# run, you must also specify the path to the tagfile here. TAGFILES = -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. +# When a file name is specified after GENERATE_TAGFILE, doxygen will create a +# tag file that is based on the input files it reads. See section "Linking to +# external documentation" for more information about the usage of tag files. GENERATE_TAGFILE = -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. +# If the ALLEXTERNALS tag is set to YES all external class will be listed in the +# class index. If set to NO only the inherited external classes will be listed. +# The default value is: NO. ALLEXTERNALS = NO -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed in +# the modules index. If set to NO, only the current project's groups will be +# listed. +# The default value is: YES. EXTERNAL_GROUPS = YES +# If the EXTERNAL_PAGES tag is set to YES all external pages will be listed in +# the related pages index. If set to NO, only the current project's pages will +# be listed. +# The default value is: YES. + +EXTERNAL_PAGES = YES + # The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). +# interpreter (i.e. the result of 'which perl'). +# The default file (with absolute path) is: /usr/bin/perl. PERL_PATH = /usr/bin/perl @@ -1013,124 +2076,293 @@ PERL_PATH = /usr/bin/perl # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base or -# super classes. Setting the tag to NO turns the diagrams off. Note that this -# option is superseded by the HAVE_DOT option below. This is only a fallback. It is -# recommended to install and use dot, since it yields more powerful graphs. +# If the CLASS_DIAGRAMS tag is set to YES doxygen will generate a class diagram +# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to +# NO turns the diagrams off. Note that this option also works with HAVE_DOT +# disabled, but it is recommended to install and use dot, since it yields more +# powerful graphs. +# The default value is: YES. CLASS_DIAGRAMS = YES -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see: +# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# You can include diagrams made with dia in doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. + +DIA_PATH = + +# If set to YES, the inheritance and collaboration graphs will hide inheritance +# and usage relations if the target is undocumented or is not a class. +# The default value is: YES. HIDE_UNDOC_RELATIONS = YES # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) +# available from the path. This tool is part of Graphviz (see: +# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# Bell Labs. The other options in this section have no effect if this option is +# set to NO +# The default value is: NO. HAVE_DOT = YES -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# the CLASS_DIAGRAMS tag to NO. +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed +# to run in parallel. When set to 0 doxygen will base this on the number of +# processors available in the system. You can set it explicitly to a value +# larger than 0 to get control over the balance between CPU load and processing +# speed. +# Minimum value: 0, maximum value: 32, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_NUM_THREADS = 0 + +# When you want a differently looking font n the dot files that doxygen +# generates you can specify the font name using DOT_FONTNAME. You need to make +# sure dot is able to find the font, which can be done by putting it in a +# standard location or by setting the DOTFONTPATH environment variable or by +# setting DOT_FONTPATH to the directory containing the font. +# The default value is: Helvetica. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTNAME = Helvetica + +# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of +# dot graphs. +# Minimum value: 4, maximum value: 24, default value: 10. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the default font as specified with +# DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set +# the path where dot can find it using this tag. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTPATH = + +# If the CLASS_GRAPH tag is set to YES then doxygen will generate a graph for +# each documented class showing the direct and indirect inheritance relations. +# Setting this tag to YES will force the CLASS_DIAGRAMS tag to NO. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. CLASS_GRAPH = NO -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. +# If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a +# graph for each documented class showing the direct and indirect implementation +# dependencies (inheritance, containment, and class references variables) of the +# class with other documented classes. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. COLLABORATION_GRAPH = YES +# If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for +# groups, showing the direct groups dependencies. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +GROUP_GRAPHS = YES + # If the UML_LOOK tag is set to YES doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling # Language. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. UML_LOOK = NO -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. +# If the UML_LOOK tag is enabled, the fields and methods are shown inside the +# class node. If there are many fields or methods and many nodes the graph may +# become too big to be useful. The UML_LIMIT_NUM_FIELDS threshold limits the +# number of items for each type to make the size more manageable. Set this to 0 +# for no limit. Note that the threshold may be exceeded by 50% before the limit +# is enforced. So when you set the threshold to 10, up to 15 fields may appear, +# but if the number exceeds 15, the total amount of fields shown is limited to +# 10. +# Minimum value: 0, maximum value: 100, default value: 10. +# This tag requires that the tag HAVE_DOT is set to YES. + +UML_LIMIT_NUM_FIELDS = 10 + +# If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and +# collaboration graphs will show the relations between templates and their +# instances. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. TEMPLATE_RELATIONS = NO -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. +# If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to +# YES then doxygen will generate a graph for each documented file showing the +# direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. INCLUDE_GRAPH = NO -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. +# If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are +# set to YES then doxygen will generate a graph for each documented file showing +# the direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. INCLUDED_BY_GRAPH = YES -# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will -# generate a call dependency graph for every global function or class method. +# If the CALL_GRAPH tag is set to YES then doxygen will generate a call +# dependency graph for every global function or class method. +# # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable call graphs for selected # functions only using the \callgraph command. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. CALL_GRAPH = NO -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will graphical hierarchy of all classes instead of a textual one. +# If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller +# dependency graph for every global function or class method. +# +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable caller graphs for selected +# functions only using the \callergraph command. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical +# hierarchy of all classes instead of a textual one. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. GRAPHICAL_HIERARCHY = YES +# If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the +# dependencies a directory has on other directories in a graphical way. The +# dependency relations are determined by the #include relations between the +# files in the directories. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +DIRECTORY_GRAPH = YES + # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are png, jpg, or gif -# If left blank png will be used. +# generated by dot. +# Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order +# to make the SVG files visible in IE 9+ (other browsers do not have this +# requirement). +# Possible values are: png, jpg, gif and svg. +# The default value is: png. +# This tag requires that the tag HAVE_DOT is set to YES. DOT_IMAGE_FORMAT = png -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found on the path. +# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to +# enable generation of interactive SVG images that allow zooming and panning. +# +# Note that this requires a modern browser other than Internet Explorer. Tested +# and working are Firefox, Chrome, Safari, and Opera. +# Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make +# the SVG files visible. Older versions of IE do not have SVG support. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +INTERACTIVE_SVG = NO + +# The DOT_PATH tag can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. +# This tag requires that the tag HAVE_DOT is set to YES. DOT_PATH = # The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). +# contain dot files that are included in the documentation (see the \dotfile +# command). +# This tag requires that the tag HAVE_DOT is set to YES. DOTFILE_DIRS = -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes that -# lay further from the root node will be omitted. Note that setting this option to -# 1 or 2 may greatly reduce the computation time needed for large code bases. Also -# note that a graph may be further truncated if the graph's image dimensions are -# not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH and MAX_DOT_GRAPH_HEIGHT). -# If 0 is used for the depth value (the default), the graph is not depth-constrained. +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). + +MSCFILE_DIRS = + +# The DIAFILE_DIRS tag can be used to specify one or more directories that +# contain dia files that are included in the documentation (see the \diafile +# command). + +DIAFILE_DIRS = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes +# that will be shown in the graph. If the number of nodes in a graph becomes +# larger than this value, doxygen will truncate the graph, which is visualized +# by representing a node as a red box. Note that doxygen if the number of direct +# children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note that +# the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. +# Minimum value: 0, maximum value: 10000, default value: 50. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs +# generated by dot. A depth value of 3 means that only nodes reachable from the +# root by following a path via at most 3 edges will be shown. Nodes that lay +# further from the root node will be omitted. Note that setting this option to 1 +# or 2 may greatly reduce the computation time needed for large code bases. Also +# note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. +# Minimum value: 0, maximum value: 1000, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. MAX_DOT_GRAPH_DEPTH = 0 -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not seem +# to support this out of the box. +# +# Warning: Depending on the platform used, enabling this option may lead to +# badly anti-aliased labels on the edges of a graph (i.e. they become hard to +# read). +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. -GENERATE_LEGEND = YES +DOT_TRANSPARENT = NO -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) support +# this, this feature is disabled by default. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. -DOT_CLEANUP = YES +DOT_MULTI_TARGETS = NO -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- +# If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page +# explaining the meaning of the various boxes and arrows in the dot generated +# graphs. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +GENERATE_LEGEND = YES -# The SEARCHENGINE tag specifies whether or not a search engine should be -# used. If set to NO the values of all tags below this one will be ignored. +# If the DOT_CLEANUP tag is set to YES doxygen will remove the intermediate dot +# files that are used to generate the various graphs. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. -SEARCHENGINE = NO +DOT_CLEANUP = YES diff --git a/Doxyfile.help b/Doxyfile.help index f5ed20c6..97907414 100644 --- a/Doxyfile.help +++ b/Doxyfile.help @@ -1,911 +1,1932 @@ -# Doxyfile 1.3.9.1 +# Doxyfile 1.8.7 # This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project +# doxygen (www.doxygen.org) for a project. # -# All text after a hash (#) is considered a comment and will be ignored +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. # The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all text +# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv +# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv +# for the list of possible encodings. +# The default value is: UTF-8. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. PROJECT_NAME = fish -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. +# The PROJECT_NUMBER tag can be used to enter a project or revision number. This +# could be handy for archiving the generated documentation or if some version +# control system is used. PROJECT_NUMBER = @PACKAGE_VERSION@ -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify an logo or icon that is included in +# the documentation. The maximum height of the logo should not exceed 55 pixels +# and the maximum width should not exceed 200 pixels. Doxygen will copy the logo +# to the output directory. + +PROJECT_LOGO = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path +# into which the generated documentation will be written. If a relative path is +# entered, it will be relative to the location where doxygen was started. If +# left blank the current directory will be used. OUTPUT_DIRECTORY = help_doc -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of source -# files, where putting all generated files in the same directory would otherwise -# cause performance problems for the file system. +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub- +# directories (in 2 levels) under the output directory of each output format and +# will distribute the generated files over these directories. Enabling this +# option can be useful when feeding doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise causes +# performance problems for the file system. +# The default value is: NO. CREATE_SUBDIRS = NO +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, -# Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese, -# Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian, -# Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, -# Swedish, and Ukrainian. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. +# The default value is: English. OUTPUT_LANGUAGE = English -# This tag can be used to specify the encoding used in the generated output. -# The encoding is not always determined by the language that is chosen, -# but also whether or not the output is meant for Windows or non-Windows users. -# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES -# forces the Windows encoding (this is the default for the Windows binary), -# whereas setting the tag to NO uses a Unix-style encoding (the default for -# all platforms other than Windows). - -USE_WINDOWS_ENCODING = NO - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. +# If the BRIEF_MEMBER_DESC tag is set to YES doxygen will include brief member +# descriptions after the members that are listed in the file and class +# documentation (similar to Javadoc). Set to NO to disable this. +# The default value is: YES. BRIEF_MEMBER_DESC = YES -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief +# description of a member or function before the detailed description +# +# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. +# The default value is: YES. REPEAT_BRIEF = YES -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is used -# as the annotated text. Otherwise, the brief description is used as-is. If left -# blank, the following values are used ("$name" is automatically replaced with the -# name of the entity): "The $name class" "The $name widget" "The $name file" -# "is" "provides" "specifies" "contains" "represents" "a" "an" "the" +# This tag implements a quasi-intelligent brief description abbreviator that is +# used to form the text in various listings. Each string in this list, if found +# as the leading text of the brief description, will be stripped from the text +# and the result, after processing the whole list, is used as the annotated +# text. Otherwise, the brief description is used as-is. If left blank, the +# following values are used ($name is automatically replaced with the name of +# the entity):The $name class, The $name widget, The $name file, is, provides, +# specifies, contains, represents, a, an and the. ABBREVIATE_BRIEF = YES # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief +# doxygen will generate a detailed section even if there is only a brief # description. +# The default value is: NO. ALWAYS_DETAILED_SEC = NO -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited -# members of a class in the documentation of that class as if those members were -# ordinary class members. Constructors, destructors and assignment operators of -# the base classes will not be shown. +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. +# The default value is: NO. INLINE_INHERITED_MEMB = NO -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. +# If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path +# before files name in the file list and in the header files. If set to NO the +# shortest path that makes the file name unique will be used +# The default value is: YES. FULL_PATH_NAMES = YES -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand +# part of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to +# strip. +# +# Note that you can specify absolute paths here, but also relative paths, which +# will be relative from the directory where doxygen is started. +# This tag requires that the tag FULL_PATH_NAMES is set to YES. STRIP_FROM_PATH = -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the +# path mentioned in the documentation of a class, which tells the reader which +# header file to include in order to use a class. If left blank only the name of +# the header file containing the class definition is used. Otherwise one should +# specify the list of include paths that are normally passed to the compiler +# using the -I flag. STRIP_FROM_INC_PATH = -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but +# less readable) file names. This can be useful is your file systems doesn't +# support long names like on DOS, Mac, or CD-ROM. +# The default value is: NO. SHORT_NAMES = NO -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like the Qt-style comments (thus requiring an -# explicit @brief command for a brief description. +# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the +# first line (until the first dot) of a Javadoc-style comment as the brief +# description. If set to NO, the Javadoc-style will behave just like regular Qt- +# style comments (thus requiring an explicit @brief command for a brief +# description.) +# The default value is: NO. JAVADOC_AUTOBRIEF = YES -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. +# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first +# line (until the first dot) of a Qt-style comment as the brief description. If +# set to NO, the Qt-style will behave just like regular Qt-style comments (thus +# requiring an explicit \brief command for a brief description.) +# The default value is: NO. -MULTILINE_CPP_IS_BRIEF = NO +QT_AUTOBRIEF = NO -# If the DETAILS_AT_TOP tag is set to YES then Doxygen -# will output the detailed description near the top, like JavaDoc. -# If set to NO, the detailed description appears after the member -# documentation. +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# multi-line C++ special comment block (i.e. a block of //! or /// comments) as +# a brief description. This used to be the default behavior. The new default is +# to treat a multi-line C++ comment block as a detailed description. Set this +# tag to YES if you prefer the old behavior instead. +# +# Note that setting this tag to YES also means that rational rose comments are +# not recognized any more. +# The default value is: NO. -DETAILS_AT_TOP = NO +MULTILINE_CPP_IS_BRIEF = NO -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. +# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the +# documentation from any documented member that it re-implements. +# The default value is: YES. INHERIT_DOCS = YES -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce a +# new page for each member. If set to NO, the documentation of a member will be +# part of the file/class/namespace that contains it. +# The default value is: NO. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen +# uses this value to replace tabs by spaces in code fragments. +# Minimum value: 1, maximum value: 16, default value: 4. + +TAB_SIZE = 4 + +# This tag can be used to specify a number of aliases that act as commands in +# the documentation. An alias has the form: +# name=value +# For example adding +# "sideeffect=@par Side Effects:\n" +# will allow you to put the command \sideeffect (or @sideeffect) in the +# documentation, which will result in a user-defined paragraph with heading +# "Side Effects:". You can put \n's in the value part of an alias to insert +# newlines. + +# Simplify Fish output from Doxygen for man pages. (see lexicon_filter.in) + +ALIASES = "key{1}=[<b>\1</b>]" +ALIASES += "key{2}=[<b>\1</b>-<em>\2</em>]" +ALIASES += "key{3}=[<b>\1</b>-<em>\3</em>]" +ALIASES += "cursor_key{2}=[<b>\2</b>]" + +ALIASES += "fish=<pre>" +ALIASES += "fish{1}=<pre>" +ALIASES += "endfish=</pre>" + +ALIASES += "asis{1}=\1" +ALIASES += "outp{1}=\1" +ALIASES += "blah{1}= \1" +ALIASES += "bltn{1}=<b>\1</b>" +ALIASES += "func{1}=<b>\1</b>" +ALIASES += "cmnd{1}=<b>\1</b>" +ALIASES += "args{1}=\1" +ALIASES += "opts{1}=\1" +ALIASES += "vars{1}=\1" +ALIASES += "optr{1}=\1" +ALIASES += "redr{1}=\1" +ALIASES += "fsfo{1}=\1" +ALIASES += "path{1}=\1" +ALIASES += "clrv{1}=\1" + +ALIASES += "strg{1}=\1" +ALIASES += "sglq{1}='\1'" +ALIASES += "dblq{1}=\"\1\"" + +ALIASES += "prmt=>" +ALIASES += "prmt{1}=\1>" +ALIASES += "sgst{1}=\1" +ALIASES += "mtch{1}=<em>\1</em>" +ALIASES += "smtc{1}=<em>\1</em>" +ALIASES += "eror{1}=<b>\1</b>" +ALIASES += "curs=_" +ALIASES += "curs{1}=\1" + +ALIASES += "bold{1}=<b>\1</b>" +ALIASES += "emph{1}=<em>\1</em>" +ALIASES += "undr{1}=<em>\1</em>" +ALIASES += "span{2}=\2" +ALIASES += "spcl{2}=\2" + +ALIASES += "bksl{1}=\\\1" + +# This tag can be used to specify a number of word-keyword mappings (TCL only). +# A mapping has the form "name=value". For example adding "class=itcl::class" +# will allow you to use the command class in the itcl::class meaning. + +TCL_SUBST = -DISTRIBUTE_GROUP_DOC = NO +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. For +# instance, some of the names that are used will be different. The list of all +# members will be omitted, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_FOR_C = NO -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or +# Python sources only. Doxygen will then generate output that is more tailored +# for that language. For instance, namespaces will be presented as packages, +# qualified scopes will look different, etc. +# The default value is: NO. -TAB_SIZE = 8 +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources. Doxygen will then generate output that is tailored for Fortran. +# The default value is: NO. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for VHDL. +# The default value is: NO. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, Javascript, +# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: +# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: +# Fortran. In the later case the parser tries to guess whether the code is fixed +# or free formatted code, this is the default for Fortran type files), VHDL. For +# instance to make doxygen treat .inc files as Fortran files (default is PHP), +# and .f files as C (default is Fortran), use: inc=Fortran f=C. +# +# Note For files without extension you can use no_extension as a placeholder. +# +# Note that for custom extensions you also need to set FILE_PATTERNS otherwise +# the files are not read by doxygen. -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. +EXTENSION_MAPPING = -ALIASES = +# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# according to the Markdown format, which allows for more readable +# documentation. See http://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you can +# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# case of backward compatibilities issues. +# The default value is: YES. -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources -# only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. +MARKDOWN_SUPPORT = YES -OPTIMIZE_OUTPUT_FOR_C = YES +# When enabled doxygen tries to link words that correspond to documented +# classes, or namespaces to their corresponding documentation. Such a link can +# be prevented in individual cases by by putting a % sign in front of the word +# or globally by setting AUTOLINK_SUPPORT to NO. +# The default value is: YES. -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources -# only. Doxygen will then generate output that is more tailored for Java. -# For instance, namespaces will be presented as packages, qualified scopes -# will look different, etc. +AUTOLINK_SUPPORT = YES -OPTIMIZE_OUTPUT_JAVA = NO +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should set this +# tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); +# versus func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. +# The default value is: NO. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. +# The default value is: NO. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: +# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen +# will parse them like normal C++ but will assume all classes use public instead +# of private inheritance when no explicit protection keyword is present. +# The default value is: NO. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES will make +# doxygen to replace the get and set methods by a property in the documentation. +# This will only work if the methods are indeed getting or setting a simple +# type. If this is not the case, or you want to show the methods anyway, you +# should set this option to NO. +# The default value is: YES. -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. +# The default value is: NO. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES to allow class member groups of the same type +# (for instance a group of public functions) to be put as a subgroup of that +# type (e.g. under the Public Functions section). Set it to NO to prevent +# subgrouping. Alternatively, this can be done per class using the +# \nosubgrouping command. +# The default value is: YES. SUBGROUPING = YES +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions +# are shown inside the group in which they are included (e.g. using \ingroup) +# instead of on a separate page (for HTML and Man pages) or section (for LaTeX +# and RTF). +# +# Note that this feature does not work in combination with +# SEPARATE_MEMBER_PAGES. +# The default value is: NO. + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions +# with only public data fields or simple typedef fields will be shown inline in +# the documentation of the scope in which they are defined (i.e. file, +# namespace, or group documentation), provided this scope is documented. If set +# to NO, structs, classes, and unions are shown on a separate page (for HTML and +# Man pages) or section (for LaTeX and RTF). +# The default value is: NO. + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or +# enum is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically be +# useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. +# The default value is: NO. + +TYPEDEF_HIDES_STRUCT = NO + +# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This +# cache is used to resolve symbols given their name and scope. Since this can be +# an expensive process and often the same symbol appears multiple times in the +# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# doxygen will become slower. If the cache is too large, memory is wasted. The +# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range +# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 +# symbols. At the end of a run doxygen will report the cache usage and suggest +# the optimal cache size from a speed point of view. +# Minimum value: 0, maximum value: 9, default value: 0. + +LOOKUP_CACHE_SIZE = 0 + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES +# documentation are documented, even if no documentation was available. Private +# class members and static file members will be hidden unless the +# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. +# Note: This will also disable the warnings about undocumented members that are +# normally produced when WARNINGS is set to YES. +# The default value is: NO. EXTRACT_ALL = NO -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class will +# be included in the documentation. +# The default value is: NO. EXTRACT_PRIVATE = NO -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. +# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal +# scope will be included in the documentation. +# The default value is: NO. + +EXTRACT_PACKAGE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file will be +# included in the documentation. +# The default value is: NO. EXTRACT_STATIC = NO -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO +# only classes defined in header files are included. Does not have any effect +# for Java sources. +# The default value is: YES. EXTRACT_LOCAL_CLASSES = YES -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. +# This flag is only useful for Objective-C code. When set to YES local methods, +# which are defined in the implementation section but not in the interface are +# included in the documentation. If set to NO only methods in the interface are +# included. +# The default value is: NO. EXTRACT_LOCAL_METHODS = NO -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base name of +# the file that contains the anonymous namespace. By default anonymous namespace +# are hidden. +# The default value is: NO. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# undocumented members inside documented classes or files. If set to NO these +# members will be included in the various overviews, but no documentation +# section is generated. This option has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. HIDE_UNDOC_MEMBERS = NO -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. +# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. If set +# to NO these classes will be included in the various overviews. This option has +# no effect if EXTRACT_ALL is enabled. +# The default value is: NO. HIDE_UNDOC_CLASSES = NO -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# (class|struct|union) declarations. If set to NO these declarations will be +# included in the documentation. +# The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. +# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# documentation blocks found inside the body of a function. If set to NO these +# blocks will be appended to the function's detailed documentation block. +# The default value is: NO. HIDE_IN_BODY_DOCS = NO -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. +# The INTERNAL_DOCS tag determines if documentation that is typed after a +# \internal command is included. If the tag is set to NO then the documentation +# will be excluded. Set it to YES to include the internal documentation. +# The default value is: NO. INTERNAL_DOCS = NO -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also +# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file +# names in lower-case letters. If set to YES upper-case letters are also # allowed. This is useful if you have classes or files whose names only differ # in case and if your file system supports case sensitive file names. Windows # and Mac users are advised to set this option to NO. +# The default value is: system dependent. CASE_SENSE_NAMES = YES -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. +# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# their full class and namespace scopes in the documentation. If set to YES the +# scope will be hidden. +# The default value is: NO. HIDE_SCOPE_NAMES = NO -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. +# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# the files that are included by a file in the documentation of that file. +# The default value is: YES. SHOW_INCLUDE_FILES = YES -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# files with double quotes in the documentation rather than with sharp brackets. +# The default value is: NO. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the +# documentation for inline members. +# The default value is: YES. INLINE_INFO = YES -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. +# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# (detailed) documentation of file and class members alphabetically by member +# name. If set to NO the members will appear in declaration order. +# The default value is: YES. SORT_MEMBER_DOCS = YES -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# descriptions of file, namespace and class members alphabetically by member +# name. If set to NO the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. +# The default value is: NO. SORT_BRIEF_DOCS = NO -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# (brief and detailed) documentation of class members so that constructors and +# destructors are listed first. If set to NO the constructors will appear in the +# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. +# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief +# member documentation. +# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting +# detailed member documentation. +# The default value is: NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# of group names into alphabetical order. If set to NO the group names will +# appear in their defined order. +# The default value is: NO. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by +# fully-qualified names, including namespaces. If set to NO, the class list will +# be sorted only by class name, not including the namespace part. # Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. +# Note: This option applies only to the class list, not to the alphabetical +# list. +# The default value is: NO. SORT_BY_SCOPE_NAME = NO -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# type resolution of all parameters of a function it will reject a match between +# the prototype and the implementation of a member function even if there is +# only one candidate or it is obvious which candidate to choose by doing a +# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# accept a match between prototype and implementation in such cases. +# The default value is: NO. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable ( YES) or disable ( NO) the +# todo list. This list is created by putting \todo commands in the +# documentation. +# The default value is: YES. GENERATE_TODOLIST = YES -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. +# The GENERATE_TESTLIST tag can be used to enable ( YES) or disable ( NO) the +# test list. This list is created by putting \test commands in the +# documentation. +# The default value is: YES. GENERATE_TESTLIST = YES -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. +# The GENERATE_BUGLIST tag can be used to enable ( YES) or disable ( NO) the bug +# list. This list is created by putting \bug commands in the documentation. +# The default value is: YES. GENERATE_BUGLIST = YES -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. +# The GENERATE_DEPRECATEDLIST tag can be used to enable ( YES) or disable ( NO) +# the deprecated list. This list is created by putting \deprecated commands in +# the documentation. +# The default value is: YES. GENERATE_DEPRECATEDLIST= YES -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. +# The ENABLED_SECTIONS tag can be used to enable conditional documentation +# sections, marked by \if <section_label> ... \endif and \cond <section_label> +# ... \endcond blocks. ENABLED_SECTIONS = -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the +# initial value of a variable or macro / define can have for it to appear in the +# documentation. If the initializer consists of more lines than specified here +# it will be hidden. Use a value of 0 to hide initializers completely. The +# appearance of the value of individual variables and macros / defines can be +# controlled using \showinitializer or \hideinitializer command in the +# documentation regardless of this setting. +# Minimum value: 0, maximum value: 10000, default value: 30. MAX_INITIALIZER_LINES = 30 -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at +# the bottom of the documentation of classes and structs. If set to YES the list +# will mention the files that were used to generate the documentation. +# The default value is: YES. SHOW_USED_FILES = YES -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This +# will remove the Files entry from the Quick Index and from the Folder Tree View +# (if specified). +# The default value is: YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces +# page. This will remove the Namespaces entry from the Quick Index and from the +# Folder Tree View (if specified). +# The default value is: YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command command input-file, where command is the value of the +# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided +# by doxygen. Whatever the program writes to standard output is used as the file +# version. For an example see the documentation. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. You can +# optionally specify a file name after the option, if omitted DoxygenLayout.xml +# will be used as the name of the layout file. +# +# Note that if you run doxygen from a directory containing a file called +# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# tag is left empty. + +LAYOUT_FILE = + +# The CITE_BIB_FILES tag can be used to specify one or more bib files containing +# the reference definitions. This must be a list of .bib files. The .bib +# extension is automatically appended if omitted. This requires the bibtex tool +# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. +# For LaTeX the style of the bibliography can be controlled using +# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the +# search path. Do not use file names with spaces, bibtex cannot handle them. See +# also \cite for info how to create references. -SHOW_DIRECTORIES = YES +CITE_BIB_FILES = #--------------------------------------------------------------------------- -# configuration options related to warning and progress messages +# Configuration options related to warning and progress messages #--------------------------------------------------------------------------- -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. +# The QUIET tag can be used to turn on/off the messages that are generated to +# standard output by doxygen. If QUIET is set to YES this implies that the +# messages are off. +# The default value is: NO. QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. +# generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES +# this implies that the warnings are on. +# +# Tip: Turn warnings on while writing the documentation. +# The default value is: YES. WARNINGS = YES -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. +# If the WARN_IF_UNDOCUMENTED tag is set to YES, then doxygen will generate +# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: YES. WARN_IF_UNDOCUMENTED = YES -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. +# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some parameters +# in a documented function, or documenting parameters that don't exist or using +# markup commands wrongly. +# The default value is: YES. WARN_IF_DOC_ERROR = YES -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. +# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that +# are documented, but have no documentation for their parameters or return +# value. If set to NO doxygen will only warn about wrong or incomplete parameter +# documentation, but not about the absence of documentation. +# The default value is: NO. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# can produce. The string should contain the $file, $line, and $text tags, which +# will be replaced by the file and line number from which the warning originated +# and the warning text. Optionally the format may contain $version, which will +# be replaced by the version of the file (if it could be obtained via +# FILE_VERSION_FILTER) +# The default value is: $file:$line: $text. WARN_FORMAT = "$file:$line: $text" -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. +# The WARN_LOGFILE tag can be used to specify a file to which warning and error +# messages should be written. If left blank the output is written to standard +# error (stderr). WARN_LOGFILE = #--------------------------------------------------------------------------- -# configuration options related to the input files +# Configuration options related to the input files #--------------------------------------------------------------------------- -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. +# The INPUT tag is used to specify the files and/or directories that contain +# documented source files. You may enter file names like myfile.cpp or +# directories like /usr/src/myproject. Separate the files or directories with +# spaces. +# Note: If this tag is empty the current directory is searched. INPUT = doc_src +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# libiconv (or the iconv built into libc) for the transcoding. See the libiconv +# documentation (see: http://www.gnu.org/software/libiconv) for the list of +# possible encodings. +# The default value is: UTF-8. + +INPUT_ENCODING = UTF-8 + # If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp -# *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm +# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank the +# following patterns are tested:*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii, +# *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, +# *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, +# *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, +# *.qsf, *.as and *.js. FILE_PATTERNS = *.doxygen -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. RECURSIVE = NO -# The EXCLUDE tag can be used to specify files and/or directories that should +# The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. EXCLUDE = -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories -# that are symbolic links (a Unix filesystem feature) are excluded from the input. +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. +# The default value is: NO. EXCLUDE_SYMLINKS = NO # If the value of the INPUT tag contains directories, you can use the # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude # certain files from those directories. +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories for example use the pattern */test/* EXCLUDE_PATTERNS = -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories use the pattern */test/* + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or directories +# that contain example code fragments that are included (see the \include +# command). EXAMPLE_PATH = # If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank all +# files are included. EXAMPLE_PATTERNS = # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. +# searched for input files to be used with the \include or \dontinclude commands +# irrespective of the value of the RECURSIVE tag. +# The default value is: NO. EXAMPLE_RECURSIVE = NO -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). +# The IMAGE_PATH tag can be used to specify one or more files or directories +# that contain images that are to be included in the documentation (see the +# \image command). IMAGE_PATH = # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command <filter> <input-file>, where <filter> -# is the value of the INPUT_FILTER tag, and <input-file> is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. If FILTER_PATTERNS is specified, this tag will be -# ignored. +# by executing (via popen()) the command: +# +# <filter> <input-file> +# +# where <filter> is the value of the INPUT_FILTER tag, and <input-file> is the +# name of an input file. Doxygen will then use the output that the filter +# program writes to standard output. If FILTER_PATTERNS is specified, this tag +# will be ignored. +# +# Note that the filter must not add or remove lines; it is applied before the +# code is scanned, but not when the output code is generated. If lines are added +# or removed, the anchors will not be placed correctly. INPUT_FILTER = # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: pattern=filter +# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how +# filters are used. If the FILTER_PATTERNS tag is empty or if none of the +# patterns match the file name, INPUT_FILTER is applied. FILTER_PATTERNS = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). +# INPUT_FILTER ) will also be used to filter the input files that are used for +# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). +# The default value is: NO. FILTER_SOURCE_FILES = NO +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. + +FILTER_SOURCE_PATTERNS = + +# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that +# is part of the input, its contents will be placed on the main page +# (index.html). This can be useful if you have a project on for instance GitHub +# and want to reuse the introduction page also for the doxygen output. + +USE_MDFILE_AS_MAINPAGE = + #--------------------------------------------------------------------------- -# configuration options related to source browsing +# Configuration options related to source browsing #--------------------------------------------------------------------------- -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. +# If the SOURCE_BROWSER tag is set to YES then a list of source files will be +# generated. Documented entities will be cross-referenced with these sources. +# +# Note: To get rid of all source code in the generated output, make sure that +# also VERBATIM_HEADERS is set to NO. +# The default value is: NO. SOURCE_BROWSER = NO -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. +# Setting the INLINE_SOURCES tag to YES will include the body of functions, +# classes and enums directly into the documentation. +# The default value is: NO. INLINE_SOURCES = NO -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# special comment blocks from generated source code fragments. Normal C, C++ and +# Fortran comments will always remain visible. +# The default value is: YES. STRIP_CODE_COMMENTS = YES -# If the REFERENCED_BY_RELATION tag is set to YES (the default) -# then for each documented function all documented -# functions referencing it will be listed. +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# function all documented functions referencing it will be listed. +# The default value is: NO. REFERENCED_BY_RELATION = YES -# If the REFERENCES_RELATION tag is set to YES (the default) -# then for each documented function all documented entities -# called/used by that function will be listed. +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. REFERENCES_RELATION = YES -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. +# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set +# to YES, then the hyperlinks from functions in REFERENCES_RELATION and +# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will +# link to the documentation. +# The default value is: YES. + +REFERENCES_LINK_SOURCE = YES + +# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the +# source code will show a tooltip with additional information such as prototype, +# brief description and links to the definition and documentation. Since this +# will make the HTML file larger and loading of large files a bit slower, you +# can opt to disable this feature. +# The default value is: YES. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +SOURCE_TOOLTIPS = YES + +# If the USE_HTAGS tag is set to YES then the references to source code will +# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# source browser. The htags tool is part of GNU's global source tagging system +# (see http://www.gnu.org/software/global/global.html). You will need version +# 4.8.6 or higher. +# +# To use it do the following: +# - Install the latest version of global +# - Enable SOURCE_BROWSER and USE_HTAGS in the config file +# - Make sure the INPUT points to the root of the source tree +# - Run doxygen as normal +# +# Doxygen will invoke htags (and that will in turn invoke gtags), so these +# tools must be available from the command line (i.e. in the search path). +# +# The result: instead of the source browser generated by doxygen, the links to +# source code will now point to the output of htags. +# The default value is: NO. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# verbatim copy of the header file for each class for which an include is +# specified. Set to NO to disable this. +# See also: Section \class. +# The default value is: YES. VERBATIM_HEADERS = YES #--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index +# Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all +# compounds will be generated. Enable this if the project contains a lot of +# classes, structs, unions or interfaces. +# The default value is: YES. ALPHABETICAL_INDEX = NO -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) +# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in +# which the alphabetical index list will be split. +# Minimum value: 1, maximum value: 20, default value: 5. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. COLS_IN_ALPHA_INDEX = 5 -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. +# In case all classes in a project start with a common prefix, all classes will +# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag +# can be used to specify a prefix (or a list of prefixes) that should be ignored +# while generating the index headers. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. IGNORE_PREFIX = #--------------------------------------------------------------------------- -# configuration options related to the HTML output +# Configuration options related to the HTML output #--------------------------------------------------------------------------- -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. +# If the GENERATE_HTML tag is set to YES doxygen will generate HTML output +# The default value is: YES. GENERATE_HTML = NO -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: html. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_OUTPUT = html -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each +# generated HTML page (for example: .htm, .php, .asp). +# The default value is: .html. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_FILE_EXTENSION = .html -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a +# The HTML_HEADER tag can be used to specify a user-defined HTML header file for +# each generated HTML page. If the tag is left blank doxygen will generate a # standard header. +# +# To get valid HTML the header file that includes any scripts and style sheets +# that doxygen needs, which is dependent on the configuration options used (e.g. +# the setting GENERATE_TREEVIEW). It is highly recommended to start with a +# default header using +# doxygen -w html new_header.html new_footer.html new_stylesheet.css +# YourConfigFile +# and then modify the file new_header.html. See also section "Doxygen usage" +# for information on how to generate the default header that doxygen normally +# uses. +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. For a description +# of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_HEADER = -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. +# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each +# generated HTML page. If the tag is left blank doxygen will generate a standard +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_FOOTER = -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style +# sheet that is used by each HTML page. It can be used to fine-tune the look of +# the HTML output. If left blank doxygen will generate a default style sheet. +# See also section "Doxygen usage" for information on how to generate the style +# sheet that doxygen normally uses. +# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as +# it is more robust and this tag (HTML_STYLESHEET) will in the future become +# obsolete. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_STYLESHEET = -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) -# of the generated HTML documentation. +# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional user- +# defined cascading style sheet that is included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefor more robust against future updates. +# Doxygen will copy the style sheet file to the output directory. For an example +# see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_STYLESHEET = + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that the +# files will be copied as-is; there are no commands or markers available. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen +# will adjust the colors in the stylesheet and background images according to +# this color. Hue is specified as an angle on a colorwheel, see +# http://en.wikipedia.org/wiki/Hue for more information. For instance the value +# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 +# purple, and 360 is red again. +# Minimum value: 0, maximum value: 359, default value: 220. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors +# in the HTML output. For a value of 0 the output will use grayscales only. A +# value of 255 will produce the most vivid colors. +# Minimum value: 0, maximum value: 255, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the +# luminance component of the colors in the HTML output. Values below 100 +# gradually make the output lighter, whereas values above 100 make the output +# darker. The value divided by 100 is the actual gamma applied, so 80 represents +# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not +# change the gamma. +# Minimum value: 40, maximum value: 240, default value: 80. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting this +# to NO can help when comparing the output of multiple runs. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_TIMESTAMP = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_SECTIONS = NO + +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries +# shown in the various tree structured indices initially; the user can expand +# and collapse entries dynamically later on. Doxygen will expand the tree to +# such a level that at most the specified number of entries are visible (unless +# a fully collapsed tree already exceeds this amount). So setting the number of +# entries 1 will produce a full collapsed tree by default. 0 is a special value +# representing an infinite number of entries and will result in a full expanded +# tree by default. +# Minimum value: 0, maximum value: 9999, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files will be +# generated that can be used as input for Apple's Xcode 3 integrated development +# environment (see: http://developer.apple.com/tools/xcode/), introduced with +# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a +# Makefile in the HTML output directory. Running make will produce the docset in +# that directory and running make install will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at +# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_DOCSET = NO + +# This tag determines the name of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# The default value is: Doxygen generated docs. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# This tag specifies a string that should uniquely identify the documentation +# set bundle. This should be a reverse domain-name style string, e.g. +# com.mycompany.MyDocSet. Doxygen will append .docset to the name. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. +# The default value is: org.doxygen.Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. +# The default value is: Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# additional HTML index files: index.hhp, index.hhc, and index.hhk. The +# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop +# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on +# Windows. +# +# The HTML Help Workshop contains a compiler that can convert all HTML output +# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# files are now used as the Windows 98 help format, and will replace the old +# Windows help format (.hlp) on all Windows platforms in the future. Compressed +# HTML files also contain an index, a table of contents, and you can search for +# words in the documentation. The HTML workshop also contains a viewer for +# compressed HTML files. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_HTMLHELP = NO -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be +# The CHM_FILE tag can be used to specify the file name of the resulting .chm +# file. You can add a path in front of the file if the result should not be # written to the html output directory. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_FILE = -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. +# The HHC_LOCATION tag can be used to specify the location (absolute path +# including file name) of the HTML help compiler ( hhc.exe). If non-empty +# doxygen will try to run the HTML help compiler on the generated index.hhp. +# The file has to be specified with full path. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. HHC_LOCATION = -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). +# The GENERATE_CHI flag controls if a separate .chi index file is generated ( +# YES) or that it should be included in the master .chm file ( NO). +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. GENERATE_CHI = NO -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index ( hhk), content ( hhc) +# and project file content. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_INDEX_ENCODING = + +# The BINARY_TOC flag controls whether a binary table of contents is generated ( +# YES) or a normal table of contents ( NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. BINARY_TOC = NO -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. +# The TOC_EXPAND flag can be set to YES to add extra items for group members to +# the table of contents of the HTML help documentation and to the tree view. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. TOC_EXPAND = NO -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that +# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help +# (.qch) of the generated HTML documentation. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify +# the file name of the resulting .qch file. The path specified is relative to +# the HTML output folder. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help +# Project output. For more information please see Qt Help Project / Namespace +# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt +# Help Project output. For more information please see Qt Help Project / Virtual +# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- +# folders). +# The default value is: doc. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_VIRTUAL_FOLDER = doc + +# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom +# filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's filter section matches. Qt Help Project / Filter Attributes (see: +# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_SECT_FILTER_ATTRS = + +# The QHG_LOCATION tag can be used to specify the location of Qt's +# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the +# generated .qhp file. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be +# generated, together with the HTML files, they form an Eclipse help plugin. To +# install this plugin and make it available under the help contents menu in +# Eclipse, the contents of the directory containing the HTML and XML files needs +# to be copied into the plugins directory of eclipse. The name of the directory +# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. +# After copying Eclipse needs to be restarted before the help appears. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the Eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have this +# name. Each documentation set should have its own identifier. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# If you want full control over the layout of the generated HTML pages it might +# be necessary to disable the index and replace it with your own. The +# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top +# of each HTML page. A value of NO enables the index and the value YES disables +# it. Since the tabs in the index contain the same information as the navigation +# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. DISABLE_INDEX = NO -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. If the tag +# value is set to YES, a side panel will be generated containing a tree-like +# index structure (just like the one that is generated for HTML Help). For this +# to work a browser that supports JavaScript, DHTML, CSS and frames is required +# (i.e. any modern browser). Windows users are probably better off using the +# HTML help feature. Via custom stylesheets (see HTML_EXTRA_STYLESHEET) one can +# further fine-tune the look of the index. As an example, the default style +# sheet generated by doxygen has an example that shows how to put an image at +# the root of the tree instead of the PROJECT_NAME. Since the tree basically has +# the same information as the tab index, you could consider setting +# DISABLE_INDEX to YES when enabling this option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. -ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO -# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be -# generated containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, -# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are -# probably better off using the HTML help feature. +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that +# doxygen will group on one line in the generated HTML documentation. +# +# Note that a value of 0 will completely suppress the enum values from appearing +# in the overview section. +# Minimum value: 0, maximum value: 20, default value: 4. +# This tag requires that the tag GENERATE_HTML is set to YES. -GENERATE_TREEVIEW = NO +ENUM_VALUES_PER_LINE = 4 -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used +# to set the initial width (in pixels) of the frame in which the tree is shown. +# Minimum value: 0, maximum value: 1500, default value: 250. +# This tag requires that the tag GENERATE_HTML is set to YES. TREEVIEW_WIDTH = 250 +# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open links to +# external symbols imported via tag files in a separate window. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of LaTeX formulas included as images in +# the HTML documentation. When you change the font size after a successful +# doxygen run you need to manually remove any form_*.png images from the HTML +# output directory to force them to be regenerated. +# Minimum value: 8, maximum value: 50, default value: 10. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are not +# supported properly for IE 6.0, but are supported on all modern browsers. +# +# Note that when changing this option you need to delete any form_*.png files in +# the HTML output directory before the changes have effect. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_TRANSPARENT = YES + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see +# http://www.mathjax.org) which uses client side Javascript for the rendering +# instead of using prerendered bitmaps. Use this if you do not have LaTeX +# installed or if you want to formulas look prettier in the HTML output. When +# enabled you may also need to install MathJax separately and configure the path +# to it using the MATHJAX_RELPATH option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +USE_MATHJAX = NO + +# When MathJax is enabled you can set the default output format to be used for +# the MathJax output. See the MathJax site (see: +# http://docs.mathjax.org/en/latest/output.html) for more details. +# Possible values are: HTML-CSS (which is slower, but has the best +# compatibility), NativeMML (i.e. MathML) and SVG. +# The default value is: HTML-CSS. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_FORMAT = HTML-CSS + +# When MathJax is enabled you need to specify the location relative to the HTML +# output directory using the MATHJAX_RELPATH option. The destination directory +# should contain the MathJax.js script. For instance, if the mathjax directory +# is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax +# Content Delivery Network so you can quickly see the result without installing +# MathJax. However, it is strongly recommended to install a local copy of +# MathJax from http://www.mathjax.org before deployment. +# The default value is: http://cdn.mathjax.org/mathjax/latest. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest + +# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax +# extension names that should be enabled during MathJax rendering. For example +# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_EXTENSIONS = + +# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# of code that will be used on startup of the MathJax code. See the MathJax site +# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# example see the documentation. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_CODEFILE = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for +# the HTML output. The underlying search engine uses javascript and DHTML and +# should work on any modern browser. Note that when using HTML help +# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) +# there is already a search function so this one should typically be disabled. +# For large projects the javascript based search engine can be slow, then +# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to +# search using the keyboard; to jump to the search box use <access key> + S +# (what the <access key> is depends on the OS and browser, but it is typically +# <CTRL>, <ALT>/<option>, or both). Inside the search box use the <cursor down +# key> to jump into the search results window, the results can be navigated +# using the <cursor keys>. Press <Enter> to select an item or <escape> to cancel +# the search. The filter options can be selected when the cursor is inside the +# search box by pressing <Shift>+<cursor down>. Also here use the <cursor keys> +# to select a filter and <Enter> or <escape> to activate or cancel the filter +# option. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +SEARCHENGINE = NO + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a web server instead of a web client using Javascript. There +# are two flavors of web server based searching depending on the EXTERNAL_SEARCH +# setting. When disabled, doxygen will generate a PHP script for searching and +# an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing +# and searching needs to be provided by external tools. See the section +# "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SERVER_BASED_SEARCH = NO + +# When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP +# script for searching. Instead the search results are written to an XML file +# which needs to be processed by an external indexer. Doxygen will invoke an +# external search engine pointed to by the SEARCHENGINE_URL option to obtain the +# search results. +# +# Doxygen ships with an example indexer ( doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: http://xapian.org/). +# +# See the section "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH = NO + +# The SEARCHENGINE_URL should point to a search engine hosted by a web server +# which will return the search results when EXTERNAL_SEARCH is enabled. +# +# Doxygen ships with an example indexer ( doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: http://xapian.org/). See the section "External Indexing and +# Searching" for details. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHENGINE_URL = + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed +# search data is written to a file for indexing by an external tool. With the +# SEARCHDATA_FILE tag the name of this file can be specified. +# The default file is: searchdata.xml. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHDATA_FILE = searchdata.xml + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the +# EXTERNAL_SEARCH_ID tag can be used as an identifier for the project. This is +# useful in combination with EXTRA_SEARCH_MAPPINGS to search through multiple +# projects and redirect the results back to the right project. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH_ID = + +# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen +# projects other than the one defined by this configuration file, but that are +# all added to the same external search index. Each project needs to have a +# unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id of +# to a relative location where the documentation can be found. The format is: +# EXTRA_SEARCH_MAPPINGS = tagname1=loc1 tagname2=loc2 ... +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTRA_SEARCH_MAPPINGS = + #--------------------------------------------------------------------------- -# configuration options related to the LaTeX output +# Configuration options related to the LaTeX output #--------------------------------------------------------------------------- -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. +# If the GENERATE_LATEX tag is set to YES doxygen will generate LaTeX output. +# The default value is: YES. GENERATE_LATEX = NO -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: latex. +# This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_OUTPUT = latex # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. +# invoked. +# +# Note that when enabling USE_PDFLATEX this option is only used for generating +# bitmaps for formulas in the HTML output, but not in the Makefile that is +# written to the output directory. +# The default file is: latex. +# This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_CMD_NAME = latex -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate +# index for LaTeX. +# The default file is: makeindex. +# This tag requires that the tag GENERATE_LATEX is set to YES. MAKEINDEX_CMD_NAME = makeindex -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. +# If the COMPACT_LATEX tag is set to YES doxygen generates more compact LaTeX +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. COMPACT_LATEX = NO -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and -# executive. If left blank a4wide will be used. +# The PAPER_TYPE tag can be used to set the paper type that is used by the +# printer. +# Possible values are: a4 (210 x 297 mm), letter (8.5 x 11 inches), legal (8.5 x +# 14 inches) and executive (7.25 x 10.5 inches). +# The default value is: a4. +# This tag requires that the tag GENERATE_LATEX is set to YES. PAPER_TYPE = a4wide -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. +# The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names +# that should be included in the LaTeX output. To get the times font for +# instance you can specify +# EXTRA_PACKAGES=times +# If left blank no extra packages will be included. +# This tag requires that the tag GENERATE_LATEX is set to YES. EXTRA_PACKAGES = -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for the +# generated LaTeX document. The header should contain everything until the first +# chapter. If it is left blank doxygen will generate a standard header. See +# section "Doxygen usage" for information on how to let doxygen write the +# default header to a separate file. +# +# Note: Only use a user-defined header if you know what you are doing! The +# following commands have a special meaning inside the header: $title, +# $datetime, $date, $doxygenversion, $projectname, $projectnumber. Doxygen will +# replace them by respectively the title of the page, the current date and time, +# only the current date, the version number of doxygen, the project name (see +# PROJECT_NAME), or the project number (see PROJECT_NUMBER). +# This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_HEADER = -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. +# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the +# generated LaTeX document. The footer should contain everything after the last +# chapter. If it is left blank doxygen will generate a standard footer. +# +# Note: Only use a user-defined footer if you know what you are doing! +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_FOOTER = + +# The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the LATEX_OUTPUT output +# directory. Note that the files will be copied as-is; there are no commands or +# markers available. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_FILES = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated is +# prepared for conversion to PDF (using ps2pdf or pdflatex). The PDF file will +# contain links (just like the HTML output) instead of page references. This +# makes the output suitable for online browsing using a PDF viewer. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. PDF_HYPERLINKS = YES -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a +# If the LATEX_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate +# the PDF file directly from the LaTeX files. Set this option to YES to get a # higher quality PDF documentation. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. USE_PDFLATEX = YES -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode +# command to the generated LaTeX files. This will instruct LaTeX to keep running +# if errors occur, instead of asking the user for help. This option is also used +# when generating formulas in HTML. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_BATCHMODE = NO -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. +# If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the +# index chapters (such as File Index, Compound Index, etc.) in the output. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_HIDE_INDICES = NO +# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source +# code with syntax highlighting in the LaTeX output. +# +# Note that which sources are shown also depends on other settings such as +# SOURCE_BROWSER. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_SOURCE_CODE = NO + +# The LATEX_BIB_STYLE tag can be used to specify the style to use for the +# bibliography, e.g. plainnat, or ieeetr. See +# http://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# The default value is: plain. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_BIB_STYLE = plain + #--------------------------------------------------------------------------- -# configuration options related to the RTF output +# Configuration options related to the RTF output #--------------------------------------------------------------------------- -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. +# If the GENERATE_RTF tag is set to YES doxygen will generate RTF output. The +# RTF output is optimized for Word 97 and may not look too pretty with other RTF +# readers/editors. +# The default value is: NO. GENERATE_RTF = NO -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: rtf. +# This tag requires that the tag GENERATE_RTF is set to YES. RTF_OUTPUT = rtf -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. +# If the COMPACT_RTF tag is set to YES doxygen generates more compact RTF +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. COMPACT_RTF = NO -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated will +# contain hyperlink fields. The RTF file will contain links (just like the HTML +# output) instead of page references. This makes the output suitable for online +# browsing using Word or some other Word compatible readers that support those +# fields. +# +# Note: WordPad (write) and others do not support links. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. RTF_HYPERLINKS = NO -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. +# Load stylesheet definitions from file. Syntax is similar to doxygen's config +# file, i.e. a series of assignments. You only have to provide replacements, +# missing definitions are set to their default value. +# +# See also section "Doxygen usage" for information on how to generate the +# default style sheet that doxygen normally uses. +# This tag requires that the tag GENERATE_RTF is set to YES. RTF_STYLESHEET_FILE = -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. +# Set optional variables used in the generation of an RTF document. Syntax is +# similar to doxygen's config file. A template extensions file can be generated +# using doxygen -e rtf extensionFile. +# This tag requires that the tag GENERATE_RTF is set to YES. RTF_EXTENSIONS_FILE = #--------------------------------------------------------------------------- -# configuration options related to the man page output +# Configuration options related to the man page output #--------------------------------------------------------------------------- -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages +# If the GENERATE_MAN tag is set to YES doxygen will generate man pages for +# classes and files. +# The default value is: NO. GENERATE_MAN = YES -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. +# The MAN_OUTPUT tag is used to specify where the man pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. A directory man3 will be created inside the directory specified by +# MAN_OUTPUT. +# The default directory is: man. +# This tag requires that the tag GENERATE_MAN is set to YES. MAN_OUTPUT = man -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) +# The MAN_EXTENSION tag determines the extension that is added to the generated +# man pages. In case the manual section does not start with a number, the number +# 3 is prepended. The dot (.) at the beginning of the MAN_EXTENSION tag is +# optional. +# The default value is: .3. +# This tag requires that the tag GENERATE_MAN is set to YES. MAN_EXTENSION = .1 -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. +# The MAN_SUBDIR tag determines the name of the directory created within +# MAN_OUTPUT in which the man pages are placed. If defaults to man followed by +# MAN_EXTENSION with the initial . removed. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_SUBDIR = + +# If the MAN_LINKS tag is set to YES and doxygen generates man output, then it +# will generate one additional man file for each entity documented in the real +# man page(s). These additional files only source the real man page, but without +# them the man command would be unable to find the correct page. +# The default value is: NO. +# This tag requires that the tag GENERATE_MAN is set to YES. MAN_LINKS = YES #--------------------------------------------------------------------------- -# configuration options related to the XML output +# Configuration options related to the XML output #--------------------------------------------------------------------------- -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. +# If the GENERATE_XML tag is set to YES doxygen will generate an XML file that +# captures the structure of the code including all documentation. +# The default value is: NO. GENERATE_XML = NO -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. +# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: xml. +# This tag requires that the tag GENERATE_XML is set to YES. XML_OUTPUT = xml -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the -# syntax of the XML files. +# If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program +# listings (including syntax highlighting and cross-referencing information) to +# the XML output. Note that enabling this will significantly increase the size +# of the XML output. +# The default value is: YES. +# This tag requires that the tag GENERATE_XML is set to YES. -XML_SCHEMA = +XML_PROGRAMLISTING = YES -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the -# syntax of the XML files. +#--------------------------------------------------------------------------- +# Configuration options related to the DOCBOOK output +#--------------------------------------------------------------------------- -XML_DTD = +# If the GENERATE_DOCBOOK tag is set to YES doxygen will generate Docbook files +# that can be used to generate PDF. +# The default value is: NO. -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. +GENERATE_DOCBOOK = NO -XML_PROGRAMLISTING = YES +# The DOCBOOK_OUTPUT tag is used to specify where the Docbook pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be put in +# front of it. +# The default directory is: docbook. +# This tag requires that the tag GENERATE_DOCBOOK is set to YES. + +DOCBOOK_OUTPUT = docbook #--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output +# Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. +# If the GENERATE_AUTOGEN_DEF tag is set to YES doxygen will generate an AutoGen +# Definitions (see http://autogen.sf.net) file that captures the structure of +# the code including all documentation. Note that this feature is still +# experimental and incomplete at the moment. +# The default value is: NO. GENERATE_AUTOGEN_DEF = NO #--------------------------------------------------------------------------- -# configuration options related to the Perl module output +# Configuration options related to the Perl module output #--------------------------------------------------------------------------- -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. +# If the GENERATE_PERLMOD tag is set to YES doxygen will generate a Perl module +# file that captures the structure of the code including all documentation. +# +# Note that this feature is still experimental and incomplete at the moment. +# The default value is: NO. GENERATE_PERLMOD = NO -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. +# If the PERLMOD_LATEX tag is set to YES doxygen will generate the necessary +# Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI +# output from the Perl module output. +# The default value is: NO. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. PERLMOD_LATEX = NO -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. This is useful -# if you want to understand what is going on. On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be nicely +# formatted so it can be parsed by a human reader. This is useful if you want to +# understand what is going on. On the other hand, if this tag is set to NO the +# size of the Perl module output will be much smaller and Perl will parse it +# just the same. +# The default value is: YES. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. PERLMOD_PRETTY = YES -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. +# The names of the make variables in the generated doxyrules.make file are +# prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. This is useful +# so different doxyrules.make files included by the same Makefile don't +# overwrite each other's variables. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. PERLMOD_MAKEVAR_PREFIX = @@ -913,108 +1934,128 @@ PERLMOD_MAKEVAR_PREFIX = # Configuration options related to the preprocessor #--------------------------------------------------------------------------- -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. +# If the ENABLE_PREPROCESSING tag is set to YES doxygen will evaluate all +# C-preprocessor directives found in the sources and include files. +# The default value is: YES. ENABLE_PREPROCESSING = YES -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. +# If the MACRO_EXPANSION tag is set to YES doxygen will expand all macro names +# in the source code. If set to NO only conditional compilation will be +# performed. Macro expansion can be done in a controlled way by setting +# EXPAND_ONLY_PREDEF to YES. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. MACRO_EXPANSION = NO -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_PREDEFINED tags. +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then +# the macro expansion is limited to the macros specified with the PREDEFINED and +# EXPAND_AS_DEFINED tags. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. EXPAND_ONLY_PREDEF = NO -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# in the INCLUDE_PATH (see below) will be search if a #include is found. +# If the SEARCH_INCLUDES tag is set to YES the includes files in the +# INCLUDE_PATH will be searched if a #include is found. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. SEARCH_INCLUDES = YES # The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. +# contain include files that are not input files but should be processed by the +# preprocessor. +# This tag requires that the tag SEARCH_INCLUDES is set to YES. INCLUDE_PATH = # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. +# directories. If left blank, the patterns specified with FILE_PATTERNS will be +# used. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. INCLUDE_FILE_PATTERNS = -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. +# The PREDEFINED tag can be used to specify one or more macro names that are +# defined before the preprocessor is started (similar to the -D option of e.g. +# gcc). The argument of the tag is a list of macros of the form: name or +# name=definition (no spaces). If the definition and the "=" are omitted, "=1" +# is assumed. To prevent a macro definition from being undefined via #undef or +# recursively expanded use the := operator instead of the = operator. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. PREDEFINED = -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition. +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this +# tag can be used to specify a list of macro names that should be expanded. The +# macro definition that is found in the sources will be used. Use the PREDEFINED +# tag if you want to use a different macro definition that overrules the +# definition found in the source code. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. EXPAND_AS_DEFINED = -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse the -# parser if not removed. +# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will +# remove all references to function-like macros that are alone on a line, have +# an all uppercase name, and do not end with a semicolon. Such function macros +# are typically used for boiler-plate code, and will confuse the parser if not +# removed. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- -# Configuration::additions related to external references +# Configuration options related to external references #--------------------------------------------------------------------------- -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# TAGFILES = file1 file2 ... +# The TAGFILES tag can be used to specify one or more tag files. For each tag +# file the location of the external documentation should be added. The format of +# a tag file without this location is as follows: +# TAGFILES = file1 file2 ... # Adding location for the tag files is done as follows: -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where loc1 and loc2 can be relative or absolute paths or URLs. See the +# section "Linking to external documentation" for more information about the use +# of tag files. +# Note: Each tag file must have a unique name (where the name does NOT include +# the path). If a tag file is not located in the directory in which doxygen is +# run, you must also specify the path to the tagfile here. TAGFILES = -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. +# When a file name is specified after GENERATE_TAGFILE, doxygen will create a +# tag file that is based on the input files it reads. See section "Linking to +# external documentation" for more information about the usage of tag files. GENERATE_TAGFILE = -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. +# If the ALLEXTERNALS tag is set to YES all external class will be listed in the +# class index. If set to NO only the inherited external classes will be listed. +# The default value is: NO. ALLEXTERNALS = NO -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed in +# the modules index. If set to NO, only the current project's groups will be +# listed. +# The default value is: YES. EXTERNAL_GROUPS = YES +# If the EXTERNAL_PAGES tag is set to YES all external pages will be listed in +# the related pages index. If set to NO, only the current project's pages will +# be listed. +# The default value is: YES. + +EXTERNAL_PAGES = YES + # The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). +# interpreter (i.e. the result of 'which perl'). +# The default file (with absolute path) is: /usr/bin/perl. PERL_PATH = /usr/bin/perl @@ -1022,140 +2063,293 @@ PERL_PATH = /usr/bin/perl # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base or -# super classes. Setting the tag to NO turns the diagrams off. Note that this -# option is superseded by the HAVE_DOT option below. This is only a fallback. It is -# recommended to install and use dot, since it yields more powerful graphs. +# If the CLASS_DIAGRAMS tag is set to YES doxygen will generate a class diagram +# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to +# NO turns the diagrams off. Note that this option also works with HAVE_DOT +# disabled, but it is recommended to install and use dot, since it yields more +# powerful graphs. +# The default value is: YES. CLASS_DIAGRAMS = YES -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see: +# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# You can include diagrams made with dia in doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. + +DIA_PATH = + +# If set to YES, the inheritance and collaboration graphs will hide inheritance +# and usage relations if the target is undocumented or is not a class. +# The default value is: YES. HIDE_UNDOC_RELATIONS = YES # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) +# available from the path. This tool is part of Graphviz (see: +# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# Bell Labs. The other options in this section have no effect if this option is +# set to NO +# The default value is: NO. HAVE_DOT = NO -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# the CLASS_DIAGRAMS tag to NO. +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed +# to run in parallel. When set to 0 doxygen will base this on the number of +# processors available in the system. You can set it explicitly to a value +# larger than 0 to get control over the balance between CPU load and processing +# speed. +# Minimum value: 0, maximum value: 32, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_NUM_THREADS = 0 + +# When you want a differently looking font n the dot files that doxygen +# generates you can specify the font name using DOT_FONTNAME. You need to make +# sure dot is able to find the font, which can be done by putting it in a +# standard location or by setting the DOTFONTPATH environment variable or by +# setting DOT_FONTPATH to the directory containing the font. +# The default value is: Helvetica. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTNAME = Helvetica + +# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of +# dot graphs. +# Minimum value: 4, maximum value: 24, default value: 10. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the default font as specified with +# DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set +# the path where dot can find it using this tag. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTPATH = + +# If the CLASS_GRAPH tag is set to YES then doxygen will generate a graph for +# each documented class showing the direct and indirect inheritance relations. +# Setting this tag to YES will force the CLASS_DIAGRAMS tag to NO. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. CLASS_GRAPH = YES -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. +# If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a +# graph for each documented class showing the direct and indirect implementation +# dependencies (inheritance, containment, and class references variables) of the +# class with other documented classes. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. COLLABORATION_GRAPH = YES +# If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for +# groups, showing the direct groups dependencies. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +GROUP_GRAPHS = YES + # If the UML_LOOK tag is set to YES doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling # Language. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. UML_LOOK = NO -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. +# If the UML_LOOK tag is enabled, the fields and methods are shown inside the +# class node. If there are many fields or methods and many nodes the graph may +# become too big to be useful. The UML_LIMIT_NUM_FIELDS threshold limits the +# number of items for each type to make the size more manageable. Set this to 0 +# for no limit. Note that the threshold may be exceeded by 50% before the limit +# is enforced. So when you set the threshold to 10, up to 15 fields may appear, +# but if the number exceeds 15, the total amount of fields shown is limited to +# 10. +# Minimum value: 0, maximum value: 100, default value: 10. +# This tag requires that the tag HAVE_DOT is set to YES. + +UML_LIMIT_NUM_FIELDS = 10 + +# If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and +# collaboration graphs will show the relations between templates and their +# instances. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. TEMPLATE_RELATIONS = NO -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. +# If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to +# YES then doxygen will generate a graph for each documented file showing the +# direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. INCLUDE_GRAPH = YES -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. +# If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are +# set to YES then doxygen will generate a graph for each documented file showing +# the direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. INCLUDED_BY_GRAPH = YES -# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will -# generate a call dependency graph for every global function or class method. +# If the CALL_GRAPH tag is set to YES then doxygen will generate a call +# dependency graph for every global function or class method. +# # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable call graphs for selected # functions only using the \callgraph command. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. CALL_GRAPH = NO -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will graphical hierarchy of all classes instead of a textual one. +# If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller +# dependency graph for every global function or class method. +# +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable caller graphs for selected +# functions only using the \callergraph command. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical +# hierarchy of all classes instead of a textual one. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. GRAPHICAL_HIERARCHY = YES +# If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the +# dependencies a directory has on other directories in a graphical way. The +# dependency relations are determined by the #include relations between the +# files in the directories. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +DIRECTORY_GRAPH = YES + # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are png, jpg, or gif -# If left blank png will be used. +# generated by dot. +# Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order +# to make the SVG files visible in IE 9+ (other browsers do not have this +# requirement). +# Possible values are: png, jpg, gif and svg. +# The default value is: png. +# This tag requires that the tag HAVE_DOT is set to YES. DOT_IMAGE_FORMAT = png -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found on the path. +# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to +# enable generation of interactive SVG images that allow zooming and panning. +# +# Note that this requires a modern browser other than Internet Explorer. Tested +# and working are Firefox, Chrome, Safari, and Opera. +# Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make +# the SVG files visible. Older versions of IE do not have SVG support. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +INTERACTIVE_SVG = NO + +# The DOT_PATH tag can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. +# This tag requires that the tag HAVE_DOT is set to YES. DOT_PATH = # The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). +# contain dot files that are included in the documentation (see the \dotfile +# command). +# This tag requires that the tag HAVE_DOT is set to YES. DOTFILE_DIRS = -# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width -# (in pixels) of the graphs generated by dot. If a graph becomes larger than -# this value, doxygen will try to truncate the graph, so that it fits within -# the specified constraint. Beware that most browsers cannot cope with very -# large images. +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). -MAX_DOT_GRAPH_WIDTH = 1024 +MSCFILE_DIRS = -# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height -# (in pixels) of the graphs generated by dot. If a graph becomes larger than -# this value, doxygen will try to truncate the graph, so that it fits within -# the specified constraint. Beware that most browsers cannot cope with very -# large images. +# The DIAFILE_DIRS tag can be used to specify one or more directories that +# contain dia files that are included in the documentation (see the \diafile +# command). -MAX_DOT_GRAPH_HEIGHT = 1024 +DIAFILE_DIRS = -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes that -# lay further from the root node will be omitted. Note that setting this option to -# 1 or 2 may greatly reduce the computation time needed for large code bases. Also -# note that a graph may be further truncated if the graph's image dimensions are -# not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH and MAX_DOT_GRAPH_HEIGHT). -# If 0 is used for the depth value (the default), the graph is not depth-constrained. +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes +# that will be shown in the graph. If the number of nodes in a graph becomes +# larger than this value, doxygen will truncate the graph, which is visualized +# by representing a node as a red box. Note that doxygen if the number of direct +# children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note that +# the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. +# Minimum value: 0, maximum value: 10000, default value: 50. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs +# generated by dot. A depth value of 3 means that only nodes reachable from the +# root by following a path via at most 3 edges will be shown. Nodes that lay +# further from the root node will be omitted. Note that setting this option to 1 +# or 2 may greatly reduce the computation time needed for large code bases. Also +# note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. +# Minimum value: 0, maximum value: 1000, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. MAX_DOT_GRAPH_DEPTH = 0 -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not seem +# to support this out of the box. +# +# Warning: Depending on the platform used, enabling this option may lead to +# badly anti-aliased labels on the edges of a graph (i.e. they become hard to +# read). +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. -GENERATE_LEGEND = YES +DOT_TRANSPARENT = NO -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) support +# this, this feature is disabled by default. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. -DOT_CLEANUP = YES +DOT_MULTI_TARGETS = NO -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- +# If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page +# explaining the meaning of the various boxes and arrows in the dot generated +# graphs. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. -# The SEARCHENGINE tag specifies whether or not a search engine should be -# used. If set to NO the values of all tags below this one will be ignored. +GENERATE_LEGEND = YES -SEARCHENGINE = NO +# If the DOT_CLEANUP tag is set to YES doxygen will remove the intermediate dot +# files that are used to generate the various graphs. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_CLEANUP = YES diff --git a/Doxyfile.user b/Doxyfile.user index 99927595..96c3bc22 100644 --- a/Doxyfile.user +++ b/Doxyfile.user @@ -1,161 +1,2355 @@ +# Doxyfile 1.8.7 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. +# +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all text +# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv +# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv +# for the list of possible encodings. +# The default value is: UTF-8. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. + PROJECT_NAME = fish + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. This +# could be handy for archiving the generated documentation or if some version +# control system is used. + PROJECT_NUMBER = 1 + +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify an logo or icon that is included in +# the documentation. The maximum height of the logo should not exceed 55 pixels +# and the maximum width should not exceed 200 pixels. Doxygen will copy the logo +# to the output directory. + +PROJECT_LOGO = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path +# into which the generated documentation will be written. If a relative path is +# entered, it will be relative to the location where doxygen was started. If +# left blank the current directory will be used. + OUTPUT_DIRECTORY = user_doc + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub- +# directories (in 2 levels) under the output directory of each output format and +# will distribute the generated files over these directories. Enabling this +# option can be useful when feeding doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise causes +# performance problems for the file system. +# The default value is: NO. + CREATE_SUBDIRS = NO + +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. +# The default value is: English. + OUTPUT_LANGUAGE = English -USE_WINDOWS_ENCODING = NO + +# If the BRIEF_MEMBER_DESC tag is set to YES doxygen will include brief member +# descriptions after the members that are listed in the file and class +# documentation (similar to Javadoc). Set to NO to disable this. +# The default value is: YES. + BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief +# description of a member or function before the detailed description +# +# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. +# The default value is: YES. + REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator that is +# used to form the text in various listings. Each string in this list, if found +# as the leading text of the brief description, will be stripped from the text +# and the result, after processing the whole list, is used as the annotated +# text. Otherwise, the brief description is used as-is. If left blank, the +# following values are used ($name is automatically replaced with the name of +# the entity):The $name class, The $name widget, The $name file, is, provides, +# specifies, contains, represents, a, an and the. + ABBREVIATE_BRIEF = YES + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# doxygen will generate a detailed section even if there is only a brief +# description. +# The default value is: NO. + ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. +# The default value is: NO. + INLINE_INHERITED_MEMB = NO -FULL_PATH_NAMES = YES + +# If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path +# before files name in the file list and in the header files. If set to NO the +# shortest path that makes the file name unique will be used +# The default value is: YES. + +FULL_PATH_NAMES = NO + +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand +# part of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to +# strip. +# +# Note that you can specify absolute paths here, but also relative paths, which +# will be relative from the directory where doxygen is started. +# This tag requires that the tag FULL_PATH_NAMES is set to YES. + STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the +# path mentioned in the documentation of a class, which tells the reader which +# header file to include in order to use a class. If left blank only the name of +# the header file containing the class definition is used. Otherwise one should +# specify the list of include paths that are normally passed to the compiler +# using the -I flag. + STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but +# less readable) file names. This can be useful is your file systems doesn't +# support long names like on DOS, Mac, or CD-ROM. +# The default value is: NO. + SHORT_NAMES = NO -JAVADOC_AUTOBRIEF = YES + +# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the +# first line (until the first dot) of a Javadoc-style comment as the brief +# description. If set to NO, the Javadoc-style will behave just like regular Qt- +# style comments (thus requiring an explicit @brief command for a brief +# description.) +# The default value is: NO. + +JAVADOC_AUTOBRIEF = NO + +# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first +# line (until the first dot) of a Qt-style comment as the brief description. If +# set to NO, the Qt-style will behave just like regular Qt-style comments (thus +# requiring an explicit \brief command for a brief description.) +# The default value is: NO. + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# multi-line C++ special comment block (i.e. a block of //! or /// comments) as +# a brief description. This used to be the default behavior. The new default is +# to treat a multi-line C++ comment block as a detailed description. Set this +# tag to YES if you prefer the old behavior instead. +# +# Note that setting this tag to YES also means that rational rose comments are +# not recognized any more. +# The default value is: NO. + MULTILINE_CPP_IS_BRIEF = NO -DETAILS_AT_TOP = NO -INHERIT_DOCS = YES -DISTRIBUTE_GROUP_DOC = NO -TAB_SIZE = 8 -ALIASES = -OPTIMIZE_OUTPUT_FOR_C = YES + +# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the +# documentation from any documented member that it re-implements. +# The default value is: YES. + +INHERIT_DOCS = NO + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce a +# new page for each member. If set to NO, the documentation of a member will be +# part of the file/class/namespace that contains it. +# The default value is: NO. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen +# uses this value to replace tabs by spaces in code fragments. +# Minimum value: 1, maximum value: 16, default value: 4. + +TAB_SIZE = 4 + +# This tag can be used to specify a number of aliases that act as commands in +# the documentation. An alias has the form: +# name=value +# For example adding +# "sideeffect=@par Side Effects:\n" +# will allow you to put the command \sideeffect (or @sideeffect) in the +# documentation, which will result in a user-defined paragraph with heading +# "Side Effects:". You can put \n's in the value part of an alias to insert +# newlines. + +# Enhance Fish docs output from Doxygen. (See lexicon_filter.in) + +ALIASES = "key{1}=<span class=\"key\"><b>\1</b></span>" +ALIASES += "key{2}=<span class=\"key\"><em>\1</em><span>-</span><b>\2</b></span>" +ALIASES += "key{3}=<span class=\"key\"><em>\1</em><span>-</span><b>\2</b></span>" +ALIASES += "cursor_key{2}=<span class=\"key\"><b>\1</b></span>" + +ALIASES += "fish=\htmlonly[block] \n<pre class=\"fish\">" +ALIASES += "fish{1}=\htmlonly[block] \n<pre class=\"fish \1\">" +ALIASES += "endfish=</pre>\endhtmlonly \n" + +ALIASES += "asis{1}=\1" +ALIASES += "outp{1}=<span class=\"output\">\1</span>" +ALIASES += "blah{1}=<span class=\"comment\">#\1</span>" +ALIASES += "bltn{1}=<span class=\"command\">\1</span>" +ALIASES += "func{1}=<span class=\"function\">\1</span>" +ALIASES += "cmnd{1}=<span class=\"binary\">\1</span>" +ALIASES += "args{1}=<span class=\"argument\">\1</span>" +ALIASES += "opts{1}=<span class=\"argument\">\1</span>" +ALIASES += "vars{1}=<span class=\"variable\">\1</span>" +ALIASES += "optr{1}=<span class=\"operator\">\1</span>" +ALIASES += "redr{1}=<span class=\"redirect\">\1</span>" +ALIASES += "fsfo{1}=<span class=\"file\">\1</span>" +ALIASES += "path{1}=<span class=\"path\">\1</span>" +ALIASES += "clrv{1}=<span class=\"variable\">\1</span>" + +ALIASES += "strg{1}=<span class=\"string\">\1</span>" +ALIASES += "sglq{1}=<span class=\"string\">'\1'</span>" +ALIASES += "dblq{1}=<span class=\"string\">\"\1\"</span>" + +ALIASES += "prmt=<span class=\"prompt\">></span>" +ALIASES += "prmt{1}=<span class=\"prompt\">\1></span>" +ALIASES += "sgst{1}=<span class=\"suggest\">\1</span>" +ALIASES += "mtch{1}=<span class=\"match\">\1</span>" +ALIASES += "smtc{1}=<span class=\"search_match\">\1</span>" +ALIASES += "eror{1}=<span class=\"error\">\1</span>" +ALIASES += "curs=<span class=\"cursor\"> </span>" +ALIASES += "curs{1}=<span class=\"cursor\">\1</span>" + +ALIASES += "bold{1}=<strong>\1</strong>" +ALIASES += "emph{1}=<em>\1</em>" +ALIASES += "undr{1}=<span class=\"underline\">\1</span>" +ALIASES += "span{2}=<span style=\"\1\">\2</span>" +ALIASES += "spcl{2}=<span class=\"\1\">\2</span>" + +ALIASES += "bksl{1}=<span>\</span>\1" + +# This tag can be used to specify a number of word-keyword mappings (TCL only). +# A mapping has the form "name=value". For example adding "class=itcl::class" +# will allow you to use the command class in the itcl::class meaning. + +TCL_SUBST = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. For +# instance, some of the names that are used will be different. The list of all +# members will be omitted, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_FOR_C = NO + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or +# Python sources only. Doxygen will then generate output that is more tailored +# for that language. For instance, namespaces will be presented as packages, +# qualified scopes will look different, etc. +# The default value is: NO. + OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources. Doxygen will then generate output that is tailored for Fortran. +# The default value is: NO. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for VHDL. +# The default value is: NO. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, Javascript, +# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: +# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: +# Fortran. In the later case the parser tries to guess whether the code is fixed +# or free formatted code, this is the default for Fortran type files), VHDL. For +# instance to make doxygen treat .inc files as Fortran files (default is PHP), +# and .f files as C (default is Fortran), use: inc=Fortran f=C. +# +# Note For files without extension you can use no_extension as a placeholder. +# +# Note that for custom extensions you also need to set FILE_PATTERNS otherwise +# the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# according to the Markdown format, which allows for more readable +# documentation. See http://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you can +# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# case of backward compatibilities issues. +# The default value is: YES. + +MARKDOWN_SUPPORT = YES + +# When enabled doxygen tries to link words that correspond to documented +# classes, or namespaces to their corresponding documentation. Such a link can +# be prevented in individual cases by by putting a % sign in front of the word +# or globally by setting AUTOLINK_SUPPORT to NO. +# The default value is: YES. + +AUTOLINK_SUPPORT = YES + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should set this +# tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); +# versus func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. +# The default value is: NO. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. +# The default value is: NO. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: +# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen +# will parse them like normal C++ but will assume all classes use public instead +# of private inheritance when no explicit protection keyword is present. +# The default value is: NO. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES will make +# doxygen to replace the get and set methods by a property in the documentation. +# This will only work if the methods are indeed getting or setting a simple +# type. If this is not the case, or you want to show the methods anyway, you +# should set this option to NO. +# The default value is: YES. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. +# The default value is: NO. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES to allow class member groups of the same type +# (for instance a group of public functions) to be put as a subgroup of that +# type (e.g. under the Public Functions section). Set it to NO to prevent +# subgrouping. Alternatively, this can be done per class using the +# \nosubgrouping command. +# The default value is: YES. + SUBGROUPING = YES + +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions +# are shown inside the group in which they are included (e.g. using \ingroup) +# instead of on a separate page (for HTML and Man pages) or section (for LaTeX +# and RTF). +# +# Note that this feature does not work in combination with +# SEPARATE_MEMBER_PAGES. +# The default value is: NO. + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions +# with only public data fields or simple typedef fields will be shown inline in +# the documentation of the scope in which they are defined (i.e. file, +# namespace, or group documentation), provided this scope is documented. If set +# to NO, structs, classes, and unions are shown on a separate page (for HTML and +# Man pages) or section (for LaTeX and RTF). +# The default value is: NO. + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or +# enum is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically be +# useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. +# The default value is: NO. + +TYPEDEF_HIDES_STRUCT = NO + +# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This +# cache is used to resolve symbols given their name and scope. Since this can be +# an expensive process and often the same symbol appears multiple times in the +# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# doxygen will become slower. If the cache is too large, memory is wasted. The +# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range +# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 +# symbols. At the end of a run doxygen will report the cache usage and suggest +# the optimal cache size from a speed point of view. +# Minimum value: 0, maximum value: 9, default value: 0. + +LOOKUP_CACHE_SIZE = 0 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. Private +# class members and static file members will be hidden unless the +# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. +# Note: This will also disable the warnings about undocumented members that are +# normally produced when WARNINGS is set to YES. +# The default value is: NO. + EXTRACT_ALL = NO + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class will +# be included in the documentation. +# The default value is: NO. + EXTRACT_PRIVATE = NO + +# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal +# scope will be included in the documentation. +# The default value is: NO. + +EXTRACT_PACKAGE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file will be +# included in the documentation. +# The default value is: NO. + EXTRACT_STATIC = YES + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO +# only classes defined in header files are included. Does not have any effect +# for Java sources. +# The default value is: YES. + EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. When set to YES local methods, +# which are defined in the implementation section but not in the interface are +# included in the documentation. If set to NO only methods in the interface are +# included. +# The default value is: NO. + EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base name of +# the file that contains the anonymous namespace. By default anonymous namespace +# are hidden. +# The default value is: NO. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# undocumented members inside documented classes or files. If set to NO these +# members will be included in the various overviews, but no documentation +# section is generated. This option has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. If set +# to NO these classes will be included in the various overviews. This option has +# no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# (class|struct|union) declarations. If set to NO these declarations will be +# included in the documentation. +# The default value is: NO. + HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# documentation blocks found inside the body of a function. If set to NO these +# blocks will be appended to the function's detailed documentation block. +# The default value is: NO. + HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation that is typed after a +# \internal command is included. If the tag is set to NO then the documentation +# will be excluded. Set it to YES to include the internal documentation. +# The default value is: NO. + INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file +# names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. +# The default value is: system dependent. + CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# their full class and namespace scopes in the documentation. If set to YES the +# scope will be hidden. +# The default value is: NO. + HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# the files that are included by a file in the documentation of that file. +# The default value is: YES. + SHOW_INCLUDE_FILES = YES + +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# files with double quotes in the documentation rather than with sharp brackets. +# The default value is: NO. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the +# documentation for inline members. +# The default value is: YES. + INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# (detailed) documentation of file and class members alphabetically by member +# name. If set to NO the members will appear in declaration order. +# The default value is: YES. + SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# descriptions of file, namespace and class members alphabetically by member +# name. If set to NO the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. +# The default value is: NO. + SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# (brief and detailed) documentation of class members so that constructors and +# destructors are listed first. If set to NO the constructors will appear in the +# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. +# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief +# member documentation. +# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting +# detailed member documentation. +# The default value is: NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# of group names into alphabetical order. If set to NO the group names will +# appear in their defined order. +# The default value is: NO. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by +# fully-qualified names, including namespaces. If set to NO, the class list will +# be sorted only by class name, not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the alphabetical +# list. +# The default value is: NO. + SORT_BY_SCOPE_NAME = NO + +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# type resolution of all parameters of a function it will reject a match between +# the prototype and the implementation of a member function even if there is +# only one candidate or it is obvious which candidate to choose by doing a +# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# accept a match between prototype and implementation in such cases. +# The default value is: NO. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable ( YES) or disable ( NO) the +# todo list. This list is created by putting \todo commands in the +# documentation. +# The default value is: YES. + GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable ( YES) or disable ( NO) the +# test list. This list is created by putting \test commands in the +# documentation. +# The default value is: YES. + GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable ( YES) or disable ( NO) the bug +# list. This list is created by putting \bug commands in the documentation. +# The default value is: YES. + GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable ( YES) or disable ( NO) +# the deprecated list. This list is created by putting \deprecated commands in +# the documentation. +# The default value is: YES. + GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional documentation +# sections, marked by \if <section_label> ... \endif and \cond <section_label> +# ... \endcond blocks. + ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the +# initial value of a variable or macro / define can have for it to appear in the +# documentation. If the initializer consists of more lines than specified here +# it will be hidden. Use a value of 0 to hide initializers completely. The +# appearance of the value of individual variables and macros / defines can be +# controlled using \showinitializer or \hideinitializer command in the +# documentation regardless of this setting. +# Minimum value: 0, maximum value: 10000, default value: 30. + MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at +# the bottom of the documentation of classes and structs. If set to YES the list +# will mention the files that were used to generate the documentation. +# The default value is: YES. + SHOW_USED_FILES = YES -SHOW_DIRECTORIES = YES + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This +# will remove the Files entry from the Quick Index and from the Folder Tree View +# (if specified). +# The default value is: YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces +# page. This will remove the Namespaces entry from the Quick Index and from the +# Folder Tree View (if specified). +# The default value is: YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command command input-file, where command is the value of the +# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided +# by doxygen. Whatever the program writes to standard output is used as the file +# version. For an example see the documentation. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. You can +# optionally specify a file name after the option, if omitted DoxygenLayout.xml +# will be used as the name of the layout file. +# +# Note that if you run doxygen from a directory containing a file called +# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# tag is left empty. + +LAYOUT_FILE = + +# The CITE_BIB_FILES tag can be used to specify one or more bib files containing +# the reference definitions. This must be a list of .bib files. The .bib +# extension is automatically appended if omitted. This requires the bibtex tool +# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. +# For LaTeX the style of the bibliography can be controlled using +# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the +# search path. Do not use file names with spaces, bibtex cannot handle them. See +# also \cite for info how to create references. + +CITE_BIB_FILES = + +#--------------------------------------------------------------------------- +# Configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated to +# standard output by doxygen. If QUIET is set to YES this implies that the +# messages are off. +# The default value is: NO. + QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES +# this implies that the warnings are on. +# +# Tip: Turn warnings on while writing the documentation. +# The default value is: YES. + WARNINGS = YES + +# If the WARN_IF_UNDOCUMENTED tag is set to YES, then doxygen will generate +# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: YES. + WARN_IF_UNDOCUMENTED = YES + +# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some parameters +# in a documented function, or documenting parameters that don't exist or using +# markup commands wrongly. +# The default value is: YES. + WARN_IF_DOC_ERROR = YES + +# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that +# are documented, but have no documentation for their parameters or return +# value. If set to NO doxygen will only warn about wrong or incomplete parameter +# documentation, but not about the absence of documentation. +# The default value is: NO. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# can produce. The string should contain the $file, $line, and $text tags, which +# will be replaced by the file and line number from which the warning originated +# and the warning text. Optionally the format may contain $version, which will +# be replaced by the version of the file (if it could be obtained via +# FILE_VERSION_FILTER) +# The default value is: $file:$line: $text. + WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning and error +# messages should be written. If left blank the output is written to standard +# error (stderr). + WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# Configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag is used to specify the files and/or directories that contain +# documented source files. You may enter file names like myfile.cpp or +# directories like /usr/src/myproject. Separate the files or directories with +# spaces. +# Note: If this tag is empty the current directory is searched. + INPUT = -FILE_PATTERNS = doc.h + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# libiconv (or the iconv built into libc) for the transcoding. See the libiconv +# documentation (see: http://www.gnu.org/software/libiconv) for the list of +# possible encodings. +# The default value is: UTF-8. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank the +# following patterns are tested:*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii, +# *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, +# *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, +# *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, +# *.qsf, *.as and *.js. + +FILE_PATTERNS = doc.h + +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. + RECURSIVE = NO + +# The EXCLUDE tag can be used to specify files and/or directories that should be +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. + EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. +# The default value is: NO. + EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories for example use the pattern */test/* + EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories use the pattern */test/* + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or directories +# that contain example code fragments that are included (see the \include +# command). + EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank all +# files are included. + EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude commands +# irrespective of the value of the RECURSIVE tag. +# The default value is: NO. + EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or directories +# that contain images that are to be included in the documentation (see the +# \image command). + IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command: +# +# <filter> <input-file> +# +# where <filter> is the value of the INPUT_FILTER tag, and <input-file> is the +# name of an input file. Doxygen will then use the output that the filter +# program writes to standard output. If FILTER_PATTERNS is specified, this tag +# will be ignored. +# +# Note that the filter must not add or remove lines; it is applied before the +# code is scanned, but not when the output code is generated. If lines are added +# or removed, the anchors will not be placed correctly. + INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: pattern=filter +# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how +# filters are used. If the FILTER_PATTERNS tag is empty or if none of the +# patterns match the file name, INPUT_FILTER is applied. + FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER ) will also be used to filter the input files that are used for +# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). +# The default value is: NO. + FILTER_SOURCE_FILES = NO + +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. + +FILTER_SOURCE_PATTERNS = + +# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that +# is part of the input, its contents will be placed on the main page +# (index.html). This can be useful if you have a project on for instance GitHub +# and want to reuse the introduction page also for the doxygen output. + +USE_MDFILE_AS_MAINPAGE = + +#--------------------------------------------------------------------------- +# Configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will be +# generated. Documented entities will be cross-referenced with these sources. +# +# Note: To get rid of all source code in the generated output, make sure that +# also VERBATIM_HEADERS is set to NO. +# The default value is: NO. + SOURCE_BROWSER = NO + +# Setting the INLINE_SOURCES tag to YES will include the body of functions, +# classes and enums directly into the documentation. +# The default value is: NO. + INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# special comment blocks from generated source code fragments. Normal C, C++ and +# Fortran comments will always remain visible. +# The default value is: YES. + STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# function all documented functions referencing it will be listed. +# The default value is: NO. + REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. + REFERENCES_RELATION = YES -VERBATIM_HEADERS = YES + +# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set +# to YES, then the hyperlinks from functions in REFERENCES_RELATION and +# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will +# link to the documentation. +# The default value is: YES. + +REFERENCES_LINK_SOURCE = YES + +# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the +# source code will show a tooltip with additional information such as prototype, +# brief description and links to the definition and documentation. Since this +# will make the HTML file larger and loading of large files a bit slower, you +# can opt to disable this feature. +# The default value is: YES. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +SOURCE_TOOLTIPS = YES + +# If the USE_HTAGS tag is set to YES then the references to source code will +# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# source browser. The htags tool is part of GNU's global source tagging system +# (see http://www.gnu.org/software/global/global.html). You will need version +# 4.8.6 or higher. +# +# To use it do the following: +# - Install the latest version of global +# - Enable SOURCE_BROWSER and USE_HTAGS in the config file +# - Make sure the INPUT points to the root of the source tree +# - Run doxygen as normal +# +# Doxygen will invoke htags (and that will in turn invoke gtags), so these +# tools must be available from the command line (i.e. in the search path). +# +# The result: instead of the source browser generated by doxygen, the links to +# source code will now point to the output of htags. +# The default value is: NO. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# verbatim copy of the header file for each class for which an include is +# specified. Set to NO to disable this. +# See also: Section \class. +# The default value is: YES. + +VERBATIM_HEADERS = NO + +#--------------------------------------------------------------------------- +# Configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all +# compounds will be generated. Enable this if the project contains a lot of +# classes, structs, unions or interfaces. +# The default value is: YES. + ALPHABETICAL_INDEX = NO + +# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in +# which the alphabetical index list will be split. +# Minimum value: 1, maximum value: 20, default value: 5. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all classes will +# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag +# can be used to specify a prefix (or a list of prefixes) that should be ignored +# while generating the index headers. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES doxygen will generate HTML output +# The default value is: YES. + GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: html. +# This tag requires that the tag GENERATE_HTML is set to YES. + HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each +# generated HTML page (for example: .htm, .php, .asp). +# The default value is: .html. +# This tag requires that the tag GENERATE_HTML is set to YES. + HTML_FILE_EXTENSION = .html -HTML_HEADER = user_doc.head.html -HTML_FOOTER = + +# The HTML_HEADER tag can be used to specify a user-defined HTML header file for +# each generated HTML page. If the tag is left blank doxygen will generate a +# standard header. +# +# To get valid HTML the header file that includes any scripts and style sheets +# that doxygen needs, which is dependent on the configuration options used (e.g. +# the setting GENERATE_TREEVIEW). It is highly recommended to start with a +# default header using +# doxygen -w html new_header.html new_footer.html new_stylesheet.css +# YourConfigFile +# and then modify the file new_header.html. See also section "Doxygen usage" +# for information on how to generate the default header that doxygen normally +# uses. +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. For a description +# of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_HEADER = doc_src/user_doc.header.html + +# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each +# generated HTML page. If the tag is left blank doxygen will generate a standard +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FOOTER = doc_src/user_doc.footer.html + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style +# sheet that is used by each HTML page. It can be used to fine-tune the look of +# the HTML output. If left blank doxygen will generate a default style sheet. +# See also section "Doxygen usage" for information on how to generate the style +# sheet that doxygen normally uses. +# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as +# it is more robust and this tag (HTML_STYLESHEET) will in the future become +# obsolete. +# This tag requires that the tag GENERATE_HTML is set to YES. + HTML_STYLESHEET = -HTML_ALIGN_MEMBERS = YES + +# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional user- +# defined cascading style sheet that is included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefor more robust against future updates. +# Doxygen will copy the style sheet file to the output directory. For an example +# see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_STYLESHEET = doc_src/user_doc.css + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that the +# files will be copied as-is; there are no commands or markers available. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_FILES = doc_src/ascii_fish.png + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen +# will adjust the colors in the stylesheet and background images according to +# this color. Hue is specified as an angle on a colorwheel, see +# http://en.wikipedia.org/wiki/Hue for more information. For instance the value +# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 +# purple, and 360 is red again. +# Minimum value: 0, maximum value: 359, default value: 220. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors +# in the HTML output. For a value of 0 the output will use grayscales only. A +# value of 255 will produce the most vivid colors. +# Minimum value: 0, maximum value: 255, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the +# luminance component of the colors in the HTML output. Values below 100 +# gradually make the output lighter, whereas values above 100 make the output +# darker. The value divided by 100 is the actual gamma applied, so 80 represents +# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not +# change the gamma. +# Minimum value: 40, maximum value: 240, default value: 80. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting this +# to NO can help when comparing the output of multiple runs. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_TIMESTAMP = NO + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_SECTIONS = NO + +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries +# shown in the various tree structured indices initially; the user can expand +# and collapse entries dynamically later on. Doxygen will expand the tree to +# such a level that at most the specified number of entries are visible (unless +# a fully collapsed tree already exceeds this amount). So setting the number of +# entries 1 will produce a full collapsed tree by default. 0 is a special value +# representing an infinite number of entries and will result in a full expanded +# tree by default. +# Minimum value: 0, maximum value: 9999, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files will be +# generated that can be used as input for Apple's Xcode 3 integrated development +# environment (see: http://developer.apple.com/tools/xcode/), introduced with +# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a +# Makefile in the HTML output directory. Running make will produce the docset in +# that directory and running make install will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at +# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_DOCSET = NO + +# This tag determines the name of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# The default value is: Doxygen generated docs. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# This tag specifies a string that should uniquely identify the documentation +# set bundle. This should be a reverse domain-name style string, e.g. +# com.mycompany.MyDocSet. Doxygen will append .docset to the name. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. +# The default value is: org.doxygen.Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. +# The default value is: Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# additional HTML index files: index.hhp, index.hhc, and index.hhk. The +# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop +# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on +# Windows. +# +# The HTML Help Workshop contains a compiler that can convert all HTML output +# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# files are now used as the Windows 98 help format, and will replace the old +# Windows help format (.hlp) on all Windows platforms in the future. Compressed +# HTML files also contain an index, a table of contents, and you can search for +# words in the documentation. The HTML workshop also contains a viewer for +# compressed HTML files. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + GENERATE_HTMLHELP = NO + +# The CHM_FILE tag can be used to specify the file name of the resulting .chm +# file. You can add a path in front of the file if the result should not be +# written to the html output directory. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + CHM_FILE = + +# The HHC_LOCATION tag can be used to specify the location (absolute path +# including file name) of the HTML help compiler ( hhc.exe). If non-empty +# doxygen will try to run the HTML help compiler on the generated index.hhp. +# The file has to be specified with full path. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + HHC_LOCATION = + +# The GENERATE_CHI flag controls if a separate .chi index file is generated ( +# YES) or that it should be included in the master .chm file ( NO). +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + GENERATE_CHI = NO + +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index ( hhk), content ( hhc) +# and project file content. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_INDEX_ENCODING = + +# The BINARY_TOC flag controls whether a binary table of contents is generated ( +# YES) or a normal table of contents ( NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members to +# the table of contents of the HTML help documentation and to the tree view. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that +# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help +# (.qch) of the generated HTML documentation. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify +# the file name of the resulting .qch file. The path specified is relative to +# the HTML output folder. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help +# Project output. For more information please see Qt Help Project / Namespace +# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt +# Help Project output. For more information please see Qt Help Project / Virtual +# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- +# folders). +# The default value is: doc. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_VIRTUAL_FOLDER = doc + +# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom +# filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's filter section matches. Qt Help Project / Filter Attributes (see: +# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_SECT_FILTER_ATTRS = + +# The QHG_LOCATION tag can be used to specify the location of Qt's +# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the +# generated .qhp file. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be +# generated, together with the HTML files, they form an Eclipse help plugin. To +# install this plugin and make it available under the help contents menu in +# Eclipse, the contents of the directory containing the HTML and XML files needs +# to be copied into the plugins directory of eclipse. The name of the directory +# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. +# After copying Eclipse needs to be restarted before the help appears. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the Eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have this +# name. Each documentation set should have its own identifier. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# If you want full control over the layout of the generated HTML pages it might +# be necessary to disable the index and replace it with your own. The +# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top +# of each HTML page. A value of NO enables the index and the value YES disables +# it. Since the tabs in the index contain the same information as the navigation +# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + DISABLE_INDEX = YES -ENUM_VALUES_PER_LINE = 4 + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. If the tag +# value is set to YES, a side panel will be generated containing a tree-like +# index structure (just like the one that is generated for HTML Help). For this +# to work a browser that supports JavaScript, DHTML, CSS and frames is required +# (i.e. any modern browser). Windows users are probably better off using the +# HTML help feature. Via custom stylesheets (see HTML_EXTRA_STYLESHEET) one can +# further fine-tune the look of the index. As an example, the default style +# sheet generated by doxygen has an example that shows how to put an image at +# the root of the tree instead of the PROJECT_NAME. Since the tree basically has +# the same information as the tab index, you could consider setting +# DISABLE_INDEX to YES when enabling this option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + GENERATE_TREEVIEW = NO + +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that +# doxygen will group on one line in the generated HTML documentation. +# +# Note that a value of 0 will completely suppress the enum values from appearing +# in the overview section. +# Minimum value: 0, maximum value: 20, default value: 4. +# This tag requires that the tag GENERATE_HTML is set to YES. + +ENUM_VALUES_PER_LINE = 4 + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used +# to set the initial width (in pixels) of the frame in which the tree is shown. +# Minimum value: 0, maximum value: 1500, default value: 250. +# This tag requires that the tag GENERATE_HTML is set to YES. + TREEVIEW_WIDTH = 250 + +# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open links to +# external symbols imported via tag files in a separate window. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of LaTeX formulas included as images in +# the HTML documentation. When you change the font size after a successful +# doxygen run you need to manually remove any form_*.png images from the HTML +# output directory to force them to be regenerated. +# Minimum value: 8, maximum value: 50, default value: 10. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are not +# supported properly for IE 6.0, but are supported on all modern browsers. +# +# Note that when changing this option you need to delete any form_*.png files in +# the HTML output directory before the changes have effect. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_TRANSPARENT = YES + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see +# http://www.mathjax.org) which uses client side Javascript for the rendering +# instead of using prerendered bitmaps. Use this if you do not have LaTeX +# installed or if you want to formulas look prettier in the HTML output. When +# enabled you may also need to install MathJax separately and configure the path +# to it using the MATHJAX_RELPATH option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +USE_MATHJAX = NO + +# When MathJax is enabled you can set the default output format to be used for +# the MathJax output. See the MathJax site (see: +# http://docs.mathjax.org/en/latest/output.html) for more details. +# Possible values are: HTML-CSS (which is slower, but has the best +# compatibility), NativeMML (i.e. MathML) and SVG. +# The default value is: HTML-CSS. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_FORMAT = HTML-CSS + +# When MathJax is enabled you need to specify the location relative to the HTML +# output directory using the MATHJAX_RELPATH option. The destination directory +# should contain the MathJax.js script. For instance, if the mathjax directory +# is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax +# Content Delivery Network so you can quickly see the result without installing +# MathJax. However, it is strongly recommended to install a local copy of +# MathJax from http://www.mathjax.org before deployment. +# The default value is: http://cdn.mathjax.org/mathjax/latest. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest + +# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax +# extension names that should be enabled during MathJax rendering. For example +# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_EXTENSIONS = + +# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# of code that will be used on startup of the MathJax code. See the MathJax site +# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# example see the documentation. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_CODEFILE = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for +# the HTML output. The underlying search engine uses javascript and DHTML and +# should work on any modern browser. Note that when using HTML help +# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) +# there is already a search function so this one should typically be disabled. +# For large projects the javascript based search engine can be slow, then +# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to +# search using the keyboard; to jump to the search box use <access key> + S +# (what the <access key> is depends on the OS and browser, but it is typically +# <CTRL>, <ALT>/<option>, or both). Inside the search box use the <cursor down +# key> to jump into the search results window, the results can be navigated +# using the <cursor keys>. Press <Enter> to select an item or <escape> to cancel +# the search. The filter options can be selected when the cursor is inside the +# search box by pressing <Shift>+<cursor down>. Also here use the <cursor keys> +# to select a filter and <Enter> or <escape> to activate or cancel the filter +# option. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +SEARCHENGINE = NO + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a web server instead of a web client using Javascript. There +# are two flavors of web server based searching depending on the EXTERNAL_SEARCH +# setting. When disabled, doxygen will generate a PHP script for searching and +# an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing +# and searching needs to be provided by external tools. See the section +# "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SERVER_BASED_SEARCH = NO + +# When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP +# script for searching. Instead the search results are written to an XML file +# which needs to be processed by an external indexer. Doxygen will invoke an +# external search engine pointed to by the SEARCHENGINE_URL option to obtain the +# search results. +# +# Doxygen ships with an example indexer ( doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: http://xapian.org/). +# +# See the section "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH = NO + +# The SEARCHENGINE_URL should point to a search engine hosted by a web server +# which will return the search results when EXTERNAL_SEARCH is enabled. +# +# Doxygen ships with an example indexer ( doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: http://xapian.org/). See the section "External Indexing and +# Searching" for details. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHENGINE_URL = + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed +# search data is written to a file for indexing by an external tool. With the +# SEARCHDATA_FILE tag the name of this file can be specified. +# The default file is: searchdata.xml. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHDATA_FILE = searchdata.xml + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the +# EXTERNAL_SEARCH_ID tag can be used as an identifier for the project. This is +# useful in combination with EXTRA_SEARCH_MAPPINGS to search through multiple +# projects and redirect the results back to the right project. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH_ID = + +# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen +# projects other than the one defined by this configuration file, but that are +# all added to the same external search index. Each project needs to have a +# unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id of +# to a relative location where the documentation can be found. The format is: +# EXTRA_SEARCH_MAPPINGS = tagname1=loc1 tagname2=loc2 ... +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTRA_SEARCH_MAPPINGS = + +#--------------------------------------------------------------------------- +# Configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES doxygen will generate LaTeX output. +# The default value is: YES. + GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: latex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. +# +# Note that when enabling USE_PDFLATEX this option is only used for generating +# bitmaps for formulas in the HTML output, but not in the Makefile that is +# written to the output directory. +# The default file is: latex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate +# index for LaTeX. +# The default file is: makeindex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES doxygen generates more compact LaTeX +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used by the +# printer. +# Possible values are: a4 (210 x 297 mm), letter (8.5 x 11 inches), legal (8.5 x +# 14 inches) and executive (7.25 x 10.5 inches). +# The default value is: a4. +# This tag requires that the tag GENERATE_LATEX is set to YES. + PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names +# that should be included in the LaTeX output. To get the times font for +# instance you can specify +# EXTRA_PACKAGES=times +# If left blank no extra packages will be included. +# This tag requires that the tag GENERATE_LATEX is set to YES. + EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for the +# generated LaTeX document. The header should contain everything until the first +# chapter. If it is left blank doxygen will generate a standard header. See +# section "Doxygen usage" for information on how to let doxygen write the +# default header to a separate file. +# +# Note: Only use a user-defined header if you know what you are doing! The +# following commands have a special meaning inside the header: $title, +# $datetime, $date, $doxygenversion, $projectname, $projectnumber. Doxygen will +# replace them by respectively the title of the page, the current date and time, +# only the current date, the version number of doxygen, the project name (see +# PROJECT_NAME), or the project number (see PROJECT_NUMBER). +# This tag requires that the tag GENERATE_LATEX is set to YES. + LATEX_HEADER = + +# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the +# generated LaTeX document. The footer should contain everything after the last +# chapter. If it is left blank doxygen will generate a standard footer. +# +# Note: Only use a user-defined footer if you know what you are doing! +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_FOOTER = + +# The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the LATEX_OUTPUT output +# directory. Note that the files will be copied as-is; there are no commands or +# markers available. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_FILES = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated is +# prepared for conversion to PDF (using ps2pdf or pdflatex). The PDF file will +# contain links (just like the HTML output) instead of page references. This +# makes the output suitable for online browsing using a PDF viewer. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. + PDF_HYPERLINKS = YES + +# If the LATEX_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate +# the PDF file directly from the LaTeX files. Set this option to YES to get a +# higher quality PDF documentation. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. + USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode +# command to the generated LaTeX files. This will instruct LaTeX to keep running +# if errors occur, instead of asking the user for help. This option is also used +# when generating formulas in HTML. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + LATEX_BATCHMODE = NO + +# If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the +# index chapters (such as File Index, Compound Index, etc.) in the output. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + LATEX_HIDE_INDICES = NO + +# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source +# code with syntax highlighting in the LaTeX output. +# +# Note that which sources are shown also depends on other settings such as +# SOURCE_BROWSER. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_SOURCE_CODE = NO + +# The LATEX_BIB_STYLE tag can be used to specify the style to use for the +# bibliography, e.g. plainnat, or ieeetr. See +# http://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# The default value is: plain. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_BIB_STYLE = plain + +#--------------------------------------------------------------------------- +# Configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES doxygen will generate RTF output. The +# RTF output is optimized for Word 97 and may not look too pretty with other RTF +# readers/editors. +# The default value is: NO. + GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: rtf. +# This tag requires that the tag GENERATE_RTF is set to YES. + RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES doxygen generates more compact RTF +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated will +# contain hyperlink fields. The RTF file will contain links (just like the HTML +# output) instead of page references. This makes the output suitable for online +# browsing using Word or some other Word compatible readers that support those +# fields. +# +# Note: WordPad (write) and others do not support links. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's config +# file, i.e. a series of assignments. You only have to provide replacements, +# missing definitions are set to their default value. +# +# See also section "Doxygen usage" for information on how to generate the +# default style sheet that doxygen normally uses. +# This tag requires that the tag GENERATE_RTF is set to YES. + RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an RTF document. Syntax is +# similar to doxygen's config file. A template extensions file can be generated +# using doxygen -e rtf extensionFile. +# This tag requires that the tag GENERATE_RTF is set to YES. + RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# Configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES doxygen will generate man pages for +# classes and files. +# The default value is: NO. + GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. A directory man3 will be created inside the directory specified by +# MAN_OUTPUT. +# The default directory is: man. +# This tag requires that the tag GENERATE_MAN is set to YES. + MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to the generated +# man pages. In case the manual section does not start with a number, the number +# 3 is prepended. The dot (.) at the beginning of the MAN_EXTENSION tag is +# optional. +# The default value is: .3. +# This tag requires that the tag GENERATE_MAN is set to YES. + MAN_EXTENSION = .3 + +# The MAN_SUBDIR tag determines the name of the directory created within +# MAN_OUTPUT in which the man pages are placed. If defaults to man followed by +# MAN_EXTENSION with the initial . removed. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_SUBDIR = + +# If the MAN_LINKS tag is set to YES and doxygen generates man output, then it +# will generate one additional man file for each entity documented in the real +# man page(s). These additional files only source the real man page, but without +# them the man command would be unable to find the correct page. +# The default value is: NO. +# This tag requires that the tag GENERATE_MAN is set to YES. + MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# Configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES doxygen will generate an XML file that +# captures the structure of the code including all documentation. +# The default value is: NO. + GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: xml. +# This tag requires that the tag GENERATE_XML is set to YES. + XML_OUTPUT = xml -XML_SCHEMA = -XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program +# listings (including syntax highlighting and cross-referencing information) to +# the XML output. Note that enabling this will significantly increase the size +# of the XML output. +# The default value is: YES. +# This tag requires that the tag GENERATE_XML is set to YES. + XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# Configuration options related to the DOCBOOK output +#--------------------------------------------------------------------------- + +# If the GENERATE_DOCBOOK tag is set to YES doxygen will generate Docbook files +# that can be used to generate PDF. +# The default value is: NO. + +GENERATE_DOCBOOK = NO + +# The DOCBOOK_OUTPUT tag is used to specify where the Docbook pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be put in +# front of it. +# The default directory is: docbook. +# This tag requires that the tag GENERATE_DOCBOOK is set to YES. + +DOCBOOK_OUTPUT = docbook + +#--------------------------------------------------------------------------- +# Configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES doxygen will generate an AutoGen +# Definitions (see http://autogen.sf.net) file that captures the structure of +# the code including all documentation. Note that this feature is still +# experimental and incomplete at the moment. +# The default value is: NO. + GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# Configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES doxygen will generate a Perl module +# file that captures the structure of the code including all documentation. +# +# Note that this feature is still experimental and incomplete at the moment. +# The default value is: NO. + GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES doxygen will generate the necessary +# Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI +# output from the Perl module output. +# The default value is: NO. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be nicely +# formatted so it can be parsed by a human reader. This is useful if you want to +# understand what is going on. On the other hand, if this tag is set to NO the +# size of the Perl module output will be much smaller and Perl will parse it +# just the same. +# The default value is: YES. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file are +# prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. This is useful +# so different doxyrules.make files included by the same Makefile don't +# overwrite each other's variables. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + PERLMOD_MAKEVAR_PREFIX = -ENABLE_PREPROCESSING = YES + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES doxygen will evaluate all +# C-preprocessor directives found in the sources and include files. +# The default value is: YES. + +ENABLE_PREPROCESSING = NO + +# If the MACRO_EXPANSION tag is set to YES doxygen will expand all macro names +# in the source code. If set to NO only conditional compilation will be +# performed. Macro expansion can be done in a controlled way by setting +# EXPAND_ONLY_PREDEF to YES. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then +# the macro expansion is limited to the macros specified with the PREDEFINED and +# EXPAND_AS_DEFINED tags. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + EXPAND_ONLY_PREDEF = NO -SEARCH_INCLUDES = YES + +# If the SEARCH_INCLUDES tag is set to YES the includes files in the +# INCLUDE_PATH will be searched if a #include is found. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +SEARCH_INCLUDES = NO + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by the +# preprocessor. +# This tag requires that the tag SEARCH_INCLUDES is set to YES. + INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will be +# used. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that are +# defined before the preprocessor is started (similar to the -D option of e.g. +# gcc). The argument of the tag is a list of macros of the form: name or +# name=definition (no spaces). If the definition and the "=" are omitted, "=1" +# is assumed. To prevent a macro definition from being undefined via #undef or +# recursively expanded use the := operator instead of the = operator. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this +# tag can be used to specify a list of macro names that should be expanded. The +# macro definition that is found in the sources will be used. Use the PREDEFINED +# tag if you want to use a different macro definition that overrules the +# definition found in the source code. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will +# remove all references to function-like macros that are alone on a line, have +# an all uppercase name, and do not end with a semicolon. Such function macros +# are typically used for boiler-plate code, and will confuse the parser if not +# removed. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration options related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES tag can be used to specify one or more tag files. For each tag +# file the location of the external documentation should be added. The format of +# a tag file without this location is as follows: +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where loc1 and loc2 can be relative or absolute paths or URLs. See the +# section "Linking to external documentation" for more information about the use +# of tag files. +# Note: Each tag file must have a unique name (where the name does NOT include +# the path). If a tag file is not located in the directory in which doxygen is +# run, you must also specify the path to the tagfile here. + TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create a +# tag file that is based on the input files it reads. See section "Linking to +# external documentation" for more information about the usage of tag files. + GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external class will be listed in the +# class index. If set to NO only the inherited external classes will be listed. +# The default value is: NO. + ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed in +# the modules index. If set to NO, only the current project's groups will be +# listed. +# The default value is: YES. + EXTERNAL_GROUPS = YES + +# If the EXTERNAL_PAGES tag is set to YES all external pages will be listed in +# the related pages index. If set to NO, only the current project's pages will +# be listed. +# The default value is: YES. + +EXTERNAL_PAGES = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of 'which perl'). +# The default file (with absolute path) is: /usr/bin/perl. + PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES doxygen will generate a class diagram +# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to +# NO turns the diagrams off. Note that this option also works with HAVE_DOT +# disabled, but it is recommended to install and use dot, since it yields more +# powerful graphs. +# The default value is: YES. + CLASS_DIAGRAMS = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see: +# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# You can include diagrams made with dia in doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. + +DIA_PATH = + +# If set to YES, the inheritance and collaboration graphs will hide inheritance +# and usage relations if the target is undocumented or is not a class. +# The default value is: YES. + HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz (see: +# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# Bell Labs. The other options in this section have no effect if this option is +# set to NO +# The default value is: NO. + HAVE_DOT = NO + +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed +# to run in parallel. When set to 0 doxygen will base this on the number of +# processors available in the system. You can set it explicitly to a value +# larger than 0 to get control over the balance between CPU load and processing +# speed. +# Minimum value: 0, maximum value: 32, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_NUM_THREADS = 0 + +# When you want a differently looking font n the dot files that doxygen +# generates you can specify the font name using DOT_FONTNAME. You need to make +# sure dot is able to find the font, which can be done by putting it in a +# standard location or by setting the DOTFONTPATH environment variable or by +# setting DOT_FONTPATH to the directory containing the font. +# The default value is: Helvetica. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTNAME = Helvetica + +# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of +# dot graphs. +# Minimum value: 4, maximum value: 24, default value: 10. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the default font as specified with +# DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set +# the path where dot can find it using this tag. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTPATH = + +# If the CLASS_GRAPH tag is set to YES then doxygen will generate a graph for +# each documented class showing the direct and indirect inheritance relations. +# Setting this tag to YES will force the CLASS_DIAGRAMS tag to NO. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + CLASS_GRAPH = NO + +# If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a +# graph for each documented class showing the direct and indirect implementation +# dependencies (inheritance, containment, and class references variables) of the +# class with other documented classes. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + COLLABORATION_GRAPH = YES + +# If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for +# groups, showing the direct groups dependencies. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + UML_LOOK = NO + +# If the UML_LOOK tag is enabled, the fields and methods are shown inside the +# class node. If there are many fields or methods and many nodes the graph may +# become too big to be useful. The UML_LIMIT_NUM_FIELDS threshold limits the +# number of items for each type to make the size more manageable. Set this to 0 +# for no limit. Note that the threshold may be exceeded by 50% before the limit +# is enforced. So when you set the threshold to 10, up to 15 fields may appear, +# but if the number exceeds 15, the total amount of fields shown is limited to +# 10. +# Minimum value: 0, maximum value: 100, default value: 10. +# This tag requires that the tag HAVE_DOT is set to YES. + +UML_LIMIT_NUM_FIELDS = 10 + +# If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and +# collaboration graphs will show the relations between templates and their +# instances. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + TEMPLATE_RELATIONS = NO + +# If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to +# YES then doxygen will generate a graph for each documented file showing the +# direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + INCLUDE_GRAPH = NO + +# If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are +# set to YES then doxygen will generate a graph for each documented file showing +# the direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH tag is set to YES then doxygen will generate a call +# dependency graph for every global function or class method. +# +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable call graphs for selected +# functions only using the \callgraph command. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + CALL_GRAPH = YES + +# If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller +# dependency graph for every global function or class method. +# +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable caller graphs for selected +# functions only using the \callergraph command. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical +# hierarchy of all classes instead of a textual one. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the +# dependencies a directory has on other directories in a graphical way. The +# dependency relations are determined by the #include relations between the +# files in the directories. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. +# Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order +# to make the SVG files visible in IE 9+ (other browsers do not have this +# requirement). +# Possible values are: png, jpg, gif and svg. +# The default value is: png. +# This tag requires that the tag HAVE_DOT is set to YES. + DOT_IMAGE_FORMAT = png + +# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to +# enable generation of interactive SVG images that allow zooming and panning. +# +# Note that this requires a modern browser other than Internet Explorer. Tested +# and working are Firefox, Chrome, Safari, and Opera. +# Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make +# the SVG files visible. Older versions of IE do not have SVG support. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +INTERACTIVE_SVG = NO + +# The DOT_PATH tag can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. +# This tag requires that the tag HAVE_DOT is set to YES. + DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the \dotfile +# command). +# This tag requires that the tag HAVE_DOT is set to YES. + DOTFILE_DIRS = -MAX_DOT_GRAPH_WIDTH = 750 -MAX_DOT_GRAPH_HEIGHT = 1024 + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). + +MSCFILE_DIRS = + +# The DIAFILE_DIRS tag can be used to specify one or more directories that +# contain dia files that are included in the documentation (see the \diafile +# command). + +DIAFILE_DIRS = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes +# that will be shown in the graph. If the number of nodes in a graph becomes +# larger than this value, doxygen will truncate the graph, which is visualized +# by representing a node as a red box. Note that doxygen if the number of direct +# children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note that +# the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. +# Minimum value: 0, maximum value: 10000, default value: 50. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs +# generated by dot. A depth value of 3 means that only nodes reachable from the +# root by following a path via at most 3 edges will be shown. Nodes that lay +# further from the root node will be omitted. Note that setting this option to 1 +# or 2 may greatly reduce the computation time needed for large code bases. Also +# note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. +# Minimum value: 0, maximum value: 1000, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. + MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not seem +# to support this out of the box. +# +# Warning: Depending on the platform used, enabling this option may lead to +# badly anti-aliased labels on the edges of a graph (i.e. they become hard to +# read). +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_TRANSPARENT = NO + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) support +# this, this feature is disabled by default. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page +# explaining the meaning of the various boxes and arrows in the dot generated +# graphs. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES doxygen will remove the intermediate dot +# files that are used to generate the various graphs. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + DOT_CLEANUP = YES -SEARCHENGINE = NO diff --git a/Makefile.in b/Makefile.in index 6634c94f..bfaa1046 100644 --- a/Makefile.in +++ b/Makefile.in @@ -148,6 +148,11 @@ HDR_FILES := $(HDR_FILES_SRC:.hdr.in=.hdr) HELP_SRC := $(wildcard doc_src/*.txt) +# +# HTML includes needed for HTML help +# + +HTML_SRC := doc_src/user_doc.header.html doc_src/user_doc.footer.html doc_src/user_doc.css # # Files in the test directory @@ -252,18 +257,19 @@ prof: all # Depend on the sources (*.hdr.in) and manually make the # intermediate *.hdr and doc.h files if needed # The sed command deletes everything including and after the first -, for simpler version numbers +# Cleans up the user_doc/html directory once Doxygen is done. -user_doc: $(HDR_FILES_SRC) Doxyfile.user user_doc.head.html $(HELP_SRC) doc.h $(HDR_FILES) - (cat Doxyfile.user ; echo PROJECT_NUMBER=$(FISH_BUILD_VERSION) | sed "s/-.*//") | doxygen - && touch user_doc - - +user_doc: $(HDR_FILES_SRC) Doxyfile.user $(HTML_SRC) $(HELP_SRC) doc.h $(HDR_FILES) lexicon_filter + (cat Doxyfile.user; echo INPUT_FILTER=./lexicon_filter; \ + echo PROJECT_NUMBER=$(FISH_BUILD_VERSION) | sed "s/-.*//") | doxygen - && touch user_doc; \ + cd user_doc/html && rm -f bc_s.png bdwn.png closed.png ftv2*.png nav*.png open.png sync_*.png tab*.* doxygen.* dynsections.js jquery.js pages.html # # Source code documentation. Also includes user documentation. # -doc: *.h *.cpp doc.h Doxyfile - (cat Doxyfile ; echo PROJECT_NUMBER=$(FISH_BUILD_VERSION)) | doxygen - ; +doc: *.h *.cpp doc.h Doxyfile lexicon_filter + (cat Doxyfile; echo INPUT_FILTER=./lexicon_filter; echo PROJECT_NUMBER=$(FISH_BUILD_VERSION)) | doxygen - ; # @@ -271,10 +277,9 @@ doc: *.h *.cpp doc.h Doxyfile # doc/refman.pdf: doc - cd doc/latex; - make; + cd doc/latex && \ + make && \ mv refman.pdf ..; - cd ../..; rm -r doc/latex; @@ -343,11 +348,67 @@ toc.txt: $(HDR_FILES:index.hdr=index.hdr.in) doc_src/index.hdr: toc.txt doc_src/index.hdr.in cat $@.in | awk '{if ($$0 ~ /@toc@/){ system("cat toc.txt");} else{ print $$0;}}' >$@ +# +# To enable the lexicon filter, we first need to be aware of what fish +# considers to be a command, function, or external binary. We use +# command_list_toc.txt for the base commands. Scan the share/functions +# directory for other functions, some of which are mentioned in the docs, and +# use /share/completions to find a good selection of binaries. Additionally, +# colour defaults from __fish_config_interactive to set the docs colours when +# used in a 'cli' style context. +# + +lexicon.txt: doc_src/commands.hdr $(FUNCTIONS_DIR_FILES) $(COMPLETIONS_DIR_FILES) share/functions/__fish_config_interactive.fish + -rm lexicon.tmp lexicon_catalog.tmp lexicon_catalog.txt $@ + # Scan sources for commands/functions/binaries/colours. If GNU sed was portable, this could be much smarter. + sed <command_list_toc.txt >>lexicon.tmp -n \ + -e "s|^.*>\([a-z][a-z_]*\)</a>|'\1'|w lexicon_catalog.tmp" \ + -e "s|'\(.*\)'|bltn \1|p"; mv lexicon_catalog.tmp lexicon_catalog.txt; \ + printf "%s\n" $(COMPLETIONS_DIR_FILES) | sed -n \ + -e "s|[^ ]*/\([a-z][a-z_-]*\).fish|'\1'|p" | fgrep -vx -f lexicon_catalog.txt | sed >>lexicon.tmp -n \ + -e 'w lexicon_catalog.tmp' \ + -e "s|'\(.*\)'|cmnd \1|p"; cat lexicon_catalog.tmp >> lexicon_catalog.txt; \ + printf "%s\n" $(FUNCTIONS_DIR_FILES) | sed -n \ + -e "s|[^ ]*/\([a-z][a-z_-]*\).fish|'\1'|p" | fgrep -vx -f lexicon_catalog.txt | sed >>lexicon.tmp -n \ + -e 'w lexicon_catalog.tmp' \ + -e "s|'\(.*\)'|func \1|p"; \ + sed <share/functions/__fish_config_interactive.fish >>lexicon.tmp -n \ + -e '/set_default/s/.*\(fish_[a-z][a-z_]*\).*$$/clrv \1/p'; \ + sed <lexicon_filter.in >>lexicon.tmp -n \ + -e '/^#.!#/s/^#.!# \(.... [a-z][a-z_]*\)/\1/p'; \ + mv lexicon.tmp lexicon.txt; rm -f lexicon_catalog.tmp lexicon_catalog.txt; + +# +# Compile Doxygen Input Filter from the lexicon. This is an executable sed +# script as Doxygen opens it via popen()(3) Input (doc.h) is piped through and +# matching words inside /fish../endfish blocks are marked up, contextually, +# with custom Doxygen commands in the form of @word_type{content}. These are +# trapped by ALIASES in the various Doxyfiles, allowing the content to be +# transformed depending on output type (HTML, man page, developer docs). In +# HTML, a style context can be applied through the /fish{style} block and +# providing suitable CSS in user_doc.css.in +# + +lexicon_filter: lexicon.txt lexicon_filter.in + -rm $@.tmp $@ + # Clean the filter input comments and set the shebang as sed can reside in + # /bin or /usr/bin and some versions dont allow more than one comment!. + sed <$@.in >$@.tmp -e 's|@sed@|'"`which sed`"'|' -e '/^[ ]*#[^!]/d' + # Scan through the lexicon, transforming each line to something useful to Doxygen. + if echo x | sed "/[[:<:]]x/d" 2>/dev/null; then \ + WORDBL='[[:<:]]'; WORDBR='[[:>:]]'; \ + else \ + WORDBL='\<'; WORDBR='\>'; \ + fi; \ + sed <lexicon.txt >>$@.tmp -n \ + -e "s|^\([a-z][a-z][a-z][a-z]\) \([a-z_-]*\)$$|s,$$WORDBL\2$$WORDBR,@\1{\2},g|p" \ + -e '$$G;s/.*\n/b tidy/p'; \ + mv $@.tmp $@; if test -x $@; then true; else chmod a+x $@; fi # # doc.h is a compilation of the various snipptes of text used both for # the user documentation and for internal help functions into a single -# file that can be parsed dy Doxygen to generate the user +# file that can be parsed by Doxygen to generate the user # documentation. # @@ -445,11 +506,12 @@ common.o: $(COMMON_FILES) # There ought to be something simpler. # -share/man: $(HELP_SRC) +share/man: $(HELP_SRC) lexicon_filter -mkdir share/man touch share/man -rm -Rf share/man/man1 - PROJECT_NUMBER=`echo $(FISH_BUILD_VERSION)| sed "s/-.*//"` ./build_tools/build_documentation.sh Doxyfile.help ./doc_src ./share + PROJECT_NUMBER=`echo $(FISH_BUILD_VERSION)| sed "s/-.*//"` INPUT_FILTER=./lexicon_filter \ + ./build_tools/build_documentation.sh Doxyfile.help ./doc_src ./share # # The build rules for installing/uninstalling fish @@ -763,6 +825,7 @@ clean: rm -f $(PROGRAMS) fish_tests key_reader rm -f command_list.txt command_list_toc.txt toc.txt rm -f doc_src/index.hdr doc_src/commands.hdr + rm -f lexicon_filter lexicon.txt lexicon.log rm -f FISH-BUILD-VERSION-FILE if test "$(HAVE_DOXYGEN)" = 1; then \ rm -rf doc user_doc share/man; \ @@ -21,7 +21,7 @@ fish depends on a curses implementation, such as ncurses. The headers and librar fish requires gettext for translation support. -Building the documentation requires Doxygen 1.5 or newer. +Building the documentation requires Doxygen 1.8 or newer. ### Autotools Build diff --git a/build_tools/build_documentation.sh b/build_tools/build_documentation.sh index 0c4a2aac..77eaad68 100755 --- a/build_tools/build_documentation.sh +++ b/build_tools/build_documentation.sh @@ -37,10 +37,12 @@ resolve_path() # Expand relative paths DOXYFILE=`resolve_path "$DOXYFILE"` INPUTDIR=`resolve_path "$INPUTDIR"` +INPUTFILTER=`resolve_path "$INPUT_FILTER"` OUTPUTDIR=`resolve_path "$OUTPUTDIR"` echo " doxygen file: $DOXYFILE" echo " input directory: $INPUTDIR" +echo " input filter: $INPUTFILTER" echo " output directory: $OUTPUTDIR" echo " skipping: $CONDEMNED_PAGES" @@ -66,6 +68,12 @@ if test -z "$DOXYGENPATH"; then exit 0 fi +# Check we have the lexicon filter +if test -z "$INPUT_FILTER"; then + echo >&2 "Lexicon filter is not available. Continuing without." + INPUTFILTER='' +fi + # Determine where our output should go if ! mkdir -p "${OUTPUTDIR}" ; then echo "Could not create output directory '${OUTPUTDIR}'" @@ -87,6 +95,7 @@ done # This prevents doxygen from generating "documentation" for intermediate directories DOXYPARAMS=$(cat <<EOF PROJECT_NUMBER=$PROJECT_NUMBER +INPUT_FILTER=$INPUTFILTER INPUT=. OUTPUT_DIRECTORY=$OUTPUTDIR QUIET=YES @@ -100,7 +109,7 @@ find "${OUTPUTDIR}" -name "*.1" -delete # Run doxygen cd "$TMPLOC" -(cat "${DOXYFILE}" ; echo "$DOXYPARAMS";) | "$DOXYGENPATH" - +(cat "${DOXYFILE}" ; echo "$DOXYPARAMS";) | "$DOXYGENPATH" - # Remember errors RESULT=$? @@ -110,15 +119,16 @@ if test "$RESULT" = 0 ; then # Postprocess the files for i in "$INPUTDIR"/*.txt; do - # It would be nice to use -i here for edit in place, but that is not portable + # It would be nice to use -i here for edit in place, but that is not portable CMD_NAME=`basename "$i" .txt`; - sed -e "s/\(.\)\\.SH/\1/" -e "s/$CMD_NAME *\\\\- *\"\(.*\)\"/\1/" "${CMD_NAME}.1" > "${CMD_NAME}.1.tmp" + sed < ${CMD_NAME}.1 > ${CMD_NAME}.1.tmp \ + -e "/.SH \"$CMD_NAME/d" \ + -e "s/^$CMD_NAME * \\\- \([^ ]*\) /\\\fB\1\\\fP -/" mv "${CMD_NAME}.1.tmp" "${CMD_NAME}.1" done - + # Erase condemned pages rm -f $CONDEMNED_PAGES - fi # Destroy TMPLOC diff --git a/configure.ac b/configure.ac index 037ee8fa..43276ff2 100644 --- a/configure.ac +++ b/configure.ac @@ -146,7 +146,7 @@ AS_IF([test x$local_gettext != xno], # Build/clean the documentation only if Doxygen is available # -doxygen_minimum=1.5 +doxygen_minimum=1.8.7 AC_ARG_WITH( doxygen, diff --git a/doc_src/FORMATTING.md b/doc_src/FORMATTING.md new file mode 100644 index 00000000..0a44f355 --- /dev/null +++ b/doc_src/FORMATTING.md @@ -0,0 +1,262 @@ +# Formatting guide for fish docs + +The fish documentation has been updated to support Doxygen 1.8.7+, and while the main benefit of this change is extensive Markdown support, the addition of a fish lexicon and syntax filter, combined with semantic markup rules allows for automatic formatting enhancements across the HTML user_docs, the developer docs and the man pages. + +Initially my motivation was to fix a problem with long options ([Issue #1557](https://github.com/fish-shell/fish-shell/issues/1557) on GitHub), but as I worked on fixing the issue I realised there was an opportunity to simplify, reinforce and clarify the current documentation, hopefully making further contribution easier and cleaner, while allowing the documentation examples to presented more clearly with less author effort. + +While the documentation is pretty robust to variations in the documentation source, adherence to the following style guide will help keep the already excellent documention in good shape moving forward. + +## Line breaks and wrapping + +Contrary to the rest of the fish source code, the documentation greatly benefits from the use of long lines and soft wrapping. It allows paragraphs to be treated as complete blocks by Doxygen, means that the semantic filter can see complete lines when deciding on how to apply syntax highlighting, and means that man pages will consistently wrap to the width of the users console in advanced pagers, such as 'most'. + +## Doxygen special commands and aliases + +While Markdown syntax forms the basis of the documentation content, there are some exceptions that require the use of Doxygen special commands. On the whole, Doxygen commands should be avoided, especially inline word formatting such as \\c as this would allow Doxygen to make unhelpful assumptions, such as converting double dashes (\--) to n-dashes (–). + +### Structure: \\page, \\section and \\subsection + +Use of Doxygen sections markers are important, as these determine what will be eventually output as a web page, man page or included in the developer docs. + +Currently the make process for the documentation is quite convoluted, but basically the HTML docs are produced from a single, compiled file, doc.h. This contains a number of \\page markers that produce the various pages used in the documentation. The format of a \\page mark is: + + \page universally_unique_page_id Page title + +The source files that contain the page markers are currently: + +- __index.hdr.in__: Core documentation +- __commands.hdr.in__: Individual commands +- __tutorial.hdr__: Tutorial +- __design.hdr__: Design document +- __faq.hdr__: Frequently Asked Questions +- __license.hdr__: Fish and 3rd party licences + +Unless there is a _VERY_ good reason and developer consensus, new pages should never be added. + +The rest of the documentation is structured using \\section and \\subsection markers. Most of the source files (listed above) contain their full content, the exception being commands, which are separated out into source text files in the doc_src directory. These files are concatenated into one file, so each one starts with a \\section declaration. The synopsis, description and examples (if present) are declared as \\subsections. The format of these marks is practically identical to the page mark. + + \section universally_unique_section_id Section title + \subsection universally_unique_subsection_id Subsection title + +Each page, section and subsection id _must_ be unique across the whole of the documentation, otherwise Doxygen will issue a warning. + +### Semantic markup: the \\fish .. \\endfish block + +While Doxygen has support for \\code..\\endcode blocks with enhanced markup and syntax colouring, it only understands the core Doxygen languages: C, C++, Objective C, Java, PHP, Python, Tcl and Fortran. To enhance Fish's syntax presentation, use the special \\fish..\\endfish blocks instead. + +Text placed in this block will be parsed by Doxygen using the included lexicon filter (see lexicon_filter.in) as a Doxygen input filter. The filter is built during make so that it can pick up information on builtins, functions and shell commands mentioned in completions and apply markup to keywords found inside the \\fish block. + +Basically, preformatted plain text inside the \\fish block is fed through the filter and is returned marked up so that Doxygen aliases can convert it back to a presentable form, according to the output document type. + +For instance: + +`echo hello world` + +is transformed into: + +`@cmnd{echo} @args{hello} @args{world}` + +which is then transformed by Doxygen into an HTML version (`make user_doc`): + +`<span class="command">echo</span> <span class="argument">hello</span> <span class="argument">world</span>` + +A man page version (`make share/man`): + +__echo__ hello world + +And a simple HTML version for the developer docs (`make doc`) and the LATEX/PDF manual (`make doc/refman.pdf`): + +`echo hello world` + +### Fonts + +In older browsers, it was easy to set the fonts used for the three basic type styles (serif, sans-serif and monospace). Modern browsers have removed these options in their respective quests for simplification, assuming the content author will provide suitable styles for the content in the site's CSS, or the end user will provide overriding styles manually. Doxygen's default styling is very simple and most users will just accept this default. + +I've tried to use a sensible set of fonts in the documentation's CSS based on 'good' terminal fonts and as a result the firt preference font used throughout the documentation is '[DejaVu](http://dejavu-fonts.org)'. The rationale behaind this is that while DejaVu is getting a little long in the tooth, it still provides the most complete support across serif, sans-serif and monospace styles (giving a well balanced feel and consistent [x-height](http://en.wikipedia.org/wiki/X-height)), has the widest support for extended Unicode characters and has a free, permissive licenses (though it's still incompatible with GPLv2, though arguably less so than the SIL Open Font license, though this is a moot point when using it solely in the docs). + +#### Fonts inside \\fish blocks and \`backticks\` + +As the point of these contructs is to make fish's syntax clearer to the user, it makes sense to mimic what the user will see in the console, therefore any content is formatted using the monospaced style, specifically monospaced fonts are chosen in the following order: + +1. __DejaVu Sans Mono__: Explained above. [[↓](http://dejavu-fonts.org)] +2. __Source Code Pro__: Monospaced code font, part of Adobe's free Edge Web Fonts. [[↓](https://edgewebfonts.adobe.com)] +3. __Menlo__: Apple supplied variant of DejaVu. +4. __Ubuntu Mono__: Ubuntu Linux's default monospaced font. [[↓](http://font.ubuntu.com)] +5. __Consolas__: Modern Microsoft supplied console font. +6. __Monaco__: Apple supplied console font since 1984! +7. __Lucida Console__: Generic mono terminal font, standard in many OS's and distros. +8. __monospace__: Catchall style. Chooses default monospaced font, often Courier. +9. __fixed__: As above, more often used on mobile devices. + +#### General Fonts + +1. __DejaVu Sans__: As above.[[↓](http://dejavu-fonts.org)] +2. __Roboto__: Elegant Google free font and is Doxygen's default [[↓](http://www.google.com/fonts/specimen/Roboto)] +3. __Lucida Grande__: Default Apple OS X content font. +4. __Calibri__: Default Microsoft Office font (since 2007). +5. __Verdana__: Good general font found in a lot of OSs. +6. __Helvetica Neue__: Better spaced and balanced Helvetica/Arial variant. +7. __Helvetica__: Standard humanist typeface found almost everywhere. +8. __Arial__: Microsoft's Helvetica. +9. __sans-serif__: Catchall style. Chooses default sans-serif typeface, often Helvetica. + +The ordering of the fonts is important as it's designed to allow the documentation to settle into a number of different identities according to the fonts available. If you have the complete DejaVu family installed, then the docs are presented using that, and if your Console is set up to use the same fonts, presentation will be completely consistent. + +On OS X, with nothing extra installed, the docs will default to Menlo and Lucida Grande giving a Mac feel. Under Windows, it will default to using Consolas and Calibri on recent versions, giving a modern Windows style. + +#### Other sources: + +- [Font Squirrel](http://www.fontsquirrel.com): Good source of open source font packages. + +### Choosing a CLI style: using a \\fish{style} block + +By default, when output as HTML, a \\fish block uses syntax colouring suited to the style of the documentation rather than trying to mimic the terminal. The block has a light, bordered background and a colour scheme that 'suggests' what the user would see in a console. + +Additional stying can be applied adding a style declaration: + + \fish{additional_style [another_style...]} + ... + \endfish + +This will translate to classes applied to the `<div>` tag, like so: + + <div class="fish additional_style another_style"> + ... + </div> + +The various classes are defined in `doc_src/user_doc.css` and new style can be simply added + +The documentation currently defines a couple of additional styles: + +- __cli-dark__: Used in the _tutorial_ and _FAQ_ to simulate a dark background terminal, with fish's default colours (slightly tweaked for legibility in the browser). + +- __synopsis__: A simple colour theme helpful for displaying the logical 'summary' of a command's syntax, options and structure. + +## Markdown + +Apart from the exceptions discussed above, the rest of the documentation now supports the use of Markdown. As such the use of Doxygen special commands for HTML tags is unnecessary. + +There are a few exceptions and extensions to the Markdown [standard](http://daringfireball.net/projects/markdown/) that are documented in the Doxygen [documentation](http://www.stack.nl/~dimitri/doxygen/manual/markdown.html). + +### \`Backticks\` + +As is standard in Markdown and 'Github Flavoured Markdown' (GFM), backticks can be used to denote inline technical terms in the documentation, `like so`. In the documentation this will set the font to the monospaced 'console' typeface and will cause the enclosed term to stand out. + +However, fenced code blocks using 4 spaces or 3 backticks (\`\`\`) should be avoided as Doxygen will interpret these as \\code blocks and try to apply standard syntax colouring, which doesn't work so well for fish examples. Use `\fish..\endfish` blocks instead. + +### Lists + +Standard Markdown list rules apply, but as Doxygen will collapse white space on output, combined with the use of long lines, it's a good idea to include an extra new line between long list items to assist future editing. + +## Special cases + +The following can be used in \\fish blocks to render some fish scenarios. These are mostly used in the tutorial when an interactive situation needs to be displayed. + +### Custom formatting tags + +- `<s>`: auto\<s\>suggestion\</s\>. +- `<m>`: \<m\>Matched\</m\> items, such as tab completions. +- `<sm>`: Matched items \<sm\>searched\<sm\> for, like grep results. +- `<error>`: \<error\>This would be shown as an error.\</error\> +- `<asis>`: \<asis\>This test will not be parsed for fish markup.\</asis\> +- `<outp>`: \<outp\>This would be rendered as command/script output.\</outp\> + +### Prompts and cursors + +- `>_`: Display a basic prompt. +- `~>_`: Display a prompt with a the home directory as the current working directory. +- `___` (3 underscores): Display a cursor. + + +### Keyboard shortcuts: @key{} and @cursor_key{} + +Graphical keyboard shortcuts can be defined using the following special commands. These allow for the different text requirements across the html and man pages. The HTML uses CSS to create a keyboard style, whereas the man page would display the key as text. + +- `@key{lable}` + Displays a key with a purely textual lable, such as: 'Tab', 'Page Up', 'Page Down', 'Home', 'End', 'F1', 'F19' and so on. + +- `@key{modifier,lable}` + Displays a keystroke requiring the use of a 'modifier' key, such as 'Control-A', 'Shift-X', 'Alt-Tab' etc. + +- `@key{modifier,entity,lable}` + Displays a keystroke using a graphical entity, such as an arrow symbol for cursor key based shortcuts. + +- `@cursor_key{entity,lable}` + A special case for cursor keys, when no modifier is needed. i.e. `@cursor_key{↑,up}` for the up arrow key. + +Some useful Unicode/HTML5 entities: + +- Up arrow: `↑` +- Down arrow: `↓` +- Left arrow: `←` +- Right arrow `→` +- Shift: `⇧` +- Tab: `⇥` +- Mac option: `⌥` +- Mac command: `⌘` + +## Notes + +### Doxygen + +Tested on: +- Ubuntu 14.04 with Doxygen 1.8.8, built from [GitHub source](https://github.com/doxygen/doxygen.git). +- CentOS 6.5 with Doxygen 1.8.8, built from [GitHub source](https://github.com/doxygen/doxygen.git). +- Mac OS X 10.9 with Homebrew install Doxygen 1.8.7 and 1.8.8. + +Graphviz was also installed in all the above testing. + +Doxygen 1.8.6 and lower do not have the \\htmlonly[block] directive which fixes a multitude of problems in the rendering of the docs. In Doxygen 1.8.7 the list of understood HTML entities was greatly increased. I tested earlier versions and many little issues returned. + +As fish ships with pre-built documentation, I don't see this as an issue. + +### Updated Configure/Makefile + +- Tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9. +- Makefile has GNU/BSD sed/grep detection. + +### HTML output + +- The output HTML is HTML5 compliant, but should quickly and elegantly degrade on older browsers without losing basic structure. +- The CSS avoids the use or browser specific extenstions (i.e. -webkit, -moz etc), using the W3C HTML5 standard instead. +- It's been tested in Chrome 37.0 and Firefox 32.0 on Mac OS X 10.9 (+Safari 7), Windows 8.1 (+Internet Explorer 11) and Ubuntu Desktop 14.04. +- My assumption is basically that if someone cares enough to want to install fish, they'll be keeping a browser current. + +### Man page output + +- Tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9. +- Output is substantially cleaner. +- Tested in cat, less, more and most pagers using the following fish script: + +``` +function manTest --description 'Test manpage' --argument page + set -l pager + for i in $argv + switch $i + case "-l" + set pager -P '/usr/bin/less -is' + case "-m" + set pager -P '/usr/bin/more -s' + case "-c" + set pager -P '/bin/cat' + end + end + man $pager ~/Projects/OpenSource/fish-shell/share/man/man1/$page.1 +end + +# Assumes 'most' is the default system pager. +# NOT PORTABLE! Paths would be need to be updated on other systems. +``` + +### Developer docs and LATEX/PDF output + +- HTML developer docs tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9. +- LATEX/PDF reference manual tested on Mac OS X 10.9 using MacTEX. PDF production returns an error (due to Doxygen's use of an outdated 'float' package), but manual PDF output is ok. + +### Future changes + +1. The documentation creation process would be better if it could be modularised further and moved out of the makefile into a number of supporting scripts. This would allow both the automake and Xcode build processes to use the documentation scripts directly. +2. Remove the Doxygen dependency entirely for the user documentation. This would be very acheivable now that the bulk of the documentation is in Markdown. +3. It would be useful to gauge what parts of the documentation are actually used by users. Judging by the amount of 'missing comment' errors during the developer docs build phase, this aspect of the docs has been rather neglected. If it is not longer used or useful, then this could change the future direction of the documentation and significantly streamline the process. + +#### Author: Mark Griffiths [@GitHub](https://github.com/MarkGriffiths) diff --git a/doc_src/alias.txt b/doc_src/alias.txt index 84288c18..028277a3 100644 --- a/doc_src/alias.txt +++ b/doc_src/alias.txt @@ -1,34 +1,34 @@ \section alias alias - create a function \subsection alias-synopsis Synopsis -<pre>alias NAME DEFINITION -alias NAME=DEFINITION</pre> +\fish{synopsis} +alias NAME DEFINITION +alias NAME=DEFINITION +\endfish \subsection alias-description Description -\c alias is a simple wrapper for the \c function builtin. -It exists for backwards compatibility with Posix -shells. For other uses, it is recommended to define a <a -href='#function'>function</a>. +`alias` is a simple wrapper for the `function` builtin. It exists for backwards compatibility with Posix shells. For other uses, it is recommended to define a <a href='#function'>function</a>. -\c fish does not keep track of which functions have been defined using -\c alias. They must be erased using <code>functions -e</code>. +`fish` does not keep track of which functions have been defined using `alias`. They must be erased using `functions -e`. -- NAME is the name of the alias -- DEFINITION is the actual command to execute. The string " $argv" will be appended. +- `NAME` is the name of the alias + +- `DEFINITION` is the actual command to execute. The string `$argv` will be appended. You cannot create an alias to a function with the same name. + \subsection alias-example Example -The following code will create \c rmi, which runs \c rm with additional -arguments on every invocation. +The following code will create `rmi`, which runs `rm` with additional arguments on every invocation. -<code>alias rmi "rm -i"</code> +\fish +alias rmi "rm -i" -This is equivalent to entering the following function: +# This is equivalent to entering the following function: -<pre>function rmi +function rmi rm -i $argv -end</pre> - +end +\endfish diff --git a/doc_src/and.txt b/doc_src/and.txt index 3eb42c19..0b4f681d 100644 --- a/doc_src/and.txt +++ b/doc_src/and.txt @@ -1,27 +1,24 @@ \section and and - conditionally execute a command \subsection and-synopsis Synopsis -<tt>COMMAND1; and COMMAND2</tt> +\fish{synopsis} +COMMAND1; and COMMAND2 +\endfish \subsection and-description Description -\c and is used to execute a command if the current exit -status (as set by the last previous command) is 0. +`and` is used to execute a command if the current exit status (as set by the last previous command) is 0. -\c and does not change the current exit status. +`and` does not change the current exit status. + +The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable. -The exit status of the last foreground command to exit can always be -accessed using the <a href="index.html#variables-status">$status</a> -variable. \subsection and-example Example -The following code runs the \c make command to build a program. If the -build succeeds, <code>make</code>'s exit status is 0, and the program is installed. If either step fails, -the exit status is 1, and <tt>make clean</tt> is run, which removes the files created by the. -build process. +The following code runs the `make` command to build a program. If the build succeeds, `make`'s exit status is 0, and the program is installed. If either step fails, the exit status is 1, and `make clean` is run, which removes the files created by the build process. -<pre> +\fish make; and make install; or make clean -</pre> +\endfish diff --git a/doc_src/ascii_fish.png b/doc_src/ascii_fish.png Binary files differnew file mode 100644 index 00000000..33765a4a --- /dev/null +++ b/doc_src/ascii_fish.png diff --git a/doc_src/begin.txt b/doc_src/begin.txt index fafe9849..6d18a606 100644 --- a/doc_src/begin.txt +++ b/doc_src/begin.txt @@ -1,49 +1,45 @@ \section begin begin - start a new block of code \subsection begin-synopsis Synopsis - <tt>begin; [COMMANDS...;] end</tt> +\fish{synopsis} +begin; [COMMANDS...;] end +\endfish \subsection begin-description Description -\c begin is used to create a new block of code. +`begin` is used to create a new block of code. -The block -is unconditionally executed. <code>begin; ...; end</tt> is equivalent -to <tt>if true; ...; end</tt>. +The block is unconditionally executed. `begin; ...; end` is equivalent to `if true; ...; end`. -\c begin is used to group a number of commands into a block. -This allows the introduction of a new variable scope, redirection of the input or -output of a set of commands as a group, or to specify precedence when -using the conditional commands like \c and. +`begin` is used to group a number of commands into a block. This allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like `and`. + +`begin` does not change the current exit status. -\c begin does not change the current exit status. \subsection begin-example Example -The following code sets a number of variables inside of a block -scope. Since the variables are set inside the block and have local -scope, they will be automatically deleted when the block ends. +The following code sets a number of variables inside of a block scope. Since the variables are set inside the block and have local scope, they will be automatically deleted when the block ends. -<pre> +\fish begin - set -l PIRATE Yarrr - ... + set -l PIRATE Yarrr + ... end -# This will not output anything, since the PIRATE variable went out -# of scope at the end of the block + echo $PIRATE -</pre> +# This will not output anything, since the PIRATE variable +# went out of scope at the end of the block +\endfish In the following code, all output is redirected to the file out.html. -<pre> +\fish begin - echo $xml_header - echo $html_header - if test -e $file - ... - end - ... - -end > out.html -</pre> + echo $xml_header + echo $html_header + if test -e $file + ... + end + ... +end > out.html +\endfish diff --git a/doc_src/bg.txt b/doc_src/bg.txt index 9c8f593a..8e9ec244 100644 --- a/doc_src/bg.txt +++ b/doc_src/bg.txt @@ -1,17 +1,17 @@ \section bg bg - send jobs to background \subsection bg-synopsis Synopsis -<tt>bg [PID...]</tt> +\fish{synopsis} +bg [PID...] +\endfish \subsection bg-description Description -\c bg sends <a href="index.html#syntax-job-control">jobs</a> to the background, resuming them if they are stopped. A background job is -executed simultaneously with fish, and does not have access to the -keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background. +`bg` sends <a href="index.html#syntax-job-control">jobs</a> to the background, resuming them if they are stopped. A background job is executed simultaneously with fish, and does not have access to the keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background. The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>. -\subsection bg-example Example -<tt>bg \%1</tt> will put the job with job ID 1 in the background. +\subsection bg-example Example +`bg %1` will put the job with job ID 1 in the background. diff --git a/doc_src/bind.txt b/doc_src/bind.txt index 8c7004d0..ff262ec6 100644 --- a/doc_src/bind.txt +++ b/doc_src/bind.txt @@ -1,97 +1,101 @@ \section bind bind - handle fish key bindings \subsection bind-synopsis Synopsis -<tt>bind [OPTIONS] SEQUENCE COMMAND</tt> +\fish{synopsis} +bind [OPTIONS] SEQUENCE COMMAND +\endfish \subsection bind-description Description -<tt>bind</tt> adds a binding for the specified key sequence to the +`bind` adds a binding for the specified key sequence to the specified command. -SEQUENCE is the character sequence to bind to. These should be written as -<a href="index.html#escapes">fish escape sequences</a>. For example, because pressing -the Alt key and another character sends that character prefixed with -an escape character, Alt-based key bindings can be written using the -\c \\e escape. For example, Alt-w can be written as -<tt>\\ew</tt>. The control character can be written in much the same way -using the \c \\c escape, for example Control-x (^X) can be written as -<tt>\\cx</tt>. Note that Alt-based key bindings are case sensitive and -Control-based key bindings are not. This is a constraint of text-based -terminals, not \c fish. - -The default key binding can be set by specifying a SEQUENCE of the empty -string (that is, <code>''</code>). It will be used whenever no -other binding matches. For most key bindings, it makes sense to use -the \c self-insert function (i.e. <tt>bind '' self-insert</tt> as the -default keybinding. This will insert any keystrokes not specifically -bound to into the editor. Non-printable characters are ignored by the -editor, so this will not result in control sequences being -printable. - -If the -k switch is used, the name of the key (such as down, up or -backspace) is used instead of a sequence. The names used are the same -as the corresponding curses variables, but without the 'key_' -prefix. (See \c terminfo(5) for more information, or use <tt>bind ---key-names</tt> for a list of all available named keys.) - -COMMAND can be any fish command, but it can also be one of a set of -special input functions. These include functions for moving the -cursor, operating on the kill-ring, performing tab completion, -etc. Use 'bind --function-names' for a complete list of these input -functions. - -When COMMAND is a shellscript command, it is a good practice to put -the actual code into a <a href="#function">function</a> and simply -bind to the function name. This way it becomes significantly easier to -test the function while editing, and the result is usually more -readable as well. - -If such a script produces output, the script needs to finish by -calling 'commandline -f repaint' in order to tell fish that a repaint -is in order. - -Key bindings are not saved between sessions by default. To save custom -keybindings, edit the \c fish_user_key_bindings function and insert the -appropriate \c bind statements. +SEQUENCE is the character sequence to bind to. These should be written as <a href="index.html#escapes">fish escape sequences</a>. For example, because pressing the Alt key and another character sends that character prefixed with an escape character, Alt-based key bindings can be written using the `\e` escape. For example, @key{Alt,w} can be written as `\ew`. The control character can be written in much the same way using the `\c` escape, for example @key{Control,X} (^X) can be written as `\cx`. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not `fish`. + +The default key binding can be set by specifying a `SEQUENCE` of the empty string (that is, ```''``` ). It will be used whenever no other binding matches. For most key bindings, it makes sense to use the `self-insert` function (i.e. ```bind '' self-insert```) as the default keybinding. This will insert any keystrokes not specifically bound to into the editor. Non- printable characters are ignored by the editor, so this will not result in control sequences being printable. + +If the `-k` switch is used, the name of the key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key_' prefix. (See `terminfo(5)` for more information, or use `bind --key-names` for a list of all available named keys.) + +`COMMAND` can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use `bind --function-names` for a complete list of these input functions. + +When `COMMAND` is a shellscript command, it is a good practice to put the actual code into a <a href="#function">function</a> and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well. + +If such a script produces output, the script needs to finish by calling `commandline -f repaint` in order to tell fish that a repaint is in order. + +Key bindings are not saved between sessions by default. To save custom keybindings, edit the `fish_user_key_bindings` function and insert the appropriate `bind` statements. The following parameters are available: -- <tt>-k</tt> or <tt>--key</tt> Specify a key name, such as 'left' or 'backspace' instead of a character sequence -- <tt>-K</tt> or <tt>--key-names</tt> Display a list of available key names -- <tt>-f</tt> or <tt>--function-names</tt> Display a list of available input functions +- `-k` or `--key` Specify a key name, such as 'left' or 'backspace' instead of a character sequence + +- `-K` or `--key-names` Display a list of available key names + +- `-f` or `--function-names` Display a list of available input functions The following special input 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 capitalize-word, make the current word begin with a capital letter -- \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 downcase-word, make the current word lowercase -- \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 upcase-word, make the current word uppercase -- \c yank, insert the latest entry of the killring into the buffer -- \c yank-pop, rotate to the previous entry of the killring +- `backward-char`, moves one character to the left + +- `backward-delete-char`, deletes one character of input to the left of the cursor + +- `backward-kill-line`, move everything from the beginning of the line to the cursor to the killring + +- `backward-kill-word`, move the word to the left of the cursor to the killring + +- `backward-word`, move one word to the left + +- `beginning-of-history`, move to the beginning of the history + +- `beginning-of-line`, move to the beginning of the line + +- `capitalize-word`, make the current word begin with a capital letter + +- `complete`, guess the remainder of the current token + +- `delete-char`, delete one character to the right of the cursor + +- `delete-line`, delete the entire line + +- `downcase-word`, make the current word lowercase + +- `dump-functions`, print a list of all key-bindings + +- `end-of-history`, move to the end of the history + +- `end-of-line`, move to the end of the line + +- `explain`, print a description of possible problems with the current command + +- `forward-char`, move one character to the right + +- `forward-word`, move one word to the right + +- `history-search-backward`, search the history for the previous match + +- `history-search-forward`, search the history for the next match + +- `kill-line`, move everything from the cursor to the end of the line to the killring + +- `kill-whole-line`, move the line to the killring + +- `kill-word`, move the next word to the killring + +- `upcase-word`, make the current word uppercase + +- `yank`, insert the latest entry of the killring into the buffer + +- `yank-pop`, rotate to the previous entry of the killring + \subsection bind-example Examples -<tt>bind \\cd 'exit'</tt> causes \c fish to exit when Control-d is pressed. +\fish +bind \cd 'exit' +\endfish +Causes `fish` to exit when @key{Control,D} is pressed. -<tt>bind -k ppage history-search-backward</tt> performs a history search when the Page Up key is pressed. +\fish +bind -k ppage history-search-backward +\endfish +Performs a history search when the @key{Page Up} key is pressed. diff --git a/doc_src/block.txt b/doc_src/block.txt index 0f4cff38..37b2de0c 100644 --- a/doc_src/block.txt +++ b/doc_src/block.txt @@ -1,40 +1,41 @@ \section block block - temporarily block delivery of events \subsection block-synopsis Synopsis - <tt>block [OPTIONS...]</tt> +\fish{synopsis} +block [OPTIONS...] +\endfish \subsection block-description Description -\c block prevents events triggered by \c fish or the -<a href="commands.html#emit"><code>emit</code></a> command from -being delivered and acted upon while the block is in place. +`block` prevents events triggered by `fish` or the <a href="commands.html#emit">`emit`</a> command from being delivered and acted upon while the block is in place. -In functions, \c block can be useful while performing work that -should not be interrupted by the shell. +In functions, `block` can be useful while performing work that should not be interrupted by the shell. -The block can be removed. Any events which triggered while the -block was in place will then be delivered. +The block can be removed. Any events which triggered while the block was in place will then be delivered. -Event blocks should not be confused with code blocks, which are created -with <code>begin</code>, <code>if</code>, <code>while</code> or -<code>for</code> +Event blocks should not be confused with code blocks, which are created with `begin`, `if`, `while` or `for` The following parameters are available: -- <tt>-l</tt> or <tt>--local</tt> Release the block automatically at the end of the current innermost code block scope -- <tt>-g</tt> or <tt>--global</tt> Never automatically release the lock -- <tt>-e</tt> or <tt>--erase</tt> Release global block +- `-l` or `--local` Release the block automatically at the end of the current innermost code block scope + +- `-g` or `--global` Never automatically release the lock + +- `-e` or `--erase` Release global block + \subsection block-example Example -<pre> +\fish # Create a function that listens for events function --on-event foo foo; echo 'foo fired'; end + # Block the delivery of events block -g + emit foo # No output will be produced + block -e # 'foo fired' will now be printed -</pre> - +\endfish diff --git a/doc_src/break.txt b/doc_src/break.txt index 3f46bb8c..32672c09 100644 --- a/doc_src/break.txt +++ b/doc_src/break.txt @@ -1,22 +1,25 @@ \section break break - stop the current inner loop \subsection break-synopsis Synopsis - <tt>LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end</tt> +\fish{synopsis} +LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end +\endfish \subsection break-description Description -\c break halts a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement. +`break` halts a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement. + +There are no parameters for `break`. -There are no parameters for <code>break</code>. \subsection break-example Example The following code searches all .c files for "smurf", and halts at the first occurrence. -<pre> +\fish for i in *.c if grep smurf $i echo Smurfs are present in $i break end end -</pre> +\endfish diff --git a/doc_src/breakpoint.txt b/doc_src/breakpoint.txt index 744727fa..8645c18d 100644 --- a/doc_src/breakpoint.txt +++ b/doc_src/breakpoint.txt @@ -1,14 +1,14 @@ \section breakpoint breakpoint - Launch debug mode \subsection breakpoint-synopsis Synopsis - <tt>breakpoint</tt> +\fish{synopsis} +breakpoint +\endfish \subsection breakpoint-description Description -\c breakpoint is used to halt a running script and launch -an interactive debugging prompt. +`breakpoint` is used to halt a running script and launch an interactive debugging prompt. -For more details, see <a href="index.html#debugging">Debugging fish -scripts</a> in the \c fish manual. +For more details, see <a href="index.html#debugging">Debugging fish scripts</a> in the `fish` manual. -There are no parameters for <code>breakpoint</code>. +There are no parameters for `breakpoint`. diff --git a/doc_src/builtin.txt b/doc_src/builtin.txt index fd93f703..4c465ef1 100644 --- a/doc_src/builtin.txt +++ b/doc_src/builtin.txt @@ -1,16 +1,22 @@ \section builtin builtin - run a builtin command \subsection builtin-synopsis Synopsis - <tt>builtin BUILTINNAME [OPTIONS...]</tt> +\fish{synopsis} +builtin BUILTINNAME [OPTIONS...] +\endfish \subsection builtin-description Description -\c builtin forces the shell to use a builtin command, rather than a function or program. +`builtin` forces the shell to use a builtin command, rather than a function or program. The following parameters are available: -- <tt>-n</tt> or <tt>--names</tt> List the names of all defined builtins +- `-n` or `--names` List the names of all defined builtins + \subsection builtin-example Example -<tt>builtin jobs</tt> executes the jobs builtin, even if a function named jobs exists. +\fish +builtin jobs +# executes the jobs builtin, even if a function named jobs exists +\endfish diff --git a/doc_src/case.txt b/doc_src/case.txt index b5601cdb..24fde280 100644 --- a/doc_src/case.txt +++ b/doc_src/case.txt @@ -1,35 +1,27 @@ \section case case - conditionally execute a block of commands \subsection case-synopsis Synopsis -<tt>switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end</tt> +\fish{synopsis} +switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end +\endfish \subsection case-description Description -\c switch performs one of several blocks of commands, depending on whether -a specified value equals one of several wildcarded values. \c case is used -together with the \c switch statement in order to determine which block should -be executed. +`switch` performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. `case` is used together with the `switch` statement in order to determine which block should be executed. -Each \c case command is given one or more parameters. The first \c case -command with a parameter that matches the string specified in the -switch command will be evaluated. \c case parameters may contain -wildcards. These need to be escaped or quoted in order to avoid -regular wildcard expansion using filenames. +Each `case` command is given one or more parameters. The first `case` command with a parameter that matches the string specified in the switch command will be evaluated. `case` parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames. -Note that fish does not fall through on case statements. Only the -first matching case is executed. +Note that fish does not fall through on case statements. Only the first matching case is executed. + +Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter. -Note that command substitutions in a case statement will be -evaluated even if its body is not taken. All substitutions, including -command substitutions, must be performed before the value can be compared -against the parameter. \subsection case-example Example If the variable \$animal contains the name of an animal, the following code would attempt to classify it: -<pre> +\fish switch $animal case cat echo evil @@ -43,8 +35,8 @@ switch $animal case '*' echo I have no idea what a $animal is end -</pre> +\endfish -If the above code was run with \c \$animal set to \c whale, the output -would be \c mammal. +If the above code was run with `$animal` set to `whale`, the output +would be `mammal`. diff --git a/doc_src/cd.txt b/doc_src/cd.txt index a1da087a..bb4dc488 100644 --- a/doc_src/cd.txt +++ b/doc_src/cd.txt @@ -1,25 +1,26 @@ \section cd cd - change directory \subsection cd-synopsis Synopsis -<tt>cd [DIRECTORY]</tt> +\fish{synopsis} +cd [DIRECTORY] +\endfish \subsection cd-description Description -\c cd changes the current working directory. +`cd` changes the current working directory. -If \c DIRECTORY is supplied, it will become the new directory. If no parameter -is given, the contents of the \c HOME environment variable will be used. +If `DIRECTORY` is supplied, it will become the new directory. If no parameter is given, the contents of the `HOME` environment variable will be used. -If \c DIRECTORY is a relative path, the paths found in the -\c CDPATH environment variable array will be tried as prefixes for the specified -path. +If `DIRECTORY` is a relative path, the paths found in the `CDPATH` environment variable array will be tried as prefixes for the specified path. + +Note that the shell will attempt to change directory without requiring `cd` if the name of a directory is provided (starting with `.`, `/` or `~`, or ending with `/`). -Note that the shell will attempt to change directory without requiring \c cd -if the name of a directory is provided (starting with '.', '/' or '~', or ending -with '/'). \subsection cd-example Examples -\c cd changes the working directory to your home directory. +\fish +cd +# changes the working directory to your home directory. -<code>cd /usr/src/fish-shell</code> changes the working directory to -<code>/usr/src/fish-shell</code>. +cd /usr/src/fish-shell +# changes the working directory to /usr/src/fish-shell +\endfish diff --git a/doc_src/command.txt b/doc_src/command.txt index cef08fdc..4f9087d6 100644 --- a/doc_src/command.txt +++ b/doc_src/command.txt @@ -1,22 +1,24 @@ \section command command - run a program \subsection command-synopsis Synopsis -<tt>command [OPTIONS] COMMANDNAME [ARGS...]</tt> +\fish{synopsis} +command [OPTIONS] COMMANDNAME [ARGS...] +\endfish \subsection command-description Description -\c command forces the shell to execute the program \c COMMANDNAME and ignore any functions or builtins with the same name. +`command` forces the shell to execute the program `COMMANDNAME` and ignore any functions or builtins with the same name. The following options are available: -- \c -h or \c --help prints help and then exits. -- \c -s or \c --search returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the <tt>$PATH</tt>. -With the \c -s option, \c command treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found. +- `-s` or `--search` returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the `$PATH`. -For basic compatibility with POSIX <tt>command</tt>, the \c -v flag is recognized as an alias for <tt>-s</tt>. +With the `-s` option, `command` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found. + +For basic compatibility with POSIX `command`, the `-v` flag is recognized as an alias for `-s`. \subsection command-example Examples -<tt>command ls</tt> causes fish to execute the \c ls program, even if an 'ls' function exists. +`command ls` causes fish to execute the `ls` program, even if an `ls` function exists. -<tt>command -s ls</tt> returns the path to the \c ls program. +`command -s ls` returns the path to the `ls` program. diff --git a/doc_src/commandline.txt b/doc_src/commandline.txt index 1d13f79e..347f4870 100644 --- a/doc_src/commandline.txt +++ b/doc_src/commandline.txt @@ -1,73 +1,59 @@ \section commandline commandline - set or get the current command line buffer \subsection commandline-synopsis Synopsis -<tt>commandline [OPTIONS] [CMD]</tt> +\fish{synopsis} +commandline [OPTIONS] [CMD] +\endfish \subsection commandline-description Description -\c commandline can be used to set or get the current contents of the command -line buffer. +`commandline` can be used to set or get the current contents of the command line buffer. -With no parameters, \c commandline returns the current value of the command -line. +With no parameters, `commandline` returns the current value of the command line. -With \c CMD specified, the command line buffer is erased and replaced with -the contents of \c CMD. +With `CMD` specified, the command line buffer is erased and replaced with the contents of `CMD`. The following options are available: -- \c -C or \c --cursor set or get the current cursor position, not - the contents of the buffer. If no argument is given, the current - cursor position is printed, otherwise the argument is interpreted - as the new cursor position. -- \c -f or \c --function inject readline functions into the - reader. This option cannot be combined with any other option. It - will cause any additional arguments to be interpreted as readline - functions, and these functions will be injected into the reader, so - that they will be returned to the reader before any additional - actual key presses are read. +- `-C` or `--cursor` set or get the current cursor position, not the contents of the buffer. If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position. -The following options change the way \c commandline updates the -command line buffer: +- `-f` or `--function` inject readline functions into the reader. This option cannot be combined with any other option. It will cause any additional arguments to be interpreted as readline functions, and these functions will be injected into the reader, so that they will be returned to the reader before any additional actual key presses are read. -- \c -a or \c --append do not remove the current commandline, append - the specified string at the end of it -- \c -i or \c --insert do not remove the current commandline, insert - the specified string at the current cursor position -- \c -r or \c --replace remove the current commandline and replace it - with the specified string (default) +The following options change the way `commandline` updates the command line buffer: -The following options change what part of the commandline is printed -or updated: +- `-a` or `--append` do not remove the current commandline, append the specified string at the end of it -- \c -b or \c --current-buffer select the entire buffer (default) -- \c -j or \c --current-job select the current job -- \c -p or \c --current-process select the current process -- \c -t or \c --current-token select the current token. +- `-i` or `--insert` do not remove the current commandline, insert the specified string at the current cursor position -The following options change the way \c commandline prints the current -commandline buffer: +- `-r` or `--replace` remove the current commandline and replace it with the specified string (default) -- \c -c or \c --cut-at-cursor only print selection up until the - current cursor position -- \c -o or \c --tokenize tokenize the selection and print one string-type token per line +The following options change what part of the commandline is printed or updated: +- `-b` or `--current-buffer` select the entire buffer (default) -If \c commandline is called during a call to complete a given string -using <code>complete -C STRING</code>, \c commandline will consider the -specified string to be the current contents of the command line. +- `-j` or `--current-job` select the current job + +- `-p` or `--current-process` select the current process + +- `-t` or `--current-token` select the current token. + +The following options change the way `commandline` prints the current commandline buffer: + +- `-c` or `--cut-at-cursor` only print selection up until the current cursor position + +- `-o` or `--tokenize` tokenize the selection and print one string-type token per line + +If `commandline` is called during a call to complete a given string using `complete -C STRING`, `commandline` will consider the specified string to be the current contents of the command line. The following options output metadata about the commandline state: -- \c -L or \c --line print the line that the cursor is on, with the topmost -line starting at 1 -- \c -S or \c --search-mode evaluates to true if the commandline is performing -a history search -- \c -P or \c --paging-mode evaluates to true if the commandline is showing -pager contents, such as tab completions +- `-L` or `--line` print the line that the cursor is on, with the topmost line starting at 1 + +- `-S` or `--search-mode` evaluates to true if the commandline is performing a history search + +- `-P` or `--paging-mode` evaluates to true if the commandline is showing pager contents, such as tab completions \subsection commandline-example Example -<tt>commandline -j $history[3]</tt> replaces the job under the cursor with the -third item from the command line history. +`commandline -j $history[3]` replaces the job under the cursor with the third item from the command line history. diff --git a/doc_src/commands.hdr.in b/doc_src/commands.hdr.in index c29675bd..f31c96e5 100644 --- a/doc_src/commands.hdr.in +++ b/doc_src/commands.hdr.in @@ -1,15 +1,38 @@ -/** \page commands Commands bundled with fish - -\htmlonly <div class="fish_left_bar fish_left_little"> \endhtmlonly +/** +\page commands Commands +\htmlonly[block] +<div class="fish_left_bar"> +<div class="logo"></div> +<div class="menu commands_menu"> +\endhtmlonly @command_list_toc@ -\htmlonly </div> \endhtmlonly -\htmlonly -<div class="fish_right_bar fish_right_big"> -<h1 class="interior_title_borderless">Commands</h1> -Fish ships with a large number of builtin commands, shellscript functions and external commands. These are all described below. +\htmlonly[block] +</div> +</div> +<div class="commands fish_right_bar"> +<h1 class="interior_title">Command reference</h1> \endhtmlonly +`fish` ships with a large number of builtin commands, shellscript functions and external commands. These are all described below. + +Almost all fish commands respond to the `-h` or `--help` options to display their relevant help, also accessible using the `help` and `man` commands, like so: + +\fish +echo -h +echo --help +# Prints help to the terminal window + +man echo +# Displays the man page in the system pager +# (normally 'less', 'more' or 'most'). + +help echo +# Open a web browser to show the relevant documentation +\endfish + @command_list@ -\htmlonly </div> \endhtmlonly +\htmlonly[block] +</div> +\endhtmlonly */ diff --git a/doc_src/complete.txt b/doc_src/complete.txt index 0c1ffa91..825faf9a 100644 --- a/doc_src/complete.txt +++ b/doc_src/complete.txt @@ -1,7 +1,14 @@ \section complete complete - edit command specific tab-completions \subsection complete-synopsis Synopsis -<tt>complete (-c|--command|-p|--path) COMMAND [(-s|--short-option) SHORT_OPTION] [(-l|--long-option|-o|--old-option) LONG_OPTION [(-a||--arguments) OPTION_ARGUMENTS] [(-w|--wraps) WRAPPED_COMMAND] [(-d|--description) DESCRIPTION] </tt> +\fish{synopsis} +complete ( -c | --command | -p | --path ) COMMAND + [( -s | --short-option ) SHORT_OPTION] + [( -l | --long-option | -o | --old-option ) LONG_OPTION] + [( -a | --arguments ) OPTION_ARGUMENTS] + [( -w | --wraps ) WRAPPED_COMMAND] + [( -d | --description ) DESCRIPTION] +\endfish \subsection complete-description Description @@ -9,85 +16,88 @@ For an introduction to specifying completions, see <a href='index.html#completion-own'>Writing your own completions</a> in the fish manual. -- <tt>COMMAND</tt> is the name of the command for which to add a completion -- <tt>SHORT_OPTION</tt> is a one character option for the command -- <tt>LONG_OPTION</tt> is a multi character option for the command -- <tt>OPTION_ARGUMENTS</tt> is parameter containing a space-separated list of possible option-arguments, which may contain subshells -- <tt>DESCRIPTION</tt> is a description of what the option and/or option arguments do -- <tt>-C STRING</tt> or <tt>--do-complete=STRING</tt> makes complete try to find all possible completions for the specified string -- <tt>-e</tt> or <tt>--erase</tt> implies that the specified completion should be deleted -- <tt>-f</tt> or <tt>--no-files</tt> specifies that the option specified by this completion may not be followed by a filename -- <tt>-n</tt> or <tt>--condition</tt> specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases. -- <tt>-o</tt> or <tt>--old-option</tt> implies that the command uses old long style options with only one dash -- <tt>-p</tt> or <tt>--path</tt> implies that the string COMMAND is the full path of the command -- <tt>-r</tt> or <tt>--require-parameter</tt> specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option -- <tt>-u</tt> or <tt>--unauthoritative</tt> implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors -- <tt>-A</tt> or <tt>--authoritative</tt> implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors -- <tt>-x</tt> or <tt>--exclusive</tt> implies both <tt>-r</tt> and <tt>-f</tt> -- <tt>-w WRAPPED_COMMAND</tt> or <tt>--wraps=WRAPPED_COMMAND</tt> causes the specified command to inherit completions from the wrapped comamnd. - -Command specific tab-completions in \c fish are based on the notion -of options and arguments. An option is a parameter which begins with a -hyphen, such as '-h', '-help' or '--help'. Arguments are parameters -that do not begin with a hyphen. Fish recognizes three styles of -options, the same styles as the GNU version of the getopt -library. These styles are: - -- Short options, like '-a'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '-la', which is equivalent to '-l -a'). Option arguments may be specified in the following parameter ('-w 32') or by appending the option with the value ('-w32'). -- Old style long options, like '-Wall'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter ('-ao null'). -- GNU style long options, like '--colors'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('--quoting-style shell') or by appending the option with a '=' and the value ('--quoting-style=shell'). GNU style long options may be abbreviated so long as the abbreviation is unique ('--h' is equivalent to '--help' if help is the only long option beginning with an 'h'). - -The options for specifying command name, command path, or command -switches may all be used multiple times to specify multiple commands -which have the same completion or multiple switches accepted by a -command. - -The \c -w or \c --wraps options causes the specified command to inherit -completions from another command. The inheriting command is said to -"wrap" the inherited command. The wrapping command may have its own -completions in addition to inherited ones. A command may wrap multiple -commands, and wrapping is transitive: if A wraps B, and B wraps C, -then A automatically inherits all of C's completions. Wrapping can -be removed using the \c -e or \c --erase options. - -When erasing completions, it is possible to either erase all -completions for a specific command by specifying <tt>complete -e -c -COMMAND</tt>, or by specifying a specific completion option to delete -by specifying either a long, short or old style option. +- `COMMAND` is the name of the command for which to add a completion. + +- `SHORT_OPTION` is a one character option for the command. + +- `LONG_OPTION` is a multi character option for the command. + +- `OPTION_ARGUMENTS` is parameter containing a space-separated list of possible option-arguments, which may contain subshells. + +- `DESCRIPTION` is a description of what the option and/or option arguments do. + +- `-C STRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string. + +- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command. + +- `-e` or `--erase` implies that the specified completion should be deleted. + +- `-f` or `--no-files` specifies that the option specified by this completion may not be followed by a filename. + +- `-n` or `--condition` specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases. + +- `-o` or `--old-option` implies that the command uses old long style options with only one dash. + +- `-p` or `--path` implies that the string `COMMAND` is the full path of the command. + +- `-r` or `--require-parameter` specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option. + +- `-u` or `--unauthoritative` implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors. + +- `-A` or `--authoritative` implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors. + +- `-x` or `--exclusive` implies both `-r` and `-f`. + +Command specific tab-completions in `fish` are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as '`-h`', '`-help`' or '`--help`'. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU version of the getopt library. These styles are: + +- Short options, like '`-a`'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '`-la`', which is equivalent to '`-l -a`'). Option arguments may be specified in the following parameter ('`-w 32`') or by appending the option with the value ('`-w32`'). + +- Old style long options, like '`-Wall`'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter ('`-ao null`'). + +- GNU style long options, like '`--colors`'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('`--quoting-style`') or by appending the option with a '`=`' and the value ('`--quoting-style=shell`'). GNU style long options may be abbreviated so long as the abbreviation is unique ('`--h`') is equivalent to '`--help`' if help is the only long option beginning with an 'h'). + +The options for specifying command name, command path, or command switches may all be used multiple times to specify multiple commands which have the same completion or multiple switches accepted by a command. + +The `-w` or `--wraps` options causes the specified command to inherit completions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own completions in addition to inherited ones. A command may wrap multiple commands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically inherits all of C's completions. Wrapping can be removed using the `-e` or `--erase` options. + +When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -e -c COMMAND`, or by specifying a specific completion option to delete by specifying either a long, short or old style option. + \subsection complete-example Example -The short style option <tt>-o</tt> for the \c gcc command requires -that a file follows it. This can be done using writing <tt>complete --c gcc -s o -r</tt>. +The short style option `-o` for the `gcc` command requires that a file follows it. This can be done using writing: + +\fish +complete -c gcc -s o -r +\endfish + +The short style option `-d` for the `grep` command requires that one of the strings '`read`', '`skip`' or '`recurse`' is used. This can be specified writing: + +\fish +complete -c grep -s d -x -a "read skip recurse" +\endfish -The short style option <tt>-d</tt> for the \c grep command requires -that one of the strings 'read', 'skip' or 'recurse' is used. This can -be specified writing <tt>complete -c grep -s d -x -a "read skip -recurse"</tt>. +The `su` command takes any username as an argument. Usernames are given as the first colon-separated field in the file /etc/passwd. This can be specified as: -The \c su command takes any username as an argument. Usernames are -given as the first colon-separated field in the file /etc/passwd. This -can be specified as: <tt>complete -x -c su -d "Username" -a "(cat -/etc/passwd|cut -d : -f 1)" </tt>. +\fish +complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)" +\endfish -The \c rpm command has several different modes. If the \c -e or \c ---erase flag has been specified, \c rpm should delete one or more -packages, in which case several switches related to deleting packages -are valid, like the \c nodeps switch. +The `rpm` command has several different modes. If the `-e` or `--erase` flag has been specified, `rpm` should delete one or more packages, in which case several switches related to deleting packages are valid, like the `nodeps` switch. This can be written as: -<tt>complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d -"Don't check dependencies"</tt> +\fish +complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies" +\endfish -where \c __fish_contains_opt is a function that checks the commandline -buffer for the presence of a specified set of options. +where `__fish_contains_opt` is a function that checks the commandline buffer for the presence of a specified set of options. -To implement an alias, use the \c -w or \c --wraps option: +To implement an alias, use the `-w` or `--wraps` option: -<tt>complete -c hub -w git</tt> +\fish +complete -c hub -w git +\endfish -Now hub inherits all of the completions from git. Note this can -also be specified in a function declaration. +Now hub inherits all of the completions from git. Note this can also be specified in a function declaration. diff --git a/doc_src/contains.txt b/doc_src/contains.txt index cc746358..f3966d82 100644 --- a/doc_src/contains.txt +++ b/doc_src/contains.txt @@ -1,26 +1,27 @@ \section contains contains - test if a word is present in a list \subsection contains-synopsis Synopsis -<code>contains [OPTIONS] KEY [VALUES...]</code> +\fish{synopsis} +contains [OPTIONS] KEY [VALUES...] +\endfish \subsection contains-description Description -\c contains tests whether the set \c VALUES contains the string -<code>KEY</code>. If so, \c contains exits with status 0; if not, it exits -with status 1. +`contains` tests whether the set `VALUES` contains the string `KEY`. If so, `contains` exits with status 0; if not, it exits with status 1. The following options are available: -- \c -i or \c --index print the word index -- \c -h or \c --help display this message +- `-i` or `--index` print the word index + \subsection contains-example Example -<pre> + +\fish for i in ~/bin /usr/local/bin - if not contains \$i \$PATH - set PATH \$PATH \$i - end + if not contains $i $PATH + set PATH $PATH $i + end end -</pre> +\endfish -The above code tests if \c ~/bin and \c /usr/local/bin are in the path and adds them if not. +The above code tests if `~/bin` and `/usr/local/bin` are in the path and adds them if not. diff --git a/doc_src/continue.txt b/doc_src/continue.txt index 9b1803f5..1585b04a 100644 --- a/doc_src/continue.txt +++ b/doc_src/continue.txt @@ -1,19 +1,23 @@ \section continue continue - skip the remainder of the current iteration of the current inner loop \subsection continue-synopsis Synopsis -<tt>LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end</tt> +\fish{synopsis} +LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end +\endfish \subsection continue-description Description -\c continue skips the remainder of the current iteration of the current inner loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement. + +`continue` skips the remainder of the current iteration of the current inner loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement. \subsection continue-example Example + The following code removes all tmp files that do not contain the word smurf. -<pre> +\fish for i in *.tmp if grep smurf $i continue end rm $i end -</pre> +\endfish diff --git a/doc_src/count.txt b/doc_src/count.txt index 7923ca00..279ead7d 100644 --- a/doc_src/count.txt +++ b/doc_src/count.txt @@ -1,29 +1,25 @@ \section count count - count the number of elements of an array \subsection count-synopsis Synopsis - <tt>count $VARIABLE</tt> +\fish{synopsis} +count $VARIABLE +\endfish \subsection count-description Description -<tt>count</tt> prints the number of arguments that were -passed to it. This is usually used to find out how many elements an -environment variable array contains. +`count` prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains. -\c count does not accept any options, including '-h'. +`count` does not accept any options, including `-h` or `--help`. + +`count` exits with a non-zero exit status if no arguments were passed to it, and with zero if at least one argument was passed. -\c count exits with a non-zero exit status if no arguments were passed -to it, and with zero if at least one argument was passed. \subsection count-example Example -<pre> +\fish count $PATH -</pre> - -returns the number of directories in the users PATH variable. +# Returns the number of directories in the users PATH variable. -<pre> count *.txt -</pre> - -returns the number of files in the current working directory ending with the suffix '.txt'. +# Returns the number of files in the current working directory ending with the suffix '.txt'. +\endfish
\ No newline at end of file diff --git a/doc_src/design.hdr b/doc_src/design.hdr index e85e7b54..c57943c5 100644 --- a/doc_src/design.hdr +++ b/doc_src/design.hdr @@ -1,138 +1,110 @@ -/** \page design Design document - -\htmlonly <div class="fish_only_bar"> \endhtmlonly +/** +\page design Design document +\htmlonly[block] +<div class="fish_only_bar"> +<div class="design"> +<h1 class="interior_title">Design documentation</h1> +\endhtmlonly \section 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: +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. --# 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. +-# Whenever possible without breaking the above goals, fish should follow the Posix syntax. + +To achieve 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. -To achieve 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. \section 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. +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 source code, making the -program harder to maintain and update. +Related features make the language larger, which makes it harder to learn. It also increases the size of the source code, 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 achieved 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 \$''. -\section sep The law of responsiveness +- Subshells, command substitution and process substitution are strongly related. `fish` only supports command substitution, the others can be achieved 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. `fish` functions have none of the drawbacks of either syntax. + +- The many Posix quoting styles are silly, especially $''. + + +\section design-response The law of responsiveness The shell should attempt to remain responsive to the user at all times, even in the face of contended or unresponsive filesystems. It is only acceptable to block in response to a user initiated action, such as running a command. Rationale: - Bad performance increases user-facing complexity, because it trains users to recognize and route around slow use cases. It is also incredibly frustrating. Examples: - Features like syntax highlighting and autosuggestions must perform all of their disk I/O asynchronously. + - Startup should minimize forks and disk I/O, so that fish can be started even if the system is under load. -\section conf Configurability is the root of all evil +\section design-configurability 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 failure of both the program and the programmer -who implemented it. +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 failure 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. +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 off by default in zsh. Other features that zsh supports that are -disabled by default include tab-completion of strings containing -wildcards, a sane completion pager and a history file. +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 off by default in zsh. Other features that zsh supports that are disabled by default include tab-completion of strings containing wildcards, a sane completion pager and a history file. \section 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. +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 too 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. +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 too 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 built-in commands and shellscript functions should be made as small as possible. Built-ins 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 I/O 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 built-in. + +- All blocks end with the `end` built-in. \section disc The law of discoverability -A program should be designed to make its features as -easy as possible to discover for the user. +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. -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 command-line programs is -through manual pages. This requires both that the user starts to use a -different program, and then she/he remembers the new information -until the next time she/he uses the same program. +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 command-line programs is through manual pages. This requires both that the user starts to use a different program, and then she/he 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 built-in 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, she/he will know the whole language, and be able to use tab-completion to discover new features. -*/ -\htmlonly </div> \endhtmlonly +\htmlonly[block] +</div> +</div> +\endhtmlonly + +*/ diff --git a/doc_src/dirh.txt b/doc_src/dirh.txt index abc498b8..d25b9c2a 100644 --- a/doc_src/dirh.txt +++ b/doc_src/dirh.txt @@ -1,12 +1,12 @@ \section dirh dirh - print directory history \subsection dirh-synopsis Synopsis -<tt>dirh</tt> +\fish{synopsis} +dirh +\endfish \subsection dirh-description Description -<tt>dirh</tt> prints the current directory history. The current position in the -history is highlighted using the color defined in the -<tt>fish_color_history_current</tt> environment variable. +`dirh` prints the current directory history. The current position in the history is highlighted using the color defined in the `fish_color_history_current` environment variable. -\c dirh does not accept any parameters. +`dirh` does not accept any parameters. diff --git a/doc_src/dirs.txt b/doc_src/dirs.txt index e5238107..231b678b 100644 --- a/doc_src/dirs.txt +++ b/doc_src/dirs.txt @@ -1,10 +1,12 @@ \section dirs dirs - print directory stack \subsection dirs-synopsis Synopsis -<tt>dirs</tt> +\fish{synopsis} +dirs +\endfish \subsection dirs-description Description -<tt>dirs</tt> prints the current directory stack, as created by the -<code><a href="#pushd">pushd</a></code> command. -\c dirs does not accept any parameters. +`dirs` prints the current directory stack, as created by the <a href="#pushd">`pushd`</a> command. + +`dirs` does not accept any parameters. diff --git a/doc_src/echo.txt b/doc_src/echo.txt index 01ddf5a5..c53d3009 100644 --- a/doc_src/echo.txt +++ b/doc_src/echo.txt @@ -1,39 +1,58 @@ \section echo echo - display a line of text \subsection echo-synopsis Synopsis - <tt>echo [STRING]</tt> +\fish{synopsis} +echo [OPTIONS] [STRING] +\endfish \subsection echo-description Description -\c echo displays a string of text. +`echo` displays a string of text. The following options are available: -- \c -n, \c Do not output a newline -- \c -s, \c Do not separate arguments with spaces -- \c -E, \c Disable interpretation of backslash escapes (default) -- \c -e, \c Enable interpretation of backslash escapes -- \c -h, \c --help Display this help +- `-n`, Do not output a newline + +- `-s`, Do not separate arguments with spaces + +- `-E`, Disable interpretation of backslash escapes (default) + +- `-e`, Enable interpretation of backslash escapes \subsection echo-escapes Escape Sequences -If \c -e is used, the following sequences are recognized: - -- \c \\\\ \c backslash -- \\a alert (BEL) -- \\b backspace -- \\c produce no further output -- \\e escape -- \\f form feed -- \\n new line -- \\r carriage return -- \\t horizontal tab -- \\v vertical tab -- \\0NNN byte with octal value NNN (1 to 3 digits) -- \\xHH byte with hexadecimal value HH (1 to 2 digits) +If `-e` is used, the following sequences are recognized: + +- `\` backslash + +- `\a` alert (BEL) + +- `\b` backspace + +- `\c` produce no further output + +- `\e` escape + +- `\f` form feed + +- `\n` new line + +- `\r` carriage return + +- `\t` horizontal tab + +- `\v` vertical tab + +- `\0NNN` byte with octal value NNN (1 to 3 digits) + +- `\xHH` byte with hexadecimal value HH (1 to 2 digits) \subsection echo-example Example -<tt>echo 'Hello World'</tt> Print hello world to stdout +\fish +echo 'Hello World' +# Print hello world to stdout -<tt>echo -e 'Top\\nBottom'</tt> Print Top and Bottom on separate lines, using an escape sequence +echo -e 'Top\nBottom' +# Print Top and Bottom on separate lines, using an escape sequence +\endfish diff --git a/doc_src/else.txt b/doc_src/else.txt index 66d8be3f..76e0c61f 100644 --- a/doc_src/else.txt +++ b/doc_src/else.txt @@ -1,21 +1,23 @@ \section else else - execute command if a condition is not met \subsection else-synopsis Synopsis -<tt>if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end</tt> +\fish{synopsis} +if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end +\endfish \subsection else-description Description -<tt>if</tt> will execute the command \c CONDITION. If the condition's exit -status is 0, the commands \c COMMANDS_TRUE will execute. If it is not 0 and -<tt>else</tt> is given, \c COMMANDS_FALSE will be executed. + +`if` will execute the command `CONDITION`. If the condition's exit status is 0, the commands `COMMANDS_TRUE` will execute. If it is not 0 and `else` is given, `COMMANDS_FALSE` will be executed. + \subsection else-example Example -The following code tests whether a file \c foo.txt exists as a regular file. +The following code tests whether a file `foo.txt` exists as a regular file. -<pre> +\fish if test -f foo.txt echo foo.txt exists else echo foo.txt does not exist end -</pre> +\endfish diff --git a/doc_src/emit.txt b/doc_src/emit.txt index f00e4233..df154c5d 100644 --- a/doc_src/emit.txt +++ b/doc_src/emit.txt @@ -1,20 +1,23 @@ \section emit emit - Emit a generic event -\subsection block-synopsis Synopsis - <tt>emit EVENT_NAME [ARGUMENTS...]</tt> +\subsection emit-synopsis Synopsis +\fish{synopsis} +emit EVENT_NAME [ARGUMENTS...] +\endfish \subsection emit-description Description -\c emit emits, or fires, an event. Events are delivered to, or caught by, special functions called event handlers. The arguments are passed to the event handlers as function arguments. +`emit` emits, or fires, an event. Events are delivered to, or caught by, special functions called event handlers. The arguments are passed to the event handlers as function arguments. + \subsection emit-example Example -The following code first defines an event handler for the generic -event named 'test_event', and then emits an event of that type. +The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type. -<pre>function event_test --on-event test_event +\fish +function event_test --on-event test_event echo event test: $argv end emit test_event something -</pre> +\endfish diff --git a/doc_src/end.txt b/doc_src/end.txt index 2d301e33..76cbe360 100644 --- a/doc_src/end.txt +++ b/doc_src/end.txt @@ -1,19 +1,19 @@ \section end end - end a block of commands. \subsection end-synopsis Synopsis -<pre> +\fish{synopsis} begin; [COMMANDS...] end if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end while CONDITION; COMMANDS...; end for VARNAME in [VALUES...]; COMMANDS...; end switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end -</pre> +\endfish \subsection end-description Description -<tt>end</tt> ends a block of commands. + +`end` ends a block of commands. For more information, read the -documentation for the block constructs, such as \c if, \c for and \c -while. +documentation for the block constructs, such as `if`, `for` and `while`. -The \c end command does not change the current exit status. +The `end` command does not change the current exit status. diff --git a/doc_src/eval.txt b/doc_src/eval.txt index 47e4627d..1ba8f97e 100644 --- a/doc_src/eval.txt +++ b/doc_src/eval.txt @@ -1,19 +1,20 @@ \section eval eval - evaluate the specified commands \subsection eval-synopsis Synopsis -<tt>eval [COMMANDS...]</tt> +\fish{synopsis} +eval [COMMANDS...] +\endfish \subsection eval-description Description -<tt>eval</tt> evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator. +`eval` evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator. + \subsection eval-example Example -The following code will call the ls command. Note that \c fish does not -support the use of shell variables as direct commands; \c eval can -be used to work around this. +The following code will call the ls command. Note that `fish` does not support the use of shell variables as direct commands; `eval` can be used to work around this. -<pre> +\fish set cmd ls eval $cmd -</pre> +\endfish diff --git a/doc_src/exec.txt b/doc_src/exec.txt index 27f6d887..f8936101 100644 --- a/doc_src/exec.txt +++ b/doc_src/exec.txt @@ -1,15 +1,15 @@ \section exec exec - execute command in current process \subsection exec-synopsis Synopsis - <tt>exec COMMAND [OPTIONS...]</tt> +\fish{synopsis} +exec COMMAND [OPTIONS...] +\endfish \subsection exec-description Description -\c exec replaces the currently running shell with a new command. -On successful completion, \c exec never returns. \c exec cannot be used -inside a pipeline. +`exec` replaces the currently running shell with a new command. On successful completion, `exec` never returns. `exec` cannot be used inside a pipeline. + \subsection exec-example Example -<tt>exec emacs</tt> starts up the emacs text editor, and exits \c fish. -When emacs exits, the session will terminate. +`exec emacs` starts up the emacs text editor, and exits `fish`. When emacs exits, the session will terminate. diff --git a/doc_src/exit.txt b/doc_src/exit.txt index cdcf54d4..5b43b612 100644 --- a/doc_src/exit.txt +++ b/doc_src/exit.txt @@ -1,14 +1,12 @@ \section exit exit - exit the shell \subsection exit-synopsis Synopsis -<tt>exit [STATUS]</tt> +\fish{synopsis} +exit [STATUS] +\endfish \subsection exit-description Description -\c exit causes fish to exit. If <tt>STATUS</tt> is -supplied, it will be converted to an integer and used as the exit -code. Otherwise, the exit code will be that of the last command executed. +`exit` causes fish to exit. If `STATUS` is supplied, it will be converted to an integer and used as the exit code. Otherwise, the exit code will be that of the last command executed. -If exit is called while sourcing a file (using the <a -href="#source">.</a> builtin) the rest of the file will be skipped, -but the shell itself will not exit. +If exit is called while sourcing a file (using the <a href="#source">.</a> builtin) the rest of the file will be skipped, but the shell itself will not exit. diff --git a/doc_src/faq.hdr b/doc_src/faq.hdr index 81bac7ae..fbc6787d 100644 --- a/doc_src/faq.hdr +++ b/doc_src/faq.hdr @@ -1,9 +1,14 @@ -/** \page faq Frequently asked questions +/** +\page faq Frequently asked questions +\htmlonly[block] +<div class="fish_left_bar"> +<div class="logo"></div> +<div class="menu faq_menu"> -\htmlonly <div class="fish_left_bar fish_left_big"> \endhtmlonly +\endhtmlonly - <a href='#faq-envvar'>How do I set or clear an environment variable?</a> -- <a href='#faq-login-cmd'>How do I run a command every login? What's fish's equivalent to <tt>.bashrc</tt>?</a> +- <a href='#faq-login-cmd'>How do I run a command every login? What's fish's equivalent to `.bashrc`?</a> - <a href='#faq-prompt'>How do I set my prompt?</a> - <a href='#faq-cmd-history'>How do I run a command from history?</a> - <a href='#faq-subcommand'>How do I run a subcommand? The backtick doesn't work!</a> @@ -20,257 +25,198 @@ - <a href='#faq-history'>Why doesn't history substitution ("!$" etc.) work?</a> - <a href='#faq-uninstalling'>How do I uninstall fish?</a> -\htmlonly +\htmlonly[block] +</div> </div> -<div class="fish_right_bar fish_right_little"> +<div class="faq fish_right_bar"> <h1 class="interior_title">Frequently Asked Questions</h1> - \endhtmlonly + \section faq-envvar How do I set or clear an environment variable? -Use the <a href="commands.html#set"><code>set</code></a> command: +Use the <a href="commands.html#set">`set`</a> command: -<pre>set -x key value -set -e key</pre> +\fish{cli-dark} +set -x key value +set -e key +\endfish -<hr> \section faq-login-cmd How do I run a command every login? What's fish's equivalent to .bashrc? -Edit the file <tt>~/.config/fish/config.fish</tt>, creating it if it does not -exist. (Note the leading period.) +Edit the file `~/.config/fish/config.fish`, creating it if it does not exist (Note the leading period). <hr> - \section faq-prompt How do I set my prompt? -The prompt is the output of the \c fish_prompt function. Put it in -<tt>~/.config/fish/functions/fish_prompt.fish</tt>. For example, a simple -prompt is: -<pre>function fish_prompt - set_color $fish_color_cwd - echo -n (prompt_pwd) - set_color normal - echo -n ' > ' -end</pre> +The prompt is the output of the `fish_prompt` function. Put it in `~/.config/fish/functions/fish_prompt.fish`. For example, a simple prompt is: -You can also use the Web configuration tool, -<a href="commands.html#fish_config"><code>fish_config</code></a>, to preview -and choose from a gallery of sample prompts. +\fish{cli-dark} +function fish_prompt + set_color $fish_color_cwd + echo -n (prompt_pwd) + set_color normal + echo -n ' > ' +end +\endfish + +You can also use the Web configuration tool, <a href="commands.html#fish_config">`fish_config`</a>, to preview and choose from a gallery of sample prompts. -<hr> \section faq-cmd-history How do I run a command from history? -Type some part of the command, and then hit the up or down arrow keys to -navigate through history matches. +Type some part of the command, and then hit the @cursor_key{↑,up} or @cursor_key{↓,down} arrow keys to navigate through history matches. <hr> - \section faq-subcommand How do I run a subcommand? The backtick doesn't work! -\c fish uses parentheses for subcommands. For example: +`fish` uses parentheses for subcommands. For example: -<pre>for i in (ls) - echo $i -end</pre> +\fish{cli-dark} +for i in (ls) + echo $i +end +\endfish -<hr> \section faq-exit-status How do I get the exit status of a command? -Use the \c $status variable. This replaces the \c $? variable used in some -other shells. +Use the `$status` variable. This replaces the `$?` variable used in some other shells. <hr> - \section faq-single-env How do I set an environment variable for just one command? -<i><tt>SOME_VAR=1 command</tt> produces an error: <tt>Unknown command "SOME_VAR=1"</tt>.</i> +<i>`SOME_VAR=1 command` produces an error: `Unknown command "SOME_VAR=1"`.</i> -Use the \c env command. +Use the `env` command. -<tt>env SOME_VAR=1 command</tt> +`env SOME_VAR=1 command` You can also declare a local variable in a block: -<pre>begin - set -lx SOME_VAR 1 - command -end</pre> +\fish{cli-dark} +begin + set -lx SOME_VAR 1 + command +end +\endfish -<hr> \section faq-customize-colors How do I customize my syntax highlighting colors? -Use the web configuration tool, -<a href="commands.html#fish_config"><code>fish_config</code></a>, or alter the -<a href="index.html#variables-color">\c fish_color family of environment variables</a>. +Use the web configuration tool, <a href="commands.html#fish_config">`fish_config`</a>, or alter the <a href="index.html#variables-color">`fish_color` family of environment variables</a>. <hr> - \section faq-update-manpage-completions How do I update man page completions? -Use the -<a href="commands.html#fish_update_completions"><tt>fish_update_completions</tt></a> -command. +Use the <a href="commands.html#fish_update_completions">`fish_update_completions`</a> command. <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 directory to ~, -and the prompt, the pwd builtin and many other directory information -sources suggest that the current directory is ~/images and its -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. +<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> -<hr> +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: -\section faq-cd-implicit I accidentally entered a directory path and fish changed directory. What happened? +Writing `cd images; ls ..` given the above directory structure would list the contents of `~/Documents`, not of `~`, even though using `cd ..` changes the current directory to `~`, and the prompt, the `pwd` builtin and many other directory information sources suggest that the current directory is `~/images` and its 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. -If fish is unable to locate a command with a given name, and it starts with '.', '/' or '~', 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 press -<code>~</code> and enter. +Another related issue is that many programs that operate on recursive directory trees, like the find command, silently ignore symlinked directories. For example, ```find $PWD -name '*.txt'``` silently fails in shells that don't resolve symlinked paths. <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, and it starts with '`.`', '`/`' or '`~`', 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 press `~` and enter. + +<hr> \section faq-open The open command doesn't work. -The \c open command uses the MIME type database and the <code>.desktop</code> files -used by Gnome and KDE to identify filetypes and default actions. If -at least one of these environments is installed, but the open command is -not working, this probably means that the relevant files are installed -in a non-standard location. Consider <a href="index.html#more-help">asking for -more help</a>. +The `open` command uses the MIME type database and the `.desktop` files used by Gnome and KDE to identify filetypes and default actions. If at least one of these environments is installed, but the open command is not working, this probably means that the relevant files are installed in a non-standard location. Consider <a href="index.html#more-help">asking for more help</a>. <hr> - \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: - +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> +\fish{cli-dark} +echo /usr/local/bin/fish >>/etc/shells +\endfish -If you installed a prepackaged version of fish, the package manager -should have already done this for you. +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/local/bin/fish</code> +\fish{cli-dark} +chsh -s /usr/local/bin/fish +\endfish -You may need to adjust the above path to e.g. \c /usr/bin/fish. Use the command <code>which fish</code> if you are unsure of where fish is installed. +You may need to adjust the above path to e.g. `/usr/bin/fish`. Use the command `which fish` if you are unsure of where fish is installed. -Unfortunately, there is no way to make the changes take effect at once. -You will need to log out and back in again. +Unfortunately, there is no way to make the changes take effect at once. You will need to log out and back in again. <hr> - \section faq-titlebar I'm seeing weird output before each prompt when using screen. What's wrong? Quick answer: Run the following command in fish: -<pre> -echo 'function fish_title;end' > ~/.config/fish/config.fish -</pre> +\fish{cli-dark} +echo 'function fish_title;end' > ~/.config/fish/config.fish +\endfish Problem solved! The long answer: -Fish is trying to set the titlebar message of your terminal. While -screen itself supports this feature, your terminal does -not. Unfortunately, when the underlying terminal doesn't support -setting the titlebar, screen simply passes through the escape codes -and text to the underlying terminal instead of ignoring them. It is -impossible detect and resolve this problem from inside fish since fish -has no way of knowing what the underlying terminal type is. For now, -the only way to fix this is to unset the titlebar message, as -suggested above. +Fish is trying to set the titlebar message of your terminal. While screen itself supports this feature, your terminal does not. Unfortunately, when the underlying terminal doesn't support setting the titlebar, screen simply passes through the escape codes and text to the underlying terminal instead of ignoring them. It is impossible detect and resolve this problem from inside fish since fish has no way of knowing what the underlying terminal type is. For now, the only way to fix this is to unset the titlebar message, as suggested above. -Note that fish has a default titlebar message, which will be used if -the fish_title function is undefined. So simply unsetting the -fish_title function will not work. +Note that fish has a default titlebar message, which will be used if the fish_title function is undefined. So simply unsetting the fish_title function will not work. <hr> - \section faq-greeting How do I change the greeting message? -Change the value of the variable \c fish_greeting or create a \c fish_greeting -function. For example, to remove the greeting use: +Change the value of the variable `fish_greeting` or create a `fish_greeting` function. For example, to remove the greeting use: -<pre> +\fish{cli-dark} set fish_greeting -</pre> +\endfish -<hr> \section faq-history Why doesn't history substitution ("!$" etc.) work? -Because history substitution is an awkward interface that was invented before -interactive line editing was even possible. Fish drops it in favor of -perfecting the interactive history recall interface. Switching requires a -small change of habits: if you want to modify an old line/word, first recall -it, then edit. E.g. don't type "sudo !!" - first press Up, then Home, then -type "sudo ". +Because history substitution is an awkward interface that was invented before interactive line editing was even possible. Fish drops it in favor of perfecting the interactive history recall interface. Switching requires a small change of habits: if you want to modify an old line/word, first recall it, then edit. E.g. don't type "sudo !!" - first press Up, then Home, then type "sudo ". Fish history recall is very simple yet effective: - - As in any modern shell, the Up arrow recalls whole lines, starting from the last line executed. A single press replaces "!!", later presses replace "!-3" and the like. - - If the line you want is far back in the history, type any part of the line and then press Up one or more times. This will constrain the recall to lines that include this text, and you will get to the line you want much faster. This replaces "!vi", "!?bar.c" and the like. - - Alt+Up recalls individual arguments, starting from the last argument in the last line executed. A single press replaces "!$", later presses replace "!!:4" and the like. - - If the argument you want is far back in history (e.g. 2 lines back - that's a lot of words!), type any part of it and then press Alt+Up. This will show only arguments containing that part and you will get what you want much faster. Try it out, this is very convenient! - - If you want to reuse several arguments from the same line ("!!:3*" and the like), consider recalling the whole line and removing what you don't need (Alt+D and Alt+Backspace are your friends). +- As in any modern shell, the Up arrow, @cursor_key{↑,Up} recalls whole lines, starting from the last line executed. A single press replaces "!!", later presses replace "!-3" and the like. + + - If the line you want is far back in the history, type any part of the line and then press Up one or more times. This will constrain the recall to lines that include this text, and you will get to the line you want much faster. This replaces "!vi", "!?bar.c" and the like. + +- @key{Alt,↑,Up} recalls individual arguments, starting from the last argument in the last line executed. A single press replaces "!$", later presses replace "!!:4" and the like. + + - If the argument you want is far back in history (e.g. 2 lines back - that's a lot of words!), type any part of it and then press @key{Alt,↑,Up}. This will show only arguments containing that part and you will get what you want much faster. Try it out, this is very convenient! + + - If you want to reuse several arguments from the same line ("!!:3*" and the like), consider recalling the whole line and removing what you don't need (@key{Alt,D} and @key{Alt,Backspace} are your friends). See <a href='index.html#editor'>documentation</a> for more details about line editing in fish. <hr> - \section faq-uninstalling Uninstalling fish -Should you wish to uninstall fish, first ensure fish is not set as your shell. Run <code>chsh -s /bin/bash</code> if you are not sure. +Should you wish to uninstall fish, first ensure fish is not set as your shell. Run `chsh -s /bin/bash` if you are not sure. Next, do the following (assuming fish was installed to /usr/local): -<pre> +\fish{cli-dark} rm -Rf /usr/local/etc/fish /usr/local/share/fish ~/.config/fish rm /usr/local/share/man/man1/fish*.1 cd /usr/local/bin rm -f fish mimedb fishd fish_indent -</pre> +\endfish -*/ - -\htmlonly +\htmlonly[block] </div> \endhtmlonly + +*/ diff --git a/doc_src/fg.txt b/doc_src/fg.txt index 53b5154f..0c09d50f 100644 --- a/doc_src/fg.txt +++ b/doc_src/fg.txt @@ -1,14 +1,17 @@ \section fg fg - bring job to foreground \subsection fg-synopsis Synopsis -<tt>fg [PID]</tt> +\fish{synopsis} +fg [PID] +\endfish \subsection fg-description Description -\c fg brings the specified <a href="index.html#syntax-job-control">job</a> to the foreground, resuming it if it is stopped. While a foreground job is -executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground. + +`fg` brings the specified <a href="index.html#syntax-job-control">job</a> to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground. The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>. + \subsection fg-example Example -<tt>fg \%1</tt> will put the job with job ID 1 in the foreground. +`fg %1` will put the job with job ID 1 in the foreground. diff --git a/doc_src/fish.txt b/doc_src/fish.txt index ed28cffd..bf9c3eb1 100644 --- a/doc_src/fish.txt +++ b/doc_src/fish.txt @@ -1,25 +1,28 @@ \section fish fish - the friendly interactive shell \subsection fish-synopsis Synopsis -fish [-h] [-v] [-c command] [FILE [ARGUMENTS...]] +\fish{synopsis} +fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]] +\endfish \subsection fish-description Description -\c fish is a command-line shell written mainly with interactive use in mind. The -full manual is available <a href='index.html'>in HTML</a> by using the -<a href='#help'>help</a> command from inside fish. +`fish` is a command-line shell written mainly with interactive use in mind. The full manual is available <a href='index.html'>in HTML</a> by using the <a href='#help'>help</a> command from inside fish. The following options are available: -- <code>-c</code> or <code>--command=COMMANDS</code> evaluate the specified commands instead of reading from the commandline -- <code>-d</code> or <code>--debug-level=DEBUG_LEVEL</code> specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1. -- <code>-h</code> or <code>--help</code> display help and exit -- <code>-i</code> or <code>--interactive</code> specify that fish is to run in interactive mode -- <code>-l</code> or <code>--login</code> specify that fish is to run as a login shell -- <code>-n</code> or <code>--no-execute</code> do not execute any commands, only perform syntax checking -- <code>-p</code> or <code>--profile=PROFILE_FILE</code> when fish exits, output timing information on all executed commands to the specified file -- <code>-v</code> or <code>--version</code> display version and exit - -The fish exit status is generally the exit status of the last -foreground command. If fish is exiting because of a parse error, the -exit status is 127. +- `-c` or `--command=COMMANDS` evaluate the specified commands instead of reading from the commandline + +- `-d` or `--debug-level=DEBUG_LEVEL` specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1. + +- `-i` or `--interactive` specify that fish is to run in interactive mode + +- `-l` or `--login` specify that fish is to run as a login shell + +- `-n` or `--no-execute` do not execute any commands, only perform syntax checking + +- `-p` or `--profile=PROFILE_FILE` when fish exits, output timing information on all executed commands to the specified file + +- `-v` or `--version` display version and exit + +The fish exit status is generally the exit status of the last foreground command. If fish is exiting because of a parse error, the exit status is 127. diff --git a/doc_src/fish_config.txt b/doc_src/fish_config.txt index 777f2522..4fa24265 100644 --- a/doc_src/fish_config.txt +++ b/doc_src/fish_config.txt @@ -2,21 +2,17 @@ \subsection fish_config-description Description -\c fish_config starts the web-based configuration interface. +`fish_config` starts the web-based configuration interface. -The web interface allows you to view your functions, variables and history, and -to make changes to your prompt and color configuration. +The web interface allows you to view your functions, variables and history, and to make changes to your prompt and color configuration. -\c fish_config starts a local web server and then opens a web browser window; when -you have finished, close the browser window and then press the Enter key to -terminate the configuration session. +`fish_config` starts a local web server and then opens a web browser window; when you have finished, close the browser window and then press the Enter key to terminate the configuration session. -<code>fish_config</code> optionally accepts name of the initial configuration tab. For e.g. <code>fish_config history</code> will start configuration interface with history tab. +`fish_config` optionally accepts name of the initial configuration tab. For e.g. `fish_config history` will start configuration interface with history tab. + +If the `BROWSER` environment variable is set, it will be used as the name of the web browser to open instead of the system default. -If the \c BROWSER environment variable is set, it will be used as the name -of the web browser to open instead of the system default. \subsection fish_config-example Example -\c fish_config opens a new web browser window and allows you to configure certain -fish settings. +`fish_config` opens a new web browser window and allows you to configure certain fish settings. diff --git a/doc_src/fish_indent.txt b/doc_src/fish_indent.txt index c5daeace..1d4694e3 100644 --- a/doc_src/fish_indent.txt +++ b/doc_src/fish_indent.txt @@ -1,17 +1,17 @@ \section fish_indent fish_indent - indenter and prettifier \subsection fish_indent-synopsis Synopsis - <tt>fish_indent [options]</tt> +\fish{synopsis} +fish_indent [OPTIONS] +\endfish \subsection fish_indent-description Description -\c fish_indent is used to indent a piece of fish -code. \c fish_indent reads commands from standard input and outputs -them to standard output. +`fish_indent` is used to indent a piece of fish code. `fish_indent` reads commands from standard input and outputs them to standard output. The following options are available: -- <tt>-h</tt> or <tt>--help</tt> displays this help message and then exits -- <tt>-i</tt> or <tt>--no-indent</tt> do not indent commands -- <tt>-v</tt> or <tt>--version</tt> displays the current fish version and then exits +- `-i` or `--no-indent` do not indent commands + +- `-v` or `--version` displays the current fish version and then exits diff --git a/doc_src/fish_prompt.txt b/doc_src/fish_prompt.txt index 5cf5abf9..1beb5304 100644 --- a/doc_src/fish_prompt.txt +++ b/doc_src/fish_prompt.txt @@ -1,28 +1,29 @@ \section fish_prompt fish_prompt - define the appearance of the command line prompt \subsection fish_prompt-synopsis Synopsis -<pre>function fish_prompt +\fish{synopsis} +function fish_prompt ... -end</pre> +end +\endfish \subsection fish_prompt-description Description -By defining the \c fish_prompt function, the user can choose a custom -prompt. The \c fish_prompt function is executed when the prompt is to -be shown, and the output is used as a prompt. +By defining the `fish_prompt` function, the user can choose a custom prompt. The `fish_prompt` function is executed when the prompt is to be shown, and the output is used as a prompt. + +The exit status of commands within `fish_prompt` will not modify the value of <a href="index.html#variables-status">$status</a> outside of the `fish_prompt` function. -The exit status of commands within \c fish_prompt will not modify the value of <a href="index.html#variables-status">$status</a> outside of the \c fish_prompt function. +`fish` ships with a number of example prompts that can be chosen with the `fish_config` command. -\c fish ships with a number of example prompts that can be chosen with the -\c fish_config command. \subsection fish_prompt-example Example A simple prompt: -<pre> +\fish 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) + printf '%s@%s%s%s%s> ' (whoami) (hostname | cut -d . -f 1) \ + (set_color $fish_color_cwd) (prompt_pwd) (set_color normal) end -</pre> +\endfish diff --git a/doc_src/fish_right_prompt.txt b/doc_src/fish_right_prompt.txt index afe0750a..21b4a195 100644 --- a/doc_src/fish_right_prompt.txt +++ b/doc_src/fish_right_prompt.txt @@ -1,23 +1,26 @@ \section fish_right_prompt fish_right_prompt - define the appearance of the right-side command line prompt \subsection fish_right_prompt-synopsis Synopsis -<pre>function fish_right_prompt +\fish{synopsis} +function fish_right_prompt ... -end</pre> +end +\endfish \subsection fish_right_prompt-description Description -\c fish_right_prompt is similar to \c fish_prompt, except that it appears on the right side of the terminal window. +`fish_right_prompt` is similar to `fish_prompt`, except that it appears on the right side of the terminal window. + +Multiple lines are not supported in `fish_right_prompt`. -Multiple lines are not supported in \c fish_right_prompt. -\subsection fish_prompt-example Example +\subsection fish_right_prompt-example Example A simple right prompt: -<pre> +\fish function fish_right_prompt -d "Write out the right prompt" date "+%m/%d/%y" end -</pre> +\endfish diff --git a/doc_src/fish_update_completions.txt b/doc_src/fish_update_completions.txt index cff5ce0b..684dac0d 100644 --- a/doc_src/fish_update_completions.txt +++ b/doc_src/fish_update_completions.txt @@ -2,8 +2,8 @@ \subsection fish_update_completions-description Description -\c fish_update_completions parses manual pages installed on the system, and attempts to create completion files in the \c fish configuration directory. +`fish_update_completions` parses manual pages installed on the system, and attempts to create completion files in the `fish` configuration directory. This does not overwrite custom completions. -There are no parameters for <code>fish_update_completions</code>. +There are no parameters for `fish_update_completions`. diff --git a/doc_src/for.txt b/doc_src/for.txt index 67a46fc3..15b28a25 100644 --- a/doc_src/for.txt +++ b/doc_src/for.txt @@ -1,25 +1,21 @@ \section for for - perform a set of commands multiple times. \subsection for-synopsis Synopsis -<tt>for VARNAME in [VALUES...]; COMMANDS...; end</tt> +\fish{synopsis} +for VARNAME in [VALUES...]; COMMANDS...; end +\endfish \subsection for-description Description -<tt>for</tt> is a loop construct. It will perform the commands specified by -\c COMMANDS multiple times. On each iteration, the environment variable specified by -\c VARNAME is assigned a new value from \c VALUES. If \c VALUES is empty, \c COMMANDS will -not be executed at all. -\subsection for-example Example - -The command +`for` is a loop construct. It will perform the commands specified by `COMMANDS` multiple times. On each iteration, the environment variable specified by `VARNAME` is assigned a new value from `VALUES`. If `VALUES` is empty, `COMMANDS` will not be executed at all. -<tt>for i in foo bar baz; echo $i; end</tt> +\subsection for-example Example -would output: +\fish +for i in foo bar baz; echo $i; end -<pre> +# would output: foo bar baz -</pre> - +\endfish diff --git a/doc_src/funced.txt b/doc_src/funced.txt index 8b070b97..143efba4 100644 --- a/doc_src/funced.txt +++ b/doc_src/funced.txt @@ -1,21 +1,18 @@ \section funced funced - edit a function interactively \subsection funced-synopsis Synopsis - <code>funced [OPTIONS] NAME</code> +\fish{synopsis} +funced [OPTIONS] NAME +\endfish \subsection funced-description Description -\c funced provides an interface to edit the definition of the function -<code>NAME</code>. +`funced` provides an interface to edit the definition of the function `NAME`. -If the \c $EDITOR environment variable is set, it will be used as the program -to edit the function. Otherwise, a built-in editor will be used. +If the `$EDITOR` environment variable is set, it will be used as the program to edit the function. Otherwise, a built-in editor will be used. -If there is no function called \c NAME a new function will be created with -the specified name +If there is no function called `NAME` a new function will be created with the specified name -- <code>-e command</code> or <code>--editor command</code> Open the function - body inside the text editor given by the command (for example, "vi"). The - command 'fish' will use the built-in editor. -- <code>-i</code> or <code>--interactive</code> Open function body in the - built-in editor. +- `-e command` or `--editor command` Open the function body inside the text editor given by the command (for example, "vi"). The command 'fish' will use the built-in editor. + +- `-i` or `--interactive` Open function body in the built-in editor. diff --git a/doc_src/funcsave.txt b/doc_src/funcsave.txt index c81961bf..a4c9e9d8 100644 --- a/doc_src/funcsave.txt +++ b/doc_src/funcsave.txt @@ -1,13 +1,10 @@ \section funcsave funcsave - save the definition of a function to the user's autoload directory \subsection funcsave-synopsis Synopsis -<tt>funcsave FUNCTION_NAME</tt> +\fish{synopsis} +funcsave FUNCTION_NAME +\endfish \subsection funcsave-description Description -\c funcsave saves the current definition of a function to -a file in the fish configuration directory. This function will be automatically -loaded by current and future fish -sessions. This can be useful if you have interactively created a new -function and wish to save it for later use. - +`funcsave` saves the current definition of a function to a file in the fish configuration directory. This function will be automatically loaded by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use. diff --git a/doc_src/function.txt b/doc_src/function.txt index cadc0d26..8c4ba89b 100644 --- a/doc_src/function.txt +++ b/doc_src/function.txt @@ -1,62 +1,69 @@ \section function function - create a function \subsection function-synopsis Synopsis - <code>function [OPTIONS] NAME; BODY; end </code> +\fish{synopsis} +function [OPTIONS] NAME; BODY; end +\endfish \subsection function-description Description -\c function creates a new function \c NAME with the body <code>BODY</code>. +`function` creates a new function `NAME` with the body `BODY`. -A function is a list of commands that will be executed when the name of the -function is given as a command. +A function is a list of commands that will be executed when the name of the function is given as a command. The following options are available: -- <code>-a NAMES</code> or <code>--argument-names NAMES</code> assigns the value of successive command-line arguments to the names given in NAMES. -- <code>-d DESCRIPTION</code> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description. -- <code>-w WRAPPED_COMMAND</code> or \c --wraps=WRAPPED_COMMAND causes the function to inherit completions from the given wrapped command. See the documentation for \c complete for more information. -- <code>-e</code> or <code>--on-event EVENT_NAME</code> tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt. -- <code>-j PID</code> or <code> --on-job-exit PID</code> tells fish to run this function when the job with group ID PID exits. Instead of PID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution. -- <code>-p PID</code> or <code> --on-process-exit PID</code> tells fish to run this function when the fish child process with process ID PID exits. -- <code>-s</code> or <code>--on-signal SIGSPEC</code> tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP). -- \c -S or \c --no-scope-shadowing allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function. -- <code>-v</code> or <code>--on-variable VARIABLE_NAME</code> tells fish to run this function when the variable VARIABLE_NAME changes value. - -If the user enters any additional arguments after the function, they -are inserted into the environment <a href="index.html#variables-arrays">variable array</a> -<code>$argv</code>. If the \c --argument-names option is provided, the arguments are -also assigned to names specified in that option. +- `-a NAMES` or `--argument-names NAMES` assigns the value of successive command-line arguments to the names given in NAMES. + +- `-d DESCRIPTION` or `--description=DESCRIPTION` is a description of what the function does, suitable as a completion description. + +- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the function to inherit completions from the given wrapped command. See the documentation for <a href="#complete">`complete`</a> for more information. + +- `-e` or `--on-event EVENT_NAME` tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt. + +- `-j PID` or `--on-job-exit PID` tells fish to run this function when the job with group ID PID exits. Instead of PID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution. + +- `-p PID` or `--on-process-exit PID` tells fish to run this function when the fish child process with process ID PID exits. + +- `-s` or `--on-signal SIGSPEC` tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP). + +- `-S` or `--no-scope-shadowing` allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function. + +- `-v` or `--on-variable VARIABLE_NAME` tells fish to run this function when the variable VARIABLE_NAME changes value. + +If the user enters any additional arguments after the function, they are inserted into the environment <a href="index.html#variables-arrays">variable array</a> `$argv`. If the `--argument-names` option is provided, the arguments are also assigned to names specified in that option. By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the <a href="#emit">emit</a> builtin. Fish generates the following named events: -- \c fish_prompt, which is emitted whenever a new fish prompt is about to be displayed. -- \c fish_command_not_found, which is emitted whenever a command lookup failed. +- `fish_prompt`, which is emitted whenever a new fish prompt is about to be displayed. + +- `fish_command_not_found`, which is emitted whenever a command lookup failed. + \subsection function-example Example -<pre> +\fish function ll - ls -l $argv + ls -l $argv end -</pre> +\endfish -will run the \c ls command, using the \c -l option, while passing on any additional files and switches to \c ls. +will run the `ls` command, using the `-l` option, while passing on any additional files and switches to `ls`. -<pre> +\fish function mkdir -d "Create a directory and set CWD" - command mkdir $argv - if test $status = 0 - switch $argv[(count $argv)] - case '-*' - - case '*' - cd $argv[(count $argv)] - return - end - end + command mkdir $argv + if test $status = 0 + switch $argv[(count $argv)] + case '-*' + + case '*' + cd $argv[(count $argv)] + return + end + end end -</pre> +\endfish -will run the mkdir command, and if it is successful, change the -current working directory to the one just created. +This will run the `mkdir` command, and if it is successful, change the current working directory to the one just created. diff --git a/doc_src/functions.txt b/doc_src/functions.txt index c1f0115e..1a5b1c07 100644 --- a/doc_src/functions.txt +++ b/doc_src/functions.txt @@ -1,51 +1,52 @@ \section functions functions - print or erase functions -\subsection function-synopsis Synopsis -<pre>functions [-n] +\subsection functions-synopsis Synopsis +\fish{synopsis} +functions [ -a | --all ] [ -n | --names ] functions -c OLDNAME NEWNAME functions -d DESCRIPTION FUNCTION -functions [-eq] FUNCTIONS...</pre> +functions [ -e | -q ] FUNCTIONS... +\endfish \subsection functions-description Description -\c functions prints or erases functions. +`functions` prints or erases functions. The following options are available: -- <code>-a</code> or <code>--all</code> lists all functions, even those whose name start with an underscore. -- <code>-c OLDNAME NEWNAME</code> or <code>--copy OLDNAME NEWNAME</code> creates a new function named NEWNAME, using the definition of the OLDNAME function. -- <code>-d DESCRIPTION</code> or <code>--description=DESCRIPTION</code> changes the description of this function. -- <code>-e</code> or <code>--erase</code> causes the specified functions to be erased. -- <code>-h</code> or <code>--help</code> displays a help message and exits. -- <code>-n</code> or <code>--names</code> lists the names of all defined functions. -- <code>-q</code> or <code>--query</code> tests if the specified functions exist. +- `-a` or `--all` lists all functions, even those whose name start with an underscore. -The default behavior of <code>functions</code>, when called with no arguments, -is to print the names of all defined functions. Unless the \c -a option is -given, no functions starting with underscores are not included in the output. +- `-c OLDNAME NEWNAME` or `--copy OLDNAME NEWNAME` creates a new function named NEWNAME, using the definition of the OLDNAME function. -If any non-option parameters are given, the definition of the specified -functions are printed. +- `-d DESCRIPTION` or `--description=DESCRIPTION` changes the description of this function. -Automatically loaded functions cannot be removed using <code>functions --e</code>. Either remove the definition file or change the -$fish_function_path variable to remove autoloaded functions. +- `-e` or `--erase` causes the specified functions to be erased. -Copying a function using \c -c copies only the body of the function, and -does not attach any event notifications from the original function. +- `-n` or `--names` lists the names of all defined functions. -Only one function's description can be changed in a single invocation -of <code>functions -d</code>. +- `-q` or `--query` tests if the specified functions exist. -The exit status of \c functions is the number of functions -specified in the argument list that do not exist, which can be used in -concert with the \c -q option. +The default behavior of `functions`, when called with no arguments, is to print the names of all defined functions. Unless the `-a` option is given, no functions starting with underscores are not included in the output. -\subsection functions-example Examples +If any non-option parameters are given, the definition of the specified functions are printed. + +Automatically loaded functions cannot be removed using `functions -e`. Either remove the definition file or change the $fish_function_path variable to remove autoloaded functions. + +Copying a function using `-c` copies only the body of the function, and does not attach any event notifications from the original function. + +Only one function's description can be changed in a single invocation of `functions -d`. -<code>functions -n</code> displays a list of currently-defined functions. +The exit status of `functions` is the number of functions specified in the argument list that do not exist, which can be used in concert with the `-q` option. + + +\subsection functions-example Examples +\fish +functions -n +# Displays a list of currently-defined functions -<code>functions -c foo bar</code> copies the \c foo function to a new function called -<code>bar</code>. +functions -c foo bar +# Copies the 'foo' function to a new function called 'bar' -<code>functions -e bar</code> erases the function <code>bar</code>. +functions -e bar +# Erases the function `bar` +\endfish diff --git a/doc_src/help.txt b/doc_src/help.txt index c4c05382..e279e62b 100644 --- a/doc_src/help.txt +++ b/doc_src/help.txt @@ -1,20 +1,21 @@ \section help help - display fish documentation \subsection help-synopsis Synopsis - <tt>help [SECTION]</tt> +\fish{synopsis} +help [SECTION] +\endfish \subsection help-description Description -\c help displays the fish help documentation. +`help` displays the fish help documentation. -If a \c SECTION is specified, the help for that command is shown. +If a `SECTION` is specified, the help for that command is shown. -If the BROWSER environment variable is set, it will be used to display the -documentation. Otherwise, fish will search for a suitable browser. +If the BROWSER environment variable is set, it will be used to display the documentation. Otherwise, fish will search for a suitable browser. + +Note that most builtin commands display their help in the terminal when given the `--help` option. -Note that most builtin commands display their help in the terminal when -given the <tt>--help</tt> option. \subsection help-example Example -<tt>help fg</tt> shows the documentation for the \c fg builtin. +`help fg` shows the documentation for the `fg` builtin. diff --git a/doc_src/history.txt b/doc_src/history.txt index 8545361d..1bdcdf1e 100644 --- a/doc_src/history.txt +++ b/doc_src/history.txt @@ -1,47 +1,44 @@ \section history history - Show and manipulate command history \subsection history-synopsis Synopsis -<pre> -history (--save | --clear | --merge) -history (--search | --delete ) (--prefix "prefix string" | --contains "search string") -</pre> +\fish{synopsis} +history ( --merge | --save | --clear ) +history ( --search | --delete ) [ --prefix "prefix string" | --contains "search string" ] +\endfish \subsection history-description Description -\c history is used to list, search and delete the history of commands used. +`history` is used to list, search and delete the history of commands used. The following options are available: +- `--merge` immediately incorporates history changes from other sessions. Ordinarily `fish` ignores history changes from sessions started after the current one. This command applies those changes immediately. + +- `--save` saves all changes in the history file. The shell automatically saves the history file; this option is provided for internal use. + +- `--clear` clears the history file. A prompt is displayed before the history is erased. + +- `--search` returns history items in keeping with the `--prefix` or `--contains` options. + +- `--delete` deletes history items. + +- `--prefix` searches or deletes items in the history that begin with the specified text string. + +- `--contains` searches or deletes items in the history that contain the specified text string. + +If `--search` is specified without `--contains` or `--prefix`, `--contains` will be assumed. + +If `--delete` is specified without `--contains` or `--prefix`, only a history item which exactly matches the parameter will be erased. No prompt will be given. If `--delete` is specified with either of these parameters, an interactive prompt will be displayed before any items are deleted. -- \c --save saves all changes in the history file. The shell automatically -saves the history file; this option is provided for internal use. -- \c --clear clears the history file. A prompt is displayed before the history -is erased. -- \c --merge immediately incorporates history changes from other sessions. Ordinarily -fish ignores history changes from sessions started after the current one. This command -applies those changes immediately. -- \c --search returns history items in keeping with the \c --prefix or -\c --contains options. -- \c --delete deletes history items. -- \c --prefix searches or deletes items in the history that begin with the -specified text string. -- \c --contains searches or deletes items in the history that contain the -specified text string. - -If \c --search is specified without \c --contains or <code>--prefix</code>, -\c --contains will be assumed. - -If \c --delete is specified without \c --contains or <code>--prefix</code>, -only a history item which exactly matches the parameter will be erased. No -prompt will be given. If \c --delete is specified with either of these -parameters, an interactive prompt will be displayed before any items are -deleted. \subsection history-examples Example -<code>history --clear</code> deletes all history items +\fish +history --clear +# Deletes all history items -<code>history --search --contains "foo"</code> outputs a list of all previous -commands containing the string "foo". +history --search --contains "foo" +# Outputs a list of all previous commands containing the string "foo". -<code>history --delete --prefix "foo"</code> interactively deletes the record -of previous commands which start with "foo". +history --delete --prefix "foo" +# Interactively deletes the record of previous commands which start with "foo". +\endfish diff --git a/doc_src/if.txt b/doc_src/if.txt index 94d2763a..0e9a7cb1 100644 --- a/doc_src/if.txt +++ b/doc_src/if.txt @@ -1,36 +1,32 @@ \section if if - conditionally execute a command \subsection if-synopsis Synopsis -<tt>if CONDITION; COMMANDS_TRUE...; [else if CONDITION2; COMMANDS_TRUE2...;] [else; COMMANDS_FALSE...;] end</tt> +\fish{synopsis} +if CONDITION; COMMANDS_TRUE...; +[else if CONDITION2; COMMANDS_TRUE2...;] +[else; COMMANDS_FALSE...;] +end +\endfish \subsection if-description Description -<tt>if</tt> will execute the command \c CONDITION. If the condition's -exit status is 0, the commands \c COMMANDS_TRUE will execute. If the -exit status is not 0 and <tt>else</tt> is given, \c COMMANDS_FALSE will -be executed. +`if` will execute the command `CONDITION`. If the condition's exit status is 0, the commands `COMMANDS_TRUE` will execute. If the exit status is not 0 and `else` is given, `COMMANDS_FALSE` will be executed. + +In order to use the exit status of multiple commands as the condition of an if block, use <a href="#begin">`begin; ...; end`</a> and the short circuit commands <a href="commands.html#and">`and`</a> and <a href="commands.html#or">`or`</a>. -In order to use the exit status of multiple commands as the condition -of an if block, use <a href="#begin"><tt>begin; ...; end</tt></a> and -the short circuit commands <a href="commands.html#and"><tt>and</tt></a> -and <a href="commands.html#or"><tt>or</tt></a>. +The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable. -The exit status of the last foreground command to exit can always be -accessed using the <a href="index.html#variables-status">$status</a> -variable. \subsection if-example Example -<pre> +The following code will print `foo.txt exists` if the file foo.txt exists and is a regular file, otherwise it will print `bar.txt exists` if the file bar.txt exists and is a regular file, otherwise it will print `foo.txt and bar.txt do not exist`. + +\fish if test -f foo.txt - echo foo.txt exists + echo foo.txt exists else if test -f bar.txt - echo bar.txt exists + echo bar.txt exists else - echo foo.txt and bar.txt do not exist + echo foo.txt and bar.txt do not exist end -</pre>will print <tt>foo.txt exists</tt> if the file foo.txt -exists and is a regular file, otherwise it will print -<tt>bar.txt exists</tt> if the file bar.txt exists -and is a regular file, otherwise it will print -<tt>foo.txt and bar.txt do not exist</tt>. +\endfish diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in index 458930f8..4a498f9d 100644 --- a/doc_src/index.hdr.in +++ b/doc_src/index.hdr.in @@ -1,789 +1,571 @@ -/** \mainpage Fish user documentation - -\htmlonly <div class="fish_left_bar"> \endhtmlonly +/** +\mainpage Documentation +\htmlonly[block] +<div class="fish_left_bar"> +<div class="logo"></div> +<div class="menu docs_menu"> +\endhtmlonly @toc@ -\htmlonly </div> \endhtmlonly -\htmlonly -<div class="fish_right_bar"> +\htmlonly[block] +</div> +</div> +<div class="docs fish_right_bar"> +<h1 class="interior_title">Documentation</h1> \endhtmlonly + \section introduction Introduction -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://fishshell.com/"><code>fish</code> homepage</a>. +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 <a href="http://fishshell.com/">`fish` homepage</a>. + \section syntax Syntax overview -Shells like fish are used by giving them commands. Every \c fish -command follows the same simple syntax. +Shells like fish are used by giving them commands. Every `fish` command follows the same simple syntax. -A command is executed by writing the name of the command followed by -any arguments. +A command is executed by writing the name of the command followed by any arguments. Example: -<code>echo hello world</code> +\fish +echo hello world +\endfish -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. +This calls the `echo` command. `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 want to find out more about the echo command used above, read -the manual page for the echo command by writing: +If you want to find out more about the echo command used above, read the manual page for the echo command by writing: `man echo` -<code>man echo</code> +`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. -\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 <code>../checkers</code>) -has to be used. +Every program on your computer can be used as a command in `fish`. If the program file is located in one of the directories in the <a href="#variables-special"><b>`PATH`</b></a>, it is sufficient to type the name of the program to use it. Otherwise the whole filename, including the directory (like `/home/me/code/checkers/checkers` or `../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 -( ). 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 behavior 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. +- `cd`, change the current directory +- `ls`, list files and directories +- `man`, display a manual page on the screen +- `mv`, move (rename) files +- `cp`, copy files +- `open`, open files with the default application associated with each filetype +- `less`, list the contents of files + +Commands and parameters are separated by the space character ' '. 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 '`ls`' command usually lists all the files and directories in the current working directory, but by using the '`-l`' switch, the behavior 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="#expand">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, \\ followed by a newline, which deletes the backslash -and the newline, and lastly \\\\, which escapes the backslash symbol. -Single quotes have no special meaning within double quotes and vice versa. +Sometimes features such as <a href="#expand">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, `\` followed by a newline, which deletes the backslash and the newline, and lastly `\\`, which escapes the backslash symbol. Single quotes have no special meaning within double quotes and vice versa. Example: -<code>rm "cumbersome filename.txt"</code> +\fish +rm "cumbersome filename.txt" +\endfish Will remove the file 'cumbersome filename.txt', while -<code>rm cumbersome filename.txt</code> +\fish +rm <asis>cumbersome filename.txt</asis> +\endfish 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>'\\a'</code> escapes the alert character -- <code>'\\b'</code> escapes the backspace character -- <code>'\\e'</code> escapes the escape character -- <code>'\\f'</code> escapes the form feed character -- <code>'\\n'</code> escapes a newline character -- <code>'\\r'</code> escapes the carriage return character -- <code>'\\t'</code> escapes the tab character -- <code>'\\v'</code> escapes the vertical tab 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>'\\&'</code> escapes the ampersand character -- <code>'\\;'</code> escapes the semicolon character -- <code>'\\"'</code> escapes the quote character -- <code>'\\''</code> escapes the apostrophe 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. For example, \\x9 is the tab character. -- <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. For example, \\011 is the tab character. -- <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. For example, \\u9 is the tab character. -- <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. For example, \\U9 is the tab character. -- <code>'\\c<i>x</i>'</code>, where <code><i>x</i></code> is a letter of the alphabet, escapes the control sequence generated by pressing the control key and the specified letter. For example, \\ci is the tab character +Some characters can not be written directly on the command line. For these characters, so called escape sequences are provided. These are: + +- '<code>\\a</code>' escapes the alert character +- '<code>\\b</code>' escapes the backspace character +- '<code>\\e</code>' escapes the escape character +- '<code>\\f</code>' escapes the form feed character +- '<code>\\n</code>' escapes a newline character +- '<code>\\r</code>' escapes the carriage return character +- '<code>\\t</code>' escapes the tab character +- '<code>\\v</code>' escapes the vertical tab 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>\\&</code>' escapes the ampersand character +- '<code>\\;</code>' escapes the semicolon character +- '<code>\\"</code>' escapes the quote character +- '<code>\\'</code>' escapes the apostrophe 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. For example, `\x9` is the tab character. + +- '<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. For example, `\011` is the tab character. + +- '<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. For example, `\u9` is the tab character. + +- '<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. For example, `\U9` is the tab character. + +- '<code>\\c<i>x</i></code>', where <code><i>x</i></code> is a letter of the alphabet, escapes the control sequence generated by pressing the control key and the specified letter. For example, `\ci` is +the tab character + \subsection redirects Input/Output (IO) redirection -Most programs use three input/output (IO) streams, each represented by -a number called a file descriptor (FD). These are: +Most programs use three input/output (IO) streams, 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. +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. +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 output.txt. +An example of a file redirection is `echo hello > output.txt`, which directs the output of the echo command to the file output.txt. -- To read standard input from a file, write <code>\<SOURCE_FILE</code> -- To write standard output to a file, write <code>\>DESTINATION</code> -- To write standard error to a file, write <code>^DESTINATION</code> -- To append standard output to a file, write <code>\>\>DESTINATION_FILE</code> -- To append standard error to a file, write <code>^^DESTINATION_FILE</code> +- To read standard input from a file, write `<SOURCE_FILE` +- To write standard output to a file, write `DESTINATION` +- To write standard error to a file, write `^DESTINATION` +- To append standard output to a file, write `>>DESTINATION_FILE` +- To append standard error to a file, write `^^DESTINATION_FILE` -<code>DESTINATION</code> can be one of the following: +`DESTINATION` 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 output will be written to that file descriptor instead. -- An ampersand followed by a minus sign (\&-). The file descriptor will be closed. + +- An ampersand (`&`) followed by the number of another file descriptor. The output will be written to that file descriptor instead. + +- 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>. +To redirect both standard output and standard error to the file 'all_output.txt', you can write `echo Hello > all_output.txt ^&1`. -Any file descriptor can be redirected in an arbitrary way by prefixing the -redirection with the file descriptor. +Any file descriptor can be redirected in an arbitrary way by prefixing the redirection with the file descriptor. -- To redirect input of FD N, write <code>N\<DESTINATION</code> -- To redirect output of FD N, write <code>N\>DESTINATION</code> -- To append the output of FD N to a file, write <code>N\>\>DESTINATION_FILE</code> +- To redirect input of FD N, write `N<DESTINATION` +- To redirect output of FD N, write `N>DESTINATION` +- To append the output of FD N to a file, write `N>>DESTINATION_FILE` -Example: <code>echo Hello 2\>output.stderr</code> and <code>echo Hello -^output.stderr</code> are equivalent, and write the standard error (file -descriptor 2) of the target program to <code>output.stderr</code>. +Example: `echo Hello 2>output.stderr` and `echo Hello ^output.stderr` are equivalent, and write the standard error (file descriptor 2) of the target program to `output.stderr`. \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 +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> +\fish +cat foo.txt | head +\endfish -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>. +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 `man cat`. -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: +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> +\fish +make fish 2> | less +\endfish + +will attempt to build the fish program, and any errors will be shown using the less pager. -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 an \& (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. +When you start a job in `fish`, `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 an \& (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> +\fish +emacs & +\endfish will start the emacs text editor in the background. + \subsection syntax-job-control Job control -Most programs allow you to suspend the program's 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 you can go back to -the suspended command by using the <a href="commands.html#fg">fg</a> -(foreground) command. +Most programs allow you to suspend the program's execution and return control to `fish` by pressing @key{Control,Z} (also referred to as `^Z`). Once back at the `fish` commandline, you can start other programs and do anything you want. If you then want you can go back to the suspended command by using the <a href="commands.html#fg">`fg`</a> (foreground) command. -If you instead want to put a suspended job into the background, use -the <a href="commands.html#bg">bg</a> command. +If you instead want to put a suspended job into the background, use the <a href="commands.html#bg">`bg`</a> command. + +To get a listing of all currently started jobs, use the <a href="commands.html#jobs">`jobs`</a> command. -To get a listing of all currently started jobs, use the <a -href="commands.html#jobs">jobs</a> command. \subsection syntax-function Functions -Functions are programs written in the fish syntax. They group together one -or more commands and their arguments using a single name. It can also be -used to start a specific command with additional arguments. +Functions are programs written in the fish syntax. They group together one or more commands and their 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 -\c ls with the argument '-l' to print a detailed listing -of the contents of the current directory: +For example, the following is a function definition that calls the command `ls` with the argument '`-l`' to print a detailed listing of the contents of the current directory: -<pre> +\fish function ll - ls -l $argv + ls -l $argv end -</pre> +\endfish + +The first line tells fish that a function by the name of `ll` is to be defined. To use it, simply write `ll` on the commandline. The second line tells fish that the command `ls -l $argv` 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='commands.html#function'>function</a> builtin. -The first line tells fish that a function by the name of \c 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='commands.html#function'>function</a> builtin. \subsubsection syntax-function-wrappers Defining aliases -One of the most common uses for functions is to slightly alter the -behavior of an already existing command. For example, one might want -to redefine the \c ls command to display colors. The switch for -turning on colors on GNU systems is \c '--color=auto'. An alias, or -wrapper, around \c ls might look like this: +One of the most common uses for functions is to slightly alter the behavior of an already existing command. For example, one might want to redefine the `ls` command to display colors. The switch for turning on colors on GNU systems is '`--color=auto`'. An alias, or wrapper, around `ls` might look like this: -<pre>function ls - command ls --color=auto $argv +\fish +function ls + command ls --color=auto $argv end -</pre> +\endfish There are a few important things that need to be noted about aliases: -- Always take care to add the \c $argv variable to the list of parameters to the wrapped command. This makes sure that if the user specifies any additional parameters to the function, they are passed on to the underlying command. -- If the alias has the same name as the aliased command, it is necessary to prefix the call to the program with \c command in order to tell fish that the function should not call itself, but rather a command with the same name. Failing to do so will cause infinite recursion bugs. +- Always take care to add the `$argv` variable to the list of parameters to the wrapped command. This makes sure that if the user specifies any additional parameters to the function, they are passed on to the underlying command. + +- If the alias has the same name as the aliased command, it is necessary to refix the call to the program with `command` in order to tell fish that the unction should not call itself, but rather a command with the same name. ailing to do so will cause infinite recursion bugs. + +To easily create a function of this form, you can use the <a href="commands.html#alias">alias</a> command. -To easily create a function of this form, you can use the -<a href="commands.html#alias">alias</a> command. \subsubsection syntax-function-autoloading Autoloading functions -Functions can be defined on the commandline or in a configuration -file, but they can also be automatically loaded. This method of -defining functions has several advantages. An autoloaded function -becomes available automatically to all running shells. If the function -definition is changed, all running shells will automatically reload -the altered version. Startup time and memory usage is improved, etc. - -Fish automatically searches through any directories in the array -variable \c $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 \c $fish_function_path is <code>~/.config/fish/functions -/etc/fish/functions /usr/share/fish/functions</code>. The exact path -to the last two of these may be slightly 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. The path -list is searched in order, meaning that by default, the system -administrator can override default fish functions, and the user can -override functions defined by the system administrator. - -It is very important that function definition files only contain the -definition for the specified function and nothing else. Otherwise, it -is possible that autoloading a function files requires that the -function already be loaded, which creates a circular dependency. - -\subsection syntax-conditional Conditional execution of code and flow control - -There are four fish builtins that let you execute commands only if a -specific criterion is met. These builtins are -<a href="commands.html#if">if</a>, -<a href="commands.html#switch">switch</a>, -<a href="commands.html#and">and</a> and -<a href="commands.html#or">or</a>. - -The \c switch command is used to execute one of possibly many blocks -of commands depending on the value of a string. See the documentation -for <a href="commands.html#switch">switch</a> for more information. - -The other conditionals use the <a href='#variables-status'>exit -status</a> of a command to decide if a command or a block of commands -should be executed. See the documentation for -<a href="commands.html#if">if</a>, <a href="commands.html#and">and</a> -and <a href="commands.html#or">or</a> for more information. +Functions can be defined on the commandline or in a configuration file, but they can also be automatically loaded. This method of defining functions has several advantages. An autoloaded function becomes available automatically to all running shells. If the function definition is changed, all running shells will automatically reload the altered version. Startup time and memory usage is improved, etc. + +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 `~/.config/fish/functions` `/etc/fish/functions` `/usr/share/fish/functions`. The exact path to the last two of these may be slightly 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. The path list is searched in order, meaning that by default, the system administrator can override default fish functions, and the user can override functions defined by the system administrator. + +It is very important that function definition files only contain the definition for the specified function and nothing else. Otherwise, it is possible that autoloading a function files requires that the function already be loaded, which creates a circular dependency. + + +\subsubsection syntax-conditional Conditional execution of code and flow control + +There are four fish builtins that let you execute commands only if a specific criterion is met. These builtins are <a href="commands.html#if">`if`</a>, <a href="commands.html#switch">`switch`</a>, <a href="commands.html#and">`and`</a> and <a href="commands.html#or">`or`</a>. + +The `switch` command is used to execute one of possibly many blocks of commands depending on the value of a string. See the documentation for <a href="commands.html#switch">switch</a> for more information. + +The other conditionals use the <a href='#variables-status'>exit status</a> of a command to decide if a command or a block of commands should be executed. See the documentation for <a href="commands.html#if">`if`</a>, <a href="commands.html#and">`and`</a> and <a href="commands.html#or">`or`</a> for more information. + \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 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 behavior of the command. A switch almost always begins with one or two hyphens. +- <b>argument</b> a parameter given to a command + +- <b>builtin</b> 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. + +- <b>command</b> a program that the shell can run. + +- <b>function</b> a block of commands 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. + +- <b>job</b> a running pipeline or command + +- <b>pipeline</b> a set of commands stringed together so that the output of one command is the input of the next command + +- <b>redirection</b> a operation that changes one of the input/output streams associated with a job + +- <b>switch</b> a special flag sent as an argument to a command that will alter the behavior of the command. A switch almost always begins with one or two hyphens. + + +\section docs Help -\section help Help +`fish` has an extensive help system. Use the <a href="commands.html#help">`help`</a> command to obtain help on a specific subject or command. For instance, writing `help syntax` displays the <a href="#syntax">syntax section</a> of this documentation. -\c fish has an extensive help system. Use the <a -href="commands.html#help">help</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. +`fish` also has man pages for its commands. For example, `man set` will show the documentation for `set` as a man page. -fish also has man pages for its commands. For example, <code>man set</code> -will show the documentation for \c set as a man page. +Help on a specific builtin can also be obtained with the `-h` parameter. For instance, to obtain help on the `fg` builtin, either type `fg -h` or `help fg`. -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 autosuggestions Autosuggestions -fish suggests commands as you type, based on command history, completions, -and valid file paths. As you type commands, you will see a completion offered after the -cursor, in a muted gray color (which can be changed with the -<code>fish_color_autosuggestion</code> variable). +fish suggests commands as you type, based on command history, completions, and valid file paths. As you type commands, you will see a completion offered after the cursor, in a muted gray color (which can be changed with the `fish_color_autosuggestion` variable). -To accept the autosuggestion (replacing the command line contents), -press right arrow or Control-F. To accept the first suggested word, press -Alt-Right or Alt-F. If the autosuggestion is not what you want, just ignore it: -it won't execute unless you accept it. +To accept the autosuggestion (replacing the command line contents), press right arrow or @key{Control,F}. To accept the first suggested word, press @key{Alt,→,Right} or @key{Alt,F}. If the autosuggestion is not what you want, just ignore it: it won't execute unless you accept it. + +Autosuggestions are a powerful way to quickly summon frequently entered commands, by typing the first few characters. They are also an efficient technique for navigating through directory hierarchies. -Autosuggestions are a powerful way to quickly summon frequently entered commands, by -typing the first few characters. They are also an efficient technique for navigating -through directory hierarchies. \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 prefix that all completions have in common. If the 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, the tab key or the space bar. Pressing 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: +Tab completion is one of the most time saving features of any modern shell. By tapping the tab key, the user asks `fish` to guess the rest of the command or parameter that the user is currently typing. If `fish` can only find one possible completion, `fish` will write it out. If there is more than one completion, `fish` will write out the longest prefix that all completions have in common. If the 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, the tab key or the space bar. Pressing any other key will exit the list and insert the pressed key into the command line. + +These are the general purpose tab completions that `fish` provides: - Completion of commands (builtins, functions and regular programs). + - Completion of shell variable names. + - Completion of usernames for tilde expansion. -- Completion of filenames, even on strings with wildcards such as '*', '**' and '?'. + +- 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: +`fish` provides a large number of program specific completions. Most of these completions are simple options like the `-l` option for `ls`, but some are more advanced. The latter include: -- The programs \c man and \c whatis show all installed -manual pages as completions. -- The \c make program uses all targets in the Makefile in -the current directory as completions. -- The \c mount command uses all mount points specified in fstab as completions. -- The \c ssh command uses all hosts that are stored -in the known_hosts file as completions. (See the ssh documentation for more information) -- The \c 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. +- The programs `man` and `whatis` show all installed manual pages as completions. -\subsection completion-own Writing your own completions +- The `make` program uses all targets in the Makefile in the current directory as completions. -Specifying your own completions is not difficult. 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="commands.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 \c /usr/share/fish/completions. (The exact path depends on -your chosen installation prefix and may be slightly different) +- The `mount` command uses all mount points specified in fstab as completions. -\subsection completion-func Useful functions for writing completions +- The `ssh` command uses all hosts 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 `apt-get`, `rpm` and `yum` commands use all installed packages as completions. -Fish ships with several functions that are very useful when writing -command specific completions. Most of these functions name begins with -the string '__fish_'. Such functions are internal to fish and their -name and interface may change in future fish versions. Still, some of -them may be very useful when writing completions. A few of these -functions are described here. Be aware that they may be removed or -changed in future versions of fish. -Functions beginning with the string '__fish_print_' print a -newline-separated list of strings. For example, -__fish_print_filesystems prints a list of all known file systems. Functions -beginning with '__fish_complete_' print out a newline separated list of -completions with descriptions. The description is separated from the -completion by a tab character. +\subsection completion-own Writing your own completions -<pre>__fish_complete_directories STRING DESCRIPTION</pre> +Specifying your own completions is not difficult. To specify a completion, use the `complete` command. `complete` takes as a parameter the name of the command to specify a completion for. For example, to add a completion for the program `myprog`, one would start the completion command with `complete -c myprog ...` -performs path completion on STRING, allowing only directories, and giving them the description DESCRIPTION. +To provide a list of possible completions for myprog, use the `-a` switch. If `myprog` accepts the arguments start and stop, this can be specified as `complete -c myprog -a 'start stop'`. The argument to the `-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. -<pre>__fish_complete_groups</pre> +`fish` has a special syntax to support specifying switches accepted by a command. The switches `-s`, `-l` and `-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: -prints a list of all user groups with the groups members as description. +\fish +complete -c myprog -s o -l output -a "yes no" +\endfish -<pre>__fish_complete_pids</pre> +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 `complete` command, see the documentationfor the <a href="commands.html#complete">complete</a> builtin, or write `complete --help` inside the `fish` shell. -prints a list of all processes IDs with the command name as description. +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) -<pre>__fish_complete_suffix SUFFIX</pre> -performs file completion allowing only files ending in SUFFIX. The mimetype database is used to find a suitable description. +\subsection completion-func Useful functions for writing completions -<pre>__fish_complete_users</pre> +`fish` ships with several functions that are very useful when writing command specific completions. Most of these functions name begins with the string '`__fish_`'. Such functions are internal to `fish` and their name and interface may change in future fish versions. Still, some of them may be very useful when writing completions. A few of these functions are described here. Be aware that they may be removed or changed in future versions of fish. -prints a list of all users with their full name as description. +Functions beginning with the string `__fish_print_` print a newline separated list of strings. For example, `__fish_print_filesystems` prints a list of all known file systems. Functions beginning with `__fish_complete_` print out a newline separated list of completions with descriptions. The description is separated from the completion by a tab character. -<pre>__fish_print_filesystems</pre> +- `__fish_complete_directories STRING DESCRIPTION` performs path completion on STRING, allowing only directories, and giving them the description DESCRIPTION. -prints a list of all known file systems. Currently, this is a static -list, and not dependent on what file systems the host operating system -actually understands. +- `__fish_complete_groups` prints a list of all user groups with the groups members as description. -<pre>__fish_print_hostnames</pre> +- `__fish_complete_pids` prints a list of all processes IDs with the command name as description. -prints a list of all known hostnames. This functions searches the -fstab for nfs servers, ssh for known hosts and checks the /etc/hosts file. +- `__fish_complete_suffix SUFFIX` performs file completion allowing only files ending in SUFFIX. The mimetype database is used to find a suitable description. -<pre>__fish_print_interfaces</pre> +- `__fish_complete_users` prints a list of all users with their full name as description. -prints a list of all known network interfaces. +- `__fish_print_filesystems` prints a list of all known file systems. Currently, this is a static list, and not dependent on what file systems the host operating system actually understands. -<pre>__fish_print_packages</pre> +- `__fish_print_hostnames` prints a list of all known hostnames. This functions searches the fstab for nfs servers, ssh for known hosts and checks the `/etc/hosts` file. -prints a list of all installed packages. This function currently handles -Debian, rpm and Gentoo packages. +- `__fish_print_interfaces` prints a list of all known network interfaces. +- `__fish_print_packages` prints a list of all installed packages. This function currently handles Debian, rpm and Gentoo packages. \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 -\c $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'. +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 \c $fish_complete_path is <code>~/.config/fish/completions -/etc/fish/completions /usr/share/fish/completions</code>. The exact -path to the last two of these may be slightly 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. +The default value for `$fish_complete_path` is `~/.config/fish/completions` `/etc/fish/completions` `/usr/share/fish/completions`. The exact path to the last two of these may be slightly 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 submitting it via -the instructions in <a href="#more-help">Further help and development</a>. +If you have written new completions for a common Unix command, please consider sharing your work by submitting it via the instructions in <a href="#more-help">Further help and development</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. Parameter expansion is a powerful mechanism that -allows you to expand the parameter in various ways, including -performing wildcard matching on files, inserting the value of -a shell variable into the parameter or even using the output of -another command as a parameter list. +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. Parameter expansion is a powerful mechanism that allows you to expand the parameter in various ways, including performing wildcard matching on files, inserting the value of a shell variable into the parameter or even using the output of another command as a parameter list. + \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: +If a star (`*`) or a question mark (`?`) is present in the parameter, `fish` attempts to match the given parameter to any files in such a way that: -- '?' can match any single character except '/'. -- '*' can match any string of characters not containing '/'. This includes matching an empty string. -- '**' matches any string of characters. This includes matching an empty string. The string may include the '/' character but does not need to. +- `?` can match any single character except '/'. -Wildcard matches are sorted case insensitively. When sorting matches -containing numbers, consecutive digits are considered to be one -element, so that the strings '1' '5' and '12' would be sorted in the -order given. +- `*` can match any string of characters not containing '/'. This includes matching an empty string. -File names beginning with a dot are not considered when wildcarding -unless a dot is specifically given as the first character of the file -name. +- `**` matches any string of characters. This includes matching an empty string. The string may include the `/` character but does not need to. + +Wildcard matches are sorted case insensitively. When sorting matches containing numbers, consecutive digits are considered to be one element, so that the strings '1' '5' and '12' would be sorted in the order given. + +File names beginning with a dot are not considered when wildcarding unless a dot is specifically given as the first character of the file name. Examples: -<code>a*</code> matches any files beginning with an 'a' in the current directory. +- `a*` 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. +- `???` matches any file in the current directory whose name is exactly three characters long. -<code>**</code> matches any files and directories in the current directory and all of its subdirectories. +- `**` matches any files and directories in the current directory and all of its subdirectories. + +Note that 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. -Note that 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 -The output of a series of commands can be used as the parameters to another -command. If a parameter contains a set of parenthesis, the text enclosed by the -parenthesis will be interpreted as a list of commands. On 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. Setting \c IFS to the empty string will disable line splitting. +The output of a series of commands can be used as the parameters to another command. If a parameter contains a set of parenthesis, the text enclosed by the parenthesis will be interpreted as a list of commands. On 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. Setting `IFS` to the empty string will disable line splitting. -The exit status of the last run command substitution is available in the <a -href='#variables-status'>status</a> variable. +The exit status of the last run command substitution is available in the <a href='#variables-status'>status</a> variable. -Only part of the output can be used, see <a href='#expand-index-range'>index -range expansion</a> for details. +Only part of the output can be used, see <a href='#expand-index-range'>index range expansion</a> for details. Examples: -The command <code>echo (basename image.jpg .jpg).png</code> will -output 'image.png'. +\fish +echo (basename image.jpg .jpg).png +# Outputs 'image.png'. + +for i in *.jpg; convert $i (basename $i .jpg).png; end +# Convert all JPEG files in the current directory to the +# PNG format using the 'convert' program. -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 using the \c convert program. +begin; set -l IFS; set data (cat data.txt); end +# Set the `data` variable to the contents of 'data.txt' +# without splitting it into an array. +\endfish -The command <code>begin; set -l IFS; set data (cat data.txt); end</code> -will set the \c data variable to the contents of 'data.txt' without -splitting it into an array. \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. +A comma separated list of characters enclosed in curly braces will be expanded so each element of the list becomes a new parameter. -Example: +Examples: +\fish +echo input.{c,h,txt} +# Outputs 'input.c input.h input.txt' -<code>echo input.{c,h,txt}</code> outputs 'input.c input.h input.txt' +mv *.{c,h} src/ +# Moves all files with the suffix '.c' or '.h' to the subdirectory src. +\endfish -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 shell variable with the same name. For an -introduction to the concept of shell variables, read the -<a href="#variables">Shell variables</a> section. +A dollar sign followed by a string of characters is expanded into the value of the shell variable with the same name. For an introduction to the concept of shell variables, read the <a href="#variables">Shell variables</a> section. Undefined and empty variables expand to nothing. -To separate a variable name from text it should immediately be followed by, -encase the variable within braces. +To separate a variable name from text it should immediately be followed by, encase the variable within braces. Examples: +\fish +echo $HOME +# Prints the home directory of the current user. + +echo $nonexistentvariable +# Prints no output. -<code>echo $HOME</code> prints the home directory of the current -user. - -<code>echo $nonexistentvariable</code> prints no output. - -<code>echo The plural of $WORD is {$WORD}s</code> prints "The plural of -cat is cats" when \c $WORD is set to cat. Note that without the braces, fish -will try to expand a variable called <code>$WORDs</code>, which may not exist. - -The latter syntax works by exploiting <a href="#expand-brace">brace -expansion</a>; care should be taken with array variables and undefined -variables, as these behave very differently to POSIX shells. - -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. The dangers noted in the third example above can therefore be -avoided by wrapping the variable in double quotes -(<code>echo {"$WORD"}s</code>). - -There is one further notable feature of fish variable -expansion. Consider the following code snippet: - -<pre> +echo The plural of $WORD is {$WORD}s +# Prints "The plural of cat is cats" when $WORD is set to cat. +\endfish + +Note that without the braces, fish will try to expand a variable called `$WORDs`, which may not exist. + +The latter syntax works by exploiting <a href="#expand-brace">brace expansion</a>; care should be taken with array variables and undefined variables, as these behave very differently to POSIX shells. + +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. The dangers noted in the third example above can therefore be avoided by wrapping the variable in double quotes (`echo {"$WORD"}s`). + +There is one further notable feature of fish variable expansion. Consider the following code snippet: + +\fish set foo a b c set a 10; set b 20; set c 30 for i in (seq (count $$foo)) - echo $$foo[$i] + echo $$foo[$i] end + # Output is: # 10 # 20 # 30 -</pre> +\endfish + +The above code demonstrates how to use multiple '`$`' symbols to expand the value of a variable as a variable name. One can 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 fifth element of the `foo` variable should be dereferenced, not the fifth element of the doubly dereferenced variable `foo`. The latter can instead be expressed as `$$foo[1][5]`. -The above code demonstrates how to use multiple '$' symbols to expand -the value of a variable as a variable name. One can 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, <code>$$foo[5]</code> will always mean the fifth -element of the \c foo variable should be dereferenced, not the fifth -element of the doubly dereferenced variable \c foo. The latter can -instead be expressed as <code>$$foo[1][5]</code>. \subsection expand-index-range Index range expansion -Both command substitution and shell variable expansion support accessing only -specific items by providing a set of indices in square brackets. It's -often needed to access a sequence of elements. To do this, use the range -operator '..' for this. A range <code>'a..b'</code>, where range limits 'a' -and 'b' are integer numbers, is expanded into a sequence of indices -'a a+1 a+2 ... b' or 'a a-1 a-2 ... b' depending on which of 'a' or 'b' -is higher. The negative range limits are calculated from the end of the array -or command substitution. +Both command substitution and shell variable expansion support accessing only specific items by providing a set of indices in square brackets. It's often needed to access a sequence of elements. To do this, use the range operator '`..`' for this. A range '`a..b`', where range limits 'a' and 'b' are integer numbers, is expanded into a sequence of indices '`a a+1 a+2 ... b`' or '`a a-1 a-2 ... b`' depending on which of 'a' or 'b' is higher. The negative range limits are calculated from the end of the array or command substitution. Some examples: -<pre> + +\fish # Limit the command substitution output -echo (seq 10)[2..5] # will use elements from 2 to 5 -# Output is: -# 2 3 4 5 +echo (seq 10)[2..5] +# Uses elements from 2 to 5 +# Output is: 2 3 4 5 # Use overlapping ranges: -echo (seq 10)[2..5 1..3] # will take elements from 2 to 5 and then elements from 1 to 3 -# Output is: -# 2 3 4 5 1 2 3 +echo (seq 10)[2..5 1..3] +# Takes elements from 2 to 5 and then elements from 1 to 3 +# Output is: 2 3 4 5 1 2 3 # Reverse output -echo (seq 10)[-1..1] # will use elements from the last output line to the first one in reverse direction -# Output is: -# 10 9 8 7 6 5 4 3 2 1 -</pre> +echo (seq 10)[-1..1] +# Uses elements from the last output line to +# the first one in reverse direction +# Output is: 10 9 8 7 6 5 4 3 2 1 +\endfish The same works when setting or expanding variables: -<pre> + +\fish # Reverse path variable set PATH $PATH[-1..1] -# or +# or set PATH[-1..1] $PATH # Use only n last items of the PATH set n -3 echo $PATH[$n..-1] -</pre> +\endfish + +Note that variables can be used as indices for expansion of variables, but not command substitution. -Note that variables can be used as indices for expansion of variables, but not -command substitution. \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. +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 (PID). The following expansions are -performed: - -- If the string is the entire word \c self, the shell's PID 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. +The `%` (percent) character at the beginning of a parameter followed by a string is expanded into a process ID (PID). The following expansions are performed: + +- If the string is the entire word `self`, the shell's PID 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. + - If none of these matches apply, an error is produced. -This form of expansion is useful for commands like kill and fg, which -take process IDs as arguments. +This form of expansion is useful for commands like kill and fg, which take process IDs as arguments. 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. +`fg %ema` will search for a process whose command line begins with the letters 'ema', such as emacs, and if found, put it in the foreground. + +`kill -s SIGINT %3` will send the SIGINT signal to the job with job ID 3. -<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. +All of the above expansions can be combined. If several expansions result in more than one parameter, all possible combinations are created. When combining multiple parameter expansions, expansions are performed in the following order: @@ -793,508 +575,446 @@ When combining multiple parameter expansions, expansions are performed in the fo - Pid expansion - Wildcard expansion -Expansions are performed from right to left, nested bracket expansions -are performed from the inside and out. +Expansions are performed from right to left, nested bracket expansions are performed from the inside and out. 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'. +If the current directory contains the files 'foo' and 'bar', the command `echo a(ls){1,2,3} ` will output 'abar1 abar2 abar3 afoo1 afoo2 afoo3'. \section variables Shell variables -Shell variables are named pieces of data, which can be created, deleted -and their values changed and used by the user. Variables may optionally be "exported", so -that a copy of the variable is available to any subprocesses the shell creates. An -exported variable is referred to as an "environment variable". +Shell variables are named pieces of data, which can be created, deleted and their values changed and used by the user. Variables may optionally be "exported", so that a copy of the variable is available to any subprocesses the shell creates. An exported variable is referred to as an "environment variable". -To set a variable value, use the <a href="commands.html#set"> \c set -command</a>. +To set a variable value, use the <a href="commands.html#set">`set` command</a>. Example: -To set the variable \c smurf_color to the value \c blue, use the command -<code>set smurf_color blue</code>. +To set the variable `smurf_color` to the value `blue`, use the command `set smurf_color blue`. -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>. +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 the variable \c smurf, write $ (dollar symbol) -followed by the name of the variable, like <code>echo Smurfs are -usually $smurf_color</code>, which would print the result 'Smurfs are -usually blue'. +To use the value of the variable `smurf`, write `$` (dollar symbol) followed by the name of the variable, like `echo Smurfs are usually $smurf_color`, which would print the result 'Smurfs are usually 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: +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 `set -e`. 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 `for`, `while` , `if`, `function`, `begin` or `switch`, and ends with the command `end`. The user can specify that a variable should have either global or local scope using the `-g/--global` or `-l/--local` switches. + +Variables can be explicitly set to be universal with the `-U` or `--universal` switch, global with the `-g` or `--global` switch, or local with the `-l` or `--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 function. Note that this is different from using the \c -l or \c --local flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. 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. +-# 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 function. Note that this is different from using the `-l` or `--local` flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. 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> + +\fish begin - # This is a nice local scope where all variables will die - set -l pirate 'There be treasure in them thar hills' + # 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> +# This will not output anything, since the pirate was local +\endfish + \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. +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 `set fish_color_cwd blue`. Since `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. -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 current local 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. +When calling a function, all current local 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': +For example: -<pre> +\fish function shiver - set phrase 'Shiver me timbers' + 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 + set phrase 'Avast, mateys' + # Calling the shiver function here can not + # change any variables in the local scope + shiver + echo $phrase end - avast -</pre> + +# Outputs "Avast, mateys" +\endfish + \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 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: +Variables can be explicitly set to be exported with the `-x` or `--export` switch, or not exported with the `-u` or `--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 exported or not exported 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: +`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> +`echo $PATH[3]` -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 \c seq -are more suited to such use. +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: +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> +\fish for i in $PATH; echo $i is in the path; end -</pre> +\endfish -To create a variable \c smurf, containing the items \c blue and \c -small, simply write: +To create a variable `smurf`, containing the items `blue` and `small`, simply write: -<pre> +\fish set smurf blue small -</pre> +\endfish 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' +\fish +# Set smurf to be an array with the elements 'blue' and 'small' set smurf blue small -\#Change the second element of smurf to 'evil' +# Change the second element of smurf to 'evil' set smurf[2] evil -\#Erase the first element +# Erase the first element set -e smurf[1] -\#Output 'evil' +# Output 'evil' echo $smurf -</pre> +\endfish + +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. -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. +A range of indices can be specified, see <a href='#expand-index-range'>index range expansion</a> for details. -A range of indices can be specified, see <a href='#expand-index-range'>index -range expansion</a> for details. +All arrays are one-dimensional and cannot contain other arrays, although it is possible to fake nested arrays using the dereferencing rules of <a href="#expand-variable">variable expansion</a>. -All arrays are one-dimensional and cannot contain other arrays, although -it is possible to fake nested arrays using the dereferencing rules of -<a href="#expand-variable">variable expansion</a>. \subsection variables-special Special variables -The user can change the settings of \c fish by changing the values of +The user can change the settings of `fish` by changing the values of certain environment variables. -- \c BROWSER, the user's 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, an array of directories in which to search for the new directory for the \c cd builtin. By default, the fish configuration defines \c CDPATH to be a universal variable with the values \c . and \c ~. -- 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 fish_greeting, the greeting message printed on startup. -- \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 fish_user_paths, an array of directories that are prepended to PATH. This can be a universal variable. -- \c PATH, an array of directories in which to search for commands -- \c umask, the current file creation mask. The preferred way to change the umask variable is through the <a href="commands.html#umask">umask 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 cannot change the -values of most of these variables. - -- \c _, the name of the currently running command. -- \c argv, 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, an array containing the last commands that were entered. -- \c HOME, the user's home directory. This variable can be changed by the user. -- \c IFS, the internal field separator that is used for word splitting with the <a href="commands.html#read">read builtin</a>. Setting this to the empty string will also disable line splitting in <a href="#expand-command-substitution">command substitution</a>. This variable can be changed by the user. -- \c PWD, the current working directory. -- \c status, the <a href="#variables-status">exit status</a> of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number. -- \c USER, the current username. This variable can be changed by the user. -- \c CMD_DURATION, the runtime of the last command in milliseconds. - -The names of these variables are mostly derived from the csh family of -shells and differ from the ones used by Bourne style shells such as -bash. - -Variables whose name are in uppercase are exported to the commands -started by fish, while 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 \c __FISH or \c __fish. These should never be used by the -user. Changing their value may break fish. +- `BROWSER`, the user's 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. + +- `CDPATH`, an array of directories in which to search for the new directory for the `cd` builtin. By default, the fish configuration defines `CDPATH` to be a universal variable with the values `.` and `~`. + +- A large number of variable starting with the prefixes `fish_color` and `fish_pager_color.` See <a href='#variables-color'>Variables for changing highlighting colors</a> for more information. + +- `fish_greeting`, the greeting message printed on startup. + +- `LANG`, `LC_ALL`, `LC_COLLATE`, `LC_CTYPE`, `LC_MESSAGES`, `LC_MONETARY`, `LC_NUMERIC` and `LC_TIME` set the language option for the shell and subprograms. See the section <a href='#variables-locale'>Locale variables</a> for more information. + +- `fish_user_paths`, an array of directories that are prepended to `PATH`. This can be a universal variable. + +- `PATH`, an array of directories in which to search for commands + +- `umask`, the current file creation mask. The preferred way to change the umask variable is through the <a href="commands.html#umask">umask function</a>. An attempt to set umask to an invalid value will always fail. + +`fish` also sends additional information to the user through the values of certain environment variables. The user cannot change the values of most of these variables. + +- `_`, the name of the currently running command. + +- `argv`, an array of arguments to the shell or function. `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. + +- `history`, an array containing the last commands that were entered. + +- `HOME`, the user's home directory. This variable can be changed by the user. + +- `IFS`, the internal field separator that is used for word splitting with the <a href="commands.html#read">read builtin</a>. Setting this to the empty string will also disable line splitting in <a href="#expand-command-substitution">command substitution</a>. This variable can be changed by the user. + +- `PWD`, the current working directory. + +- `status`, the <a href="#variables-status">exit status</a> of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number. + +- `USER`, the current username. This variable can be changed by the user. + +- `CMD_DURATION`, the runtime of the last command in milliseconds. + +The names of these variables are mostly derived from the csh family of shells and differ from the ones used by Bourne style shells such as bash. + +Variables whose name are in uppercase are exported to the commands started by fish, while 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. `fish` also uses several variables internally. Such variables are prefixed with the string `__FISH` or `__fish.` These should never be used by the user. Changing their value may break fish. \subsection variables-status The status variable -Whenever a process exits, an exit status is returned to the program -that started it (usually the shell). This exit status is an integer -number, which tells the calling application how the execution of the -command went. In general, a zero exit status means that the command -executed without problem, but a non-zero exit status means there was -some form of problem. +Whenever a process exits, an exit status is returned to the program that started it (usually the shell). This exit status is an integer number, which tells the calling application how the execution of the command went. In general, a zero exit status means that the command executed without problem, but a non-zero exit status means there was some form of problem. -Fish stores the exit status of the last process in the last job to -exit in the \c status variable. +Fish stores the exit status of the last process in the last job to exit in the `status` variable. -If \c fish encounters a problem while executing a command, the status -variable may also be set to a specific value: +If `fish` encounters a problem while executing a command, the status variable may also be set to a specific value: - 1 is the generally the exit status from fish builtin commands if they were supplied with invalid arguments + - 124 means that the command was not executed because none of the wildcards in the command produced any matches + - 125 means that while an executable with the specified name was located, the operating system could not actually execute the command + - 126 means that while a file with the specified name was located, it was not executable + - 127 means that no function, builtin or command with the given name could be located If a process exits through a signal, the exit status will be 128 plus the number of the signal. + \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'>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 highlighting 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 -- \c fish_pager_color_secondary, the background color of the every second completion +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'>set_color</a> command. The `--bold` or `-b` switches accepted by `set_color` are also accepted. + +The following variables are available to change the highlighting colors in fish: + +- `fish_color_normal`, the default color + +- `fish_color_command`, the color for commands + +- `fish_color_quote`, the color for quoted blocks of text + +- `fish_color_redirection`, the color for IO redirections + +- `fish_color_end`, the color for process separators like ';' and '&' + +- `fish_color_error`, the color used to highlight potential errors + +- `fish_color_param`, the color for regular command parameters + +- `fish_color_comment`, the color used for code comments + +- `fish_color_match`, the color used to highlight matching parenthesis + +- `fish_color_search_match`, the color used to highlight history search matches + +- `fish_color_operator`, the color for parameter expansion operators like '*' and '~' + +- `fish_color_escape`, the color used to highlight character escapes like '\\n' and '\\x70' + +- `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: + +- `fish_pager_color_prefix`, the color of the prefix string, i.e. the string that is to be completed + +- `fish_pager_color_completion`, the color of the completion itself + +- `fish_pager_color_description`, the color of the completion description + +- `fish_pager_color_progress`, the color of the progress bar at the bottom left corner + +- `fish_pager_color_secondary`, the background color of the every second completion Example: To make errors highlighted and red, use: -<code>set fish_color_error red --bold</code> +\fish +set fish_color_error red --bold +\endfish + \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'. +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'. + +`LANG`, `LC_ALL`, `LC_COLLATE`, `LC_CTYPE`, `LC_MESSAGES`, `LC_MONETARY`, `LC_NUMERIC` and `LC_TIME` set the language option for the shell and subprograms. These variables work as follows: `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. -\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 Builtin commands -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. To avoid -code duplication, and to avoid the confusion of subtly differing -versions of the same command, \c fish generally only implements builtins for -actions which cannot be performed by a regular command. +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. To avoid code duplication, and to avoid the confusion of subtly differing versions of the same command, `fish` generally only implements builtins for actions which cannot be performed by a regular command. + +For a list of all builtins, functions and commands shipped with fish, see the <a href="#toc-commands">table of contents</a>. The documentation is also available by using the `--help` switch of the command. -For a list of all builtins, functions and commands shipped with fish, -see the <a href="#toc-commands">table of contents</a>. The -documentation is also available by using the <code>--help</code> -switch of the command. \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 `fish` editor features copy and paste, a searchable history and many editor functions that can be bound to special keyboard shortcuts. + +Similar to bash, fish has Emacs and Vi editing modes. The default editing mode is Emacs. You can switch to Vi mode with `fish_vi_key_bindings` and switch back with `fish_default_key_bindings`. -Similar to bash, fish has Emacs and Vi editing modes. The default -editing mode is Emacs. You can switch to Vi mode with \c fish_vi_key_bindings -and switch back with \c fish_default_key_bindings. \subsection emacs-mode Emacs mode commands -- Tab <a href="#completion">completes</a> the current token. -- Home or Ctrl-A moves the cursor to the beginning of the line. -- End or Ctrl-E moves to the end of line. If the cursor is already at the end of the line, and an autosuggestion is available, End or Ctrl-E accepts the autosuggestion. -- Left (or Ctrl-B) and Right (or Ctrl-F) move the cursor left or right by one character. If the cursor is already at the end of the line, and an autosuggestion is available, the Right key and the Ctrl-F combination accept the suggestion. -- Alt-Left and Alt-Right move the cursor one word left or right, or moves forward/backward in the directory history if the command line is empty. If the cursor is already at the end of the line, and an autosuggestion is available, Alt-Right (or Alt-F) accepts the first word in the suggestion. -- 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 respectively. -- Ctrl-C deletes the entire line. -- Ctrl-D delete one character to the right of the cursor. If the command line is empty, Ctrl-D will exit fish. -- Ctrl-K moves contents from the cursor to the end of line to the <a href="#killring">killring</a>. -- Ctrl-U moves contents from the beginning of line to the cursor to the <a href="#killring">killring</a>. -- Ctrl-L clears and repaints the screen. -- Ctrl-W moves the previous word to the <a href="#killring">killring</a>. -- Alt-D moves the 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 <code>'| less;'</code> to the end of the job under the cursor. The result is that the output of the command will be paged. -- Alt-C capitalizes the current word. -- Alt-U makes the current word uppercase. -- F1 shows the manual page for the current command, if one exists. - -You can change these key bindings using the -<a href="commands.html#bind">bind</a> builtin command. +- @key{Tab} <a href="#completion">completes</a> the current token. + +- @key{Home} or @key{Control,A} moves the cursor to the beginning of the line. + +- @key{End} or @key{Control,E} moves to the end of line. If the cursor is already at the end of the line, and an autosuggestion is available, @key{End} or @key{Control,E} accepts the autosuggestion. + +- @cursor_key{←,Left} (or @key{Control,B}) and @cursor_key{→,Right} (or @key{Control,F}) move the cursor left or right by one character. If the cursor is already at the end of the line, and an autosuggestion is available, the @cursor_key{→,Right} key and the @key{Control,F} combination accept the suggestion. + +- @key{Alt,←,Left} and @key{Alt,→,Right} move the cursor one word left or right, or moves forward/backward in the directory history if the command line is empty. If the cursor is already at the end of the line, and an autosuggestion is available, @key{Alt,→,Right} (or @key{Alt,F}) accepts the first word in the suggestion. + +- @cursor_key{↑,Up} and @cursor_key{↓,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. + +- @key{Alt,↑,Up} and @key{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. + +- @key{Delete} and @key{Backspace} removes one character forwards or backwards respectively. + +- @key{Control,C} deletes the entire line. + +- @key{Control,D} delete one character to the right of the cursor. If the command line is empty, @key{Control,D} will exit fish. + +- @key{Control,K} moves contents from the cursor to the end of line to the <a href="#killring">killring</a>. + +- @key{Control,U} moves contents from the beginning of line to the cursor to the <a href="#killring">killring</a>. + +- @key{Control,L} clears and repaints the screen. + +- @key{Control,W} moves the previous word to the <a href="#killring">killring</a>. + +- @key{Alt,D} moves the next word to the <a href="#killring">killring</a>. + +- @key{Alt,W} prints a short description of the command under the cursor. + +- @key{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. + +- @key{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. + +- @key{Alt,C} capitalizes the current word. + +- @key{Alt,U} makes the current word uppercase. + +- @key{F1} shows the manual page for the current command, if one exists. + +You can change these key bindings using the <a href="commands.html#bind">bind</a> builtin command. + \subsection vi-mode Vi mode commands -Vi mode allows for the use of Vi-like commands when at the bash prompt. -You'll initially be in insert mode. Hitting the escape key takes you -into command mode where you can use, but aren't limited to, the following. - -- h moves cursor left -- l moves cursor right -- A moves cursor to end of line and put in insert mode -- 0 (zero) Move cursor to beginning of line (doesn't put in insert mode) -- i put into insert mode at current position -- a put into insert mode after current position -- dd Delete line (saved for pasting) -- D delete text after current cursor position (saved for pasting) -- p paste text that was deleted -- u undo +Vi mode allows for the use of Vi-like commands when at the bash prompt. You'll initially be in insert mode. Hitting the escape key takes you into command mode where you can use, but aren't limited to, the following. + +- @key{h} moves cursor left + +- @key{l} moves cursor right + +- @key{Shift,A} moves cursor to end of line and put in insert mode + +- @key{0} (zero) Move cursor to beginning of line (doesn't put in insert mode) + +- @key{i} put into insert mode at current position + +- @key{a} put into insert mode after current position + +- @key{d}@key{d} Delete line (saved for pasting) + +- @key{Shift,D} delete text after current cursor position (saved for pasting) + +- @key{p} paste text that was deleted + +- @key{u} undo + - etc for many of the other Vi commands + \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. +`fish` uses an Emacs style kill ring for copy and paste functionality. Use @key{Control,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 @key{Control,Y}. After pasting, use @key{Alt,Y} to rotate to the previous kill. -If the environment variable DISPLAY is set and the \c xsel program is installed, \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. +If the environment variable `DISPLAY` is set and the `xsel` program is installed, `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. +\subsection history-search Searchable history -By pressing Alt-Up and Alt-Down, a history search is also performed, -but instead of searching for a complete commandline, each commandline -is broken into separate elements just like it would be before -execution, and the history is searched for an element matching that under -the cursor. +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 @key{Alt,↑,Up} and @key{Alt,↓,Down}, a history search is also performed, but instead of searching for a complete commandline, each commandline is broken into separate elements just like it would be before execution, and the history is searched for an element matching that under the cursor. History searches can be aborted by pressing the escape key. -Prefixing the commandline with a space will prevent the entire line -from being stored in the history. +Prefixing the commandline with a space will prevent the entire line from being stored in the history. -The history is stored in the file <code>~/.config/fish/fish_history</code>. +The history is stored in the file `~/.config/fish/fish_history`. Examples: -To search for previous entries containing the word \c 'make', type \c 'make' -in the console and press the up key. +To search for previous entries containing the word 'make', type `make` in the console and press the up key. + +If the commandline reads `cd m`, place the cursor over the `m` character and press @key{Alt,↑,Up} to search for previously typed words containing 'm'. -If the commandline reads '<code>cd m</code>', place the cursor over the \c m -character and press Alt-Up to search for previously typed words containing 'm'. \subsection multiline Multiline editing -The fish commandline editor can be used to work on commands that are -several lines long. There are three ways to make a command span more -than a single line: +The fish commandline editor can be used to work on commands that are several lines long. There are three ways to make a command span more than a single line: + +- Pressing the @key{Enter} key while a block of commands is unclosed, such as when one or more block commands such as `for`, `begin` or `if` do not have a corresponding `end` command. -- Pressing the Enter key while a block of commands is unclosed, such as when one or more block commands such as \c 'for', \c 'begin' or \c 'if' do not have a corresponding \c 'end' command. -- Pressing Alt-Enter instead of pressing the Enter key. -- By inserting a backslash (\\) character before pressing the Enter key, escaping the newline. +- Pressing @key{Alt,Enter} instead of pressing the @key{Enter} key. + +- By inserting a backslash (`\`) character before pressing the @key{Enter} key, escaping the newline. + +The fish commandline editor works exactly the same in single line mode and in multiline mode. To move between lines use the left and right arrow keys and other such keyboard shortcuts. -The fish commandline editor works exactly the same in single line mode -and in multiline mode. To move between lines use the left and right -arrow keys and other such keyboard shortcuts. \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 behavior. +Normally when `fish` starts a program, this program will be put in the foreground, meaning it will take control of the terminal and `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 fish's behavior. + +-# By ending a command with the `&` (ampersand) symbol, the user tells `fish` to put the specified command into the background. A background process will be run simultaneous with `fish`. `fish` will retain control of the terminal, so the program will not be able to read from the keyboard. + +-# By pressing @key{Control,Z}, the user stops a currently running foreground program and returns control to `fish`. Some programs do not support this feature, or remap it to another key. GNU Emacs uses @key{Control,X} @key{z} to stop running. --# 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="commands.html#fg">fg</a> and <a href="commands.html#bg">bg</a> builtin commands, the user can send any currently running job into the foreground or background. +-# By using the <a href="commands.html#fg">`fg`</a> and <a href="commands.html#bg">`bg`</a> builtin commands, the user can send any currently running job into the foreground or background. + +Note that functions cannot be started in the background. Functions that are stopped and then restarted in the background using the `bg` command will not execute correctly. -Note that functions cannot be started in the background. Functions that -are stopped and then restarted in the background using the \c bg command -will not execute correctly. \section initialization Initialization files -On startup, \c fish evaluates the files /usr/share/fish/config.fish -(Or /usr/local/fish... if you installed fish in /usr/local), -/etc/fish/config.fish (Or ~/etc/fish/... if you installed fish in your -home directory) and ~/.config/fish/config.fish (Or any other directory -specified by the \$XDG_CONFIG_HOME variable), 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. +On startup, `fish` evaluates the files `/usr/share/fish/config.fish` (Or `/usr/local/fish...` if you installed fish in `/usr/local`), `/etc/fish/config.fish` (Or `~/etc/fish/...` if you installed fish in your home directory) and `~/.config/fish/config.fish` (Or any other directory specified by the `$XDG_CONFIG_HOME` variable), 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 ~/.config/fish/config.fish file: +If you want to add the directory `~/linux/bin` to your PATH variable when using a login shell, add the following to your `~/.config/fish/config.fish` file: -<pre>if status --is-login - set PATH $PATH ~/linux/bin -end</pre> +\fish +if status --is-login + set PATH $PATH ~/linux/bin +end +\endfish -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: +If you want to run a set of commands when `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> +\fish +function on_exit --on-process %self + echo fish is now exiting +end +\endfish + + +<a href="#variables-universal">Universal variables</a> are stored in the file `.config/fish/fishd.MACHINE_ID`, where MACHINE_ID is typically your MAC address. Do not edit this file directly, as your edits may be overwritten. Edit them through fish scripts or by using fish interactively instead. -<a href="#variables-universal">Universal variables</a> are stored in -the file .config/fish/fishd.MACHINE_ID, where MACHINE_ID is typically your -MAC address. Do not edit this file directly, as your edits may be overwritten. -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. +`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: @@ -1303,73 +1023,47 @@ Detected errors include: - 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, \c fish_pager_color_progress -and \c fish_pager_color_secondary. 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. + +When the cursor is over a parenthesis or a quote, `fish` also highlights its matching quote or parenthesis. + +To customize the syntax highlighting, you can set the environment variables `fish_color_normal`, `fish_color_command`, `fish_color_substitution`, `fish_color_redirection`, `fish_color_end`, `fish_color_error`, `fish_color_param`, `fish_color_comment`, `fish_color_match`, `fish_color_search_match`, `fish_color_cwd`, `fish_pager_color_prefix`, `fish_pager_color_completion`, `fish_pager_color_description`, `fish_pager_color_progress` and `fish_pager_color_secondary`. Usually, the value of these variables will be one of `black`, `red`, `green`, `brown`, `yellow`, `blue`, `magenta`, `purple`, `cyan`, `white` or `normal`, but they can be an array containing any color options for the `set_color` command. + +\fish +set fish_color_error black --background=red --bold +# Make all commandline errors be written in a black, +# bold font, with a red background. +\endfish \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 \c fish_prompt function is called. -The first argument to fish_title will contain the most -recently executed foreground command as a string, starting with fish 2.2. +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 `fish_title` function. The `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. The first argument to fish_title will contain the most recently executed foreground command as a string, starting with fish 2.2. Examples: -<p> -The default \c fish title is -</p> -<p> -<pre> +The default `fish` title is + +\fish function fish_title echo $_ ' ' pwd end -</pre> -</p> +\endfish -<p> To show the last command in the title: -</p> -<p> -<pre> + +\fish function fish_title echo $argv[1] end -</pre> -</p> +\endfish \subsection greeting Configurable greeting -If a function named \c fish_greeting exists, it will be run when entering -interactive mode. Otherwise, if an environment variable named \c fish_greeting -exists, it will be printed. +If a function named `fish_greeting` exists, it will be run when entering interactive mode. Otherwise, if an environment variable named `fish_greeting` exists, it will be printed. + \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 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 @@ -1381,49 +1075,41 @@ Example: To specify a signal handler for the WINCH signal, write: -<pre>function --on-signal WINCH my_signal_handler - echo Got WINCH signal! +\fish +function --on-signal WINCH my_signal_handler + echo Got WINCH signal! end -</pre> +\endfish + +For more information on how to define new event handlers, see the documentation for the <a href='commands.html#function'>function</a> command. -For more information on how to define new event handlers, see the -documentation for the <a href='commands.html#function'>function</a> -command. \subsection debugging Debugging fish scripts -Fish includes a built in debugger. The debugger allows you to stop -execution of a script at an arbitrary point and launch a prompt. This -prompt can then be used to check or change the value of any variables -or perform any shellscript command. To resume normal execution of the -script, simply exit the prompt. +Fish includes a built in debugger. The debugger allows you to stop execution of a script at an arbitrary point and launch a prompt. This prompt can then be used to check or change the value of any variables or perform any shellscript command. To resume normal execution of the script, simply exit the prompt. + +To start the debugger, simply call the builtin command `breakpoint`. The default action of the TRAP signal is to call this builtin, so a running script can be debugged by sending it the TRAP signal. Once in the debugger, it is easy to insert new breakpoints by using the funced function to edit the definition of a function. -To start the debugger, simply call the builtin command -'breakpoint'. The default action of the TRAP signal is to call this -builtin, so a running script can be debugged by sending it the TRAP -signal. Once in the debugger, it is easy to insert new breakpoints by -using the funced function to edit the definition of a function. \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 initialization files to function properly. To solve this -problem, either copy the initialization files to each fish users home -directory, or install them in /etc. +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 initialization 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 more-help Further help and development -If you have a question not answered by this documentation, there are -several avenues for help: +If you have a question not answered by this documentation, there are several avenues for help: -# The official mailing list at <a href='https://lists.sf.net/lists/listinfo/fish-users'>fish-users@lists.sf.net</a> --# The Internet Relay Chat channel, \c #fish on \c irc.oftc.net + +-# The Internet Relay Chat channel, \#fish on `irc.oftc.net` + -# The <a href="https://github.com/fish-shell/fish-shell/">project GitHub page</a> -If you have an improvement for fish, you can submit it via the mailing list -or the GitHub page. -*/ +If you have an improvement for fish, you can submit it via the mailing list or the GitHub page. -\htmlonly </div> \endhtmlonly +\htmlonly[block] +</div> +\endhtmlonly +*/ diff --git a/doc_src/isatty.txt b/doc_src/isatty.txt index 0a0caf73..91e5c9c7 100644 --- a/doc_src/isatty.txt +++ b/doc_src/isatty.txt @@ -1,29 +1,33 @@ \section isatty isatty - test if a file or file descriptor is a tty. \subsection isatty-synopsis Synopsis -<tt>isatty [FILE | DEVICE | FILE DESCRIPTOR NUMBER]</tt> +\fish{synopsis} +isatty [FILE | DEVICE | FILE DESCRIPTOR NUMBER] +\endfish \subsection isatty-description Description -<tt>isatty</tt> tests if a file or file descriptor is a tty. -The argument may be in the form of a file path, device, or file descriptor -number. Without an argument, <tt>standard input</tt> is implied. + +`isatty` tests if a file or file descriptor is a tty. The argument may be in the form of a file path, device, or file descriptor number. Without an argument, `standard input` is implied. If the resolved file descriptor is a tty, the command returns zero. Otherwise, the command exits one. No messages are printed to standard error. + \subsection isatty-examples Examples From an interactive shell, the commands below exit with a return value of zero: -<pre> + +\fish isatty isatty stdout isatty 2 echo | isatty /dev/fd/1 -</pre> +\endfish And these will exit non-zero: -<pre> + +\fish echo | isatty isatty /dev/fd/9 isatty stdout > file isatty 2 2> file -</pre> +\endfish diff --git a/doc_src/jobs.txt b/doc_src/jobs.txt index 8b96d127..613266d3 100644 --- a/doc_src/jobs.txt +++ b/doc_src/jobs.txt @@ -1,25 +1,27 @@ \section jobs jobs - print currently running jobs \subsection jobs-synopsis Synopsis -<code>jobs [OPTIONS] [PID]</code> +\fish{synopsis} +jobs [OPTIONS] [PID] +\endfish \subsection jobs-description Description -<code>jobs</code> prints a list of the currently -running <a href="index.html#syntax-job-control">jobs</a> and their status. + +`jobs` prints a list of the currently running <a href="index.html#syntax-job-control">jobs</a> and their status. jobs accepts the following switches: -- <code>-c</code> or <code>--command</code> prints the command name for each process in jobs. -- <code>-g</code> or <code>--group</code> only prints the group ID of each job. -- <code>-h</code> or <code>--help</code> displays a help message and exits. -- <code>-l</code> or <code>--last</code> prints only the last job to be started. -- <code>-p</code> or <code>--pid</code> prints the process ID for each process in all jobs. +- `-c` or `--command` prints the command name for each process in jobs. + +- `-g` or `--group` only prints the group ID of each job. + +- `-l` or `--last` prints only the last job to be started. + +- `-p` or `--pid` prints the process ID for each process in all jobs. + +On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100\%. -On systems that supports this feature, jobs will print the CPU usage -of each job since the last command was executed. The CPU usage is -expressed as a percentage of full CPU activity. Note that on -multiprocessor systems, the total activity may be more than 100\%. \subsection jobs-example Example -<code>jobs</code> outputs a summary of the current jobs. +`jobs` outputs a summary of the current jobs. diff --git a/doc_src/license.hdr b/doc_src/license.hdr index f431e07a..eac13766 100644 --- a/doc_src/license.hdr +++ b/doc_src/license.hdr @@ -1,1420 +1,417 @@ /** \page license Licenses -\htmlonly <div class="fish_only_bar"> \endhtmlonly +\htmlonly[block] +<div class="fish_only_bar"> +<div class="license"> +<h1 class="interior_title">Licenses for fish</h1> -<h2>License for fish</h2> +\endhtmlonly -Fish Copyright (C) 2005-2009 Axel Liljencrantz. Fish is released under -the GNU General Public License, version 2. The license agreement is -included below. +`fish` Copyright © 2005-2009 Axel Liljencrantz. `fish` is released under the GNU General Public License, version 2. The license agreement is included below. +## <a name="GPL2_SEC1"> GNU GENERAL PUBLIC LICENSE -<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. -51 Franklin Street, 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. -</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> + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA -<h2>License for wcslcat and wcslcpy</h2> + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. -\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. +## <a name="GPL2_SEC2"> Preamble -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> +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. -<h2>License for XSel</h2> +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. -The XSel command, written and copyrighted by Conrad Parker, is -distributed together with \c fish. +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. +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. -It is Copyright (C) 2001 Conrad Parker <conrad@vergenet.net> +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. -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. +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. +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. -<HR> +The precise terms and conditions for copying, distribution and modification follow. -<h2>License for xdgmime and glibc</h2> -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, version 2 or later, or under the Academic Free License, -version 2. Version 2 of the LGPL license agreement is included below. +## <a name="GPL2_SEC3"> TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -Fish contains code from the glibc library, namely the wcstok -function. This code is licensed under the LGPL, version 2 or -later. Version 2 of the LPGL license agreement is included below. +- 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". + 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. -<H2><A NAME="SEC1" HREF="#TOC1">GNU LESSER GENERAL PUBLIC LICENSE</A></H2> +1. 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. + + 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. + +2. 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: + + -# You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. + + -# 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. + + -# 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.) + + 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. + + 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. + + 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. + +3. 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: + + -# 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, + + -# 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, + + -# 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.) + + 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. + + 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. + +4. 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. + +5. 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. + +6. 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. + +7. 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. + + 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. + + 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. + + This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. + +8. 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. + +9. 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. + + 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. + +10. 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. + + __NO WARRANTY__ + +11. 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. + +12. 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. + + +---- + + +## License for wcslcat and wcslcpy + +`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. + + +---- + + +## License for XSel + +The XSel command, written and copyrighted by Conrad Parker, is distributed together with `fish`. + +It is Copyright © 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. + + +---- + + +## License for xdgmime and glibc + +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, version 2 or later, or under the Academic Free License, version 2. Version 2 of the LGPL license agreement is included below. + +Fish contains code from the glibc library, namely the wcstok function. This code is licensed under the LGPL, version 2 or later. Version 2 of the LPGL license agreement is included below. + + +## <a name="LGPL2_SEC1"> GNU LESSER GENERAL PUBLIC LICENSE -<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> - -<h2>License for printf</h2> - -Copyright (C) 1990-2007 Free Software Foundation, Inc. Printf (from GNU -Coreutils 6.9) is released under the GNU General Public License, version 2. -The license agreement is included below. - -<H2><A NAME="SEC1" HREF="gpl.html#TOC1">GNU GENERAL PUBLIC LICENSE</A></H2> -<P> + 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.] + +## <a name="LGPL2_SEC2"> Preamble + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + + +## <a name="LGPL2_SEC3"> TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + +- 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". + + 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. + + 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".) + + "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. + + 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. + +1. 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. + + 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. + +2. 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: + + -# The modified work must itself be a software library. + + -# You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. + + -# You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. + + -# 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. + + (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.) + + 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. + + 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. + + 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. + +3. 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. + + 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. + + This option is useful when you wish to copy part of the code of the Library into a program that is not a library. + +4. 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. + + 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. + +5. 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. + + 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. + + 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. + + 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.) + + 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. + +6. 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. + + 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: + + -# 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.) + + -# 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. + + -# 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. + + -# 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. + + -# Verify that the user has already received a copy of these materials or that you have already sent this user a copy. + + 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. + + 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. + +7. 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: + + -# 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. + + -# 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. + +8. 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. + +9. 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. + +10. 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. + +11. 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. + + 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. + + 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. + + This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. + +12. 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. + +13. 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. + + 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. + +14. 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. + + __NO WARRANTY__ + +15. 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. + +16. 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. + + +---- + + +## License for printf + +Copyright © 1990-2007 Free Software Foundation, Inc. Printf (from GNU Coreutils 6.9) is released under the GNU General Public License, version 2. The license agreement is included below. + + +# <a name="GPL2_SEC1"> GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 -</P> - -<PRE> -Copyright (C) 1989, 1991 Free Software Foundation, Inc. -51 Franklin Street, 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. -</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> - -<h2>License for UTF8</h2> - -<p>Copyright (c) 2007 Alexey Vatchenko <av@bsdua.org> - -<p>Permission to use, copy, modify, and/or 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. - -<p>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. - -\htmlonly </div> \endhtmlonly + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 51 Franklin Street, 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. + + +## Preamble + + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +The precise terms and conditions for copying, distribution and modification follow. + + +## TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + +- 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". + + 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. + +1. 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. + + 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. + +2. 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: + + -# You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. + + -# 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. + + -# 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.) + + 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. + + 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. + + 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. + +3. 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: + + -# 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, + + -# 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, + + -# 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.) + + 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. + + 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. + +4. 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. + +5. 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. + +6. 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. + +7. 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. + + 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. + + 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. + + This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. + +8. 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. + +9. 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. + + 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. + +10. 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. + + __NO WARRANTY__ + +11. 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. + +12. 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. + + +---- + + +## License for UTF8 + +Copyright © 2007 Alexey Vatchenko \<av@bsdua.org> + +Permission to use, copy, modify, and/or 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. + + +\htmlonly[block] +</div> +</div> +\endhtmlonly */ diff --git a/doc_src/math.txt b/doc_src/math.txt index 8e1fd3b5..994f1515 100644 --- a/doc_src/math.txt +++ b/doc_src/math.txt @@ -2,25 +2,19 @@ \section math math - Perform mathematics calculations \subsection math-synopsis Synopsis - <tt>math EXPRESSION</tt> +\fish{synopsis} +math EXPRESSION +\endfish \subsection math-description Description -\c math is used to perform mathematical calculations. It is a very -thin wrapper for the bc program, which makes it possible to specify an -expression from the command line without using non-standard extensions -or a pipeline. +`math` is used to perform mathematical calculations. It is a very thin wrapper for the bc program, which makes it possible to specify an expression from the command line without using non-standard extensions or a pipeline. + +For a description of the syntax supported by math, see the manual for the bc program. Keep in mind that parameter expansion takes place on any expressions before they are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis have to be escaped. -For a description of the syntax supported by math, see the manual for -the bc program. Keep in mind that parameter expansion takes place on -any expressions before they are evaluated. This can be very useful in -order to perform calculations involving shell variables or the -output of command substitutions, but it also means that parenthesis -have to be escaped. \subsection math-example Examples -<code>math 1+1</code> outputs 2. +`math 1+1` outputs 2. -<code>math $status-128</code> outputs the numerical exit status of the -last command minus 128. +`math $status-128` outputs the numerical exit status of the last command minus 128. diff --git a/doc_src/mimedb.txt b/doc_src/mimedb.txt index e38597eb..19747444 100644 --- a/doc_src/mimedb.txt +++ b/doc_src/mimedb.txt @@ -1,26 +1,28 @@ \section mimedb mimedb - lookup file information via the mime database \subsection mimedb-synopsis Synopsis -<tt>mimedb [OPTIONS] FILES...</tt> +\fish{synopsis} +mimedb [OPTIONS] FILES... +\endfish \subsection mimedb-description Description -\c mimedb queries the MIME type database and the \c .desktop files -installed on the system in order to find information on -the files listed in <code>FILES</code>. The information that \c mimedb -can retrieve includes the MIME type for a file, a description of the type, -and the default action that can be performed on the file. \c mimedb can also -be used to launch the default action for this file. +`mimedb` queries the MIME type database and the `.desktop` files installed on the system in order to find information on the files listed in `FILES`. The information that `mimedb` can retrieve includes the MIME type for a file, a description of the type, and the default action that can be performed on the file. `mimedb` can also be used to launch the default action for this file. The following options are available: -- \c -t, \c --input-file-data determines the files' type both by their filename and by their contents (default behaviour). -- \c -f, \c --input-filename determines the files' type by their filename. -- \c -i, \c --input-mime specifies that the arguments are not files, but MIME types. -- \c -m, \c --output-mime outputs the MIME type of each file (default behaviour). -- \c -f, \c --output-description outputs the description of each MIME type. -- \c -a, \c --output-action outputs the default action of each MIME type. -- \c -l, \c --launch launches the default action for the specified files. -- \c -h, \c --help displays a help message and exit. -- \c -v, \c --version displays the version number and exits. +- `-t`, `--input-file-data` determines the files' type both by their filename and by their contents (default behaviour). +- `-f`, `--input-filename` determines the files' type by their filename. + +- `-i`, `--input-mime` specifies that the arguments are not files, but MIME types. + +- `-m`, `--output-mime` outputs the MIME type of each file (default behaviour). + +- `-f`, `--output-description` outputs the description of each MIME type. + +- `-a`, `--output-action` outputs the default action of each MIME type. + +- `-l`, `--launch` launches the default action for the specified files. + +- `-v`, `--version` displays the version number and exits. diff --git a/doc_src/nextd.txt b/doc_src/nextd.txt index 297063af..8d7c9035 100644 --- a/doc_src/nextd.txt +++ b/doc_src/nextd.txt @@ -1,24 +1,29 @@ \section nextd nextd - move forward through directory history \subsection nextd-synopsis Synopsis -<tt>nextd [-l | --list] [POS]</tt> +\fish{synopsis} +nextd [ -l | --list ] [POS] +\endfish \subsection nextd-description Description -<tt>nextd</tt> moves forwards <tt>POS</tt> positions in the history of visited -directories; if the end of the history has been hit, a warning is printed. -If the <code>-l></code> or <code>--list</code> flag is specified, the current -directory history is also displayed. +`nextd` moves forwards `POS` positions in the history of visited directories; if the end of the history has been hit, a warning is printed. + +If the `-l` or `--list` flag is specified, the current directory history is also displayed. + \subsection nextd-example Example -\code +\fish cd /usr/src # Working directory is now /usr/src + cd /usr/src/fish-shell # Working directory is now /usr/src/fish-shell + prevd # Working directory is now /usr/src + nextd -# Working directory is now /usr/src/fish-shell</pre> -\endcode +# Working directory is now /usr/src/fish-shell +\endfish diff --git a/doc_src/not.txt b/doc_src/not.txt index a1a1d206..7848d2dc 100644 --- a/doc_src/not.txt +++ b/doc_src/not.txt @@ -1,21 +1,23 @@ \section not not - negate the exit status of a job \subsection not-synopsis Synopsis -<tt>not COMMAND [OPTIONS...]</tt> +\fish{synopsis} +not COMMAND [OPTIONS...] +\endfish \subsection not-description Description -\c not negates the exit status of another command. If the exit status -is zero, \c not returns 1. Otherwise, \c not returns 0. +`not` negates the exit status of another command. If the exit status is zero, `not` returns 1. Otherwise, `not` returns 0. + \subsection not-example Example The following code reports an error and exits if no file named spoon can be found. -<pre> +\fish if not test -f spoon - echo There is no spoon - exit 1 + echo There is no spoon + exit 1 end -</pre> +\endfish diff --git a/doc_src/open.txt b/doc_src/open.txt index 4dc03f9b..85e91e72 100644 --- a/doc_src/open.txt +++ b/doc_src/open.txt @@ -1,12 +1,15 @@ \section open open - open file in its default application \subsection open-synopsis Synopsis - <tt>open FILES...</tt> +\fish{synopsis} +open FILES... +\endfish \subsection open-description Description -\c open opens a file in its default application, using the \c xdg-open command if it exists, or else the <a href="commands.html#mimedb">mimedb</a> command. +`open` opens a file in its default application, using the `xdg-open` command if it exists, or else the <a href="commands.html#mimedb">mimedb</a> command. + \subsection open-example Example -<tt>open *.txt</tt> opens all the text files in the current directory using your system's default text editor. +`open *.txt` opens all the text files in the current directory using your system's default text editor. diff --git a/doc_src/or.txt b/doc_src/or.txt index 3567917f..1cd1d768 100644 --- a/doc_src/or.txt +++ b/doc_src/or.txt @@ -1,27 +1,23 @@ \section or or - conditionally execute a command \subsection or-synopsis Synopsis - <tt>COMMAND1; or COMMAND2</tt> +\fish{synopsis} +COMMAND1; or COMMAND2 +\endfish \subsection or-description Description -\c or is used to execute a command if the current exit -status (as set by the last previous command) is not 0. +`or` is used to execute a command if the current exit status (as set by the last previous command) is not 0. -\c or does not change the current exit status. +`or` does not change the current exit status. + +The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable. -The exit status of the last foreground command to exit can always be -accessed using the <a href="index.html#variables-status">$status</a> -variable. \subsection or-example Example -The following code runs the \c make command to build a program. If the -build succeeds, the program is installed. If either step fails, -<tt>make clean</tt> is run, which removes the files created by the -build process. +The following code runs the `make` command to build a program. If the build succeeds, the program is installed. If either step fails, `make clean` is run, which removes the files created by the build process. -<pre> +\fish make; and make install; or make clean -</pre> - +\endfish diff --git a/doc_src/popd.txt b/doc_src/popd.txt index deb3719f..92816835 100644 --- a/doc_src/popd.txt +++ b/doc_src/popd.txt @@ -1,24 +1,27 @@ \section popd popd - move through directory stack \subsection popd-synopsis Synopsis -<tt>popd</tt> +\fish{synopsis} +popd +\endfish \subsection popd-description Description -<tt>popd</tt> removes the top directory from the directory stack and -changes the working directory to the new top directory. Use <a -href="#pushd"><tt>pushd</tt></a> to add directories to the stack. +`popd` removes the top directory from the directory stack and changes the working directory to the new top directory. Use <a href="#pushd">`pushd`</a> to add directories to the stack. + \subsection popd-example Example -<pre> +\fish pushd /usr/src # Working directory is now /usr/src # Directory stack contains /usr/src + pushd /usr/src/fish-shell # Working directory is now /usr/src/fish-shell # Directory stack contains /usr/src /usr/src/fish-shell + popd # Working directory is now /usr/src # Directory stack contains /usr/src -</pre> +\endfish diff --git a/doc_src/prevd.txt b/doc_src/prevd.txt index e49faff2..cd0c99ac 100644 --- a/doc_src/prevd.txt +++ b/doc_src/prevd.txt @@ -1,26 +1,29 @@ \section prevd prevd - move backward through directory history \subsection prevd-synopsis Synopsis -<tt>prevd [-l | --list] [POS]</tt> +\fish{synopsis} +prevd [ -l | --list ] [POS] +\endfish \subsection prevd-description Description -<tt>prevd</tt> moves backwards <tt>POS</tt> positions in the history -of visited directories; if the beginning of the history has been hit, -a warning is printed. +`prevd` moves backwards `POS` positions in the history of visited directories; if the beginning of the history has been hit, a warning is printed. + +If the `-l` or `--list` flag is specified, the current history is also displayed. -If the <code>-l</code> or <code>--list</code> flag is specified, the current -history is also displayed. \subsection prevd-example Example -\code +\fish cd /usr/src # Working directory is now /usr/src + cd /usr/src/fish-shell # Working directory is now /usr/src/fish-shell + prevd # Working directory is now /usr/src + nextd -# Working directory is now /usr/src/fish-shell</pre> -\endcode +# Working directory is now /usr/src/fish-shell +\endfish diff --git a/doc_src/psub.txt b/doc_src/psub.txt index 7f4dbedd..e6347d85 100644 --- a/doc_src/psub.txt +++ b/doc_src/psub.txt @@ -1,26 +1,20 @@ \section psub psub - perform process substitution \subsection psub-synopsis Synopsis - <tt>COMMAND1 (COMMAND2|psub [-f]) </tt> +\fish{synopsis} +COMMAND1 ( COMMAND2 | psub [-f] ) +\endfish \subsection psub-description Description -Posix shells feature a syntax that is a mix between command -substitution and piping, called process substitution. It is used to -send the output of a command into the calling command, much like -command substitution, but with the difference that the output is not -sent through commandline arguments but through a named pipe, with the -filename of the named pipe sent as an argument to the calling -program. \c psub combined with a -regular command substitution provides the same functionality. +Posix shells feature a syntax that is a mix between command substitution and piping, called process substitution. It is used to send the output of a command into the calling command, much like command substitution, but with the difference that the output is not sent through commandline arguments but through a named pipe, with the filename of the named pipe sent as an argument to the calling program. `psub` combined with a regular command substitution provides the same functionality. + +If the `-f` or `--file` switch is given to `psub`, `psub` will use a regular file instead of a named pipe to communicate with the calling process. This will cause `psub` to be significantly slower when large amounts of data are involved, but has the advantage that the reading process can seek in the stream. -If the \c -f or \c --file switch is given to <tt>psub</tt>, \c psub will use a -regular file instead of a named pipe to communicate with the calling -process. This will cause \c psub to be significantly slower when large -amounts of data are involved, but has the advantage that the reading -process can seek in the stream. \subsection psub-example Example -<tt>diff (sort a.txt|psub) (sort b.txt|psub)</tt> shows the difference -between the sorted versions of files a.txt and b.txt. +\fish +diff (sort a.txt | psub) (sort b.txt | psub) +# shows the difference between the sorted versions of files `a.txt` and `b.txt`. +\endfish
\ No newline at end of file diff --git a/doc_src/pushd.txt b/doc_src/pushd.txt index dbcd7f91..25d93936 100644 --- a/doc_src/pushd.txt +++ b/doc_src/pushd.txt @@ -1,23 +1,27 @@ \section pushd pushd - push directory to directory stack \subsection pushd-synopsis Synopsis -<tt>pushd [DIRECTORY]</tt> +\fish{synopsis} +pushd [DIRECTORY] +\endfish \subsection pushd-description Description -The <tt>pushd</tt> function adds \c DIRECTORY to the top of the directory stack -and makes it the current working directory. <a href="#popd"><tt>popd</tt></a> will pop it off and -return to the original directory. + +The `pushd` function adds `DIRECTORY` to the top of the directory stack and makes it the current working directory. <a href="#popd">`popd`</a> will pop it off and return to the original directory. + \subsection pushd-example Example -<pre> +\fish pushd /usr/src # Working directory is now /usr/src # Directory stack contains /usr/src + pushd /usr/src/fish-shell # Working directory is now /usr/src/fish-shell # Directory stack contains /usr/src /usr/src/fish-shell + popd # Working directory is now /usr/src # Directory stack contains /usr/src -</pre> +\endfish diff --git a/doc_src/pwd.txt b/doc_src/pwd.txt index 138e8dcb..46b6419f 100644 --- a/doc_src/pwd.txt +++ b/doc_src/pwd.txt @@ -1,10 +1,12 @@ \section pwd pwd - output the current working directory \subsection pwd-synopsis Synopsis - <tt>pwd</tt> +\fish{synopsis} +pwd +\endfish \subsection pwd-description Description -\c pwd outputs (prints) the current working directory. +`pwd` outputs (prints) the current working directory. -Note that \c fish always resolves symbolic links in the current directory path. +Note that `fish` always resolves symbolic links in the current directory path. diff --git a/doc_src/random.txt b/doc_src/random.txt index b6bb9df0..5e50232a 100644 --- a/doc_src/random.txt +++ b/doc_src/random.txt @@ -1,25 +1,24 @@ \section random random - generate random number \subsection random-synopsis Synopsis - <tt>random [SEED]</tt> +\fish{synopsis} +random [SEED] +\endfish \subsection random-description Description -\c random outputs a random number from 0 to 32766, inclusive. +`random` outputs a random number from 0 to 32766, inclusive. + +If a `SEED` value is provided, it is used to seed the random number generator, and no output will be produced. This can be useful for debugging purposes, where it can be desirable to get the same random number sequence multiple times. If the random number generator is called without first seeding it, the current time will be used as the seed. -If a \c SEED value is provided, it is used to seed the random number -generator, and no output will be produced. This can be useful for debugging -purposes, where it can be desirable to get the same random number sequence -multiple times. If the random number generator is called without first -seeding it, the current time will be used as the seed. \subsection random-example Example The following code will count down from a random number to 1: -<pre> +\fish for i in (seq (random) -1 1) - echo $i - sleep + echo $i + sleep end -</pre> +\endfish diff --git a/doc_src/read.txt b/doc_src/read.txt index 48ae9b05..aee3e85b 100644 --- a/doc_src/read.txt +++ b/doc_src/read.txt @@ -1,43 +1,49 @@ \section read read - read line of input into variables \subsection read-synopsis Synopsis -<tt>read [OPTIONS] [VARIABLES...]</tt> +\fish{synopsis} +read [OPTIONS] [VARIABLES...] +\endfish \subsection read-description Description -<tt>read</tt> reads one line from standard -input and stores the result in one or more shell variables. +`read` reads one line from standard input and stores the result in one or more shell variables. The following options are available: -- <tt>-c CMD</tt> or <tt>--command=CMD</tt> sets the initial string in the interactive mode command buffer to <tt>CMD</tt>. -- <tt>-g</tt> or <tt>--global</tt> makes the variables global. -- <tt>-l</tt> or <tt>--local</tt> makes the variables local. -- <tt>-m NAME</tt> or <tt>--mode-name=NAME</tt> specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available. -- <tt>-n NCHARS</tt> or <tt>--nchars=NCHARS</tt> causes \c read to return after reading NCHARS characters rather than waiting for a complete line of input. -- <tt>-p PROMPT_CMD</tt> or <tt>--prompt=PROMPT_CMD</tt> uses the output of the shell command \c PROMPT_CMD as the prompt for the interactive mode. The default prompt command is <tt>set_color green; echo read; set_color normal; echo "> "</tt>. -- <code>-s</code> or <code>--shell</code> enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode. -- <code>-u</code> or <code>--unexport</code> prevents the variables from being exported to child processes (default behaviour). -- <code>-U</code> or <code>--universal</code> causes the specified shell variable to be made universal. -- <code>-x</code> or <code>--export</code> exports the variables to child processes. -- <code>-a</code> or <code>--array</code> stores the result as an array. - -\c read reads a single line of input from stdin, breaks it into tokens -based on the <tt>IFS</tt> shell variable, and then assigns one -token to each variable specified in <tt>VARIABLES</tt>. If there are more -tokens than variables, the complete remainder is assigned to the last variable. -As a special case, if \c IFS is set to the empty string, each character of the -input is considered a separate token. - -If \c -a or \c --array is provided, only one variable name is allowed and the -tokens are stored as an array in this variable. - -See the documentation for \c set for more details on the scoping rules for -variables. +- `-c CMD` or `--command=CMD` sets the initial string in the interactive mode command buffer to `CMD`. + +- `-g` or `--global` makes the variables global. + +- `-l` or `--local` makes the variables local. + +- `-m NAME` or `--mode-name=NAME` specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available. + +- `-n NCHARS` or `--nchars=NCHARS` causes `read` to return after reading NCHARS characters rather than waiting for a complete line of input. + +- `-p PROMPT_CMD` or `--prompt=PROMPT_CMD` uses the output of the shell command `PROMPT_CMD` as the prompt for the interactive mode. The default prompt command is <code>set_color green; echo read; set_color normal; echo "> "</code>. + +- `-s` or `--shell` enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode. + +- `-u` or `--unexport` prevents the variables from being exported to child processes (default behaviour). + +- `-U` or `--universal` causes the specified shell variable to be made universal. + +- `-x` or `--export` exports the variables to child processes. + +- `-a` or `--array` stores the result as an array. + +`read` reads a single line of input from stdin, breaks it into tokens based on the `IFS` shell variable, and then assigns one token to each variable specified in `VARIABLES`. If there are more tokens than variables, the complete remainder is assigned to the last variable. As a special case, if `IFS` is set to the empty string, each character of the input is considered a separate token. + +If `-a` or `--array` is provided, only one variable name is allowed and the tokens are stored as an array in this variable. + +See the documentation for `set` for more details on the scoping rules for variables. + \subsection read-example Example -The following code stores the value 'hello' in the shell variable -<tt>$foo</tt>. +The following code stores the value 'hello' in the shell variable `$foo`. -<tt>echo hello|read foo</tt> +\fish +echo hello|read foo +\endfish diff --git a/doc_src/return.txt b/doc_src/return.txt index 9563cf39..af4ca9ae 100644 --- a/doc_src/return.txt +++ b/doc_src/return.txt @@ -1,26 +1,25 @@ \section return return - stop the current inner function \subsection return-synopsis Synopsis -<tt>function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end</tt> +\fish{synopsis} +function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end +\endfish \subsection return-description Description -\c return halts a currently running function. The exit status is set -to \c STATUS if it is given. +`return` halts a currently running function. The exit status is set to `STATUS` if it is given. + +It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement to conditionally stop the executing function and return to the caller, but it can also be used to specify the exit status of a function. -It is usually added inside of a conditional block such as an <a -href="#if">if</a> statement or a <a href="#switch">switch</a> -statement to conditionally stop the executing function and return to -the caller, but it can also be used to specify the exit status of a -function. \subsection return-example Example + The following code is an implementation of the false command as a fish function -<pre> +\fish function false - return 1 + return 1 end -</pre> +\endfish diff --git a/doc_src/set.txt b/doc_src/set.txt index 6602e860..0b3d8417 100644 --- a/doc_src/set.txt +++ b/doc_src/set.txt @@ -1,98 +1,94 @@ \section set set - display and change shell variables. \subsection set-synopsis Synopsis -<pre> +\fish{synopsis} set [SCOPE_OPTIONS] set [OPTIONS] VARIABLE_NAME VALUES... set [OPTIONS] VARIABLE_NAME[INDICES]... VALUES... -set (-q | --query) [SCOPE_OPTIONS] VARIABLE_NAMES... -set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME -set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]... -</pre> +set ( -q | --query ) [SCOPE_OPTIONS] VARIABLE_NAMES... +set ( -e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME +set ( -e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]... +\endfish \subsection set-description Description -<code>set</code> manipulates <a href="index.html#variables">shell -variables</a>. +`set` manipulates <a href="index.html#variables">shell variables</a>. -If set is called with no arguments, the names and values of all -shell variables are printed. If some of the scope or export -flags have been given, only the variables matching the specified scope -are printed. +If set is called with no arguments, the names and values of all shell variables are printed. If some of the scope or export flags have been given, only the variables matching the specified scope are printed. -With both variable names and values provided, \c set assigns the variable -<code>VARIABLE_NAME</code> the values <code>VALUES...</code>. +With both variable names and values provided, `set` assigns the variable `VARIABLE_NAME` the values `VALUES...`. The following options control variable scope: -- <code>-l</code> or <code>--local</code> forces the specified shell variable to be given a scope that is local to the current block, even if a variable with the given name exists and is non-local -- <code>-g</code> or <code>--global</code> causes the specified shell variable to be given a global scope. Non-global variables disappear when the block they belong to ends -- <code>-U</code> or <code>--universal</code> causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current users fish instances on the current computer, and will be preserved across restarts of the shell. -- <code>-x</code> or <code>--export</code> causes the specified shell variable to be exported to child processes (making it an "environment variable") -- <code>-u</code> or <code>--unexport</code> causes the specified shell variable to NOT be exported to child processes + +- `-l` or `--local` forces the specified shell variable to be given a scope that is local to the current block, even if a variable with the given name exists and is non-local + +- `-g` or `--global` causes the specified shell variable to be given a global scope. Non-global variables disappear when the block they belong to ends + +- `-U` or `--universal` causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current users fish instances on the current computer, and will be preserved across restarts of the shell. + +- `-x` or `--export` causes the specified shell variable to be exported to child processes (making it an "environment variable") + +- `-u` or `--unexport` causes the specified shell variable to NOT be exported to child processes + The following options are available: -- <code>-e</code> or <code>--erase</code> causes the specified shell variable to be erased -- <code>-q</code> or <code>--query</code> test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined. -- <code>-n</code> or <code>--names</code> List only the names of all defined variables, not their value -- <code>-L</code> or <code>--long</code> do not abbreviate long values when printing set variables - -If a variable is set to more than one value, the variable will be an -array with the specified elements. If a variable is set to zero -elements, it will become an array with zero elements. - -If the variable name is one or more array elements, such as -<code>PATH[1 3 7]</code>, only those array elements specified will be -changed. When array indices are specified to \c set, multiple arguments -may be used to specify additional indexes, e.g. <code>set PATH[1] -PATH[4] /bin /sbin</code>. 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. + +- `-e` or `--erase` causes the specified shell variable to be erased + +- `-q` or `--query` test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined. + +- `-n` or `--names` List only the names of all defined variables, not their value + +- `-L` or `--long` do not abbreviate long values when printing set variables + + +If a variable is set to more than one value, the variable will be an array with the specified elements. If a variable is set to zero elements, it will become an array with zero elements. + +If the variable name is one or more array elements, such as `PATH[1 3 7]`, only those array elements specified will be changed. When array indices are specified to `set`, multiple arguments may be used to specify additional indexes, e.g. `set PATH[1] PATH[4] /bin /sbin`. 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. 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 previous variable scope is used. --# 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 function. Note that this is different from using the \c -l or \c --local flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. If no function is executing, the variable will be global. -The exporting rules when creating or updating a variable are identical -to the scoping rules for variables: +-# 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 function. Note that this is different from using the `-l` or `--local` flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. If no function is executing, the variable will be global. + + +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 exported or unexported and has never before been defined, the variable will not be exported. + In query mode, the scope to be examined can be specified. -In erase mode, if variable indices are specified, only the specified -slices of the array variable will be erased. +In erase mode, if variable indices are specified, only the specified slices of the array variable will be erased. -\c set requires all options to come before any -other arguments. For example, <code>set flags -l</code> will have -the effect of setting the value of the variable <code>flags</code> to -'-l', not making the variable local. +`set` requires all options to come before any other arguments. For example, `set flags -l` will have the effect of setting the value of the variable `flags` to '-l', not making the variable local. -In assignment mode, \c set exits with a non-zero exit status if variable -assignments could not be successfully performed. If the variable assignments -were performed, the exit status is unchanged. This allows simultaneous capture -of the output and exit status of a subcommand, e.g. <code>if set output -(command)</code>. In query mode, the exit status is the number of variables that -were not found. In erase mode, \c set exits with a zero exit status in case of -success, with a non-zero exit status if the commandline was invalid, if the -variable was write-protected or if the variable did not exist. +In assignment mode, `set` exits with a non-zero exit status if variable assignments could not be successfully performed. If the variable assignments were performed, the exit status is unchanged. This allows simultaneous capture of the output and exit status of a subcommand, e.g. `if set output (command)`. In query mode, the exit status is the number of variables that were not found. In erase mode, `set` exits with a zero exit status in case of success, with a non-zero exit status if the commandline was invalid, if the variable was write-protected or if the variable did not exist. -\subsection set-example Example -<code>set -xg</code> will print all global, exported variables. +\subsection set-example Example +\fish +set -xg +# Prints all global, exported variables. -<code>set foo hi</code> sets the value of the variable foo to be hi. +set foo hi +# Sets the value of the variable $foo to be 'hi'. -<code>set -e smurf</code> removes the variable \c smurf. +set -e smurf +# Removes the variable $smurf -<code>set PATH[4] ~/bin</code> changes the fourth element of the \c PATH array to \c ~/bin +set PATH[4] ~/bin +# Changes the fourth element of the $PATH array to ~/bin -<pre>if set python_path (which python) +if set python_path (which python) echo "Python is at $python_path" -end</pre> - -The above outputs the path to Python if \c which returns true. +end +# Outputs the path to Python if `which` returns true. +\endfish diff --git a/doc_src/set_color.txt b/doc_src/set_color.txt index 546889cd..f48926a8 100644 --- a/doc_src/set_color.txt +++ b/doc_src/set_color.txt @@ -1,44 +1,41 @@ \section set_color set_color - set the terminal color \subsection set_color-synopsis Synopsis - <tt>set_color [-h --help] [-b --background COLOR] [COLOR]</tt> +\fish{synopsis} +set_color [OPTIONS] [COLOR] +\endfish \subsection set_color-description Description -\c set_color changes the foreground and/or background color of the terminal. -\c COLOR is one of black, red, green, brown, yellow, blue, magenta, -purple, cyan, white and normal. +`set_color` changes the foreground and/or background color of the terminal. `COLOR` is one of black, red, green, brown, yellow, blue, magenta, purple, cyan, white and normal. -If your terminal supports term256 (modern xterms and OS X Lion), -you can specify an RGB value with three or six hex digits, such -as A0FF33 or f2f. \c fish will choose the closest supported color. +If your terminal supports term256 (modern xterms and OS X Lion), you can specify an RGB value with three or six hex digits, such as A0FF33 or f2f. `fish` will choose the closest supported color. The following options are available: -- \c -b, \c --background \c COLOR sets the background color. -- \c -c, \c --print-colors prints a list of all valid color names. -- \c -h, \c --help displays a help message and exit. -- \c -o, \c --bold sets bold or extra bright mode. -- \c -u, \c --underline sets underlined mode. +- `-b`, `--background` `COLOR` sets the background color. -Calling <tt>set_color normal</tt> will set the terminal color to -the default color of the terminal. +- `-c`, `--print-colors` prints a list of all valid color names. -Some terminals use the --bold escape sequence to switch to a brighter -color set. On such terminals, <code>set_color white</code> will result -in a grey font color, while <code>set_color --bold white</code> will -result in a white font color. +- `-o`, `--bold` sets bold or extra bright mode. + +- `-u`, `--underline` sets underlined mode. + + +Calling `set_color normal` will set the terminal color to the default color of the terminal. + +Some terminals use the `--bold` escape sequence to switch to a brighter color set. On such terminals, `set_color white` will result in a grey font color, while `set_color --bold white` will result in a white font color. Not all terminal emulators support all these features. -\c set_color uses the terminfo database to look up how to change terminal -colors on whatever terminal is in use. Some systems have old and -incomplete terminfo databases, and may lack color information for -terminals that support it. +`set_color` uses the terminfo database to look up how to change terminal colors on whatever terminal is in use. Some systems have old and incomplete terminfo databases, and may lack color information for terminals that support it. + \subsection set_color-example Examples -<pre>set_color red; echo "Roses are red" + +\fish +set_color red; echo "Roses are red" set_color blue; echo "Violets are blue" -set_color 62A ; echo "Eggplants are dark purple" +set_color 62A; echo "Eggplants are dark purple" set_color normal; echo "Normal is nice too" -</pre> +\endfish diff --git a/doc_src/source.txt b/doc_src/source.txt index 8798e9d9..dba14045 100644 --- a/doc_src/source.txt +++ b/doc_src/source.txt @@ -1,30 +1,24 @@ \section source source - evaluate contents of file. \subsection source-synopsis Synopsis -<tt>source FILENAME [ARGUMENTS...]</tt> +\fish{synopsis} +source FILENAME [ARGUMENTS...] +\endfish \subsection source-description Description -\c source evaluates the commands of the specified file in the current -shell. This is different from starting a new process to perform the -commands (i.e. <tt>fish < FILENAME</tt>) since the commands will be -evaluated by the current shell, which means that changes in -shell variables will affect the current shell. If additional arguments are -specified after the file name, they will be inserted into the $argv -variable. +`source` evaluates the commands of the specified file in the current shell. This is different from starting a new process to perform the commands (i.e. `fish < FILENAME`) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the $argv variable. -If no file is specified, or if the file name '-' is used, stdin will -be read. +If no file is specified, or if the file name '`-`' is used, stdin will be read. -The return status of \c source is the return status of the last job to -execute. If something goes wrong while opening or reading the file, -\c source exits with a non-zero status. +The return status of `source` is the return status of the last job to execute. If something goes wrong while opening or reading the file, `source` exits with a non-zero status. -\c . (a single period) is an alias for the \c source command. The use of \c . -is deprecated in favour of \c source, and \c . will be removed in a future -version of fish. +`.` (a single period) is an alias for the `source` command. The use of `.` is deprecated in favour of `source`, and `.` will be removed in a future version of fish. -\subsection source-example Example -<tt>source ~/.config/fish/config.fish</tt> causes fish to re-read its initialization file. +\subsection source-example Example +\fish +source ~/.config/fish/config.fish +# Causes fish to re-read its initialization file. +\endfish diff --git a/doc_src/status.txt b/doc_src/status.txt index d6238ae3..b939f6fe 100644 --- a/doc_src/status.txt +++ b/doc_src/status.txt @@ -1,21 +1,34 @@ \section status status - query fish runtime information \subsection status-synopsis Synopsis - <tt>status [OPTION]</tt> +\fish{synopsis} +status [OPTION] +\endfish \subsection status-description Description -With no arguments, <tt>status</tt> displays a summary of the current login and job control status of the shell. + +With no arguments, `status` displays a summary of the current login and job control status of the shell. The following options are available: -- <tt>-c</tt> or <tt>--is-command-substitution</tt> returns 0 if fish is currently executing a command substitution. -- <tt>-b</tt> or <tt>--is-block</tt> returns 0 if fish is currently executing a block of code. -- <tt>-i</tt> or <tt>--is-interactive</tt> returns 0 if fish is interactive - that is, connected to a keyboard. -- <tt>-l</tt> or <tt>--is-login</tt> returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up the PATH. -- <tt>--is-full-job-control</tt> returns 0 if full job control is enabled. -- <tt>--is-interactive-job-control</tt> returns 0 if interactive job control is enabled. -- <tt>--is-no-job-control</tt> returns 0 if no job control is enabled. -- <tt>-f</tt> or <tt>--current-filename</tt> prints the filename of the currently running script. -- <tt>-n</tt> or <tt>--current-line-number</tt> prints the line number of the currently running script. -- <tt>-j CONTROLTYPE</tt> or <tt>--job-control=CONTROLTYPE</tt> sets the job control type, which can be <tt>none</tt>, <tt>full</tt>, or <tt>interactive</tt>. -- <tt>-t</tt> or <tt>--print-stack-trace</tt> prints a stack trace of all function calls on the call stack. -- <tt>-h</tt> or <tt>--help</tt> displays a help message and exit. + +- `-c` or `--is-command-substitution` returns 0 if fish is currently executing a command substitution. + +- `-b` or `--is-block` returns 0 if fish is currently executing a block of code. + +- `-i` or `--is-interactive` returns 0 if fish is interactive - that is, connected to a keyboard. + +- `-l` or `--is-login` returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up the PATH. + +- `--is-full-job-control` returns 0 if full job control is enabled. + +- `--is-interactive-job-control` returns 0 if interactive job control is enabled. + +- `--is-no-job-control` returns 0 if no job control is enabled. + +- `-f` or `--current-filename` prints the filename of the currently running script. + +- `-n` or `--current-line-number` prints the line number of the currently running script. + +- `-j CONTROLTYPE` or `--job-control=CONTROLTYPE` sets the job control type, which can be `none`, `full`, or `interactive`. + +- `-t` or `--print-stack-trace` prints a stack trace of all function calls on the call stack. diff --git a/doc_src/switch.txt b/doc_src/switch.txt index 7b9b0308..9bba2bb0 100644 --- a/doc_src/switch.txt +++ b/doc_src/switch.txt @@ -1,35 +1,26 @@ \section switch switch - conditionally execute a block of commands \subsection switch-synopsis Synopsis -<tt>switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end</tt> +\fish{synopsis} +switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end +\endfish \subsection switch-description Description -\c switch performs one of several blocks of commands, depending on whether -a specified value equals one of several wildcarded values. \c case is used -together with the \c switch statement in order to determine which block should -be executed. +`switch` performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. `case` is used together with the `switch` statement in order to determine which block should be executed. -Each \c case command is given one or more parameters. The first \c case -command with a parameter that matches the string specified in the -switch command will be evaluated. \c case parameters may contain -wildcards. These need to be escaped or quoted in order to avoid -regular wildcard expansion using filenames. +Each `case` command is given one or more parameters. The first `case` command with a parameter that matches the string specified in the switch command will be evaluated. `case` parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames. -Note that fish does not fall through on case statements. Only the -first matching case is executed. +Note that fish does not fall through on case statements. Only the first matching case is executed. + +Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter. -Note that command substitutions in a case statement will be -evaluated even if its body is not taken. All substitutions, including -command substitutions, must be performed before the value can be compared -against the parameter. \subsection switch-example Example -If the variable \$animal contains the name of an animal, the following -code would attempt to classify it: +If the variable \$animal contains the name of an animal, the following code would attempt to classify it: -<pre> +\fish switch $animal case cat echo evil @@ -42,8 +33,7 @@ switch $animal case '*' echo I have no idea what a $animal is end -</pre> - -If the above code was run with \c \$animal set to \c whale, the output -would be \c mammal. +\endfish +If the above code was run with `$animal` set to `whale`, the output +would be `mammal`. diff --git a/doc_src/test.txt b/doc_src/test.txt index 809c3eaf..632e7901 100644 --- a/doc_src/test.txt +++ b/doc_src/test.txt @@ -1,109 +1,126 @@ \section test test - perform tests on files and text \subsection test-synopsis Synopsis - <tt>test [EXPRESSION]</tt> +\fish{synopsis} +test [EXPRESSION] +\endfish \subsection test-description Description -Tests the expression given and sets the exit status to 0 if true, -and 1 if false. An expression is made up of one or more operators -and their arguments. +Tests the expression given and sets the exit status to 0 if true, and 1 if false. An expression is made up of one or more operators and their arguments. The following operators are available to examine files and directories: -- <tt>-b FILE</tt> returns true if \c FILE is a block device. -- <tt>-c FILE</tt> returns true if \c FILE is a character device. -- <tt>-d FILE</tt> returns true if \c FILE is a directory. -- <tt>-e FILE</tt> returns true if \c FILE exists. -- <tt>-f FILE</tt> returns true if \c FILE is a regular file. -- <tt>-g FILE</tt> returns true if \c FILE has the set-group-ID bit set. -- <tt>-G FILE</tt> returns true if \c FILE exists and has the same group ID -as the current user. -- <tt>-L FILE</tt> returns true if \c FILE is a symbolic link. -- <tt>-O FILE</tt> returns true if \c FILE exists and is owned by the current -user. -- <tt>-p FILE</tt> returns true if \c FILE is a named pipe. -- <tt>-r FILE</tt> returns true if \c FILE is marked as readable. -- <tt>-s FILE</tt> returns true if the size of \c FILE is greater than zero. -- <tt>-S FILE</tt> returns true if \c FILE is a socket. -- <tt>-t FD</tt> returns true if the file descriptor \c FD is a terminal (TTY). -- <tt>-u FILE</tt> returns true if \c FILE has the set-user-ID bit set. -- <tt>-w FILE</tt> returns true if \c FILE is marked as writable; note that this does not check if the filesystem is read-only. -- <tt>-x FILE</tt> returns true if \c FILE is marked as executable. + +- `-b FILE` returns true if `FILE` is a block device. + +- `-c FILE` returns true if `FILE` is a character device. + +- `-d FILE` returns true if `FILE` is a directory. + +- `-e FILE` returns true if `FILE` exists. + +- `-f FILE` returns true if `FILE` is a regular file. + +- `-g FILE` returns true if `FILE` has the set-group-ID bit set. + +- `-G FILE` returns true if `FILE` exists and has the same group ID as the current user. + +- `-L FILE` returns true if `FILE` is a symbolic link. + +- `-O FILE` returns true if `FILE` exists and is owned by the current user. + +- `-p FILE` returns true if `FILE` is a named pipe. + +- `-r FILE` returns true if `FILE` is marked as readable. + +- `-s FILE` returns true if the size of `FILE` is greater than zero. + +- `-S FILE` returns true if `FILE` is a socket. + +- `-t FD` returns true if the file descriptor `FD` is a terminal (TTY). + +- `-u FILE` returns true if `FILE` has the set-user-ID bit set. + +- `-w FILE` returns true if `FILE` is marked as writable; note that this does not check if the filesystem is read-only. + +- `-x FILE` returns true if `FILE` is marked as executable. The following operators are available to compare and examine text strings: -- <tt>STRING1 = STRING2</tt> returns true if the strings \c STRING1 and -\c STRING2 are identical. -- <tt>STRING1 != STRING2</tt> returns true if the strings \c STRING1 and -\c STRING2 are not identical. -- <tt>-n STRING</tt> returns true if the length of \c STRING is non-zero. -- <tt>-z STRING</tt> returns true if the length of \c STRING is zero. + +- `STRING1 = STRING2` returns true if the strings `STRING1` and `STRING2` are identical. + +- `STRING1 != STRING2` returns true if the strings `STRING1` and `STRING2` are not identical. + +- `-n STRING` returns true if the length of `STRING` is non-zero. + +- `-z STRING` returns true if the length of `STRING` is zero. The following operators are available to compare and examine numbers: -- <tt>NUM1 -eq NUM2</tt> returns true if \c NUM1 and \c NUM2 are numerically equal. -- <tt>NUM1 -ne NUM2</tt> returns true if \c NUM1 and \c NUM2 are not numerically equal. -- <tt>NUM1 -gt NUM2</tt> returns true if \c NUM1 is greater than <tt>NUM2</tt>. -- <tt>NUM1 -ge NUM2</tt> returns true if \c NUM1 is greater than or equal to <tt>NUM2</tt>. -- <tt>NUM1 -lt NUM2</tt> returns true if \c NUM1 is less than <tt>NUM2</tt>. -- <tt>NUM1 -le NUM2</tt> returns true if \c NUM1 is less than or equal to <tt>NUM2</tt>. -Note that only integers are supported. For more complex mathematical -operations, including fractions, the \c env program may be useful. Consult the -documentation for your operating system. +- `NUM1 -eq NUM2` returns true if `NUM1` and `NUM2` are numerically equal. + +- `NUM1 -ne NUM2` returns true if `NUM1` and `NUM2` are not numerically equal. + +- `NUM1 -gt NUM2` returns true if `NUM1` is greater than `NUM2`. + +- `NUM1 -ge NUM2` returns true if `NUM1` is greater than or equal to `NUM2`. + +- `NUM1 -lt NUM2` returns true if `NUM1` is less than `NUM2`. + +- `NUM1 -le NUM2` returns true if `NUM1` is less than or equal to `NUM2`. + +Note that only integers are supported. For more complex mathematical operations, including fractions, the `env` program may be useful. Consult the documentation for your operating system. Expressions can be combined using the following operators: -- <tt>COND1 -a COND2</tt> returns true if both \c COND1 and \c COND2 are true. -- <tt>COND1 -o COND2</tt> returns true if either \c COND1 or \c COND2 are true. -Expressions can be inverted using the \c ! operator: -- <tt>! EXPRESSION</tt> returns true if \c EXPRESSION is false, and false if -\c EXPRESSION is true. +- `COND1 -a COND2` returns true if both `COND1` and `COND2` are true. + +- `COND1 -o COND2` returns true if either `COND1` or `COND2` are true. + +Expressions can be inverted using the `!` operator: + +- `! EXPRESSION` returns true if `EXPRESSION` is false, and false if `EXPRESSION` is true. Expressions can be grouped using parentheses. -- <tt>( EXPRESSION )</tt> returns the value of <tt>EXPRESSION</tt>. -Note that parentheses will usually require escaping with <tt>\\(</tt> to avoid -being interpreted as a command substitution. + +- `( EXPRESSION )` returns the value of `EXPRESSION`. + + Note that parentheses will usually require escaping with `\(` to avoid being interpreted as a command substitution. + \subsection test-example Examples -If the \c /tmp directory exists, copy the \c /etc/motd file to it: +If the `/tmp` directory exists, copy the `/etc/motd` file to it: -<pre> +\fish if test -d /tmp cp /etc/motd /tmp/motd end -</pre> +\endfish -If the variable \c MANPATH is defined and not empty, print the contents. -(If \c MANPATH is not defined, then it will expand to zero arguments, unless -quoted.) +If the variable `MANPATH` is defined and not empty, print the contents. (If `MANPATH` is not defined, then it will expand to zero arguments, unless quoted.) -<pre> +\fish if test -n "$MANPATH" echo $MANPATH end -</pre> +\endfish -Parentheses and the \c -o and \c -a operators can be combined to produce -more complicated expressions. In this example, success is printed if there is -a \c /foo or \c /bar file as well as a \c /baz or \c /bat file. +Parentheses and the `-o` and `-a` operators can be combined to produce more complicated expressions. In this example, success is printed if there is a `/foo` or `/bar` file as well as a `/baz` or `/bat` file. -<pre> -if test \\( -f /foo -o -f /bar \\) -a \\( -f /baz -o -f /bat \\) +\fish +if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \) echo Success. end. -</pre> +\endfish + \subsection test-standards Standards -\c test implements a subset of the -<a href="http://www.unix.com/man-page/POSIX/1/test/">IEEE Std 1003.1-2008 -(POSIX.1) standard</a>. The following exceptions apply: -- The \c < and \c > operators for comparing strings are not implemented. -- Because this test is a shell builtin and not a standalone utility, using - the -c flag on a special file descriptors like standard input and output - may not return the same result when invoked from within a pipe as one - would expect when invoking the \c test utility in another shell. - - In cases such as this, one can use \c command \c test to explicitly - use the system's standalone \c test rather than this \c builtin \c test. +`test` implements a subset of the <a href="http://www.unix.com/man-page/POSIX/1/test/">IEEE Std 1003.1-2008 (POSIX.1) standard</a>. The following exceptions apply: + +- The `<` and `>` operators for comparing strings are not implemented. + +- Because this test is a shell builtin and not a standalone utility, using the -c flag on a special file descriptors like standard input and output may not return the same result when invoked from within a pipe as one would expect when invoking the `test` utility in another shell. + In cases such as this, one can use `command` `test` to explicitly use the system's standalone `test` rather than this `builtin` `test`. diff --git a/doc_src/trap.txt b/doc_src/trap.txt index aaaa5b2b..d4380550 100644 --- a/doc_src/trap.txt +++ b/doc_src/trap.txt @@ -1,43 +1,37 @@ \section trap trap - perform an action when the shell receives a signal \subsection trap-synopsis Synopsis -<tt>trap [OPTIONS] [[ARG] SIGSPEC ... ]</tt> +\fish{synopsis} +trap [OPTIONS] [[ARG] SIGSPEC ... ] +\endfish \subsection trap-description Description -\c trap is a wrapper around the fish event delivery -framework. It exists for backwards compatibility with POSIX -shells. For other uses, it is recommended to define an <a -href='index.html#event'>event handler</a>. +`trap` is a wrapper around the fish event delivery framework. It exists for backwards compatibility with POSIX shells. For other uses, it is recommended to define an <a href='index.html#event'>event handler</a>. The following parameters are available: -- \c ARG is the command to be executed on signal delivery. -- \c SIGSPEC is the name of the signal to trap. -- \c -h or \c --help displays help and exits. -- \c -l or \c --list-signals prints a list of signal names. -- \c -p or \c --print prints all defined signal handlers. +- `ARG` is the command to be executed on signal delivery. -If \c ARG and \c SIGSPEC are both specified, \c ARG is the command to be -executed when the signal specified by \c SIGSPEC is delivered. +- `SIGSPEC` is the name of the signal to trap. -If \c ARG is absent (and there is a single SIGSPEC) or -, each specified -signal is reset to its original disposition (the value it had upon -entrance to the shell). If \c ARG is the null string the signal -specified by each \c SIGSPEC is ignored by the shell and by the commands -it invokes. +- `-l` or `--list-signals` prints a list of signal names. -If \c ARG is not present and \c -p has been supplied, then the trap commands -associated with each \c SIGSPEC are displayed. If no arguments are -supplied or if only \c -p is given, \c trap prints the list of commands -associated with each signal. +- `-p` or `--print` prints all defined signal handlers. -Signal names are case insensitive and the \c SIG prefix is optional. +If `ARG` and `SIGSPEC` are both specified, `ARG` is the command to be executed when the signal specified by `SIGSPEC` is delivered. -The return status is 1 if any \c SIGSPEC is invalid; otherwise trap -returns 0. +If `ARG` is absent (and there is a single SIGSPEC) or -, each specified signal is reset to its original disposition (the value it had upon entrance to the shell). If `ARG` is the null string the signal specified by each `SIGSPEC` is ignored by the shell and by the commands it invokes. + +If `ARG` is not present and `-p` has been supplied, then the trap commands associated with each `SIGSPEC` are displayed. If no arguments are supplied or if only `-p` is given, `trap` prints the list of commands associated with each signal. + +Signal names are case insensitive and the `SIG` prefix is optional. + +The return status is 1 if any `SIGSPEC` is invalid; otherwise trap returns 0. \subsection trap-example Example -<code>trap "status --print-stack-trace" SIGUSR1</code> prints a stack trace -each time the \c SIGUSR1 signal is sent to the shell. +\fish +trap "status --print-stack-trace" SIGUSR1 +# Prints a stack trace each time the SIGUSR1 signal is sent to the shell. +\endfish
\ No newline at end of file diff --git a/doc_src/tutorial.hdr b/doc_src/tutorial.hdr index 58f925d5..173c187b 100644 --- a/doc_src/tutorial.hdr +++ b/doc_src/tutorial.hdr @@ -1,746 +1,590 @@ -/** \page tutorial Tutorial - -\htmlonly - -<style type="text/css"> - -body.tutorial_body { - font-family: "Helvetica Neue", Verdana, Helvetica, Arial, sans-serif; - font-size: 13pt; - background-color: #1E335E; - margin: 0; -} - -pre { - border: solid #AAA 1px; - background-color: black; - color: white; - padding: 10px 12px; - font-size: 10pt; - font-family: Menlo, Monaco, "DejaVu Sans Mono", "Courier New", Courier, monospace; - line-height: 140%; - white-space: pre-wrap; - margin-top: 10px; - tab-size: 4; - -moz-tab-size: 4; - -o-tab-size: 4; -} - -p { - margin-bottom: 10px; - margin-top: 0; - color: #333333; - line-height: 1.25em; -} - -tt { - font-family: monospace; -} - -.suggest { - color: #555; -} - -pre u { - border-bottom: 2px solid #0F0; - text-decoration: none; -} - -.meta { - color: white; -} - -pre b { - /* Used for commands */ - color: #005fd7; - font-weight: normal; -} - -pre i { - /* Used for arguments */ - color: #00afff; - font-style: normal; -} - -pre em { - /* Used for path/help word */ - color: #0a0; - font-style: normal; -} - -.quote { - color: #A50; -} - -.error { - /* Used for errors */ - color: #F55; - font-weight: bold; -} - -.tutorial_nav { - position: relative; - z-index: 2; - margin-left: 10px; - margin-top: 15px; -} - -.tutorial_nav ul { - padding: 0 15px; - margin: 0; -} - -.tutorial_nav li { - margin: 0; - line-height: normal; - height: auto; - color: #EEE; - font-size: 12pt; - font-family: "Trebuchet MS", Verdana, Arial, sans-serif; - list-style-image: none; - list-style-position: outside; - list-style-type: none; - padding: 3px 15px; - margin: 0 -15px; -} - -.tutorial_nav a { - color: inherit; - text-decoration: none; - font-family: - font-size: 12pt; -} - -.tutorial_nav .chevron { - font-family: Times, "Times New Roman"; - color: #DDF; - font-size: 16pt; - line-height: 10pt; - font-weight: bold; -} - -.no_shadow > li > a, -.no_shadow { - text-shadow: none; -} - -.nav > li > a:hover { - text-decoration: none; - background-color: inherit; - color: #99BBFF; -} - -/* Override some default left bar stuff */ -ul.nav li { - margin-bottom: 0; -} - - -.title_top { - width: 100%; - text-align: left; - color: white; - font-size: 18pt; - height: 72px; - z-index: 1; - text-indent: 260px; -} - -.tutorial_content { - -moz-box-shadow: -5px 0px 5px -2px black; - -webkit-box-shadow: -5px 0px 5px -2px black; - box-shadow: -5px 0px 5px -2px black; - - margin-left: 280px; - padding: 1px 25px 10px 10px; - position: relative; - z-index: 5; - background-color: white; -} - -h3 { - font-size: 25px; - margin-top: 12px; -} - -h1, h2, h3 { color: #1E335E; } -h1.interior_title { - color: #333; - padding-bottom: 10px; - border-bottom: 1px solid #AAA; -} - -h1 { font-size: 150%; } -h2 { font-size: 135%; } -h3 { font-size: 110%; } - - - -</style> - - -<div class="fish_left_bar fish_left_medium"> - <div class="tutorial_nav"> - <ul class="nav no_shadow"> - <li><a href="#tut_why_fish"><span class="chevron">›</span> Why fish?</a></li> - <li><a href="#tut_learning_Fish"><span class="chevron">›</span> Learning fish</a></li> - <li><a href="#tut_running_commands"><span class="chevron">›</span> Running Commands</a></li> - <li><a href="#tut_getting_help"><span class="chevron">›</span> Getting Help</a></li> - <li><a href="#tut_syntax_highlighting"><span class="chevron">›</span> Syntax Highlighting</a></li> - <li><a href="#tut_wildcards"><span class="chevron">›</span> Wildcards</a></li> - <li><a href="#tut_pipes_and_redirections"><span class="chevron">›</span> Pipes and Redirections</a></li> - <li><a href="#tut_autosuggestions"><span class="chevron">›</span> Autosuggestions</a></li> - <li><a href="#tut_tab_completions"><span class="chevron">›</span> Tab Completions</a></li> - <li><a href="#tut_variables"><span class="chevron">›</span> Variables</a></li> - <li><a href="#tut_exit_status"><span class="chevron">›</span> Exit Status</a></li> - <li><a href="#tut_exports"><span class="chevron">›</span> Shell Variables</a></li> - <li><a href="#tut_lists"><span class="chevron">›</span> Lists</a></li> - <li><a href="#tut_command_substitutions"><span class="chevron">›</span> Command Substitutions</a></li> - <li><a href="#tut_combiners"><span class="chevron">›</span> Combiners (And, Or, Not)</a></li> - <li><a href="#tut_conditionals"><span class="chevron">›</span> Conditionals (If, Else, Switch)</a></li> - <li><a href="#tut_functions"><span class="chevron">›</span> Functions</a></li> - <li><a href="#tut_loops"><span class="chevron">›</span> Loops</a></li> - <li><a href="#tut_prompt"><span class="chevron">›</span> Prompt</a></li> - <li><a href="#tut_startup"><span class="chevron">›</span> Startup</a></li> - </ul> - </div> +/** +\page tutorial Tutorial +\htmlonly[block] +<div class="fish_left_bar"> +<div class="logo"></div> +<div class="menu tutorial_menu"> +\endhtmlonly +- <a href="#tut_why_fish">Why fish?</a> +- <a href="#tut_learning_Fish">Learning fish</a> +- <a href="#tut_running_commands">Running Commands</a> +- <a href="#tut_getting_help">Getting Help</a> +- <a href="#tut_syntax_highlighting">Syntax Highlighting</a> +- <a href="#tut_wildcards">Wildcards</a> +- <a href="#tut_pipes_and_redirections">Pipes and Redirections</a> +- <a href="#tut_autosuggestions">Autosuggestions</a> +- <a href="#tut_tab_completions">Tab Completions</a> +- <a href="#tut_variables">Variables</a> +- <a href="#tut_exit_status">Exit Status</a> +- <a href="#tut_exports">Shell Variables</a> +- <a href="#tut_lists">Lists</a> +- <a href="#tut_command_substitutions">Command Substitutions</a> +- <a href="#tut_combiners">Combiners (And, Or, Not)</a> +- <a href="#tut_conditionals">Conditionals (If, Else, Switch)</a> +- <a href="#tut_functions">Functions</a> +- <a href="#tut_loops">Loops</a> +- <a href="#tut_prompt">Prompt</a> +- <a href="#tut_path">$PATH</a> +- <a href="#tut_startup">Startup</a> +- <a href="#tut_autoload">Autoloading Functions</a> +- <a href="#tut-more">Ready for more?</a> + +\htmlonly[block] +</div> </div> -<div class="fish_right_bar fish_right_medium"> - +<div class="tutorial fish_right_bar"> <h1 class="interior_title">fish tutorial</h1> +\endhtmlonly + +\section tut_why_fish Why fish? + +`fish` is a fully-equipped command line shell (like bash or zsh) that is smart and user-friendly. `fish` supports powerful features like syntax highlighting, autosuggestions, and tab completions that just work, with nothing to learn or configure. -<h2 id="tut_why_fish">Why fish?</h2> +If you want to make your command line more productive, more useful, and more fun, without learning a bunch of arcane syntax and configuration options, then `fish` might be just what you're looking for! -<p>fish is a fully-equipped command line shell (like bash or zsh) that is smart and user-friendly. fish supports powerful features like syntax highlighting, autosuggestions, and tab completions that just work, with nothing to learn or configure. -<p>If you want to make your command line more productive, more useful, and more fun, without learning a bunch of arcane syntax and configuration options, then fish might be just what you're looking for! +\section tut_learning_Fish Learning fish -<h2 id="tut_learning_Fish">Learning fish</h2> +This tutorial assumes a basic understanding of command line shells and Unix commands, and that you have a working copy of `fish`. -<p>This tutorial assumes a basic understanding of command line shells and Unix commands, and that you have a working copy of fish. +If you have a strong understanding of other shells, and want to know what `fish` does differently, search for the magic phrase <em>unlike other shells</em>, which is used to call out important differences. -<p>If you have a strong understanding of other shells, and want to know what fish does differently, search for the magic phrase <i>unlike other shells</i>, which is used to call out important differences. +When you start `fish`, you should see this: -<p>When you start fish, you should see this: +\fish{cli-dark} +<outp>Welcome to fish, the friendly interactive shell</outp> +<outp>Type <span class="cwd">help</span> for instructions on how to use fish</outp> +<asis>you@hostname</asis> ~>____ +\endfish -<pre> -Welcome to fish, the friendly interactive shell -Type <em>help</em> for instructions on how to use fish -you@hostname <em>~</em>> -</pre> +`fish` comes with a default prompt that shows your username, hostname, and working directory. You'll see <a href="#tut_prompt">how to change your prompt</a> further down. From now on, we'll pretend your prompt is just a '`>`' to save space. -<p>fish comes with a default prompt that shows your username, hostname, and working directory. You'll see <a href="#tut_prompt">how to change your prompt</a> further down. From now on, we'll pretend your prompt is just a '>' to save space. -<h2 id="tut_running_commands">Running Commands</h2> +\section tut_running_commands Running Commands -<p>fish runs commands like other shells: you type a command, followed by its arguments. Spaces are separators: +`fish` runs commands like other shells: you type a command, followed by its arguments. Spaces are separators: -<pre> -> <b>echo</b> <i>hello world</i> -hello world -</pre> +\fish{cli-dark} +>_ echo hello world +<outp>hello world</outp> +\endfish You can include a literal space in an argument with a backslash, or by using single or double quotes: -<pre> -> <b>mkdir</b> <i>My\ Files</i> -> <b>cp</b> <i>~/Some\ File</i> <i class=quote>'My Files'</i> -> <b>ls</b> <i class=quote>"My Files"</i> -Some File -</pre> +\fish{cli-dark} +>_ mkdir My\ Files +>_ cp ~/Some\ File 'My Files' +>_ ls "My Files" +<outp>Some File</outp> +\endfish Commands can be chained with semicolons. -<h2 id="tut_getting_help">Getting Help</h2> -fish has excellent help and man pages. Run <tt>help</tt> to open help in a web browser, and <tt>man</tt> to open it in a man page. You can also ask for help with a specific command, for example, <tt>help set</tt> to open in a web browser, or <tt>man set</tt> to see it in the terminal. +\section tut_getting_help Getting Help + +`fish` has excellent help and man pages. Run `help` to open help in a web browser, and `man` to open it in a man page. You can also ask for help with a specific command, for example, `help set` to open in a web browser, or `man set` to see it in the terminal. + +\fish{cli-dark} +>_ man set +<outp>set - handle shell variables</outp> +<outp> Synopsis...</outp> +\endfish + -<pre> -> <b>man</b> <i>set</i> -set - handle shell variables - Synopsis... -</pre> +\section tut_syntax_highlighting Syntax Highlighting -<h2 id="tut_syntax_highlighting">Syntax Highlighting</h2> -You'll quickly notice that fish performs syntax highlighting as you type. Invalid commands are colored red by default: +You'll quickly notice that `fish` performs syntax highlighting as you type. Invalid commands are colored red by default: -<pre> -> <b class="error">/bin/mkd</b> -</pre> +\fish{cli-dark} +>_ <error>/bin/mkd</error> +\endfish A command may be invalid because it does not exist, or refers to a file that you cannot execute. When the command becomes valid, it is shown in a different color: -<pre> -> <b>/bin/mkdir</b> -</pre> +\fish{cli-dark} +>_ /bin/mkdir +\endfish -fish will underline valid file paths as you type them: +`fish` will underline valid file paths as you type them: -<pre> -> <b>cat</b> <i><span style="text-decoration: underline">~/somef<u>i</u></span></i> -</pre> +\fish{cli-dark} +>_ cat <u>~/somefi</u>___ +\endfish -<p>This tells you that there exists a file that starts with '<tt>somefi</tt>', which is useful feedback as you type. +This tells you that there exists a file that starts with '`somefi`', which is useful feedback as you type. -<p>These colors, and many more, can be changed by running <tt>fish_config</tt>, or by modifying variables directly. +These colors, and many more, can be changed by running `fish_config`, or by modifying variables directly. -<h2 id="tut_wildcards">Wildcards</h2> -fish supports the familiar wildcard *. To list all JPEG files: +\section tut_wildcards Wildcards -<pre> -> <b>ls</b> <i>*.jpg</i> -lena.jpg -meena.jpg -santa maria.jpg -</pre> +`fish` supports the familiar wildcard `*`. To list all JPEG files: -<p>You can include multiple wildcards: +\fish{cli-dark} +>_ ls *.jpg +<outp>lena.jpg</outp> +<outp>meena.jpg</outp> +<outp>santa maria.jpg</outp> +\endfish -<pre> -> <b>ls</b> <i>l*.p*</i> -lena.png -lesson.pdf -</pre> +You can include multiple wildcards: -<p>Especially powerful is the <i>recursive wildcard</i> ** which searches directories recursively: +\fish{cli-dark} +>_ ls l*.p* +<outp>lena.png</outp> +<outp>lesson.pdf</outp> +\endfish -<pre> -> <b>ls</b> <i>/var/**.log</i> -/var/log/system.log -/var/run/sntp.log -</pre> +Especially powerful is the recursive wildcard ** which searches directories recursively: -<p>If that directory traversal is taking a long time, you can Control-C out of it. +\fish{cli-dark} +>_ ls /var/**.log +<outp>/var/log/system.log</outp> +<outp>/var/run/sntp.log</outp> +\endfish -<h2 id="tut_pipes_and_redirections">Pipes and Redirections</h2> +If that directory traversal is taking a long time, you can @key{Control,C} out of it. -<p>You can pipe between commands with the usual vertical bar: -<pre> -> <b>echo</b> <i>hello world</i> | <b>wc</b> - 1 2 12 -</pre> +\section tut_pipes_and_redirections Pipes and Redirections -<p>stdin and stdout can be redirected via the familiar < and >. Unlike other shells, stderr is redirected with a caret ^ +You can pipe between commands with the usual vertical bar: -<pre> -> <b>grep</b> <i>fish</i> < /etc/shells > ~/output.txt ^ ~/errors.txt -</pre> +\fish{cli-dark} +>_ echo hello world | wc +<outp> 1 2 12</outp> +\endfish -<h2 id="tut_autosuggestions">Autosuggestions</h2> +stdin and stdout can be redirected via the familiar < and >. Unlike other shells, stderr is redirected with a caret ^ -fish suggests commands as you type, and shows the suggestion to the right of the cursor, in gray. For example: +\fish{cli-dark} +>_ grep fish < /etc/shells > ~/output.txt ^ ~/errors.txt +\endfish -<pre> -> <b class="error">/bin/h</b><span class="suggest"><u>o</u>stname</span> -</pre> + +\section tut_autosuggestions Autosuggestions + +`fish` suggests commands as you type, and shows the suggestion to the right of the cursor, in gray. For example: + +\fish{cli-dark} +>_ <error>/bin/h</error><s>___ostname</s> +\endfish It knows about paths and options: -<pre> -> <b>grep</b> <i>--i<span class="suggest"><u>g</u>nore-case</span></i> -</pre> +\fish{cli-dark} +>_ grep --i<s>___gnore-case</s> +\endfish And history too. Type a command once, and you can re-summon it by just typing a few letters: -<pre> -> <b>r</b><span class="suggest"><u>s</u>ync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo</span> -</pre> +\fish{cli-dark} +>_ <error>r</error><s>___sync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo</s> +\endfish -To accept the autosuggestion, hit right arrow or Control-F. To accept a single word of the autosuggestion, hit Alt+right arrow. If the autosuggestion is not what you want, just ignore it. +To accept the autosuggestion, hit right arrow or @key{Control,F}. To accept a single word of the autosuggestion, @key{Alt,→} (right arrow). If the autosuggestion is not what you want, just ignore it. -<h2 id="tut_tab_completions">Tab Completions</h2> +\section tut_tab_completions Tab Completions -<p>fish comes with a rich set of tab completions, that work "out of the box." +`fish` comes with a rich set of tab completions, that work "out of the box." -<p>Press tab, and fish will attempt to complete the command, argument, or path: +Press tab, and `fish` will attempt to complete the command, argument, or path: -<pre> -> <b class="error">/pri</b><span class="meta"><tab> →</span> <b>/private/</b> -</pre> +\fish{cli-dark} +>_ <error>/pri</error> @key{Tab} → /private/ +\endfish -<p>If there's more than one possibility, it will list them: -<pre> -> <b class="error">~/stuff/s</b><span class="meta"><tab></span> -<i>~/stuff/s</i>cript.sh <i class="quote">(Executable, 4.8kB)</i> <i>~/stuff/s</i>ources/ <i class="quote">(Directory)</i> -</pre> +If there's more than one possibility, it will list them: -<p>Hit tab again to cycle through the possibilities. +\fish{cli-dark} +>_ <error>~/stuff/s</error> @key{Tab} +<outp><m>~/stuff/s</m>cript.sh <i>(Executable, 4.8kB)</i> <m>~/stuff/s</m>ources/ <i>(Directory)</i></outp> +\endfish -<p>fish can also complete many commands, like git branches: +Hit tab again to cycle through the possibilities. -<pre> -> <b>git</b> <i>merge pr</i><span class="meta"><tab> →</span> git merge prompt_designer -> <b>git</b> <i>checkout b</i><span class="meta"><tab></span> -<i>b</i>uiltin_list_io_merge <i class="quote">(Branch)</i> <i>b</i>uiltin_set_color <i class="quote">(Branch)</i> <i>b</i>usted_events <i class="quote">(Tag)</i> -</pre> +`fish` can also complete many commands, like git branches: -Try hitting tab and see what fish can do! +\fish{cli-dark} +>_ git merge pr @key{Tab} → git merge prompt_designer +>_ git checkout b @key{Tab} +<outp><m>b</m>uiltin_list_io_merge <i>(Branch)</i> <m>b</m>uiltin_set_color <i>(Branch)</i> <m>b</m>usted_events <i>(Tag)</i></outp> +\endfish -<h2 id="tut_variables">Variables</h2> +Try hitting tab and see what `fish` can do! -<p>Like other shells, a dollar sign performs <i>variable substitution</i>: +\section tut_variables Variables -<pre> -> <b>echo</b> <i>My home directory is $HOME</i> -My home directory is /home/tutorial -</pre> +Like other shells, a dollar sign performs variable substitution: + +\fish{cli-dark} +>_ echo My home directory is $HOME +<outp>My home directory is /home/tutorial</outp> +\endfish Variable substitution also occurs in double quotes, but not single quotes: -<pre> -> <b>echo</b> <i class="quote">"My current directory is </i><i>$</i><i class="quote">PWD"</i> -My current directory is /home/tutorial -> <b>echo</b> <i class="quote">'My current directory is $PWD'</i> -My current directory is $PWD -</pre> +\fish{cli-dark} +>_ echo "My current directory is $PWD" +<outp>My current directory is /home/tutorial</outp> +>_ echo 'My current directory is $PWD' +<outp>My current directory is $PWD</outp> +\endfish + +Unlike other shells, `fish` has no dedicated syntax for setting variables. Instead it has an ordinary command: `set`, which takes a variable name, and then its value. -Unlike other shells, fish has no dedicated syntax for setting variables. Instead it has an ordinary command: <tt>set</tt>, which takes a variable name, and then its value. +\fish{cli-dark} +>_ set name 'Mister Noodle' +>_ echo $name +<outp>Mister Noodle</outp> +\endfish -<pre> -> <b>set</b> <i>name</i> <i class="quote">'Mister Noodle'</i> -> <b>echo</b> <i>$name</i> -Mister Noodle -</pre> +(Notice the quotes: without them, `Mister` and `Noodle` would have been separate arguments, and `$name` would have been made into a list of two elements.) -<p>(Notice the quotes: without them, <tt>Mister</tt> and <tt>Noodle</tt> would have been separate arguments, and <tt>$name</tt> would have been made into a <i>list</i> of two elements.) +Unlike other shells, variables are not further split after substitution: -<p>Unlike other shells, variables are <i>not</i> further split after substitution: +\fish{cli-dark} +>_ mkdir $name +>_ ls +<outp>Mister Noodle</outp> +\endfish -<pre> -> <b>mkdir</b> <i>$name</i> -> <b>ls</b> -Mister Noodle -</pre> +In bash, this would have created two directories "Mister" and "Noodle". In `fish`, it created only one: the variable had the value "Mister Noodle", so that is the argument that was passed to `mkdir`, spaces and all. -In bash, this would have created two directories "Mister" and "Noodle". In fish, it created only one: the variable had the value "Mister Noodle", so that is the argument that was passed to <span style="mono">mkdir</span>, spaces and all. -<h2 id="tut_exit_status">Exit Status</h2> +\section tut_exit_status Exit Status -Unlike other shells, fish stores the exit status of the last command in <tt>$status</tt> instead of <tt>$?</tt>. +Unlike other shells, `fish` stores the exit status of the last command in `$status` instead of `$?`. -<pre> -> <b>false</b> -> <b>echo</b> <i>$status</i> -1 -</pre> +\fish{cli-dark} +>_ false +>_ echo $status +<outp>1</outp> +\endfish Zero is considered success, and non-zero is failure. -<h2 id="tut_exports">Exports (Shell Variables)</h2> -Unlike other shells, fish does not have an export command. Instead, a variable is exported via an option to <tt>set</tt>, either <tt>--export</tt> or just <tt>-x</tt>. +\section tut_exports Exports (Shell Variables) + +Unlike other shells, `fish` does not have an export command. Instead, a variable is exported via an option to `set`, either `--export` or just `-x`. -<pre> -> <b>set</b> <i>-x MyVariable SomeValue</i> -> <b>env</b> | <b>grep</b> <i>MyVariable</i> -<span style="background: #A0A">MyVariable</span>=SomeValue -</pre> +\fish{cli-dark} +>_ set -x MyVariable SomeValue +>_ env | grep MyVariable +<outp><sm>MyVariable</sm>=SomeValue</outp> +\endfish -You can erase a variable with <tt>-e</tt> or <tt>--erase</tt> -<pre> -> <b>set</b> <i>-e MyVariable</i> -> <b>env</b> | <b>grep</b> <i>MyVariable</i> -<span class="meta">(no output)</span> -</pre> +You can erase a variable with `-e` or `--erase` -<h2 id="tut_lists">Lists</h2> +\fish{cli-dark} +>_ set -e MyVariable +>_ env | grep MyVariable +<outp>(no output)</outp> +\endfish -<p>The <tt>set</tt> command above used quotes to ensure that <tt>Mister Noodle</tt> was one argument. If it had been two arguments, then <tt>name</tt> would have been a <i>list</i> of length 2. In fact, all variables in fish are really lists, that can contain any number of values, or none at all. -<p>Some variables, like <tt>$PWD</tt>, only have one value. By convention, we talk about that variable's value, but we really mean its <i>first</i> (and only) value. +\section tut_lists Lists -<p>Other variables, like <tt>$PATH</tt>, really do have multiple values. During <i>variable expansion</i>, the variable expands to become multiple arguments: +The `set` command above used quotes to ensure that `Mister Noodle` was one argument. If it had been two arguments, then `name` would have been a list of length 2. In fact, all variables in `fish` are really lists, that can contain any number of values, or none at all. -<pre> -> <b>echo</b> <i>$PATH</i> -/usr/bin /bin /usr/sbin /sbin /usr/local/bin -</pre> +Some variables, like `$PWD`, only have one value. By convention, we talk about that variable's value, but we really mean its first (and only) value. -<p>Lists cannot contain other lists: there is no recursion. A variable is a list of strings, full stop. +Other variables, like `$PATH`, really do have multiple values. During variable expansion, the variable expands to become multiple arguments: -<p>Get the length of a list with <tt>count</tt>: +\fish{cli-dark} +>_ echo $PATH +<outp>/usr/bin /bin /usr/sbin /sbin /usr/local/bin</outp> +\endfish -<pre> -> <b>count</b> <i>$PATH</i> -5 -</pre> +Lists cannot contain other lists: there is no recursion. A variable is a list of strings, full stop. + +Get the length of a list with `count`: + +\fish{cli-dark} +>_ count $PATH +<outp>5</outp> +\endfish You can append (or prepend) to a list by setting the list to itself, with some additional arguments. Here we append /usr/local/bin to $PATH: -<pre> -> <b>set</b> <i>PATH $PATH /usr/local/bin</i> -</pre> +\fish{cli-dark} +>_ set PATH $PATH /usr/local/bin +\endfish You can access individual elements with square brackets. Indexing starts at 1 from the beginning, and -1 from the end: -<pre> -> <b>echo</b> <i>$PATH</i> -/usr/bin /bin /usr/sbin /sbin /usr/local/bin -> <b>echo</b> <i>$PATH[1]</i> -/usr/bin -> <b>echo</b> <i>$PATH[-1]</i> -/usr/local/bin -</pre> + +\fish{cli-dark} +>_ echo $PATH +<outp>/usr/bin /bin /usr/sbin /sbin /usr/local/bin</outp> +>_ echo $PATH[1] +<outp>/usr/bin</outp> +>_ echo $PATH[-1] +<outp>/usr/local/bin</outp> +\endfish You can also access ranges of elements, known as "slices:" -<pre> -> <b>echo</b> <i>$PATH[1..2]</i> -/usr/bin /bin -> <b>echo</b> <i>$PATH[-1..2]</i> -/usr/local/bin /sbin /usr/sbin /bin -</pre> +\fish{cli-dark} +>_ echo $PATH[1..2] +<outp>/usr/bin /bin</outp> +>_ echo $PATH[-1..2] +<outp>/usr/local/bin /sbin /usr/sbin /bin</outp> +\endfish -You can iterate over a list (or a slice) with a <i>for loop</i>: +You can iterate over a list (or a slice) with a for loop: -<pre> -> <b>for</b> <i>val</i> <b>in</b> <i>$PATH</i> - <b>echo</b> <i>"entry: $val"</i> - <b>end</b> -entry: /usr/bin/ -entry: /bin -entry: /usr/sbin -entry: /sbin -entry: /usr/local/bin -</pre> +\fish{cli-dark} +>_ for val in $PATH + echo "entry: $val" + end +<outp>entry: /usr/bin/</outp> +<outp>entry: /bin</outp> +<outp>entry: /usr/sbin</outp> +<outp>entry: /sbin</outp> +<outp>entry: /usr/local/bin</outp> +\endfish -<h2 id="tut_command_substitutions">Command Substitutions</h2> +\section tut_command_substitutions Command Substitutions -Command substitutions use the output of one command as an argument to another. Unlike other shells, fish does not use backticks ` for command substitutions. Instead, it uses parentheses: +Command substitutions use the output of one command as an argument to another. Unlike other shells, `fish` does not use backticks ` for command substitutions. Instead, it uses parentheses: -<pre> -> <b>echo</b> <i>In (</i><b>pwd</b><i>), running (</i><b>uname</b><i>)</i> -In /home/tutorial, running FreeBSD -</pre> +\fish{cli-dark} +>_ echo In (pwd), running (uname) +<outp>In /home/tutorial, running FreeBSD</outp> +\endfish A common idiom is to capture the output of a command in a variable: -<pre> -> <b>set</b> <i>os (</i><b>uname</b><i>)</i> -> <b>echo</b> <i>$os</i> -Linux -</pre> +\fish{cli-dark} +>_ set os (uname) +>_ echo $os +<outp>Linux</outp> +\endfish Command substitutions are not expanded within quotes. Instead, you can temporarily close the quotes, add the command substitution, and reopen them, all in the same argument: -<pre> -> <b>touch</b> <i class="quote">"testing_"</i><i>(</i><b>date</b> <i>+%s</i><i>)</i><i class="quote">".txt"</i> -> <b>ls</b> <i>*.txt</i> -testing_1360099791.txt -</pre> +\fish{cli-dark} +>_ touch <i class="quote">"testing_"</i>(date +%s)<i class="quote">".txt"</i> +>_ ls *.txt +<outp>testing_1360099791.txt</outp> +\endfish -<h2 id="tut_combiners">Combiners (And, Or, Not)</h2> -Unlike other shells, fish does not have special syntax like && or || to combine commands. Instead it has commands <tt>and</tt>, <tt>or</tt>, and <tt>not</tt>. +\section tut_combiners Combiners (And, Or, Not) -<pre> -> <b>cp</b> <i>file1.txt file1_bak.txt</i>; <b>and echo</b> <i class="quote">"Backup successful"</i>; <b>or echo</b> <i class="quote">"Backup failed"</i> -Backup failed -</pre> +Unlike other shells, `fish` does not have special syntax like && or || to combine commands. Instead it has commands `and`, `or`, and `not`. -<h2 id="tut_conditionals">Conditionals (If, Else, Switch)</h2> +\fish{cli-dark} +>_ cp file1.txt file1_bak.txt; and echo "Backup successful"; or echo "Backup failed" +<outp>Backup failed</outp> +\endfish -Use <tt>if</tt>, <tt>else if</tt>, and <tt>else</tt> to conditionally execute code, based on the exit status of a command. -<pre> -<b>if grep</b> <i>fish /etc/shells</i> - <b>echo</b> <i>Found fish</i> -<b>else if grep</b> <i>bash /etc/shells</i> - <b>echo</b> <i>Found bash</i> -<b>else</b> - <b>echo</b> <i>Got nothing</i> -<b>end</b> -</pre> +\section tut_conditionals Conditionals (If, Else, Switch) -There is also a <tt>switch</tt> command: +Use `if`, `else if`, and `else` to conditionally execute code, based on the exit status of a command. -<pre> -<b>switch</b> <i>(</i><b>uname</b><i>)</i> - <b>case</b> <i>Linux</i> - <b>echo</b> <i>Hi Tux!</i> - <b>case</b> <i>Darwin</i> - <b>echo</b> <i>Hi Hexley!</i> - <b>case</b> <i>FreeBSD NetBSD DragonFly</i> - <b>echo</b> <i>Hi Beastie!</i> - <b>case</b> <i class="quote">'*'</i> - <b>echo</b> <i>Hi, stranger!</i> -<b>end</b> -</pre> +\fish{cli-dark} +if grep fish /etc/shells + echo Found fish +else if grep bash /etc/shells + echo Found bash +else + echo Got nothing +end +\endfish + +There is also a `switch` command: + +\fish{cli-dark} +switch (uname) +case Linux + echo Hi Tux! +case Darwin + echo Hi Hexley! +case FreeBSD NetBSD DragonFly + echo Hi Beastie! +case '*' + echo Hi, stranger! +end +\endfish + +Note that `case` does not fall through, and can accept multiple arguments or (quoted) wildcards. -Note that <tt>case</tt> does not fall through, and can accept multiple arguments or (quoted) wildcards. -<h2 id="tut_functions">Functions</h2> +\section tut_functions Functions -A fish function is a list of commands, which may optionally take arguments. Unlike other shells, arguments are not passed in "numbered variables" like <tt>$1</tt>, but instead in a single list <tt>$argv</tt>. To create a function, use the <tt>function</tt> builtin: +A `fish` function is a list of commands, which may optionally take arguments. Unlike other shells, arguments are not passed in "numbered variables" like `$1`, but instead in a single list `$argv`. To create a function, use the `function` builtin: -<pre> -> <i><b>function</b> say_hello - <b>echo</b> Hello $argv - <b>end</b></i> -> <b>say_hello</b> -Hello -> <b>say_hello <i>everybody!</i></b> -Hello everybody! -</pre> +\fish{cli-dark} +>_ function say_hello + echo Hello $argv + end +>_ say_hello +<outp>Hello</outp> +>_ say_hello everybody! +<outp>Hello everybody!</outp> +\endfish -<p>Unlike other shells, fish does not have aliases or special prompt syntax. Functions take their place. +Unlike other shells, `fish` does not have aliases or special prompt syntax. Functions take their place. -<p>You can list the names of all functions with the <tt>functions</tt> keyword (note the plural!). fish starts out with a number of functions: +You can list the names of all functions with the `functions` keyword (note the plural!). `fish` starts out with a number of functions: -<pre> -> <b>functions</b> -alias, cd, delete-or-exit, dirh, dirs, down-or-search, eval, export, fish_command_not_found_setup, fish_config, fish_default_key_bindings, fish_prompt, fish_right_prompt, fish_sigtrap_handler, fish_update_completions, funced, funcsave, grep, help, history, isatty, ls, man, math, nextd, nextd-or-forward-word, open, popd, prevd, prevd-or-backward-word, prompt_pwd, psub, pushd, seq, setenv, sgrep, trap, type, umask, up-or-search, vared -</pre> +\fish{cli-dark} +>_ functions +<outp>alias, cd, delete-or-exit, dirh, dirs, down-or-search, eval, export, fish_command_not_found_setup, fish_config, fish_default_key_bindings, fish_prompt, fish_right_prompt, fish_sigtrap_handler, fish_update_completions, funced, funcsave, grep, help, history, isatty, ls, man, math, nextd, nextd-or-forward-word, open, popd, prevd, prevd-or-backward-word, prompt_pwd, psub, pushd, seq, setenv, sgrep, trap, type, umask, up-or-search, vared</outp> +\endfish -<p>You can see the source for any function by passing its name to <tt>functions</tt>: +You can see the source for any function by passing its name to `functions`: -<pre> -> <b>functions</b> <i>ls</i> +\fish{cli-dark} +>_ functions ls function ls --description 'List contents of directory' - command ls -G $argv + command ls -G $argv end -</pre> +\endfish + -<h2 id="tut_loops">Loops</h2> +\section tut_loops Loops While loops: -<pre> -> <b>while</b> <i>true</i> - <b>echo</b> <i class="quote">"Loop forever"</i> -<b>end</b> -Loop forever -Loop forever -Loop forever -... -</pre> +\fish{cli-dark} +>_ while true + echo <i class="quote">"Loop forever"</i> +end +<outp>Loop forever</outp> +<outp>Loop forever</outp> +<outp>Loop forever</outp> +<outp>...</outp> +\endfish For loops can be used to iterate over a list. For example, a list of files: -<pre> -> <b>for</b> <i>file in *.txt</i> - <b>cp</b> <i>$file $file.bak</i> -<b>end</b> -</pre> +\fish{cli-dark} +>_ for file in *.txt + cp $file $file.bak +end +\endfish Iterating over a list of numbers can be done with `seq`: -<pre> -> <b>for</b> <i>x in (</i><b>seq</b> <i>5)</i> - <b>touch</b> <i>file_$x.txt</i> -<b>end</b> -</pre> +\fish{cli-dark} +>_ for x in (seq 5) + touch file_$x.txt +end +\endfish -<h2 id="tut_prompt">Prompt</h2> +\section tut_prompt Prompt -Unlike other shells, there is no prompt variable like PS1. To display your prompt, fish executes a function with the name <tt>fish_prompt</tt>, and its output is used as the prompt. +Unlike other shells, there is no prompt variable like PS1. To display your prompt, `fish` executes a function with the name `fish_prompt`, and its output is used as the prompt. You can define your own prompt: -<pre> -> <b>function <i>fish_prompt</i> - echo <i>"New Prompt % "</i> - end</b> -New Prompt % <u> </u> -</b> -</pre> - -Multiple lines are OK. Colors can be set via <tt>set_color</tt>, passing it named ANSI colors, or hex RGB values: - -<pre> -> <b>function</b> <i>fish_prompt</i> - <b>set_color</b> <i>purple</i> - <b>date</b> <i class="quote">"+%m/%d/%y"</i> - <b>set_color</b> <i>FF0</i> - <b>echo</b> <i>(</i><b>pwd</b><i>)</i> <i class="quote">'>'</i> - <b>set_color</b> <i>normal</i> - <b>end</b> + +\fish{cli-dark} +>_ function fish_prompt + echo "New Prompt % " +end +<asis>New Prompt % </asis>___ +\endfish + +Multiple lines are OK. Colors can be set via `set_color`, passing it named ANSI colors, or hex RGB values: + +\fish{cli-dark} +>_ function fish_prompt + set_color purple + date "+%m/%d/%y" + set_color FF0 + echo (pwd) '>' + set_color normal + end <span style="color: purple">02/06/13</span> -<span style="color: #FF0">/home/tutorial ></span><u> </u> -</b> -</pre> +<span style="color: #FF0">/home/tutorial ></span>___ +\endfish -<p>You can choose among some sample prompts by running <tt>fish_config prompt</tt>. fish also supports RPROMPT through <tt>fish_right_prompt</tt>. +You can choose among some sample prompts by running `fish_config prompt`. `fish` also supports RPROMPT through `fish_right_prompt`. -<h3>$PATH</h2> +\section tut-path $PATH -<tt>$PATH</tt> is an environment variable containing the directories in which fish searches for commands. Instead of separating entries with a colon, $PATH is a list. You can modify $PATH in a few ways: +`$PATH` is an environment variable containing the directories in which `fish` searches for commands. Instead of separating entries with a colon, $PATH is a list. You can modify $PATH in a few ways: -<p><ol> -<li>By modifying the <tt>$fish_user_paths</tt> variable, which is automatically appended to <tt>$PATH</tt>. For example, to permanently add /usr/local/bin to your <tt>$PATH</tt>, you could write: +-# By modifying the `$fish_user_paths` variable, which is automatically appended to `$PATH`. For example, to permanently add `/usr/local/bin` to your `$PATH`, you could write: -<pre> -> <b>set</b> <i>-U fish_user_paths $fish_user_paths /usr/local/bin</i> -</pre> +\fish{cli-dark} +>_ set -U fish_user_paths $fish_user_paths /usr/local/bin +\endfish +-# Directly in config.fish (see below). -<li>Directly in config.fish (see below).</li> -</ol> -<h2 id="tut_startup">Startup (Where's .bashrc?)</h2> +\section tut_startup Startup (Where's .bashrc?) -<p>fish starts by executing commands in <tt>~/.config/fish/config.fish</tt>. You can create it if it does not exist. +`fish` starts by executing commands in `~/.config/fish/config.fish`. You can create it if it does not exist. -<p>It is possible to directly create functions and variables in <tt>config.fish</tt> file, using the commands shown above. For example: +It is possible to directly create functions and variables in `config.fish` file, using the commands shown above. For example: -<p><pre> -> <b>cat</b> <i>~/.config/fish/config.fish</i> +\fish{cli-dark} +>_ cat ~/.config/fish/config.fish set -x PATH $PATH /sbin/ function ll ls -lh $argv end -</pre> +\endfish -<p>However, it is more common and efficient to use <i>autoloading functions</i> and <i>universal variables</i>. +However, it is more common and efficient to use autoloading functions and universal variables. -<h3>Autoloading Functions</h2> +\section tut-autoload Autoloading Functions -<p>When fish encounters a command, it attempts to <i>autoload</i> a function for that command, by looking for a file with the name of that command in <tt>~/.config/fish/functions/</tt>. +When `fish` encounters a command, it attempts to autoload a function for that command, by looking for a file with the name of that command in `~/.config/fish/functions/`. -<p>For example, if you wanted to have a function <tt>ll</tt>, you would add a text file <tt>ll.fish</tt> to <tt>~/.config/fish/functions</tt>: +For example, if you wanted to have a function `ll`, you would add a text file `ll.fish` to `~/.config/fish/functions`: -<pre> -> <b>cat</b> <i>~/.config/fish/functions/ll.fish</i> +\fish{cli-dark} +>_ cat ~/.config/fish/functions/ll.fish function ll - ls -lh $argv + ls -lh $argv end -</pre> +\endfish This is the preferred way to define your prompt as well: -<pre> -> <b>cat</b> <i>~/.config/fish/functions/fish_prompt.fish</i> +\fish{cli-dark} +>_ cat ~/.config/fish/functions/fish_prompt.fish function fish_prompt - echo (pwd) '> ' + echo (pwd) "> " end -</pre> +\endfish -<p>See the documentation for <a href="commands.html#funced">funced</a> and <a href="commands.html#funcsave">funcsave</a> for ways to create these files automatically. +See the documentation for <a href="commands.html#funced">funced</a> and <a href="commands.html#funcsave">funcsave</a> for ways to create these files automatically. -<h3>Universal Variables</h2> +\section tut-universal Universal Variables -<p>A universal variable is a variable whose value is shared across all instances of fish, now and in the future - even after a reboot. You can make a variable universal with <tt>set -U</tt>: +A universal variable is a variable whose value is shared across all instances of `fish`, now and in the future - even after a reboot. You can make a variable universal with `set -U`: -<pre> -> <b>set</b> <i>-U EDITOR vim</i> -</pre> +\fish{cli-dark} +>_ set -U EDITOR vim +\endfish Now in another shell: -<pre> -> <b>echo</b> <i>$EDITOR</i> +\fish{cli-dark} +>_ echo $EDITOR vim -</pre> +\endfish -<h3>Ready for more?</h2> +\section tut-more Ready for more? -<p>If you want to learn more about fish, there is <a href="index.html">lots of detailed documentation</a>, an <a href="https://lists.sourceforge.net/lists/listinfo/fish-users">official mailing list</a>, the IRC channel <tt>#fish</tt> on <tt>irc.oftc.net</tt>, and the <a href="http://github.com/fish-shell/fish-shell/">github page</a>. +If you want to learn more about fish, there is <a href="index.html">lots of detailed documentation</a>, an <a href="https://lists.sourceforge.net/lists/listinfo/fish-users">official mailing list</a>, the IRC channel \#fish on `irc.oftc.net`, and the <a href="https://github.com/fish-shell/fish-shell/">github page</a>. +\htmlonly[block] </div> - \endhtmlonly +\endhtmlonly +*/ diff --git a/doc_src/type.txt b/doc_src/type.txt index 8945102c..2f55d72a 100644 --- a/doc_src/type.txt +++ b/doc_src/type.txt @@ -1,25 +1,32 @@ \section type type - indicate how a command would be interpreted \subsection type-synopsis Synopsis - <tt>type [OPTIONS] NAME [NAME ...]</tt> +\fish{synopsis} +type [OPTIONS] NAME [NAME ...] +\endfish \subsection type-description Description -With no options, \c type indicates how each \c NAME would be interpreted if used as a command name. +With no options, `type` indicates how each `NAME` would be interpreted if used as a command name. The following options are available: -- \c -h or \c --help prints help and then exits. -- \c -a or \c --all prints all of possible definitions of the specified names. -- \c -f or \c --no-functions suppresses function and builtin lookup. -- \c -t or \c --type prints <tt>function</tt>, <tt>builtin</tt>, or <tt>file</tt> if \c NAME is a shell function, builtin, or disk file, respectively. -- \c -p or \c --path returns the name of the disk file that would be executed, or nothing if 'type -t name' would not return 'file'. -- \c -P or \c --force-path returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the <tt>$PATH</tt>. -- \c -q or \c --quiet suppresses all output; this is useful when testing the exit status. +- `-a` or `--all` prints all of possible definitions of the specified names. + +- `-f` or `--no-functions` suppresses function and builtin lookup. + +- `-t` or `--type` prints `function`, `builtin`, or `file` if `NAME` is a shell function, builtin, or disk file, respectively. + +- `-p` or `--path` returns the name of the disk file that would be executed, or nothing if `type -t name` would not return `file`. + +- `-P` or `--force-path` returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the <tt>$PATH</tt>. + +- `-q` or `--quiet` suppresses all output; this is useful when testing the exit status. -\c type sets the exit status to 0 if the specified command was found, -and 1 if it could not be found. \subsection type-example Example -<tt>type fg</tt> outputs the string 'fg is a shell builtin'. +\fish +type fg +# Outputs the string 'fg is a shell builtin'. +\endfish diff --git a/doc_src/ulimit.txt b/doc_src/ulimit.txt index 7b4e3c45..86ffe2b6 100644 --- a/doc_src/ulimit.txt +++ b/doc_src/ulimit.txt @@ -1,66 +1,64 @@ \section ulimit ulimit - set or get resource usage limits \subsection ulimit-synopsis Synopsis -<tt>ulimit [OPTIONS] [LIMIT]</tt> +\fish{synopsis} +ulimit [OPTIONS] [LIMIT] +\endfish \subsection ulimit-description Description -\c ulimit builtin sets or outputs the resource usage limits of the -shell and any processes spawned by it. If a new limit value is -omitted, the current value of the limit of the resource is printed; otherwise, -the specified limit is set to the new value. +`ulimit` builtin sets or outputs the resource usage limits of the shell and any processes spawned by it. If a new limit value is omitted, the current value of the limit of the resource is printed; otherwise, the specified limit is set to the new value. Use one of the following switches to specify which resource limit to set or report: -- <code>-c</code> or <code>--core-size</code>: the maximum size of core files created. By setting this limit to zero, core dumps can be disabled. -- <code>-d</code> or <code>--data-size</code>: the maximum size of a process' data segment. -- <code>-f</code> or <code>--file-size</code>: the maximum size of files created by the shell. -- <code>-l</code> or <code>--lock-size</code>: the maximum size that may be locked into memory. -- <code>-m</code> or <code>--resident-set-size</code>: the maximum resident set size. -- <code>-n</code> or <code>--file-descriptor-count</code>: the maximum number of open file descriptors (most systems do not allow this value to be set). -- <code>-s</code> or <code>--stack-size</code>: the maximum stack size. -- <code>-t</code> or <code>--cpu-time</code>: the maximum amount of CPU time in seconds. -- <code>-u</code> or <code>--process-count</code>: the maximum number of processes available to a single user. -- <code>-v</code> or <code>--virtual-memory-size</code> The maximum amount of virtual memory available to the shell. +- `-c` or `--core-size`: the maximum size of core files created. By setting this limit to zero, core dumps can be disabled. + +- `-d` or `--data-size`: the maximum size of a process' data segment. + +- `-f` or `--file-size`: the maximum size of files created by the shell. + +- `-l` or `--lock-size`: the maximum size that may be locked into memory. + +- `-m` or `--resident-set-size`: the maximum resident set size. + +- `-n` or `--file-descriptor-count`: the maximum number of open file descriptors (most systems do not allow this value to be set). + +- `-s` or `--stack-size`: the maximum stack size. + +- `-t` or `--cpu-time`: the maximum amount of CPU time in seconds. + +- `-u` or `--process-count`: the maximum number of processes available to a single user. + +- `-v` or `--virtual-memory-size` The maximum amount of virtual memory available to the shell. Note that not all these limits are available in all operating systems. -The value of limit can be a number in the unit specified for -the resource or one of the special values <tt>hard</tt>, <tt>soft</tt>, or <tt>unlimited</tt>, -which stand for the current hard limit, the current soft limit, and no -limit, respectively. +The value of limit can be a number in the unit specified for the resource or one of the special values `hard`, `soft`, or `unlimited`, which stand for the current hard limit, the current soft limit, and no limit, respectively. + +If limit is given, it is the new value of the specified resource. If no option is given, then `-f` is assumed. Values are in kilobytes, except for `-t`, which is in seconds and `-n` and `-u`, which are unscaled values. The return status is 0 unless an invalid option or argument is supplied, or an error occurs while setting a new limit. + +`ulimit` also accepts the following switches that determine what type of limit to set: + +- `-H` or `--hard` sets hard resource limit + +- `-S` or `--soft` sets soft resource limit -If limit is given, it is the new value of the specified resource. If -no option is given, then \c -f is assumed. Values are in kilobytes, -except for \c -t, which is in seconds and \c -n and \c -u, which are unscaled -values. The return status is 0 unless an invalid option or argument is -supplied, or an error occurs while setting a new limit. +A hard limit can only be decreased. Once it is set it cannot be increased; a soft limit may be increased up to the value of the hard limit. If neither -H nor -S is specified, both the soft and hard limits are updated when assigning a new limit value, and the soft limit is used when reporting the current value. -\c ulimit also accepts the following switches that determine what type of -limit to set: +The following additional options are also understood by `ulimit`: -- <code>-H</code> or <code>--hard</code> sets hard resource limit -- <code>-S</code> or <code>--soft</code> sets soft resource limit +- `-a` or `--all` prints all current limits -A hard limit can only be decreased. Once it is set it cannot be -increased; a soft limit may be increased up to the value of the hard -limit. If neither -H nor -S is specified, both the soft and hard -limits are updated when assigning a new limit value, and the soft -limit is used when reporting the current value. +The `fish` implementation of `ulimit` should behave identically to the implementation in bash, except for these differences: -The following additional options are also understood by <tt>ulimit</tt>: +- Fish `ulimit` supports GNU-style long options for all switches -- <code>-a</code> or <code>--all</code> prints all current limits -- <code>-h</code> or <code>--help</code> displays help and exits. +- Fish `ulimit` does not support the `-p` option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish. -The \c fish implementation of \c ulimit should behave identically to the -implementation in bash, except for these differences: +- Fish `ulimit` does not support getting or setting multiple limits in one command, except reporting all values using the -a switch -- Fish \c ulimit supports GNU-style long options for all switches -- Fish \c ulimit does not support the \c -p option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish. -- Fish \c ulimit does not support getting or setting multiple limits in one command, except reporting all values using the -a switch \subsection ulimit-example Example -<tt>ulimit -Hs 64</tt> sets the hard stack size limit to 64 kB. +`ulimit -Hs 64` sets the hard stack size limit to 64 kB. diff --git a/doc_src/umask.txt b/doc_src/umask.txt index bc9aac0c..7429d8a9 100644 --- a/doc_src/umask.txt +++ b/doc_src/umask.txt @@ -1,58 +1,41 @@ \section umask umask - set or get the file creation mode mask \subsection umask-synopsis Synopsis -<code>umask [OPTIONS] [MASK]</code> +\fish{synopsis} +umask [OPTIONS] [MASK] +\endfish \subsection umask-description Description -\c umask displays and manipulates the "umask", or file creation mode mask, -which is used to restrict the default access to files. - -The umask may be expressed either as an octal number, which represents -the rights that will be removed by default, or symbolically, which represents -the only rights that will be granted by default. - -Access rights are explained in the manual page for the \c chmod(1) program. - -With no parameters, the current file creation mode mask is printed as -an octal number. - -- <code>-h</code> or <code>--help</code> prints this message. -- <code>-S</code> or <code>--symbolic</code> prints the umask in symbolic form instead of octal form. -- <code>-p</code> or <code>--as-command</code> outputs the umask in a form that may be reused as input - -If a numeric mask is specified as a parameter, the current shell's umask -will be set to that value, and the rights specified by that mask will be -removed from new files and directories by default. - -If a symbolic mask is specified, the desired permission bits, and -not the inverse, should be specified. A symbolic mask is a comma -separated list of rights. Each right consists of three parts: - -- The first part specifies to whom this set of right applies, and can -be one of \c u, \c g, \c o or \c a, where \c u specifies the user who -owns the file, \c g specifies the group owner of the file, \c o -specific other users rights and \c a specifies all three should be -changed. -- The second part of a right specifies the mode, and can be one of \c -=, \c + or \c -, where \c = specifies that the rights should be set to -the new value, \c + specifies that the specified right should be added -to those previously specified and \c - specifies that the specified -rights should be removed from those previously specified. -- The third part of a right specifies what rights should be changed -and can be any combination of \c r, \c w and \c x, representing -read, write and execute rights. - -If the first and second parts are skipped, they are assumed to be \c a -and \c =, respectively. As an example, <code>r,u+w</code> means all -users should have read access and the file owner should also have -write access. +`umask` displays and manipulates the "umask", or file creation mode mask, which is used to restrict the default access to files. + +The umask may be expressed either as an octal number, which represents the rights that will be removed by default, or symbolically, which represents the only rights that will be granted by default. + +Access rights are explained in the manual page for the `chmod`(1) program. + +With no parameters, the current file creation mode mask is printed as an octal number. + +- `-h` or `--help` prints this message. + +- `-S` or `--symbolic` prints the umask in symbolic form instead of octal form. + +- `-p` or `--as-command` outputs the umask in a form that may be reused as input + +If a numeric mask is specified as a parameter, the current shell's umask will be set to that value, and the rights specified by that mask will be removed from new files and directories by default. + +If a symbolic mask is specified, the desired permission bits, and not the inverse, should be specified. A symbolic mask is a comma separated list of rights. Each right consists of three parts: + +- The first part specifies to whom this set of right applies, and can be one of `u`, `g`, `o` or `a`, where `u` specifies the user who owns the file, `g` specifies the group owner of the file, `o` specific other users rights and `a` specifies all three should be changed. + +- The second part of a right specifies the mode, and can be one of `=`, `+` or `-`, where `=` specifies that the rights should be set to the new value, `+` specifies that the specified right should be added to those previously specified and `-` specifies that the specified rights should be removed from those previously specified. + +- The third part of a right specifies what rights should be changed and can be any combination of `r`, `w` and `x`, representing read, write and execute rights. + +If the first and second parts are skipped, they are assumed to be `a` and `=`, respectively. As an example, `r,u+w` means all users should have read access and the file owner should also have write access. Note that symbolic masks currently do not work as intended. -\subsection umask-example Example -<code>umask 177</code> or <code>umask u=rw</code> sets the file -creation mask to read and write for the owner and no permissions at -all for any other users. +\subsection umask-example Example +`umask 177` or `umask u=rw` sets the file creation mask to read and write for the owner and no permissions at all for any other users. diff --git a/doc_src/user_doc.css b/doc_src/user_doc.css new file mode 100644 index 00000000..5c041fd3 --- /dev/null +++ b/doc_src/user_doc.css @@ -0,0 +1,274 @@ +* { + margin: 0; + box-sizing: border-box; +} +html { font-size: 62.5%; } +html, body { + min-height: 100%; + background: #fff; + color: #111; +} +body { + text-rendering: optimizeLegibility; + overflow: hidden; +} +.logo { + width: 210px; + height: 147px; + margin-left: 2rem; + margin-bottom: -3rem; + background-image: url(ascii_fish.png); +} +/*Top site index*/ +.qindex { + font: 500 1.4rem/3.6rem DejaVuSansCondensed, DejaVuSans, Roboto, "Lucida Grande", Calibri, Verdana, "Helvetica Neue", Helvetica, Arial, sans-serif; + border: none; + color: white; + text-align: center; + position: relative; + background-color: #1f2d53; + width: 100%; + height: 3.6rem; +} +/* Don't show the header */ +.header { display: none; } +/*Substructure*/ +.contents { + margin: 0; + min-width: 570px; +} +.fish_left_bar, .fish_right_bar, .fish_only_bar { + position: absolute; + top: 3.6rem; + bottom: 0; + overflow-y: scroll; + -webkit-overflow-scrolling: touch; /* necessary for momentum scrolling */ + font: 400 1.3rem/2.1rem DejaVuSans, Roboto, "Lucida Grande", Calibri, Verdana, "Helvetica Neue", Helvetica, Arial, sans-serif; +} +.fish_left_bar { + width: 25rem; + color: white; + font-family: DejaVuSansCondensed, DejaVuSans, Roboto, "Lucida Grande", Calibri, Verdana, "Helvetica Neue", Helvetica, Arial, sans-serif; + background-color: #1f2d53; +} +.fish_right_bar { + margin-left: 25rem; + margin-right: 0; + padding: 0 3rem; + box-shadow: -0.3rem 0.3rem 1rem #000818; +} +.fish_only_bar { + width: 100%; + padding-bottom: 3rem; +} +hr { + height: 0; + border: none; + border-top: 1px solid #AAA; +} +/*Interaction*/ +a { color: #3d5cb3; } +.qindex a { + color: white; + text-decoration: none; +} +.qindex a:hover { text-decoration: underline; } +.fish_left_bar a { + color: white; + text-decoration: none; +} +.fish_left_bar a:visited { color: inherit; } +.fish_left_bar a:hover { color: #88aaff; } +.fish_right_bar a { text-decoration: none; } +.fish_right_bar a:hover { text-decoration: underline; } +/* Adjust lists */ +.fish_left_bar ul { + padding-left: 2rem; + padding-right: 1rem; +} +.fish_right_bar ul { + list-style-type: circle; + padding-left: 2.4rem; + margin: 1.4rem 0; +} +.fish_right_bar ul li { + margin-bottom: 0.6rem; +} +.fish_right_bar p > code { + display: inline-block; +} +/* Typography */ +p { margin: 1rem 0; } +h1, h2, h3, h4, h5, h6 { + color: #1f2d53; + font-family: DejaVuSansCondensed-Bold, DejaVuSans, Roboto, "Lucida Grande", Calibri, Verdana, sans-serif; +} +h1 { + margin: 1.6rem 0 1rem 0; + font-weight: 700; + font-size: 1.7rem; +} +h2 { + margin: 1.6rem 0 1rem 0; + font-weight: 700; + font-size: 1.7rem; +} +h3 { + margin: 1rem 0 0.4rem 0; + font-weight: 500; + font-size: 1.5rem; +} +.interior_title { + font-size: 2rem; + margin: 2rem 0 1.4rem 0; + color: #414141; + padding-bottom: 10px; + border-bottom: 1px solid #AAA; +} +em { + font-style: normal; +} +/* Special Formmating */ +/* Keyboard */ +.key span { + display:none; +} +.key em { + margin-right: 2px; +} +.key em, .key b { + padding: 1px 4px; + background-color: #fafafa; + background: linear-gradient(to bottom, #eee 0%,#fafafa 100%); + border: 1px solid #bbb; + border-radius: 3px; + font-weight: normal; + white-space: nowrap; + box-shadow: 0 1px 2px #ddd; +} +/* Console display */ +tt, code, pre, .fish { + font-family: "DejaVu Sans Mono", "Source Code Pro", Menlo, "Ubuntu Mono", Consolas, Monaco, "Lucida Console", monospace, fixed; + font-weight: 500; + text-shadow: 0 0 0 rgba(0,0,0,0.4); /*Stronger anti-aliasing*/ + white-space: -moz-pre-wrap; + white-space: -pre-wrap; + white-space: -o-pre-wrap; + white-space: pre-wrap; + word-wrap: break-word; +} + +/*Default 'light' console*/ +.fish { + margin: 1rem 0; + padding: 0.6rem 1rem; + font-size: 1.2rem; + line-height: 1.8rem; + color: #111; + background-color: #fafafa; + border: 1px solid #bbb; + border-radius: 0.6rem; + box-shadow: 0 0.2rem 0.2rem #eee; +} +.comment, .suggest { color: #555; } +.command, .function, .binary { color: #223aa4; } +.argument, .path, .file { color: #5961cf; } +.string { color: #6c6d08; } +.operator, .variable, .match, .history { color: #1c8885; } + +/* Synopsis variant */ +.synopsis { + border: none; + color: #333; + text-shadow: 0 0 0 rgba(0,0,0,0.2); + background: none; + font-size: 1.3rem; + padding: 0; + box-shadow: none; +} +.synopsis .comment, .synopsis .suggest { color: #669; } +.synopsis .command, .synopsis .function, .synopsis .binary { color: #333; } +.synopsis .argument, .synopsis .path, .synopsis .file { color: #666; } + +/* Console variants */ +.cli-dark { + background-color: #222; + color: #ccc; + text-shadow: none; + padding: 0.6rem 1.2rem; + border-radius: 0.6rem; +} +.cli-dark .key em, .cli-dark .key b { + background-color: #ccc; + box-shadow: 0 0.1rem 0 #666; + border: 1px solid #333; + color: #000; + padding: 0 3px; +} +.cli-dark .comment { color: #c33; } +.cli-dark .command, .cli-dark .function, .cli-dark .binary { color: #6159de; } +.cli-dark .argument, .cli-dark .path, .cli-dark .file { color: #00afff; } +.cli-dark .redirect { color: #fff; } +.cli-dark .operator,.cli-dark .variable, .cli-dark .match, .cli-dark .history { color: #2ff; } +.cli-dark .string { color: #b3b206; } +.cli-dark .suggest, .cli-dark em { color: #777; } +.cli-dark .match { color: #2ff; } +.cli-dark .search_match { background-color: #a100a3; } +.cli-dark .cwd, .cli-dark .prompt .path { color: #2f2; } +.cli-dark .prompt { color: #999; } +.cli-dark .cursor { border-bottom: 2px solid #3F3; } +.cli-dark .underline { color: #00afff; text-decoration: underline; } +.cli-dark .error, .cli-dark .error .path { color: #f33; font-weight: bold; } + + +/*Menus*/ +.menu { margin: 1.4rem 0; line-height: 2.2rem; } +.menu ul { list-style-type: none; } +.menu > ul li { position: relative; } +.menu > ul li:before { + content: "›"; + color: #88aaff; + font-size: 1.6rem; + position: absolute; + left: -1rem; + top: -1px; +} +/*Page overrides*/ +/*Documentation*/ +.docs_menu { line-height: 2rem; } +.docs_menu > ul > li { position: static; } +.docs_menu > ul ul { margin: 0.6rem 0; } +.docs_menu > ul ul > li { margin-bottom: 0.2rem; } +/*Tutorial*/ +.tutorial_menu { margin-left: 2rem; } +/*Design*/ +.design { + max-width: 780px; + margin: 0 auto; + padding: 0 4rem; +} +/*Commands*/ +.commands_menu { line-height: 2rem; margin-left: 2rem; } +/*FAQ*/ +.faq_menu { line-height: 2rem; margin-top: 4rem; margin-right: 2rem;} +.faq_menu > ul > li { position: static; } +.faq_menu > ul li { margin-bottom: 0.6rem; } + +/*Licenses*/ +.license { + max-width: 780px; + margin: 0 auto; + padding: 0 4rem; +} +.license li { margin: 1rem 0; } +.license ul li:first-child { + list-style-type: none; + position: relative; +} +.license ul li:first-child:before { + content: "0."; + position: absolute; + left: -2rem; +} + + diff --git a/doc_src/user_doc.footer.html b/doc_src/user_doc.footer.html new file mode 100644 index 00000000..308b1d01 --- /dev/null +++ b/doc_src/user_doc.footer.html @@ -0,0 +1,2 @@ +</body> +</html> diff --git a/doc_src/user_doc.header.html b/doc_src/user_doc.header.html new file mode 100644 index 00000000..8e1be50c --- /dev/null +++ b/doc_src/user_doc.header.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html lang="en"> +<head> +<meta charset="utf-8" /> +<meta http-equiv="X-UA-Compatible" content="IE=edge"/> +<meta name="generator" content="Doxygen $doxygenversion"/> +<title>$projectname: $title</title> +$extrastylesheet +</head> +<body> +<div id="top" class="qindex"><!-- do not close this div here, it is closed by doxygen! --> +<a href="http://fishshell.com/"><code>fish</code> shell</a> +| +<a href="index.html">Documentation</a> +| +<a href="tutorial.html">Tutorial</a> +| +<a href="design.html">Design</a> +| +<a href="commands.html">Commands</a> +| +<a href="faq.html">FAQ</a> +| +<a href="license.html">License</a> diff --git a/doc_src/vared.txt b/doc_src/vared.txt index 609172d7..35235787 100644 --- a/doc_src/vared.txt +++ b/doc_src/vared.txt @@ -1,14 +1,15 @@ \section vared vared - interactively edit the value of an environment variable \subsection vared-synopsis Synopsis - <tt>vared VARIABLE_NAME</tt> +\fish{synopsis} +vared VARIABLE_NAME +\endfish \subsection vared-description Description -\c vared is used to interactively edit the value of an environment -variable. Array variables as a whole can not be edited using \c vared, -but individual array elements can. +`vared` is used to interactively edit the value of an environment variable. Array variables as a whole can not be edited using `vared`, but individual array elements can. + \subsection vared-example Example -<code>vared PATH[3]</code> edits the third element of the PATH array +`vared PATH[3]` edits the third element of the PATH array diff --git a/doc_src/while.txt b/doc_src/while.txt index 496c36c2..c06874d5 100644 --- a/doc_src/while.txt +++ b/doc_src/while.txt @@ -1,21 +1,22 @@ \section while while - perform a command multiple times \subsection while-synopsis Synopsis -<tt>while CONDITION; COMMANDS...; end</tt> +\fish{synopsis} +while CONDITION; COMMANDS...; end +\endfish \subsection while-description Description -<tt>while</tt> repeatedly executes <tt>CONDITION</tt>, and if the exit status -is 0, then executes <tt>COMMANDS</tt>. -If the exit status of \c CONDITION is non-zero on the first iteration, -\c COMMANDS will not be executed at all. +`while` repeatedly executes `CONDITION`, and if the exit status is 0, then executes `COMMANDS`. + +If the exit status of `CONDITION` is non-zero on the first iteration, `COMMANDS` will not be executed at all. + +Use <a href="#begin">`begin; ...; end`</a> for complex conditions; more complex control can be achieved with `while true` containing a <a href="#break">break</a>. -Use <a href="#begin"><tt>begin; ...; end</tt></a> for complex conditions; more -complex control can be achieved with <tt>while true</tt> containing a -<a href="#break">break</a>. \subsection while-example Example -<tt>while test -f foo.txt; echo file exists; sleep 10; end</tt> -outputs 'file exists' at 10 second intervals as long as -the file foo.txt exists. +\fish +while test -f foo.txt; echo file exists; sleep 10; end +# outputs 'file exists' at 10 second intervals as long as the file foo.txt exists. +\endfish
\ No newline at end of file diff --git a/lexicon_filter.in b/lexicon_filter.in new file mode 100644 index 00000000..cab61bce --- /dev/null +++ b/lexicon_filter.in @@ -0,0 +1,624 @@ +#! @sed@ -f +#. +# A Doxygen filter for building Fish's lexicon, for documentation bling. +#. +# Written specially for Fish, the shell for the 90's, in sed, the state of the +# art text processor from the 70's. Who's sed? sed's dead, baby, sed's dead.* +# by Mark Griffiths <mark@thebespokepixel.com> *but quite portable +#. +# Finds /fish../endfish blocks in documentation source files and enhances +# markup. Requires that the four character word 'classes' declared here are +# added to Doxyfiles as aliases i.e.: +#. +# Enhance for HTML Help pages (Doxyfile.user)… +# ALIASES = "fish=\htmlonly[block] \n<pre class=\"fish\">" +# ALIASES += "fish{1}=\htmlonly[block] \n<pre class=\"fish \1\">" +# ALIASES += "endfish=</pre>\endhtmlonly \n" +#. +# ALIASES += "blah{1}=<span class=\"comment\">\1</span>" +# ALIASES += "bltn{1}=<span class=\"command\">\1</span>" and so on... +#. +# And simplify for man pages (Doxyfile.help)… +# ALIASES = "fish=<pre>" +# ALIASES += "fish{1}=<pre>" +# ALIASES += "endfish=</pre>" +#. +# ALIASES += "blah{1}=\1" +# ALIASES += "bltn{1}=<em>\1</em>"... +#. +# It's meant to only ever be run once, during make, as Doxygen's 'INPUT +# FILTER', though can be run interactively by passing a file in via stdin. It +# wont respond to arguments. +#. +# It's most easily tested by passing test strings into the compiled script: +#. +# echo "/fish Line to test" | ./fish_lexicon_filter +#. +# The, at times, archiac looking regex is down to ensuring portable sed BREs +#. +# Licensed under whatever terms are most compatible with Fish's GPLv2 license, +# bascially free to use/reuse/redistribute/laugh at/be inspired by. Don't +# pretend it's your code unless you've spent more late nights on it than me but +# if it saves you a late night, do what you can to help rebalance karma. If it +# doesn't work or breaks something, it's your fault for using it: if it seems +# to work it's more likely a hallucination than anything based in reality. +#. +# Pattern flow control for scanning doc.h +/\\fish/,/\\endfish/ { + # Open \fish block, firstly it it's on it's own line + /^\\fish$/b + /^\\fish{[^}]*}$/b + # Then if it's inline. Remove and process immediately... + /^\\fish.*$/ { + # Catch @ symbol + s/@/(at)/ + s/^\\fish// + s/\\endfish// + b html + } + # Output blank lines + /^$/b + # Inside \fish block. Process... + /\\endfish/!{ + # Catch @ symbol + s/@/((d))/ + # Preprocess HTML and HTML-like formatting + /<[^>]*>/ { + b html + } + # Process the rest + b process + } + # End block + /\\endfish/b +} +#. +# This is not the pattern we're looking for +b +#. +# Process any HTML tags. +# Structured to reduce sed's greediness. +:html +# Spans +s|<span style=['"]\([^'"][^'"]*\)">|@span{\1,| +s|<span class=['"]\([^'"][^'"]*\)">|@spcl{\1,| +s|</span>|}| +#. +# Bold +s|<b>|@bold{| +s|<b [^>]*>|@bold{| +s|</b>|}| +#. +# Strong (synonimous with emphasis) +s|<strong>|@bold{| +s|<strong [^>]*>|@bold{| +s|</strong>|}| +#. +# EMPHasis +s|<em>|@emph{| +s|<em [^>]*>|@emph{| +s|</em>|}| +#. +# Italic (synonimous with emphasis) +s|<i>|@emph{| +s|<i [^>]*>|@emph{| +s|</i>|}| +#. +# UNDeRline +s|<u>|@undr{| +s|<u [^>]*>|@undr{| +s|</u>|}| +t html +#. +# Some handy non-standard extensions +# autoSuGgeSTion +s|<s>|@sgst{| +s|<s [^>]*>|@sgst{| +s|</s>|}| +#. +# MaTCH +s|<m>|@mtch{| +s|<m [^>]*>|@mtch{| +s|</m>|}| +#. +# SearchMaTCh +s|<sm>|@smtc{| +s|<sm [^>]*>|@smtc{| +s|</sm>|}| +#. +# ERrOR +s|<error>|@eror{| +s|<error [^>]*>|@eror{| +s|</error>|}| +#. +# AsIs - protect from auto-formatting +s|<asis>|@asis{| +s|</asis>|}| +#. +# OUTPut - protect from auto-formatting +s|<outp>|@outp{| +s|</outp>|}| +t html +#. +# Clean other unhandled html +s|<\([A-Za-z][A-Za-z]*\)[^>]*>\([^<]*\)</\1>|\2| +t html +#. +# Start processing entities +:process +# Output: +# Line marked as output pass through +/@outp/ { + b +} +# Comments: +# Capture full line comments +/^\( *\)#\(.*\)$/ { + # Assume any line starting with a # is complete + s//\1@blah{\2}/ + t +} +# Match sub-line comments +/#[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]/ ! { + s/#\(.*$\)/\\\ +<@blah{#\1}\ +/ +} +#. +# Protected entities These shouldn't allow nested structure, so we move them +# to a marked, new line for a future extract/process/insert action. +#. +# AsIs block - resists formatting. +s/@asis{\(.*\)}/\\\ +<@asis{\1}\ +/g +#. +# Manual <span> +s/@span{\(.*\)}/\\\ +<@span{\1}\ +/g +#. +# String Literals +s/"\([^"]*\)"/\\\ +<@dblq{\1}\ +/g +s/'\([^']*\)'/\\\ +<@sglq{\1}\ +/g +#. +# AutoSuggestions. +s/@sgst{\([^}]*\)}/\\\ +<@sgst{\1}\ +/ +#. +# Command/Function options +# Short options +s/ -\([A-Za-z][A-Za-z]*\)\([^A-Za-z}]\)/ \\\ +<@opts{-\1}\ +\2/g +#. +# Long options +s/ --\([A-Za-z][A-Za-z0-9=_-]*\)\([^A-Za-z0-9=_-]*\)/ \\\ +<@opts{--\1}\ +\2/g +#. +# Prompt +s/~>_/\\\ +<@prmt{\ +<@path{~}\ +}/ +s/^>_/@prmt/ +#. +# Cursor +#. +s/___$/@curs/ +s/___\(.\)/\\\ +<@curs{\1}\ +/ +#. +# Trailing Backslash +s/ \\$/ @bksl{ }/ +#. +# Paths +/\n<@dblq[^}]*[~/]/b protect +/\n<@sglq[^}]*[~/]/b protect +/\n<@span[^}]*[~/]/b protect +#. +# Normal Directory +s|mkdir |mkdir :| +s|\([~/:][/]*[.A-Za-z_0-9/-]*\)\\ |\1=|g +s| \([~/][/]*[.A-Za-z_0-9/=-]*\)| \\\ +<@path{\1}\ +|g +s| \(:[/]*[.A-Za-z_0-9/=-]*\)| \\\ +<@path{\1}\ +|g +t protect +#. +# Dot Relative Directory (no spaces in path) +s| \(./[A-Za-z_0-9/-]*\)| \\\ +<@path{\1}\ +|g +b protect +#. +# Tidy up. Merge back 'pure' entities from hold space. +:tidy +#. +# Convert loose text to arguments +s/ \([a-zA-Z0-9+%*.-][{},a-zA-Z0-9%*._/?!=-]*\)/ @args{\1}/g +#. +# Or when tight to a newline +s|\n\([a-zA-Z0-9+%*.-][{},a-zA-Z0-9%*._/?!-]*\)|\ +@args{\1}|g +#. +# Or when tight to the beginning +s|^\([a-zA-Z][{},a-zA-Z0-9%*._/?!-]*\)|@args{\1}|g +#. +# Pick up loose text after markup. +s/\([})]\)\([a-zA-Z0-9+%*.,][,a-zA-Z0-9%*._/?!-]*\);/\1@args{\2};/g +s/\([})]\)\([a-zA-Z0-9+%*.,][,a-zA-Z0-9%*._/?!-]*\)$/\1@args{\2}/g +#. +# Uncomment the following 2 lines (ss) to log the pattern buffer. +s/^.*$/Pattern : &/w lexicon.log +s/^Pattern : // +#. +# Uncomment the following 4 lines (xssx) to log the hold buffer. +x +s/^.*$/HoldBufr: &/w lexicon.log +s/^HoldBufr: // +x +#. +# Tack the hold space to the end of the pattern buffer. +G +#. +# Uncomment the folowing two lines (ss) to log the buffer join. +s/^.*$/Joined : &/w lexicon.log +s/^Joined : // +#. +# Iterate over alternate lines, matching '<' to '\' +:join +s,\([^\\ ]*\)\\\n\([^<]*\)<\(@[^}]*[}\\]\),\1\3\2, +t join +# Clean up stray new lines +s/\n//g +#. +# Uncomment the folowing two lines (ss) to log the buffer before 'cleaning'. +s/^.*$/PreClean: &/w lexicon.log +s/^PreClean: // +# Clean up special cases +#. +/@blah/{ + s/\(blah{[^@]*\)@sglq{\([^}]*\)}/\1'\2'/ + s/\(blah{[^@]*\)@dblq{\([^}]*\)}/\1"\2"/ + s/\(blah{[^@]*\)@....{\([^}]*\)}/\1\2/ +} +/@dblq/{ + :cleandblq + s/\(dblq{[^@}<]*\)[<]*@...[^q]{\([^}]*\)}/\1\2/ + t cleandblq +} +/@sglq/{ + :cleansglq + s/\(sglq{[^@}<]*\)[<]*@...[^q]{\([^}]*\)}/\1\2/ + t cleansglq +} +/@vars/{ + :cleanvars + s/\(vars{@optr{$}[^@}]*\)@bltn{\([^}]*\)}/\1\2/ + s/\(vars{@optr{$}[^@}]*\)@func{\([^}]*\)}/\1\2/ + s/\(vars{@optr{$}[^@}]*\)@cmnd{\([^}]*\)}/\1\2/ + s/\(vars{@optr{$}[^@}]*\)@args{\([^}]*\)}/\1\2/ + t cleanvars +} +/@redr/{ + :cleanredr + s/\(redr{[^@}]*\)@bltn{\([^}]*\)}/\1\2/ + s/\(redr{[^@}]*\)@func{\([^}]*\)}/\1\2/ + s/\(redr{[^@}]*\)@cmnd{\([^}]*\)}/\1\2/ + s/\(redr{[^@}]*\)@fsfo{\([^}]*\)}/\1\2/ + s/\(redr{[^}]*\)}\( *\)@path{\([^}]*\)/\1\2\3/ + t cleanredr +} +/@sgst/{ + s/@sgst{<@/@sgst{@/ + :cleansgst + s/\(sgst{@curs{.}[^@]*\)@bltn{\([^}]*\)}/\1\2/ + s/\(sgst{@curs{.}[^@]*\)@func{\([^}]*\)}/\1\2/ + s/\(sgst{@curs{.}[^@]*\)@cmnd{\([^}]*\)}/\1\2/ + s/\(sgst{@curs{.}[^@]*\)@opts{\([^}]*\)}/\1\2/ + s/\(sgst{@curs{.}[^@]*\)@path{\([^}]*\)}/\1\2/ + s/\(sgst{@curs{.}[^@]*\)@args{\([^}]*\)}/\1\2/ + s/\(sgst{@curs{.}[^@]*\)@fsfo{\([^}]*\)}/\1\2/ + t cleansgst +} +/@fsfo/{ + :cleanfsfo + s/\(fsfo{[^@}]*\)@bltn{\([^}]*\)}/\1\2/ + s/\(fsfo{[^@}]*\)@func{\([^}]*\)}/\1\2/ + s/\(fsfo{[^@}]*\)@cmnd{\([^}]*\)}/\1\2/ + t cleanfsfo +} +/@prmt{/{ + s/@prmt{<@path/@prmt{@path/ +} +#. +# Restore Paths +/@fsfo/ { + s/\(@fsfo{[^=]*\)=/\1 / +} +/@path/ { + :cleanpath + s/\(@path{[^:]*\):/\1/ + s/\(@path{[^=]*\)=/\1\\ / + t cleanpath + s/@path{}// +} +#. +# Finally, restructure to follow Fish's command [arguments] semantics. +# Find the initial command, and change any others to arguments, up to a |, ( or ; +# Assumes that a valid line will start with either a builtin, a function or a binary. +#. +# 'if' and 'for' seem to be special cases +#. +# Uncomment the folowing two lines (ss) to log the buffer before semantic conversion. +s/^.*$/PreArgs : &/w lexicon.log +s/^PreArgs : // +#. +# Find initial commands/functions/binaries +#. +# Store prmt, if present +#. +/@prmt/ { +h +s/^\(@prmt *\).*$/\1/ +x +s/^@prmt *// +} +#. +# Special case for optional commands +s/@args{\[@bltn/@args{[@xbln/g +# Special case for one-line 'if' statements +/@bltn{if}/ { + s//@xbln{if}/ + s/@bltn{set}/@xbln{set}/ + s/@bltn{not}/@xbln{not}/ + s/@bltn{else}/@xbln{else}/ + s/@bltn{contains}/@xbln{contains}/ + s/@bltn{test}/@xbln{test}/ + s/@bltn{end}/@xbln{end}/ + s/@cmnd{grep}/@xcmd{grep}/ +} +# one-line 'for' statements +/@bltn{for}/ { + s//@xbln{for}/ + s/@args{in}/@xbln{in}/ +} +# one-line 'begin' statements +/@bltn{begin}/ { + s//@xbln{begin}/ + s/@bltn{end}/@xbln{end}/ +} +# one-line 'break' statements +/@bltn{break}/ { + s//@xbln{break}/ + s/@bltn{end}/@xbln{end}/ +} +# one-line 'continue' statements +/@bltn{continue}/ { + s//@xbln{continue}/ + s/@bltn{end}/@xbln{end}/ +} +# one-line 'switch' statements +/@bltn{switch}/ { + s//@xbln{switch}/ + s/@bltn{case}/@xbln{case}/ + s/@bltn{end}/@xbln{end}/ +} +# one-line 'function' statements +/@bltn{function}/ { + s//@xbln{function}/ + s/@bltn{return}/@xbln{return}/ + s/@bltn{end}/@xbln{end}/ +} +# one-line 'bind' statements - special input functions +/@bltn{bind}/ { + s//@xbln{bind}/ + s/@....{\([a-z]*\)}\(-[a-z-]*\)/@args{\1\2}/ +} +# one-line 'builtin' statements +s/@bltn{builtin} @bltn/@xbln{builtin} @xbln/g +s/@bltn{builtin} @cmnd/@xbln{builtin} @xcmd/g +s/@bltn{builtin} @func/@xbln{builtin} @xfnc/g +#. +# one-line 'command' statements +s/@bltn{command} @bltn/@xbln{command} @xbln/g +s/@bltn{command} @cmnd/@xbln{command} @xcmd/g +s/@bltn{command} @func/@xbln{command} @xfnc/g +#. +# one-line 'and/or' statements +s/@bltn{and} @bltn/@xbln{and} @xbln/g +s/@bltn{and} @cmnd/@xbln{and} @xcmd/g +s/@bltn{and} @func/@xbln{and} @xfnc/g +s/@bltn{or} @bltn/@xbln{or} @xbln/g +s/@bltn{or} @cmnd/@xbln{or} @xcmd/g +s/@bltn{or} @func/@xbln{or} @xfnc/g +#. +s/^\( *\)@cmnd/\1@xcmd/ +s/\( *[;()] *\)@cmnd/\1@xcmd/g +s/\( *@redr{|} *\)@cmnd/\1@xcmd/g +s/^\( *\)@bltn/\1@xbln/ +s/\( *[;()] *\)@bltn/\1@xbln/g +s/\( *@redr{|} *\)@bltn/\1@xbln/g +s/^\( *\)@func/\1@xfnc/ +s/\( *[;()] *\)@func/\1@xfnc/g +s/\( *@redr{|} *\)@func/\1@xfnc/g +s/\\@bltn{\([^}]*\)/@args{@bksl{\1}/g +s/@bltn/@args/g +s/@func/@args/g +s/@cmnd/@args/g +#. +s/^.*$/PostArgs: &/w lexicon.log +s/^PostArgs: // +#. +s/xbln/bltn/g +s/xfnc/func/g +s/xcmd/cmnd/g +x +/^@prmt/ { +G +s/^@prmt \n/@prmt / +} +/^@prmt/ ! { +x +} +#. +# Mark up sesitive character entities. +#. +:entities +s/</\</g +s/>/\>/g +s/((d))/@/g +#. +# Final post processing +s/};\([^]]\)/}@redr{;}\1/g +s/};$/}@redr{;}/ +s/ \[\([@(]\)/ @args{[}\1/g +s/ \[\([A-Z]*\) / @args{[\1} /g +s/@args{\([a-zA-Z0-9_.]*\)}\]/@args{\1]}/g +s/@args{\([a-zA-Z0-9_.]*\)}: /@args{\1:} /g +s/@bltn{echo} @fsfo/@bltn{echo} @args/g +s/@bltn{echo}\([a-zA-Z0-9.@{} _-]*\)@fsfo/@bltn{echo}\1@args/g +s/ \] / @args{]} /g +s/ \]$/ @args{]}/g +s/\]}\]$/]]}/ +s/\\\([()]\)/@optr{@bksl{\1}}/g +s/\([()]\)/@optr{\1}/g +s/\\n/@bksl{n}/ +s/ \\$// +#. +# Uncomment the folowing two lines (ss) to log the final output, sent to Doxygen. +s/^.*$/Output : &\ +\ +/w lexicon.log +s/^Output : // +s/\n\n$// +#. +# Lines are reassembled, so branch to end +b +# === Main End === +#. +#. +# === Subroutines === +# Branched to when content requires. +#. +# Move protected content to hold space and mark up other entities. +:protect +s/^.*$/Input : &/w lexicon.log +s/^Input : // +h +# Clear out any content that has already been marked up, to prevent futher +# markup on words that should be left alone. +#. +:patternflush +s/\n<@[^}]*[}\\]// +s/\\ [^\\]*$/\\/ +t patternflush +s/\n$//g +#. +# Swap the pattern and hold buffers and remove unmarked lines and extra +# characters. Basically the inverse of the 'patternflush' action, with +# additional trailing characters stripped. +x +/^\<@[^}]*$/ ! { + s/[^\<]*// + s/^ *\\\n//g + s/\n *\\//g + s/[()] \\//g + s/^[^\<][^@][^\\]*// + s/\n[]|;) ][^\\]*\\// + s/\n[]|;) a-zA-Z0-9-][^\\]*$// + s/\n[]|;)}]\\// + s/\n[]|;)}]\n// + s/\n[]|;)}]$// + s/[()]$// + s/}@curs/}/ + s/\n@curs$// + s/\n[^\<@][^\\]*\\// + s/\n[^\<@][^\\]*// + s/^\\// + s/\n$//g +} +s/\\\n/\ +/ +s/\< \n// +s/^[a-z][a-z]* \n// +#. +# Swap the buffers back. +x +#. +# A special case. Tidy up after commands. +# Redirectors +s/\([^{|] *\)|/\1@redr{|}/g +s/&$/@redr{\&}/ +s/\([^{&] *\)&[^a-z]/\1@redr{\&}/g +s/\([^{<>^] *\)\([0-9]* *[<>^][<>^]*[^@][a-zA-Z0-9./_-]*\)/\1@redr{\2}/g +s/\\}/}\\/g +#. +# Now we can add in 'unsafe' entities that would be too greedy. +# Arrays +s/[[][0-9$a-zA-Z_;. -]*]/@args{&}/g +#. +# Declared Variables +s/\($[$]*\)\([A-Za-z_0-9][A-Za-z_0-9]*\)/@vars{@optr{\1}\2}/g +#. +# Files +s/\([^@]\)\([A-Za-z0-9_-][A-Za-z0-9_-]*\.[a-z0-9*][a-z0-9*]*\)/\1@fsfo{\2}/g +#. +:commands +#. +#### This section is built in the Makefile. Just some formatting examples. ##### +#. +# Fish builtin (bltn) <- 4 character code that has a Doxygen alias counterpart +# template : s/[[:<:]]function[[:>:]]/@bltn{&}/ +#. +# s,[[:<:]]function[[:>:]],@bltn{function},g +# s,[[:<:]]begin[[:>:]],@bltn{begin},g +# ... +#. +# Fish functions (func) +# Populated by 'public' functions' filename. +#. +# s,[[:<:]]fish_pwd[[:>:]],@func{fish_pwd},g +# s,[[:<:]]fish_prompt[[:>:]],@func{fish_prompt},g +# ... +#. +# Shell Command (cmnd) +# Populated from completion filenames +#. +# s,[[:<:]]seq[[:>:]],@cmnd{seq},g +# s,[[:<:]]rm[[:>:]],@cmnd{rm},g +# ... +#. +# Color Variable (clrv) +# Populated from __fish_config_interactive.fish +# Allows fish's 'special' color variables to be identified +#. +# s,[[:<:]]fish_color_normal[[:>:]],@clrv{fish_color_normal},g +# s,[[:<:]]fish_color_command[[:>:]],@clrv{fish_color_command},g +#. +# Once all of the commands/functions/variables/special's have been marked up, +# branch back to tidy up and collapse the pattern/hold buffers back to a +# single line. +#. +# b tidy +#. +#. +# Below is a special section that adds vocabuarly to the lexicon during 'make'. +# As the lexicon is written into the output lexicon_filter, portability is +# automatically handled. +#. +#.!# cmnd whoami +#.!# cmnd mkdir +#.!# cmnd basename +#.!# bltn sleep +#.!# args in diff --git a/user_doc.head.html b/user_doc.head.html deleted file mode 100644 index eae673f5..00000000 --- a/user_doc.head.html +++ /dev/null @@ -1,166 +0,0 @@ -<html> -<head> -<title>fish user documentation</title> -<link href="doxygen.css" rel="stylesheet" type="text/css"> - -<style type='text/css'> - -/* fish documentation CSS overrides */ - -/* No scrollbar on the body. Our columns are independently scrollable */ -body -{ - overflow: hidden; -} - -.fish_left_bar, .fish_right_bar, .fish_only_bar -{ - position: absolute; - top: 36px; - bottom: 0; - overflow-y: scroll; - -webkit-overflow-scrolling: touch; /* necessary for momentum scrolling */ -} - -.fish_left_bar -{ - width: 250px; - color: white; -} -.fish_left_bar a { color: white; } -.fish_left_bar a:visited { color: inherit; } -.fish_right_bar -{ - margin-left: 250px; - margin-right: 0px; - padding: 0 0 0 20px; /* 20 px on left */ - background-color: white; - -moz-box-shadow: -5px 0px 5px -2px black; - -webkit-box-shadow: -5px 0px 5px -2px black; - box-shadow: -5px 0px 5px -2px black; -} - -.fish_right_bar p -{ - margin-right: 8px; -} - -.fish_left_big { width: 380px; } -.fish_right_little { margin-left: 380px; } - -.fish_left_medium { width: 280; } -.fish_right_medium { margin-left: 280; } - -.fish_left_little { width: 200px; } -.fish_right_big { margin-left: 200px; } - - -.fish_only_bar -{ - padding: 0px 20px; -} - -h1, h2, h3 { color: #1E335E; } - -h1 { font-size: 150%; } -h2 { font-size: 115%; } -h3 { font-size: 105%; } - -/* Don't show the header */ -div.header { display: none; } - -h1.interior_title, h1.interior_title_borderless { - color: #333; -} - -h1.interior_title { - padding-bottom: 10px; - border-bottom: 1px solid #AAA; -} - -div.contents { margin: 0px; } - -div.qindex -{ - height: 30px; - line-height: 30px; - text-align: center; - background-image: none; - color: white; - border: none; -} -.fish_left_bar, div.header, div.qindex -{ - background-color: #1E335E; -} - -div.qindex -{ - border: none; - padding: 3px 0px; - - /* Ensure the bottom border is visible over the left column */ - position: relative; - z-index: 2; -} -div.qindex a -{ - color: white; -} - -/* Hide the doxygen logo */ -.footer { display: none; } - -/* Don't let pre elements create a minimum width on the right bar */ -.fish_right_bar pre { white-space:pre-wrap; } - -/* Adjust list */ -.fish_left_bar ul { - padding-left: 27px; - padding-right: 10px; -} -.fish_left_bar ul li { margin-bottom: 5px; } - -/* Tighter lists for the little (command) bar */ -.fish_left_little ul li { margin-bottom: 0; } - -/* Adjust sublists */ -.fish_left_bar ul ul { padding-left: 17px; } -.fish_left_bar ul ul li { margin-bottom: 0; } - -/* Link hover */ -.fish_left_bar a:hover { - text-decoration: none; - background-color: inherit; - color: #99BBFF; -} - -/* Horizontal bar */ -hr { - height: 1px; - border: 0; - background-color: #AAA; -} - -</style> -</head> -<body> - -<div class="qindex"> - - <a class="qindex" href="http://fishshell.com/"><tt>fish</tt> shell</a> -| - <a class="qindex" href="index.html">Documentation</a> -| - <a class="qindex" href="tutorial.html">Tutorial</a> -| -<a class="qindex" href="design.html">Design</a> -| -<a class="qindex" href="commands.html">Commands</a> -| -<a class="qindex" href="faq.html">FAQ</a> -| -<a class="qindex" href="license.html">License</a> - -</div> - |
