doc de-awkwardization

doc/8-advanced/channels.md

@@ -5,8 +5,8 @@ the "Channels" dialog allows manipulation of the song's channels.
 ![channels dialog](channels.png)
 
 each channel has the following options:
-- **Visible**: uncheck the box to hide the channel from view. pattern data will be kept.
+- **Visible**: uncheck the box to hide the channel from the pattern view. pattern data will be kept.
 - crossed-arrows button: click and drag to rearrange pattern data throughout the song.
-  - note: this does _not_ move channels around within a chip! it only affects pattern data.
-- **Name** is the name displayed at the top of each channel in the tracker view.
-- to the right of that is the abbreviation used above each channel in the order view.
+  - note: this does **not** move channels around! it only moves the channel's pattern data.
+- **Name**: the name displayed at the top of each channel in the pattern view.
+- the next setting is "short name", which is displayed in the orders view and/or when a channel is collapsed.

doc/8-advanced/chanosc.md

@@ -1,25 +1,24 @@
 # oscilloscope (per-channel)
 
-the "Oscilloscope (per-channel)" dialog shows an individual oscilloscope for each channel during playback.
+the "Oscilloscope (per-channel)" windows displays several oscilloscope views (one per channel).
 
 ![oscilloscope per-channel configuration view](chanosc.png)
 
-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.
+right-clicking the view will display the configuration view shown above:
+- **Columns**: sets the amount of columns for the oscilloscope views.
+- **Size (ms)**: sets how much of a channel's output is captured for the oscilloscope view.
+- **Center waveform**: when enabled, the displayed waveforms will be centered using an auto-correlation algorithm.
 - **Automatic columns**: sets the number of columns based on the number of channels.
   - **Off**: use the Columns setting.
   - **Mode 1**: always fewer columns than rows.
   - **Mode 2**: bias slightly toward more columns.
   - **Mode 3**: always more columns than rows.
-- **Amplitude**: scales amplitude for all oscilloscopes.
-- **Gradient**: see below.
-- the color selector sets the color for all waveforms. 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:
+- **Amplitude**: scales amplitude for all oscilloscope views.
+- **Gradient**: this allows you to use a gradient for determining the waveforms' colors instead of a single color. see the gradient section for more information.
+  - if this option is off, a color selector will be displayed. right-click on it for some options:
+    - select between the square selector and the color wheel selector.
+    - **Alpha bar**: display an opacity bar.
+- **Text format**: this allows you to display some text on each oscilloscope view. the following codes may be used:
   - `%c`: channel name
   - `%C`: channel short name
   - `%d`: channel number (starting from 0)
@@ -35,27 +34,32 @@ right-clicking within the view will change it to the configuration view shown ab
   - `%V`: volume (percentage)
   - `%b`: volume (hex)
   - `%%`: percent sign
-- the OK button returns from options view to the oscilloscopes.
+
+click on OK to return to the main view.
 
 ## 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.
+when enabling the Gradient setting, a gradient view is displayed in where circular "points" can be placed.
+each point adds a color spot.
+the resulting image is used to look up the waveform's 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:
+- right-click to place a point.
+- left-click on a point to change its color:
+  - a color picker is displayed, alongside two settings.
   - **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**: currently does nothing.
-  - **Note Trigger**: changes color when a new note is played.
+  - **Spread**: the size of the solid center of the circle. increasing it fills more of the circle with the color.
+- middle-click on a point to delete it.
+
+- **Background**: sets the gradient's background color.
+- **X Axis**: determines what the horizontal axis maps to.
+- **Y Axis**: determines what the vertical axis maps to. these can be set to the following:
+  - **None (0%)**: always left or bottom
+  - **None (50%)**: always center
+  - **None (100%)**: always right or top
+  - **Frequency**: changes color with frequency
+  - **Volume**: changes color with volume
+  - **Channel**: changes color based on channel number (first channel is 0% and last is 100%)
+  - **Brightness**: currently does nothing
+  - **Note Trigger**: changes color when a new note is played

doc/8-advanced/chip-manager.md

@@ -1,15 +1,15 @@
 # chip manager
 
