New "guides" section!

Also, some tiny fixes to other docs I noticed along the way.

doc/3-pattern/effects.md

@@ -84,7 +84,7 @@ not all chips support these effects.
 
 ## other
 
-- `9xxx`: **Set sample position.** jumps current sample to position `xxx \* 0x100`.
+- `9xxx`: **Set sample position.** jumps current sample to position `xxx * 0x100`.
   - Not all chips support this effect.
 - `EBxx`: **Set sample bank.**
   - Does not apply on Amiga.
@@ -97,52 +97,52 @@ additionally, [each chip has its own effects](../7-systems/README.md).
 
 ## macro table
 
-ID | macro
----|-----------------------------
-00 | volume
-01 | arpeggio
-02 | duty/noise
-03 | waveform
-04 | pitch
-05 | extra 1
-06 | extra 2
-07 | extra 3
-08 | extra A (ALG)
-09 | extra B (FM)
-0A | extra C (FMS)
-0B | extra D (AMS)
-0C | panning left
-0D | panning right
-0E | phase reset
-0F | extra 4
-10 | extra 5
-11 | extra 6
-12 | extra 7
-13 | extra 8
-|   | **operator 1 macros**
-20 | AM
-21 | AR
-22 | DR
-23 | MULT
-24 | RR
-25 | SL
-26 | TL
-27 | DT2
-28 | RS
-29 | DT
-2A | D2R
-2B | SSG-EG
-2C | DAM
-2D | DVB
-2E | EGT
-2F | KSL
-30 | SUS
-31 | VIB
-32 | WS
-33 | KSR
-40 | **operator 2 macros**
-60 | **operator 3 macros**
-80 | **operator 4 macros**
+ ID  | macro
+-----|-----------------------------
+`00` | volume
+`01` | arpeggio
+`02` | duty/noise
+`03` | waveform
+`04` | pitch
+`05` | extra 1
+`06` | extra 2
+`07` | extra 3
+`08` | extra A (ALG)
+`09` | extra B (FM)
+`0A` | extra C (FMS)
+`0B` | extra D (AMS)
+`0C` | panning left
+`0D` | panning right
+`0E` | phase reset
+`0F` | extra 4
+`10` | extra 5
+`11` | extra 6
+`12` | extra 7
+`13` | extra 8
+|    | **operator 1 macros**
+`20` | AM
+`21` | AR
+`22` | DR
+`23` | MULT
+`24` | RR
+`25` | SL
+`26` | TL
+`27` | DT2
+`28` | RS
+`29` | DT
+`2A` | D2R
+`2B` | SSG-EG
+`2C` | DAM
+`2D` | DVB
+`2E` | EGT
+`2F` | KSL
+`30` | SUS
+`31` | VIB
+`32` | WS
+`33` | KSR
+`40` | **operator 2 macros**
+`60` | **operator 3 macros**
+`80` | **operator 4 macros**
 
 the interpretation of duty, wave and extra macros depends on chip/instrument type:
 

doc/5-wave/README.md

@@ -2,24 +2,23 @@
 
 Wavetable synthesizers, in context of Furnace, are sound sources that operate on extremely short n-bit PCM streams. By extremely short, no more than 256 bytes. This amount of space is nowhere near enough to store an actual sampled sound, it allows certain amount of freedom to define a waveform shape.
 
-Maximum wave width (length) is 256 bytes, and maximum wave height (depth) is 256 steps.
-
 Each chip has its own maximum size, shown in the following table. If a larger wave is defined for these chips, it will be squashed to fit within the constraints of the chips. Some hardware doesn't work well with the wavetable synthesizer (described below); these systems are marked in the "synth?" column.
 
 system              | width | height | synth?
---------------------|------:|:-------|:-----:
+--------------------|------:|:-------|:------
 Bubble System       |    32 | 16     | 
 Game Boy            |    32 | 16     | 
-Game.com            |    32 | 16     | 
-Namco WSG           |    32 | 16     | 
+SM8521              |    32 | 16     | 
+Namco WSG           |    32 | 16     | RAM only
 WonderSwan          |    32 | 16     | 
-Namco N163          |  ≤128 | 16     | 
-Super Nintendo      |  ≤256 | 16     | 
+Namco 163           |  ≤128 | 16     | 
+SNES                |  ≤256 | 16     | 
 PC Engine           |    32 | 32     | 
 Virtual Boy         |    32 | 64     | no
 Famicom Disk System |    64 | 64     | 
 Konami SCC          |    32 | 256    | 
 Seta X1-010         |   128 | 256    | 
+Amiga               |  ≤256 | 256    | 
 
 
 # wavetable editor

doc/9-guides/README.md

@@ -0,0 +1,5 @@
+# guides
+
+here is a small collection of useful tricks and techniques to really make Furnace sing.
+
+- [using samples with limited playback rates](limited-samples.md)

doc/9-guides/limited-samples.md

@@ -0,0 +1,24 @@
+# using samples with limited playback rates
+
+some sample-based chips have a limited number of available sample playback rates. when working with these chips, notes entered in the pattern editor will play back at the closest available rate... which might be perfect, or might be several semitones off. the solution is to prepare samples to work around this.
+
+for example: using the NES, a `C-4` note in the PCM channel means the associated sample will play back at a rate of 8363Hz. let's say we want to use a slap bass sample recorded at a rate of 22050Hz in which the audible pitch is A-2. let's also say that when we put a `C-4` note in the tracker, we want to hear the bass play at what sounds like C-3, transposed three semitones higher than the recorded pitch.
+
+here's how to make this example work:
+
+- load up the sample and open it in the sample editor.
+- the Note selector will show "F-6"; add the three semitones mentioned above to make it "G#6". the Hz will change to 26217.
+- use the Resample button. in the pop-up dialog, type in `8363`, then click Resample.
+- select the instrument from the instrument list, and in the pattern editor, enter a `C-4` in the PCM channel. it should sound like a slap bass playing a C-3 note.
+
+the NES PCM frequency table shows the sixteen notes can be played. if a `D-4` is entered, the slap bass will be heard at D-3 as desired. what if we want to hear a C#3, though?
+
+- load up the original sample in a new slot and open it in the sample editor.
+- the Note selector will show "F-6"; this time we add four semitones to make it "A-6". the Hz will change to 27776.
+- just like before, use the Resample button. in the little pop-up, type in `8363` (yes, the NES's C-4 rate), then click Resample.
+- select the instrument from the instrument list and open it in the instrument editor. turn on "Use sample map".
+- in the leftmost column, find C#5. click in the next column and enter the number of the second sample. in the next column to the right, click the "C#4" and hit the key for C-4 to change it.
+- in the pattern editor, enter a `C#4`; it should sound like a C#3!
+- try adding another entry in the sample map so the note D#4 plays the second sample at D-4.
+
+

doc/README.md

@@ -10,6 +10,7 @@ this documentation is a work in progress! expect several sections to be incomple
 6. [samples](6-sample/README.md)
 7. [list of sound chips](7-systems/README.md)
 8. [advanced topics](8-advanced/README.md)
+9. [guides](9-guides/README.md)
 
 # attribution