-Announce controls where "Installed foo" mails are sent; leave empty to
-not send any. CodeName, Origin and Description are used by ziyi and
-put in the Release files. OverrideCodeName is used by Denise.
-Priority determines which suite is used for the Maintainers file as
-generated by charisma/da_mkmaintainers (highest wins).
+Announce (optional): controls where "Installed foo" mails are sent.
+
+CodeName, Origin and Description (optional): This settings are used by ziyi
+and put in the Release files.
+
+OverrideCodeName (optional): used by Denise.
+
+Priority (optional) determines which suite is used for the Maintainers file
+as generated by charisma/da_mkmaintainers (highest wins).
+
+CopyChanges (optional): if this variable is present it should be a path
+into the archive (i.e. "Dir::RootDir"); any upload targeted for a suite
+with this config option present will have the .changes file copied into
+that path.
+
+CopyKatie (optional): if this is present it should be an absolute path; any
+upload targeted for a suite with this config option present will have the
+.katie file copied into that path. This option is similar to CopyChanges
+and will most often be used with it; they're seperate because .changes
+files are mirrored and .katie files aren't, so the paths will usually be
+different.
+
+There are more optional variables, such as VersionChecks. Please see
+katie.conf for examples.
+
+================================================================================
+
+SuiteMappings
+-------------
+
+Optional. List of mappings for the Distribution file in a .changes file, e.g.:
+
+| SuiteMappings
+| {
+| "map stable proposed-updates";
+| "map frozen unstable";
+| "map-unreleased stable unstable";
+| "map-unreleased proposed-updates unstable";
+| "ignore testing";
+| };
+
+There are three mapping types:
+
+(1) map <source> <dest>
+
+ Any target suite of '<source>' is unconditionally overriden to
+ '<dest>'.
+
+(2) map-unreleased <source> <dest>
+
+ Any upload targeted for suite '<source>' will be mapped to
+ '<dest>' iff it contains uploads for an architecture that is not
+ part of '<source>'.
+
+(3) ignore <suite>
+
+ Any target suite of '<suite>' is unconditionally removed from
+ the list of target suites. NB: if the upload had only one
+ target suite this will lead to rejection.
+
+NB: ordering is not guaranteed.