Add doc/note/quirks.md
diff --git a/doc/note/quirks.md b/doc/note/quirks.md
new file mode 100644
index 0000000..f919da3
--- /dev/null
+++ b/doc/note/quirks.md
@@ -0,0 +1,34 @@
+# Quirks
+
+Quirks are configuration options that let Wuffs more closely match other codec
+implementations.
+
+Some codecs and file formats are more tightly specified than others. When a
+spec doesn't fully dictate how to treat malformed files, different codec
+implementations have disagreed on whether to accept it (e.g. whether they
+follow Postel's Principle of "be liberal in what you accept") and if so, how to
+interpret it. Some implementations also raise those decisions to the
+application level, not the library level: "provide mechanism, not policy".
+
+For example, in an animated GIF image, the first frame might not fill out the
+entire image, and different implementations choose a different default color
+for the outside pixels: opaque black, transparent black, or something else.
+
+Wuffs, out of the box, makes particular choices (typically mimicking the de
+facto canonical implementation), but enabling various quirks result in
+different choices. In particular, quirks are useful in regression testing that
+Wuffs and another implementation produce the same output for the same input,
+even for malformed input.
+
+
+## Wuffs API
+
+Each quirk is assigned a `uint32_t` value, packed using the [base38 namespace
+convention](/doc/note/base38-and-fourcc.md). Decoders and encoders can have a
+`set_quirk_enabled!(quirk base.u32, enabled base.bool)` method whose first
+argument is this `uint32_t` value.
+
+For example, the base38 encoding of `"gif "` is `0xF8586`, so that the
+GIF-specific quirks have a `uint32_t` value of `((0xF8586 << 10) | n)`, for
+some small integer `n`. The generated `C` language file defines human-readable
+names for those constant values.
diff --git a/std/gif/decode_gif.wuffs b/std/gif/decode_gif.wuffs
index 252071f..b96ccee 100644
--- a/std/gif/decode_gif.wuffs
+++ b/std/gif/decode_gif.wuffs
@@ -31,30 +31,7 @@
// --------
-// Quirks are configuration options that let Wuffs more closely match other
-// codec implementations.
-//
-// Some codecs and file formats are more tightly specified than others. When a
-// spec doesn't fully dictate how to treat malformed files, different codec
-// implementations have disagreed on whether to accept it (e.g. whether they
-// follow Postel's Principle of "be liberal in what you accept") and if so, how
-// to interpret it. Some implementations also raise those decisions to the
-// application level, not the library level: "provide mechanism, not policy".
-//
-// For example, in an animated image, the first frame might not fill out the
-// entire image, and different implementations choose a different default color
-// for the outside pixels: opaque black, transparent black, or something else.
-//
-// Wuffs, out of the box, makes particular choices (typically mimicking the de
-// facto canonical implementation), but enabling various quirks result in
-// different choices. In particular, quirks are useful in regression testing
-// that Wuffs and another implementation produce the same output for the same
-// input, even for malformed input.
-//
-// In terms of the Wuffs API, each quirk is assigned a uint32 value. A base38
-// (github.com/google/wuffs/lib/base38) value can fit in 21 bits. Leaving the
-// high bit of a uint32 reserved, the low 10 bits hold a package-specific
-// enumeration: the base38 value acts as a namespace.
+// Quirks are discussed in (/doc/note/quirks.md).
//
// The base38 encoding of "gif " is 0xF8586.
