People regularly ask how to make abbreviations global (i.e., private to
a fish session) rather than universal. So explain how to do so in the
`abbr` man page.
Fixes#3446
After implementing `builtin fish_realpath` it was noticed that it did
not behave like GNU `realpath` without options. Which is super annoying
since that was the whole point of implementing the command. Major
failure on my part since I wrote the unit tests to match the behavior of
the existing `wrealpath()` function that I simply exposed as a builtin
command. Rather than actually verifying it behaved in a manner
compatible with GNU realpath.
Also, while the decision to call the builtin `fish_realpath` seemed to
make sense at the time of the original commit further reflection has
shown that to be a silly, idiosyncratic, thing to have done. So rename
it to simply `realpath`.
Fixes 3400
This adds a flag to the `history search` command to limit the number of
matching entries to the first "n". The default is unlimited. This is
mostly useful in conjunction with aliases (i.e., functions) that are
intended to report the "n" most recent matching history entries without
piping the result through the user's pager.
Fixes#3244
This deprecates the use of long options for history sub-commands (e.g.,
`history --delete`) in favor of proper sub-commands (e.g., `history
delete`). It also eliminates the short options for those sub-commands.
Also change option processing to allow options anywhere on the command
line to match how the vast majority of fish builtins handle flags.
Replace --with-time with --show-time.
Fixes#3367
Update history docs.
Note - the omission of a mention of timezone was intentional. These were recorded as naive timestamps lacking timezone information in the first place.
Improves the grouping of multiline history entries
by sepearating the timestamps and history entires onto seperate lines.
Use wcsftime() Saves us a conversion, might as well.
The previous solution would not erase the previous bindings if
fish_vi_key_bindings was called with a mode argument. So if the user
switched to vi with a different initial mode, they'd keep their previous
bindings also.
Supersedes e89057b.
The vi-bindings function would unconditionally erase all bindings,
making it impossible to call it last. This would disable the
mode-indicator (and in future also the cursor).
Make it so any argument to fish_vi_key_bindings stops it from erasing
bindings.
It would also be possible to demand an argument to erase (or to erase as
a separate step). but the usual case seems to be _switching_ to a set of bindings.
Implementing the --shadow-builtin flag has proven to be highly controversial.
Revert the introduction of that flag to the `function` command. If someone
shoots themselves in the foot by redefining a builtin as a function that's
their problem and not our responsibility to protect them from doing so.
Fixes#3319
Fixes fish-shell/fish-site/issues/34.
These make the inline commands illegible on Android Chrome:
respectively, overlapped with other text, and smaller than the body
text.
The recent change to reconcile the history builtin command and function
broke an undocumented behavior of `history --delete`. This change
reinstates that behavior. It also adds an explicit `--exact` search mode
for the `--search` and `--delete` subcommands.
Fixes#3270
This was erroneously omitted from the previous commit.
Now backspace in insert mode does backward-delete-char, in default mode
backward-char (i.e. no deleting, just moving). This is consistent with vim.
This undoes the inheritance since it shared too much.
The idea here is to share bindings that aren't something the editors we're inspired by do - there's no "execute" in vi.
The basic editing and moving bindings are now vi-style in vi-mode and emacs-style in default mode.
Update docs for "brblack", "brwhite" existing.
We no longer mention colors like grey, brown and purple, which are aliases
for yellow, magenta, white/black. The color names still work but there
isn't a good argument for there being two ways to do that: especially in
the age of 24-bit terminals where one might expect yellow and brown or
magenta and purple to actually be different colors.
Copyedit rest of document for inaccuracies, strange advice, brevity (a lot
of "you" pronouns, for example.)
Document the color fallback feature (set_color 313554 blue) that's been
present quite a while.
The `set_color normal` text had a comment that caused
the example to wrap to the next line in an 80 column window.
Shorten the comment so the example fits on one line.
This fixes several problems with how the builtin `history` command handles
arguments. It now complains and refuses to do anything if the user specifies
incompatible actions (e.g., `--search` and `--clear`). It also fixes a
regression introduced by previous changes with regard to invocations that
don't explicitly specify `--search` or a search term.
Enhances the history man page to clarify the behavior of various options.
This change is already far larger than I like so unit tests will be added
in a separate commit.
Fixes#3224.
Note: This fixes only a couple problems with the interactive `history
--delete` command in the `history` function. The main problem will be
dealt with via issue #31.
Restores erroneous changes to lexicon_filter and changes to doc_src/ pages. Done by hand to ensure version history.
Fixes display of % when misinterpreted by Doxygen.
Make `fish_indent`, `fish_key_reader` and `fish` recognize and assign
the same meaning to the `-d` and `-D` flags. Also, fix some errors and
stylistic issues in the associated man pages.
Fixes#3191
The previous commit to add a `--with-timestamp` flag to the `history` command
caused me to notice the history function didn't recognize the new long option.
Neither did it recognize the short options for the builtin command. This
change fixes both of those issues.
This change allows the user to specify the script name on the CLI in addition
to being redirected from stdin. It also adds a `-w` flag to write the modified
script to the original file.
This change does several things. First, and most important, it allows
dumping the "n" most recent stack frames on each debug() call. Second,
it demangles the C++ symbols. Third, it prepends each debug() message
with the debug level.
Unrelated to the above I've replaced all `assert(!is_forked_child());`
statements with `ASSERT_IS_NOT_FORKED_CHILD()` for consistency.
It's currently too easy for someone to bork their shell by doing something
like `function test; return 0; end`. That's obviously a silly, contrived,
example but the point is that novice users who learn about functions are
prone to do something like that without realizing it will bork the shell. Even
expert users who know about the `test` builtin might forget that, say, `pwd`
is a builtin.
This change adds a `--shadow-builtin` flag that must be specified to
indicate you know what you're doing.
Fixes#3000
The original `key_reader` program was useful but didn't do much that `xxd`
or `od -tx1z` didn't do. Furthermore, it wasn't built and installed by
default. This change adds features that make it superior to those programs
for decoding interactive key presses and makes it a first-class citizen
like the `fish_indent` program that is always available.
Fixes#2991
This makes it easy for the user to request floating point output with the
desired number of digits after the decimal point (not to be confused with
significant digits).
Note that this is just a thin wrapper so someone can say `math -s3 10 / 3`
rather than `math "scale=3; 10 /3"`.
Resolves#1643
* Add missing color definitions to __fish_init_1_50_0 reset.
The values where determined by inspecting the values of:
* fish_color_end
* fish_color_user
* fish_color_host
after resetting the color theme via fish_config.
* Add documentation for fish_color_user and fish_color_host.
I noticed that Doxygen was also complaining about the "<asis>" and "<bs>"
tags. So convert those to the backslash form like we did for "<outp>" in the
previous commit.
Doxygen has been warning that `<outp>` and `</outp>` are not valid XML/HTML commands since commit cb6d5d76 on 20016-04-04. That's primarily because there is at present no way to tell Doxygen to recognize new XML/HTML tags. The actual errors look like this:
```
.../string.doxygen:187: warning: Unsupported xml/html tag </outp> found
```
I hate build errors since they a) cause needless concern, and b) make it harder to notice when I've introduced a new error. So switch from XML/C## style markup to Doxygen style markup for the "outp" annotation.
Modify `fish_indent` to emit redirections without a space before the target of
the redirection; e.g., "2>&1" rather than "2>& 1" as the former is clearer to
humans.
Fixes#2899
I didn't notice when I merged commit cb6d5d76c8
by thebespokepixel.com that it removed the explicit wrapping in the `string`
man page. That makes `man string` harder to read so reinstate the explicit
wrapping.
- Add options to the autotools build to set the path for the "vendor"
or "extra" configuration snippets, functions and completions
directories.
- Remove the vendor_completions directory from the Xcode build, as
these are relocatable and compiling the paths in does not make sense.
This allows packaging tools like Homebrew and Nix to use a common
directory outside of the main prefix for third-party completions, and
to make these available for programmatic discovery through `pkg-config`.
Closes#2113
Closes#2699
Fixes issues with:
* 'string' function synopsis
* Redirection display issues
* Better file & path detection
* Rendering of % & @ chars in both html and man
* @ symbol in tutorial
Improves robustness by implementing an @EOL marker to prevent hold buffer dumping extra chars after the end of an expression.
Added new '{{' and '}}' meta-chars for when you want curly braces in a regexp that was previously tripping up the lexicon.
Improve man/html presentation consistency for
* string
* printf
* prompt_pwd
* type
Use cli-styling for 'practical' examples.
Add <bs> tag for presenting content with preceding backslash.
Signed-off-by: Mark Griffiths <mark@thebespokepixel.com>
The existing implementation grows the $dirprev array without bounds. Besides
causing what would appear to be a memory leak it also makes the nextd and
prevd commands more expensive than they need to be. It also makes it harder to
create a useful "menu" cd command.
In addition to implementing a reasonable limit on the size of the $dirprev
array I've reformatted the code using fish_indent.
Update the documentation to include mentions of the $dirprev and $dirnext
variables as well as the limit on how much directory history is kept.
Fixes 2836
The swap-selection-start-stop function goes to the other end of the highlighted text, the equivalent of `o' for vim visual mode.
Add binding to the swap-selection-start-stop function, `o' when in visual
mode.
Document swap-selection-start-stop, begin-selection, end-selection, kill-selection.
We silently upgrade existing abbreviations and change the separator when
saving.
This does not yet warn when the user is using the old syntax.
Resolves#2051
This narrows the range of Unicode codepoints fish reserves for its own
use from U+E000 thru U+F8FE (6399 codepoints) to U+F600 thru U+F73F (320
codepoints). This is still not ideal since fish shouldn't be using any
Unicode private-use codepoints but it's a step in the right direction.
This partially addresses issue #2684.
This allows "vendors" (i.e. third-party upstreams interested in
supporting fish) to add auto-loaded functions and eager-loaded
configuration "snippets", while still allowing both the user and the administrator to
fully override all of that.
This has been inspired by systemd's configuration hierarchy, and implements a similar scheme
whereby files with the same name in higher-ranking directories override files in lower-ranking ones.
Fixes#1956
Expand globs to zero arguments (nullglob) only for set, for and count.
The warning about failing globs, and setting the accompanying $status,
now happens regardless of mode, interactive or not.
It is assumed that the above commands are the common cases where
nullglob behaviour is desirable.
More importantly, doing this with `set` is a real feature enabler,
since the resulting empty array can be passed on to any command.
The previous behaviour was actually all nullglob (since commit
cab115c8b9), but this was undocumented;
the failglob warning was still printed in interactive mode,
and the documentation was bragging about failglob behaviour.
This changes the default escape timeout for the default keybindings (emacs
mode) to 300ms and the default for vi keybindings to 10ms.
I couldn't resist fixing a few nits in the fish_vi_key_bindings.fish file
since I was touching it to set the escape timeout.
This fixes all but one of the warnings documented in issue #2685. The
sole remaining warning is from the
string split '' abc
example in doc_src/string.txt. That example results in the man page
displaying
string split {} abc
I leave it to someone else to fix that problem (I'll open an issue
specifically for it since it took some effort to track down the source
of the warning).
Resolves issue #2685.
This is meant to make it clear that fish cannot control the terminal
window background color. It also augments the set_color documentation to
describe how it decides which color the terminal can display.
Resolves#2421.
Resolves#2184.
The random builtin command may or may not produce values with a truly
random distribution. So make the documentation reflect that reality. Also,
make the command consistent with similar shells (e.g., bash, zsh) which
produce a range of [0..32767].
Resolves issue #1272.
* Add a note to the `--wrap` docs saying that wrapping only works when
specifying completions for commands, not for paths.
* Add more info about how `--arguments` is handled.
* Indicate which options can be repeated in the usage lines.
* Reorder the options in usage slightly to group better.
* Reorder the option descriptions to match the order as seen in usage.
* Update some of the option descriptions.
* Fix the documentation for -C to show that it must be `-CSTRING`
instead of `-C STRING`.
* Document the behavior of `-C` with no argument.
* Tweak some of the explanatory text after the option list.
* Delete `--authoritative` and `--unauthoritative` from the
documentation entirely. Those options appear to not actually do
anything in the new parser.
The special token "normal" should not be in the basic sixteen color table
because a) it is not a color, and b) it is special cased with the result of
resetting the terminal colors (usually via a ANSI X3.64 CSI [0m sequence).
This adds support for the ANSI x3.64 "bright" colors in the basic sixteen
color palette. This is especially useful when trying to use the base colors
as a background color. The "bright" variants tend to be more useful as
background colors compared to the non-bright variants.
This also fixes a bug in so far as palette number 7 is actually grey and
not white whereas palette number 15 is white. At least on the terminal
emulators on which I've tested this change (Ubuntu xterm & uxterm, Mac
OS X Terminal & iTerm2).
Resolves issue #1464.
This reduces code duplication and adds some previously unavailable
bindings that don't quite _violate_ the vi-principle (like
prevd-or-backward-word on alt-left) and matches other "impure" bindings
like \cf for forward-word (a quite emacs-ish binding) we already have.
Fixes#2412Fixes#2472Fixes#2255
This adds the new builtin 'string' which supports various string
manipulation and matching algorithms, including PCRE based regular
expressions.
Fixes#2296
Squashed commit of the following:
commit 4c3eaeb6e57d76463e9683c327142b0aeafb92b8
Author: ridiculousfish <corydoras@ridiculousfish.com>
Date: Sat Sep 12 12:51:30 2015 -0700
Remove testdata and doc dirs from pcre2 source
commit b2a8b4b50f2398b204fb72cfe4b5ba77ece2e1ab
Merge: 11c8a477974aab
Author: ridiculousfish <corydoras@ridiculousfish.com>
Date: Sat Sep 12 12:32:40 2015 -0700
Merge branch 'string' of git://github.com/msteed/fish-shell into string-test
commit 7974aab6d3
Author: Michael Steed <msteed@saltstack.com>
Date: Fri Sep 11 13:00:02 2015 -0600
build pcre2 lib only, no docs
commit eb20b43d2d
Merge: 1a09e705f519cb
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Sep 10 20:00:47 2015 -0600
Merge branch 'string' of github.com:msteed/fish-shell into string
commit 1a09e709d0
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Sep 10 19:58:24 2015 -0600
rebase on master & address the fallout
commit a0ec9772cd
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Sep 10 19:26:45 2015 -0600
use fish's wildcard_match() for glob matching
commit 64c25a01e3
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Aug 27 08:19:23 2015 -0600
some fixes from review
- string_get_arg_stdin(): simplify and don't discard the argument when
the trailing newline is absent
- fix calls to pcre2 for e.g. string match -r -a 'a*' 'b'
- correct test for args coming from stdin
commit ece7f35ec5
Author: Michael Steed <msteed68@gmail.com>
Date: Sat Aug 22 19:35:56 2015 -0600
fixes from review
- Makefile.in: restore iwyu target
- regex_replacer_t::replace_matches(): correct size passed to realloc()
commit 9ff7477a92
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Aug 20 13:08:33 2015 -0600
Minor doc improvements
commit baf4e096b2
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 19 18:29:02 2015 -0600
another attempt to fix the ci build
commit 896a2c2b27
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 19 18:03:49 2015 -0600
Updates after review comments
- make match/replace without -a operate on the first match on each
argument
- use different exit codes for "no operation performed" and errors, as
grep does
- refactor regex compile code
- use human-friendly error messages from pcre2
- improve error handling & reporting elsewhere
- add a few tests
- make some doc fixes
- some simplification & cleanup
- fix ci build failure (I hope)
commit efd47dcbda
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 12 00:26:07 2015 -0600
fix dependencies for parallel make
commit ed0850e2db
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 23:37:22 2015 -0600
Add missing pcre2 files + .gitignore
commit 9492e7a7e9
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 22:44:05 2015 -0600
add pcre2-10.20 and update license.hdr
commit 1a60b93371
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 22:41:19 2015 -0600
add string builtin files
- string builtin source, tests, & docs
- changes to configure.ac & Makefile.in
commit 5f519cb2a2
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Sep 10 19:26:45 2015 -0600
use fish's wildcard_match() for glob matching
commit 2ecd24f795
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Aug 27 08:19:23 2015 -0600
some fixes from review
- string_get_arg_stdin(): simplify and don't discard the argument when
the trailing newline is absent
- fix calls to pcre2 for e.g. string match -r -a 'a*' 'b'
- correct test for args coming from stdin
commit 45b777e4dc
Author: Michael Steed <msteed68@gmail.com>
Date: Sat Aug 22 19:35:56 2015 -0600
fixes from review
- Makefile.in: restore iwyu target
- regex_replacer_t::replace_matches(): correct size passed to realloc()
commit 981cbb6ddf
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Aug 20 13:08:33 2015 -0600
Minor doc improvements
commit ddb6a2a8fd
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 19 18:29:02 2015 -0600
another attempt to fix the ci build
commit 1e34e3191b
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 19 18:03:49 2015 -0600
Updates after review comments
- make match/replace without -a operate on the first match on each
argument
- use different exit codes for "no operation performed" and errors, as
grep does
- refactor regex compile code
- use human-friendly error messages from pcre2
- improve error handling & reporting elsewhere
- add a few tests
- make some doc fixes
- some simplification & cleanup
- fix ci build failure (I hope)
commit 34232e152d
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 12 00:26:07 2015 -0600
fix dependencies for parallel make
commit 00d7e78169
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 23:37:22 2015 -0600
Add missing pcre2 files + .gitignore
commit 4498aa5f57
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 22:44:05 2015 -0600
add pcre2-10.20 and update license.hdr
commit 290c58c72e
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 22:41:19 2015 -0600
add string builtin files
- string builtin source, tests, & docs
- changes to configure.ac & Makefile.in
When declaring a function using the function "function", the options must follow, not precede, the function name.
The examples demonstrate this syntax, but the synopsis previously showed the options preceding the name.
In FAQ:
> I'm seeing weird output before each prompt when using screen. What's wrong?
The command provided is
echo 'function fish_title;end' > ~/.config/fish/config.fish
Using `>` will overwrite current config.fish.
We should use `>>` instead.
Support for space-delimited abbreviations was added to the expansion
parser in fbade198; this commit extends that support to the user-facing
tools, and documents the space-separated behaviour. Equals-delimited
abbreviations are expected to be removed before the next release.
Work on #731.
--inherit-variable takes a variable name and snapshots its current
value. When the function is executed, it will have a local variable with
this value already defined. Printing the function source will include
synthesized `set -l` lines for the values.
This is primarily useful for functions that are created on the fly, such
as in `psub`.
Making `true` into a builtin is a significant optimization to `while
true` loops. As long as `true` is a builtin, we may as well make `false`
builtin as well (despite the fact that it's not typically executed in a
loop).
Apparently, in zsh, Meta+H can be used to display the manpage for
the current command. This commit adds this zsh feature to fish shell.
The F1 keybinding is left, although it's now secondary according to
fish help, as some terminal emulators don't let the user press F1 key.
re: fish-shell/fish-shell@2726712e01
As this is rendering ok in Firefox, this version should pickup the best
fonts for most browser/os variants based on 'font-stretch' support.
`.fish_left_bar` should be condensed, the main body font shouldn't.
Binds with the same sequence in multiple modes was not working right.
Fix up the implementation to propagate modes everywhere as necessary.
This means that `bind` will properly list distinct binds with the same
sequence, and `bind -e` will take mode into account properly as well.
Note that `bind -e seq` now assumes the bind is in the default bind
mode, whereas before it would erase the first binding with that sequence
regardless of mode.
`bind -e -a` still erases all binds in all modes, though `bind -M mode
-e -a` still only erases all binds in the selected mode.
<em> used to represent something else, but as far as I can tell, all
uses of <em> in the documentation today actually represent text that's
supposed to be visibly different. Notably, the documentation on
supported escapes uses <em> to indicate the letters that are a
placeholder for e.g. a hex digit, as opposed to being a literal
character.
The `--null` flag to `read` makes it split incoming lines on NUL instead
of newlines. This is intended for processing the output of a command
that uses NUL separators (such as `find -print0`).
Fixes#1694.
This font, at least under Kubuntu 14.04 and Firefox I use is rather
ugly. Anti-aliasing is wrong, and the spaces between letters are
rather random. It makes reading the documentation headings and table
of contents harder than it needs to be.
Those issues don't happen with DejaVu Sans.
This includes:
- Fixing some typos and misspellings
- Being consistent with pronouns (she/he)
- Hyphenating "built-in" and "command-line" where appropriate
Widened 'Commands' menu + fish logo
fish logo added to FAQ menu
'Commands' menu content aligned with Docs menu
'FAQ' menu content aligned and made 1st order as all entires are long
and wrap.
Major documentation cleanup and update.
- Fixes Issue #1557
- Moves entire documentation to Markdown format. Much simpler.
- Fully supports Doxygen 1.8.7+
- All documentation targets updated: user_doc, share/man, doc and
doc/refman.pdf.
- Tested across Ubuntu, CentOS and Mac OS.
See doc_src/FORMATTING.md for in depth rationale and style guide.
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.
Completely fixes#1557 and the underlying Doxygen changes that caused
it. Should make fish docs simpler and more robust, more consistent and
generally prettier.
todo:
- trap unmarked text as arguments in context
- test & fix sed portability - see in particular. (so far tested on BSD
(Mac) and GNU sed).
- test Makefile changes
- last round of aesthetic changes and getting that ascii fish in there…
Addresses issue #1557 as well as fixing many typos, HTML errors and
inconsistencies. Also introduces automatic syntax colouring and enables
new documentation to be written in Markdown. TODO fix Tutorial.
Rework for Doxygen >1.8. Moved large parts of the documentation to a
simplified format, making use of Markdown enhancements and fixing bad
long options.
IFS is used for more than just the read builtin. Setting it to the empty
string also disables line-splitting in command substitution, and it's
done this for the past 7 years. Some day we may have a better way to do
this, but for now, document the current solution.
The docs claimed that the $HOME and $USER variables could only be
changed by the root user. This is untrue. They can be changed by
non-root users as well.
Add the --wraps option to 'complete' and 'function'. This allows a
command to (recursively) inherit the completions of a wrapped command.
Fixes#393.
When evaluating a completion, we inspect the entire "wrap chain" for a
command, i.e. we follow the sequence of wrapping until we either hit a
loop (which we silently ignore) or the end of the chain. We then
evaluate completions as if the wrapping command were substituted with
the wrapped command. Currently this only works for commands, i.e.
'complete --command gco --wraps git\ checkout' won't work (that would
seem to encroaching on abbreviations anyways). It might be useful to
show an error message for that case.
The commandline builtin reflects the commandline with the wrapped
command substituted in, so e.g. git completions (which inspect the
command line) will just work. This sort of command line munging is
also performed by 'complete -C' so it's not totally without precedent.
'alias will also now mark its generated function as wrapping the
'target.
Completely fixes#1557 and the underlying Doxygen changes that caused
it. Should make fish docs simpler and more robust, more consistent and
generally prettier.
todo:
- trap unmarked text as arguments in context
- test & fix sed portability - see in particular. (so far tested on BSD
(Mac) and GNU sed).
- test Makefile changes
- last round of aesthetic changes and getting that ascii fish in there…
Addresses issue #1557 as well as fixing many typos, HTML errors and
inconsistencies. Also introduces automatic syntax colouring and enables
new documentation to be written in Markdown. TODO fix Tutorial.
Rework for Doxygen >1.8. Moved large parts of the documentation to a
simplified format, making use of Markdown enhancements and fixing bad
long options.
