--- freem/doc/freem.texi	2025/05/02 15:16:36	1.37
+++ freem/doc/freem.texi	2025/05/02 20:01:12	1.38
@@ -4751,10 +4751,63 @@ The effect of this is that the operation
 @cindex variables, local
 @cindex local variables
 
+@section Local Variables Overview
+
+FreeM @emph{local variables} have the same data structure as global variables, but are scoped to a single FreeM process, and stored in memory.
+
+Each local comprises three elements:
+
+@itemize @bullet
+@item
+An alphabetic name beginning with a letter or a percent sign (@code{%})
+@item
+Optionally, one or more comma-delimited subscripts, enclosed in parentheses
+@item
+A value of up to 255 characters in length
+@end itemize
+
+@node Creating Local Variables
+@section Creating Local Variables
+@cindex local variables, creating
+
+To create a local variable, use the @code{SET} command:
+
+@example
+SET MYLOCAL("foo","bar")="this is the data value"
+@end example
+
+@node Removing Local Variables
+@section Removing Local Variables
+@cindex local variables, removing
+
+To remove an entire local variable, you can use the @code{KILL} command with the unsubscripted name of the variable:
+
+@example
+KILL MYLOCAL
+@end example
+
+If you only want to remove part of a local variable, i.e., beginning at a certain subscript level, use the @code{KILL} command with a subscripted name:
+
+@example
+KILL MYLOCAL("foo")
+@end example
+
+This will remove only the @code{"foo"} subscript and all of its children.
+
+If you only want to remove the data value at a specific subscript level, leaving the subscript itself intact, use @code{KVALUE}:
+
+@example
+KVALUE MYLOCAL("foo")
+@end example
+
 @node Scoping
 @chapter Scoping
 @cindex scoping
 
+By default, FreeM local variables and their values are scoped to the entire process, meaning that any function or subroutine can access and modify their values. This can lead to pernicious bugs.
+
+M provides the @code{NEW} command to work around these issues. When @code{NEW} is called with a local variable as its argument, FreeM will scope the variable to the process stack frame in which the @code{NEW} command occured. When exiting the stack frame (i.e. with the @code{QUIT} command), FreeM will restore the variable to its value prior to being @code{NEW}ed.
+
 @node Decision Constructs
 @chapter Decision Constructs
 @cindex decision constructs