diff --git a/core/map.xml b/core/map.xml
index cc6bb145..de2c7bc0 100644
--- a/core/map.xml
+++ b/core/map.xml
@@ -28,7 +28,19 @@
xmlns:c="http://www.lovullo.com/calc"
xmlns:t="http://www.lovullo.com/rater/apply-template"
core="true"
- desc="Mapping templates/functions">
+ title="Map Sets">
+
+
+ The problem with \texttt{case} statements is that they are very
+ verbose, which is greatly distracting for smaller cases, and~can
+ take away from the actual intent of the~code. Map~sets make simple
+ cases simple by allowing concise map definitions.
+
+ If \ref{_map-set_/@name@} is provided, then each map implicitly
+ operates on that reference as its input, unless overridden using
+ \ref{_map_/@name@}. \ref{_map-set_/@default@} can be used to
+ provide a constant default if no mapping is otherwise available; see
+ also~\ref{_map-else_}.
@@ -42,14 +54,13 @@
+
-
@@ -59,6 +70,20 @@
+ Mappings are defined using \ref{_map_}. The input defaults to
+ the~reference declared by~\ref{_map-set_/@name@},
+ if~provided. \ref{_map_/@name@} takes precedence, even if
+ the~former is provided. Just like \texttt{case}~statements,
+ multiple inputs can be provided by specifying multiple references;
+ this means that each \ref{_map_/@name@} can differ.\footnote{This
+ isn't particularly intuitive or recommended, but it does simplify
+ certain tasks enough to maybe justify this type of use.}
+
+ Just like \texttt{case}~statements themselves, maps are
+ surjective---the codomain implicitly includes $0$~to handle all
+ default cases, unless a default is provided.
+
+
@@ -113,6 +138,12 @@
+ The default condition can be handled in two different ways: via
+ \ref{_map-set_/@default@}, or using \ref{_map-else_}; the latter
+ provides more flexibility and generally reads better. Both cannot
+ be used together.
+
+