Merge pull request #1212 from ElectricKeet/doc-general

Doc updates for 0.6pre6.

doc/2-interface/menu-bar.md

@@ -8,6 +8,7 @@ the menu bar allows you to select five menus: file, edit, settings, window and h
 - **open...**: opens the file picker, allowing you to select a song to open.
 - **open recent**: contains a list of the songs you've opened before.
   - **clear history**: this option erases the file history.
+
 - **save**: saves the current song.
   - opens the file picker if this is a new song, or a backup.
 - **save as...**: opens the file picker, allowing you to save the song under a different name.
@@ -29,12 +30,14 @@ the menu bar allows you to select five menus: file, edit, settings, window and h
     - Arcade (YM2151 + SegaPCM 5-channel compatibility)
     - Neo Geo CD (DefleMask 1.0+)
   - only use this option if you really need it. there are features which DefleMask does not support, like some effects and FM macros, so these will be lost.
+
 - **export audio...**: export your song to a .wav file. see next section for more details.
 - **export VGM...**: export your song to a .vgm file. see next section for more details.
 - **export ZSM...**: export your song to a .zsm file. see next section for more details.
   - only available when there's a YM2151 and/or VERA.
 - **export command stream...**: export song data to a command stream file. see next section for more details.
   - this option is for developers.
+  
 - **add chip...**: add a chip to the current song.
 - **configure chip...**: set a chip's parameters.
   - for a list of parameters, see [7-systems](../7-systems/README.md).
@@ -42,6 +45,7 @@ the menu bar allows you to select five menus: file, edit, settings, window and h
   - **Preserve channel positions**: enable this option to make sure Furnace does not auto-arrange/delete channels to compensate for differing channel counts. this can be useful for doing ports, e.g. from Genesis to PC-98.
 - **remove chip...**: remove a chip.
   - **Preserve channel positions**: same thing as above.
+
 - **restore backup**: restore a previously saved backup.
   - Furnace keeps up to 5 backups of a song.
   - the backup directory is located in:
@@ -49,6 +53,7 @@ the menu bar allows you to select five menus: file, edit, settings, window and h
     - macOS: `~/Library/Application Support/Furnace/backups`
     - Linux/other: `~/.config/furnace/backups`
   - this directory grows in size as you use Furnace. remember to delete old backups periodically to save space.
+
 - **exit**: I think you know what this does.
 
 ## export audio
@@ -131,6 +136,7 @@ it's not really useful, unless you're a developer and want to use a command stre
 
 - **undo**: reverts the last action.
 - **redo**: repeats what you undid previously.
+
 - **cut**: moves the current selection in the pattern view to clipboard.
 - **copy**: copies the current selection in the pattern view to clipboard.
 - **paste**: inserts the clipboard's contents in the cursor position.
@@ -147,11 +153,16 @@ it's not really useful, unless you're a developer and want to use a command stre
   - if the selection is tall, it will select the entire column.
   - if a column is already selected, it will select the entire channel.
   - if a channel is already selected, it will select the entire pattern.
+
 - **operation mask**: this is an advanced feature. see [this page](../3-pattern/opmask.md) for more information.
 - **input latch**: this is an advanced feature. see [this page](../3-pattern/inputlatch.md) for more information.
+
 - **note/octave up/down**: transposes notes in the current selection.
+
 - **values up/down**: changes values in the current selection by ±1 or ±16.
+
 - **transpose**: transpose notes or change values by a specific amount.
+
 - **interpolate**: fills in gaps in the selection by interpolation between values.
 - **change instrument**: changes the instrument number in a selection.
 - **gradient/fade**: replace the selection with a "gradient" that goes from the beginning of the selection to the end.
@@ -163,17 +174,22 @@ it's not really useful, unless you're a developer and want to use a command stre
 - **randomize**: replaces the selection with random values.
   - does not affect the note column.
 - **invert values**: `00` becomes `FF`, `01` becomes `FE`, `02` becomes `FD` and so on.
+
 - **flip selection**: flips the selection so it is backwards.
 - **collapse/expand amount**: allows you to specify how much to collapse/expand in the next options.
 - **collapse**: shrinks the selected contents.
 - **expand**: expands the selected contents.
