Interactive Documentation

Help Builtin

The help builtin is used to display and traverse shed's documentation interactively. When executed with no argument, it will open the main help index page.

Navigation

If given a topic like help {topic}, it will interpret the given topic like so:

1. if topic is an absolute or relative path to an existing file, that file is opened directly.
2. Otherwise, each directory in SHED_HPATH is scanned for a file whose stem (filename without extension) starts with topic. The first match wins.
3. if no filename matches, the help pages included with shed are scanned the same way. (those start with help/)
4. If still no match, every page is searched for *tag* markers that match topic. The highest scoring tag determines which page opens and where the pager lands on that page.

The help pager has common keybindings for existing pagers like less:

• j / Down - Scroll down one line
• k / Up - Scroll up one line
• d / PageDown - Scroll down one page
• u / PageUp - Scroll up one page
• g - Jump to the top of the page
• G - Jump to the bottom of the page
• q - Quit the pager
• /{pat} - Search for the next occurrence of pat in the page
• ?{pat} - Search for the previous occurrence of pat in the page
• n - Repeat the last search in the same direction
• N - Repeat the last search in the opposite direction

Each page contains cross-reference links to other pages/tags that can be used to quickly jump to other topics. These links can be clicked on using the mouse, or navigated to by entering "hint mode" with Tab. After pressing Tab, letters in brackets will appear next to all visible links. Pressing the letter next to the link will follow the link. If you have navigated to multiple pages, h and l can be used to move forward and backward through them.

Markup Language

Help pages use a simple markup language inspired by vim's helpfile format. All markers are paired: an opening character introduces a styled run, and a matching character closes it. Markers only activate when the surrounding text makes them unambiguous (e.g. a * followed by whitespace stays a literal asterisk).

• *tag* - Searchable tag. Becomes the target of help {tag} lookups. Rendered bold yellow.
• |reference|/|ref|(reference) - Cross-reference link to another help page. When the |...|(...) form is used, the left side is used for display and the right side is used for the link target. Rendered bold cyan.
• code - Inline code or literal command. Rendered in green.
• #header# - Header text. Rendered bold magenta.
• {keyword}/[keyword] - Word highlighting. Rendered italic.
• ~~~...~~~ - Raw block. Everything between the triple tildes is rendered literally, with no styling or markup. Useful for including code blocks or other preformatted text.