# Mediante help

This folder is the user-facing documentation: one page per dialog or topic,
linked from the dialog it explains ("Help ↗" in its title bar) and shown in
the Help window (Help ▸ Main Topics, or **F1**, which opens the page of the
window in front). It is not `docs/`, which holds research and design notes for
development.

**How the pieces divide.** A control's *tooltip* says what it does, in one
line. The help page says why it exists, what it costs, and what it matches in
OctaMED or MED SoundStudio. A dialog carries neither kind of paragraph in its
body: text in the body is only for things that change as you use it (a count,
a warning that applies right now).

`docs/settings.md` is the settings reference and predates this folder; it
follows the same rule and stays where it is, because Settings and the Help
menu link to it there.

## Pages

| Page | Opened from |
|---|---|
| [Block Properties](block-properties.md) | Block ▸ Block Properties… ▸ Help ↗, or F1 in it |
| [Instrument Properties](instrument-properties.md) | Instrument ▸ Instrument Properties… ▸ Help ↗, or F1 in it |
| [Sample editor](sample-editor.md) | The Sample tab of Instrument Properties; linked from its page |
| [Song Properties](song-properties.md) | Song ▸ Song Properties… ▸ Help ↗, or F1 in it |
| [Song Tempo and Tempo Operations](song-tempo.md) | Song ▸ Song Tempo… or Tools ▸ Conversions ▸ Tempo Operations… ▸ Help ↗, or F1 in either |
| [Plugins](plugins.md) | Song ▸ Plugins… ▸ Help ↗, or F1 in it |
| [List windows](list-windows.md) | Song ▸ Playing Sequence… / Block List… / Instrument List… ▸ Help ↗, or F1 in them |
| [Find & Replace](find-replace.md) | Edit ▸ Find and Replace… ▸ Help ↗, or F1 in it |
| [Transpose](transpose.md) | Tools ▸ Transpose… ▸ Help ↗, or F1 in it |
| [Generate Slides](generate-slides.md) | Tools ▸ Generate Slides… ▸ Help ↗, or F1 in it |
| [Generate Volume Echo](generate-volume-echo.md) | Tools ▸ Generate Volume Echo… ▸ Help ↗, or F1 in it |
| [Module Annotation](module-annotation.md) | View ▸ Module Annotation… ▸ Help ↗, or F1 in it |
| [CDP](cdp.md) | The sample editor's Commands ▸ Effects ▸ CDP effect… and Commands ▸ Generate ▸ With CDP… ▸ Help ↗, or F1 in either |
| [Shortcut Keys](shortcut-keys.md) | Help ▸ Shortcut Keys… ▸ Help ↗, or F1 in it |
| [WAM Sample Effect](wam-sample-effect.md) | Instrument ▸ Instrument Properties… ▸ Sample ▸ Commands ▸ Effects ▸ WAM effect… ▸ Help ↗, or F1 in it |
| [Vocoder](vocoder.md) | Instrument ▸ Instrument Properties… ▸ Sample ▸ Commands ▸ Effects ▸ Vocoder… ▸ Help ↗, or F1 in it |
| [Restore](restore.md) | Instrument ▸ Instrument Properties… ▸ Sample ▸ Commands ▸ Effects ▸ Declip… or Dequantise… ▸ Help ↗, or F1 in it |
| [Settings reference](../docs/settings.md) | Settings ▸ Settings reference ↗, Help ▸ Settings Reference… |

## Writing a page

- Name the page after the dialog, in kebab case: `block-properties.md`.
- Start with what the dialog is for, in two or three sentences.
- Then one section per field or group of fields, in the order they appear.
- Say what OctaMED or MED SoundStudio does where Mediante matches or differs.
- Markdown, in the subset the Help window draws (`js/help-viewer.js`):
  headings, paragraphs, lists (nested by indent), pipe tables, block quotes,
  fenced code, rules; bold, italic, code spans and links. No HTML — it is
  shown as text. A page stays readable as plain text too ("As text ↗").
- Link another page with a relative path (`block-properties.md`,
  `../docs/settings.md#resampler`); it opens in the Help window. A new page
  must also be added to the viewer's list (`ALLOWED` in `js/help-viewer.js`)
  if it is not in `help/`.