* txr.1: More discussion of ranges.

2 files changed, 26 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index fc73e42d..783aa5a2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2012-01-26  Kaz Kylheku  <kaz@kylheku.com>
 
+	* txr.1: More discussion of ranges.
+
+2012-01-26  Kaz Kylheku  <kaz@kylheku.com>
+
 	* match.c (format_field): Removed useless use of cat_str (no longer
 	needed because str is already a string). The purpose was to reduce
 	character to strings.
diff --git a/txr.1 b/txr.1
index ff427fc8..2b015d60 100644
--- a/txr.1
+++ b/txr.1
@@ -4886,6 +4886,7 @@ Retrieve the specified range of elements, exactly as if
 using (sub-list <list> <from-index> <to-below-index>).
 The range of elements is specified in the car and cdr fields of a cons cell,
 for which the .. (dotdot) syntactic sugar is useful.
+See the section on Indexing below.
 
 .IP [<vector> <index>]
 Retrieve the specified element of a vector. This is equivalent to
@@ -4896,6 +4897,7 @@ Retrieve the specified range of elements, exactly as if
 using (sub-vec <list> <from-index> <to-below-index>).
 The range of elements is specified in the car and cdr fields of a cons cell,
 for which the .. (dotdot) syntactic sugar is useful.
+See the section on Range Indexing below.
 
 .IP [<string> <index>]
 Retrieve the specified element of a string. This is equivalent to
@@ -4915,6 +4917,26 @@ range updates the form which contains the list, so the expression denoting the
 list must be an assignable place.
 
 .TP
+Range Indexing
+
+Array and list range indexing is based from zero. The first element element
+zero. Furthermore, the value -1 refers to the last element of the array or
+list, and -2 to the second last and so forth. So the range 1 .. -2 means
+"everything except for the first element and the last two".
+
+The symbol t represents the position one past the end of the array or
+list, so 0 .. t denotes the entire list or array, and the range t .. t
+represents the empty range just beyond the last element.
+It is possible to assign to t .. t. For instance:
+
+  (defvar list '(1 2 3))
+  (set [list t .. t] '(4)) ;; list is now (1 2 3 4)
+
+Either end of the range can also be specified as nil. If the start is specified
+as nil, it means zero. If the end is specified as nil, it means one element
+past the end. Thus nil .. nil spans all of the elements.
+
+.TP
 Notes:
 
 The dwim operator allows for a Lisp-1 flavor of programming in TXR Lisp,