+
 - **collapse pattern**: same as collapse, but affects the entire pattern.
 - **expand pattern**: same as expand, but affects the entire pattern.
+
 - **collapse song**: same as collapse, but affects the entire song.
   - it also changes speeds and pattern length to compensate.
 - **expand song**: same as expand, but affects the entire song.
   - it also changes speeds and pattern length to compensate.
+
 - **find/replace**: opens the Find/Replace window. see [this page](../3-pattern/find-replace.md) for more information.
+
 - **clear**: allows you to mass-delete things like songs, instruments and the like.
 
 # settings
@@ -202,9 +218,11 @@ it's not really useful, unless you're a developer and want to use a command stre
 - **chip manager**: shows/hides the Chip Manager window.
 - **compatibility flags**: shows/hides the Compatibility Flags window.
 - **song comments**: shows/hides the Song Comments window.
-- **instrument editor**: shows/hides the Instrument Editor.
+
+- **instrument editor**: shows/hides the Instrument Editor
 - **wavetable editor**: shows/hides the Wavetable Editor.
 - **sample editor**: shows/hides the Sample Editor.
+
 - **play/edit controls**: shows/hides the Play/Edit Controls.
 - **piano/input pad**: shows/hides the Piano/Input Pad window.
 - **oscilloscope (master)**: shows/hides the oscilloscope.

doc/3-pattern/effects.md

@@ -7,17 +7,15 @@ however, effects are continuous, which means you only need to type it once and t
 ## volume
 
 - `0Axy`: **Volume slide.**
-  - If `x` is 0 then this is a slide down.
-  - If `y` is 0 then this is a slide up.
-- `F8xx`: **Single tick volume slide up.**
-- `F9xx`: **Single tick volume slide down.**
-- `F3xx`: **Fine volume slide up.** 64× slower than `0Axy`.
-- `F4xx`: **Fine volume slide down.** 64× slower than `0Axy`.
-- `FAxy`: **Fast volume slide.** 4× faster than `0Axy`.
-  - If `x` is 0 then this is a slide down.
-  - If `y` is 0 then this is a slide up.
+  - If `x` is 0 then this slides volume down by `y` each tick.
+  - If `y` is 0 then this slides volume up by `x` each tick.
+- `FAxy`: **Fast volume slide.** same as `0Axy` above but 4× faster.
+- `F3xx`: **Fine volume slide up.** same as `0Ax0` but 64× slower.
+- `F4xx`: **Fine volume slide down.** same as `0A0x` but 64× slower.
+- `F8xx`: **Single tick volume slide up.** adds `x` to volume on first tick only.
+- `F9xx`: **Single tick volume slide down.** subtracts `x` from volume on first tick only.
 
-- `07xy`: **Tremolo.** changes volume to be "wavy" with a sine LFO. `x` is the speed, while `y` is the depth.
+- `07xy`: **Tremolo.** changes volume to be "wavy" with a sine LFO. `x` is the speed. `y` is the depth.
   - Tremolo is downward only.
   - Maximum tremolo depth is -60 volume steps.
 
@@ -29,21 +27,22 @@ however, effects are continuous, which means you only need to type it once and t
 - `F1xx`: **Single tick pitch slide up.**
 - `F2xx`: **Single tick pitch slide down.**
 
-- `03xx`: **Portamento.** slides the current note's pitch to the specified note.
+- `03xx`: **Portamento.** slides the current note's pitch to the specified note.  `x` is the slide speed.
   - A note _must_ be present for this effect to work.
 - `E1xy`: **Note slide up.** `x` is the speed, while `y` is how many semitones to slide up.
 - `E2xy`: **Note slide down.** `x` is the speed, while `y` is how many semitones to slide down.
+
 - `EAxx`: **Toggle legato.** while on, notes instantly change the pitch of the currrently playing sound instead of starting it over.
 - `00xy`: **Arpeggio.** after using this effect the channel will rapidly switch between semitone values of `note`, `note + x` and `note + y`.