-the **chip manager** window does exactly what it says.
+the **chip manager** window allows you to manage chips, including adding, changing, moving or removing them.
 
 ![chip manager](chip-manager.png)
 
-**Preserve channel order**: make existing pattern data stay in place even when chips are rearranged. if turned off, pattern data will rearrange to match (the default, and usually the desired behavior).
+**Preserve channel order**: make existing pattern data stay in place even when chips are rearranged. when turned off, pattern data will be arranged to match (the default, and usually desired behavior).
 
-to move a chip around, click and drag the ![crossed-arrows](chip-manager-move.png) button to its left.
+to move a chip around, click and drag the ![crossed-arrows](chip-manager-move.png) button to the left.
 
-to replace a chip with a different one, click the **Change** button and select the replacement.
+to replace a chip with a different one, click the **Change** button. this will display the chip selector.
 
-to remove a chip entirely, click the ![X](chip-manager-remove.png) button.
+to remove a chip, click the ![X](chip-manager-remove.png) button.
 
-click a chip's name to open its options, where one can set clock rate, chip variant, and other specifics.
+click on a chip's name to open chip configuration. this allows you to change chip options, such as clock rate, chip type and so on.

doc/8-advanced/comments.md

@@ -4,4 +4,4 @@
 
 comments, credits, or any arbitrary text may be entered here. it has no effect on the song.
 
-there is no word wrap; long lines must be broken manually with the Enter key.
+there is no word wrap; long lines must be broken manually with the Enter/Return key.

doc/8-advanced/compat-flags.md

@@ -1,5 +1,5 @@
 # compatibility flags
 
-the **Compatibility Flags** window contains several tabs full of settings that change aspects of tracking and playback. a new Furnace song will have these disabled, while opening a DefleMask module, .mod, or earlier Furnace file will automatically set the appropriate options.
+the **Compatibility Flags** window contains several tabs full of settings that change playback behavior. a new Furnace song will have these disabled, while opening a DefleMask module, .mod, or earlier Furnace file will automatically set the appropriate options.
 
 hovering over most options will bring up additional info about them. it is not recommended to change any of these, especially the ones in the DefleMask and Old Furnace sections.

doc/8-advanced/grooves.md

@@ -1,9 +1,6 @@
 # grooves
 
-grooves are macros for speed.
-
-a **groove** is the equivalent of repeating `0Fxx` commands on each row to get a cycle of speeds. for example, a groove of "6 4 5 3" makes the first row 6 ticks long, the next row 4 ticks, then 5, 3, 6, 4, 5, 3...
-
+a **groove** is the equivalent of repeating `0Fxx` effects on each row to get a cycle of speeds. for example, a groove of "6 4 5 3" makes the first row 6 ticks long, the next row 4 ticks, then 5, 3, 6, 4, 5, 3...
 
 ![groove](groove.png)
 
@@ -13,18 +10,17 @@ to set the song's groove:
 - click again so it becomes "Groove".
 - enter a sequence of up to 16 speeds.
 
-
 ![groove patterns](grooves.png)
 
-the "Grooves" window is for entering preset groove patterns.
-- the **`+`** button adds a new groove pattern; click in the pattern to edit it.
+the "Grooves" window displays the list of groove patterns in the song.
+- the **`+`** button adds a new groove pattern; click in the groove pattern to edit it.
 - the **`×`** buttons remove them.
 
 a single `09xx` command will switch to the matching numbered groove pattern.
 
-## BPM
+## tempo
 
-this is a non-exhaustive list of grooves and their equivalent BPM.
+this is a non-exhaustive list of grooves and their equivalent tempo in BPM.
 
 note: this table assumes a song's tick rate setting is left at its default value for the chosen engine speed: 60 for NTSC, or 50 for PAL.
 

doc/8-advanced/osc.md

@@ -4,6 +4,6 @@ the Oscilloscope shows the audio output as a waveform.
 
 ![oscilloscope view](osc.png)
 
-right-clicking on the oscilloscope toggles the adjustment sliders:
-- waveform height zoom
-- width of viewed audio (window size) in milliseconds.
+right-clicking on the oscilloscope toggles adjustment sliders:
+- waveform height (zoom)
+- window size (how much of the output to display) in milliseconds.