From dd47c650e42a0910f7788d572edc7cea761a91f7 Mon Sep 17 00:00:00 2001
From: Vince Reuter <vince.reuter@gmail.com>
Date: Thu, 16 May 2019 13:50:00 -0400
Subject: [PATCH] doc how to customize text repr; close #47

---
 .gitignore    |  2 +-
 docs/howto.md | 27 +++++++++++++++++++++++++++
 mkdocs.yml    |  1 +
 3 files changed, 29 insertions(+), 1 deletion(-)
 create mode 100644 docs/howto.md

diff --git a/.gitignore b/.gitignore
index e0616a5..246a74e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -72,4 +72,4 @@ Thumbs.db
 build/
 dist/
 attmap.egg-info/
-
+docs/autodoc_build
diff --git a/docs/howto.md b/docs/howto.md
new file mode 100644
index 0000000..300512f
--- /dev/null
+++ b/docs/howto.md
@@ -0,0 +1,27 @@
+# Use cases and "how-to..."
+
+## ...customize a subtype's text rendition
+In a subclass, override `_excl_from_repr`, using key and/or type of value. 
+
+The most basic implementation is a no-op, excluding nothing:
+```python
+def _excl_from_repr(self, k, cls):
+    return False
+```
+
+To exclude by key, though, you can do something like:
+```python
+def _excl_from_repr(self, k, cls):
+    protected = ["reserved_metadata", "REZKEY"]
+    return k in protected
+```
+
+To exclude by value type, you can use something like:
+```python
+def _excl_from_repr(self, k, cls):
+    return issubclass(cls, BaseOmissionType)
+```
+where `BaseOmissionType` is a proxy for the name of some type of values that may 
+be stored in your mapping but that you prefer to not display in its text representation.
+
+The two kinds of exclusion criteria may be combined as desired.
diff --git a/mkdocs.yml b/mkdocs.yml
index ae5eb3b..fe9ab9e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -8,6 +8,7 @@ nav:
     - Home: README.md
   - Reference:
     - API: autodoc_build/attmap.md
+    - Howto: howto.md
     - Support: support.md
     - Contributing: contributing.md
     - Changelog: changelog.md