-- `E0xx`: **Set arpeggio speed.** this sets the number of ticks between arpeggio values.
+- `E0xx`: **Set arpeggio speed.** this sets the number of ticks between arpeggio values. default is 1.
 
 - `04xy`: **Vibrato.** changes pitch to be "wavy" with a sine LFO. `x` is the speed, while `y` is the depth.
   - Maximum vibrato depth is ±1 semitone.
 - `E3xx`: **Set vibrato direction.** `xx` may be one of the following:
-  - `00`: Up and down.
+  - `00`: Up and down. default.
   - `01`: Up only.
   - `02`: Down only.
-- `E4xx`: **Set vibrato range** in 1/16th of a semitone.
+- `E4xx`: **Set vibrato range** in 1/16th of a semitone. 
 
 ## panning
 
@@ -51,15 +50,15 @@ not all chips support these effects.
 
 - `08xy`: **Set panning.** changes stereo volumes independently. `x` is the left channel and `y` is the right one.
 - `88xy`: **Set rear panning.** changes rear channel volumes independently. `x` is the rear left channel and `y` is the rear right one.
+- `81xx`: **Set volume of left channel** (from `00` to `FF`).
+- `82xx`: **Set volume of right channel** (from `00` to `FF`).
+- `89xx`: **Set volume of rear left channel** (from `00` to `FF`).
+- `8Axx`: **Set volume of rear right channel** (from `00` to `FF`).
 
 - `80xx`: **Set panning (linear).** this effect behaves more like other trackers:
   - `00` is left.
   - `80` is center.
   - `FF` is right.
-- `81xx`: **Set volume of left channel** (from `00` to `FF`).
-- `82xx`: **Set volume of right channel** (from `00` to `FF`).
-- `89xx`: **Set volume of rear left channel** (from `00` to `FF`).
-- `8Axx`: **Set volume of rear right channel** (from `00` to `FF`).
 
 ## time
 
@@ -67,12 +66,14 @@ not all chips support these effects.
 - `0Fxx`: **Set speed 2.** during alternating speeds or a groove, this sets the second speed.
 
 - `Cxxx`: **Set tick rate.** changes tick rate to `xxx` Hz (ticks per second).
-  - `xxx` may be from `000` to `3ff`.
-- `F0xx`: **Set BPM.** changes tick rate according to beats per minute.
+  - `xxx` may be from `000` to `3FF`.
+- `F0xx`: **Set BPM.** changes tick rate according to beats per minute. range is `01` to `FF`.
 
-- `0Bxx`: **Jump to order.** this can be used to loop a song.
-- `0Dxx`: **Jump to next pattern.** this can be used to shorten the current order.
-- `FFxx`: **Stop song.** stops playback and ends the song.
+- `0Bxx`: **Jump to order.** `x` is the order to play after the current row.
+  - this marks the end of a loop with order `x` as the loop start.
+- `0Dxx`: **Jump to next pattern.** skips the current row and remainder of current order.
+  - this can be used to shorten the current order.
+- `FFxx`: **Stop song.** stops playback and ends the song. `x` is ignored.
 
 ## note
 

doc/7-systems/README.md

@@ -27,6 +27,7 @@ this is a list of sound chips that Furnace supports, including effects.
 - [PC Engine/TurboGrafx-16](pce.md)
 - [PC Speaker](pcspkr.md)
 - [Philips SAA1099](saa1099.md)
+- [Pokémon mini](pokemini.md)
 - [Capcom QSound](qsound.md)
 - [Ricoh RF5C68](ricoh.md)
 - [SegaPCM](segapcm.md)

doc/7-systems/game-boy.md

@@ -2,7 +2,7 @@
 
 the Nintendo Game Boy is one of the most successful portable game systems ever made.
 
-with stereo sound, two pulse channels, a wave channel and a noise one it packed some serious punch.
+with stereo sound, two pulse channels, a wave channel and a noise channel, it packed some serious punch.
 
 # effects
 
@@ -20,3 +20,9 @@ with stereo sound, two pulse channels, a wave channel and a noise one it packed
   - `y` is the shift.
   - set to `0` to disable it.
 - `14xx`: **set sweep direction.** `0` is up and `1` is down.
