diff --git a/tconfpy.3 b/tconfpy.3
index e1c3299..9dfe11c 100644
--- a/tconfpy.3
+++ b/tconfpy.3
@@ -2089,6 +2089,109 @@
 statement will be ignored.
 
 
+.SH GOTCHAS
+
+\*(TC is a "little language".  It is purpose-built to do one
+and only one thing well: process configuration options.  Even
+so, it is complex enough that there are a few things that can
+"bite" you when writing these configuration files:
+
+
+.IP \(bu 4
+Probably the most common problem is attempting to do this:
+
+.nf
+    foo = bar
+
+    .if foo == bar
+       ...
+    .endif
+.fi
+
+But this will not work.  \*(TC is very strict about requiring you to
+explicity distinguish between
+.B variable names
+and
+.B variable references.
+
+The example above checks to see if the string "foo" equals
+the string "bar" - which, of course, it never does.
+
+What you probably want is to compare the value of variable \'foo\' with
+some string:
+
+.nf
+    foo = bar
+
+    .if [foo] == bar
+       ...
+    .endif
+.fi
+
+Now you're comparing the
+.B value
+of the variable \'foo\' with the string "bar".
+
+By the way, this was done for a very good reason.  By requiring the user
+explicitly note whether they want the name or value of a variable (instead of
+inferring it from context), you can mix both literal text and variable values
+on either side of a comparison or assignment:
+
+.nf
+    foo = bar
+
+    foo[foo]foo = bar      # Means: foobarfoo = bar
+
+   .if foo[foo] == foobar  # Means: .if foobar == foobar
+
+.IP \(bu 4
+Namespaces are a handy way to keep configuration options organized,
+especially in large or complex configurations.  However, you need to
+keep track of the current namespace when doing things:
+
+.nf
+    foo = bar
+     ....
+
+    [NS-NEW]
+
+    .if [foo] == something  # Checks value of NS-NEW.foo - will cause error
+                            # since no such variable exists
+.fi
+
+
+.IP \(bu 4
+Remember that "last assignment wins" when setting variable values:
+
+.nf
+    myvar = 100
+
+    ... a long configuration file
+
+    myvar = 200
+.fi
+
+At the end of all this, \'myvar\' will be set to 200.  This can be
+especially annoying if you \'.include\' a configuration file after
+you've set a value and the included file resets it.  As a matter of
+style, it's best to do all the \'.include\'s at the top of the master
+configuration file so you won't get bitten by this one.
+
+.IP \(bu 4
+Remember that case matters.  \'Foo\', \'foo\', and \'foO\' are all
+different variable names.
+
+.IP \(bu 4
+Remember that all variable references are
+.B string replacements
+no matter what the type of the variable actually is.  \*(TC
+type and value enforcement is used to return the proper value and
+type to the calling program.  But within the actual processing
+of a configuration file, variable references (i.e., the values of
+variables) are always treated as
+.B strings.
+
+
 .SH ADVANCED TOPICS FOR PROGRAMMERS
 
 Here are some ideas on how you might combine \*(TC features