` tag, like so:
...
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
```html
: These words are underlined.
: autosuggestion.
: Matched items, such as tab completions.
: Matched items searched for, like grep results.
: Render the contents with a preceding backslash. Useful when presenting output.
: This would be shown as an error.
: This text will not be parsed for fish markup.
: This would be rendered as command/script output.
{{ and }}: Required when wanting curly braces in regular expression example.
```
### Prompts and cursors
```html
>_: 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.
```
#### Author: Mark Griffiths [@GitHub](https://github.com/MarkGriffiths)