+
+# links
+
+- [Gameboy sound hardware](https://gbdev.gg8.se/wiki/articles/Gameboy_sound_hardware) - detailed technical information
+
+- [GameBoy Sound Table](http://www.devrs.com/gb/files/sndtab.html) - note frequency table

doc/7-systems/pokemini.md

@@ -0,0 +1,7 @@
+# Pokémon mini
+
+the Pokémon mini is a ridiculously small handheld system from 2001. its single pulse channel has only three volume steps (full, half, and off)... but 256 pulse widths.
+
+# effects
+
+none.

doc/8-advanced/chanosc.md

@@ -1,16 +1,53 @@
 # oscilloscope (per channel)
 
-The "Oscilloscope (per channel)" dialog shows an individual oscilloscope for each channel during playback.
+the "Oscilloscope (per channel)" dialog shows an individual oscilloscope for each channel during playback.
 
 ![oscilloscope per-channel configuration view](chanosc.png)
 
-Right-clicking within the view will change it to the configuration view shown above:
-- **Columns**: Sets the number of columns the view will be split into.
-- **Size (ms)**: Sets what length of audio is visible in each oscilloscope.
-- **Center waveform**: Does its best to latch to the channel's note frequency and centers the display.
-- **Gradient**: (document this)
-- The color selector sets the waveform color. Right-clicking on it pops up an option dialog:
-  - Select between the square selector and the color wheel selector.
-  - **Alpha bar**: Adds a transparency selector.
-- The boxes below that are for selecting colors numerically by red-green-blue-alpha, hue-saturation-value-alpha, and HTML-style RGBA in hex.
-- The OK button returns from options view to regular.
+right-clicking within the view will change it to the configuration view shown above:
+- **Columns**: arranges oscilloscopes into this many columns.
+- **Size (ms)**: sets what length of audio is visible in each oscilloscope.
+- **Center waveform**: does its best to latch the waveform to the channel's note frequency and centers the display.
+- **Gradient**: see below.
+- the color selector sets the waveform color. right-clicking on it pops up an option dialog:
+  - select between the square selector and the color wheel selector.
+  - **Alpha bar**: adds a transparency selector.
+- the boxes below that are for selecting colors numerically by red-green-blue-alpha, hue-saturation-value-alpha, and HTML-style RGBA in hex.
+- **Text format**: this string determins what text is shown in the top-left of each oscilloscope. it can be any text, and the following shortcodes will be replaced with information about the channel:
+  - `%c`: channel name
+  - `%C`: channel short name
+  - `%d`: channel number (starting from 0)
+  - `%D`: channel number (starting from 1)
+  - `%i`: instrument name
+  - `%I`: instrument number (decimal)
+  - `%x`: instrument number (hex)
+  - `%s`: chip name
+  - `%S`: chip ID
+  - `%v`: volume (decimal)
+  - `%V`: volume (percentage)
+  - `%b`: volume (hex)
+  - `%%`: percent sign
+- The OK button returns from options view to the oscilloscopes.
+
+## gradient
+
+![oscilloscope per-channel gradient configuration view](chanosc-gradient.png)
+
+in this mode, the color selector is replaced by a square field onto which circular "stops" can be placed. each stop adds a soft circle of color. the resulting image is used to look up the oscilloscope color as determined by each axis.
+
+- right-click to place a stop.
+- left-click on a stop to change its color. the color selector is the same as above, with two additions:
+  - **Distance**: the size of the circle.
+  - **Spread**: the size of the solid center of the circle. increasing it fills more of the circle with the target color.
+
+- **Background**: sets background color for entire field.
+- **X Axis**: determines what the horizontal maps to, from left to right.\
+  **Y Axis**: determines what the vertical maps to, from bottom to top. these can be set to the following:
+  - **None (0%)**: stays at the left or bottom.
+  - **None (50%)**: stays at the center.
+  - **None (100%)**: stays at the right or top.
+  - **Frequency**: changes color with note frequency.
+  - **Volume**: changes color with volume.
+  - **Channel**: changes color based on channel number.
+  - **Brightness**: {{document this}}
+  - **Note Trigger**: changes color when a new note is played.