[librep] Introduced 'defvar-setq'. It's a replacement of 'define-special-variable' whose name is very confusi

[Christopher Bratusek <chrisb src gnome org>]

commit 3408db9ab825a27a37dfd0319eb4efa86b35282c
Author: Teika kazura <teika lavabit com>
Date:   Sat Jul 17 20:47:22 2010 +0900

    Introduced 'defvar-setq'.
    It's a replacement of 'define-special-variable' whose name is very confusing.

 lisp/rep.jl                  |    2 ++
 lisp/rep/lang/interpreter.jl |   21 ++++++++++++++-------
 man/lang.texi                |   27 ++++++++++++++++++---------
 man/news.texi                |    4 ++++
 4 files changed, 38 insertions(+), 16 deletions(-)
---
diff --git a/lisp/rep.jl b/lisp/rep.jl
index eebd534..60a805f 100644
--- a/lisp/rep.jl
+++ b/lisp/rep.jl
@@ -52,6 +52,8 @@
 (defun _ (arg) arg)
 (export-bindings '(_))
 
+;; These functions get exported by 'rep' module, so available
+;; virtually without explicit import.
 (export-bindings (parse-interface '(compound-interface
 				    (structure-interface rep.lang.interpreter)
 				    (structure-interface rep.lang.symbols)
diff --git a/lisp/rep/lang/interpreter.jl b/lisp/rep/lang/interpreter.jl
index bc6fc8a..c614bd0 100644
--- a/lisp/rep/lang/interpreter.jl
+++ b/lisp/rep/lang/interpreter.jl
@@ -288,19 +288,26 @@ See also `setq'. Returns the value of the last FORM."
 ;; XXX it would be nice to do the same for setq.. might stress the
 ;; XXX interpreter somewhat..? :-(
 
-(defmacro define-special-variable (var #!optional value doc)
-  "define-special-variable VARIABLE [VALUE [DOC]]
+(defmacro defvar-setq (var #!optional value doc)
+  "defvar-setq VARIABLE [VALUE [DOC]]
+
+Declares the symbol VARIABLE as a special variable, and sets its value
+to VALUE (or false if VALUE isn't defined). If DOC is given it will be
+installed as the documentation string associated with VARIABLE.
 
-Declares the symbol VARIABLE as a special variable, then
-unconditionally sets its value to VALUE (or false if VALUE isn't
-defined). If DOC is given it will be installed as the documentation
-string associated with VARIABLE."
+It's the same as the previous `define-special-variable'."
 
   (list 'progn
 	(list 'defvar var nil doc)
 	(list 'setq var value)))
 
-(export-bindings '(setq-default define-special-variable))
+(defmacro define-special-variable (var #!optional value doc)
+  "Use defvar-setq instead."
+  (list 'progn
+	(list 'defvar var nil doc)
+	(list 'setq var value)))
+
+(export-bindings '(setq-default defvar-setq define-special-variable))
 
 
 ;; Misc syntax
diff --git a/man/lang.texi b/man/lang.texi
index 4bbf3c3..1907735 100644
--- a/man/lang.texi
+++ b/man/lang.texi
@@ -344,12 +344,13 @@ You can make visible this variable to other modules. This will
 be explained later in the section on modules.
 
 Like Elisp, @code{defvar} does not override an existing value. (But
- code{define} does.) Function @code{define-special-variable} is
- code{defvar} + @code{setq}, so it declares a global variable, and
-sets the value. (Yes, a very bad name.)
+ code{define} does.) Function @code{defvar-setq} is @code{defvar} +
+ code{setq}, so it declares a global variable, and sets the value.
+(It was previously called @code{define-special-variable}, but
+a new, better name is provided now.)
 
 Now, an important point. It's a common technique to change the value
-of a varible temporarily with @code{let} in Elisp. This works too
+of a variable temporarily with @code{let} in Elisp. This works too
 in Rep, but ONLY with global variable. Please see the next example:
 
 @lisp
@@ -375,7 +376,7 @@ This is the lexical scope.
 
 There's also the notion of ``fluid'' variables in Rep which is an
 intermediate between lexical and dynamic. In my personal opinion,
-fluids are not so useful because Rep's grammar is poor. But it is
+fluids are not so much useful because Rep's grammar is poor. But it is
 used in Sawfish, too. See @xref{Fluid Variables}.
 
 @subheading Functions
@@ -420,7 +421,7 @@ you can easily write helper functions which are only visible to
 the wrapping function.
 
 Use @code{#!optional} and @code{#!rest}, instead of @code{&}. You can
-also use named argument passing wich @code{#!key}. See @xref{Lambda
+also use named argument passing with @code{#!key}. See @xref{Lambda
 Expressions}.
 
 In Rep, you can't @code{funcall} symbols. It's of frequent use for
@@ -3581,6 +3582,16 @@ Don't use @code{defvar} if @code{define} suffices. For the reason,
 see @xref{Modules and Special Variables}.
 @end defspec
 
+ defmac defvar-setq var @t{#!optional} value doc
+It's @code{defvar} + @code{setq}, so defines @var{var} as a special
+variable, and sets the value to @var{value}.
+ end defmac
+
+ defmac define-special-variable var @t{#!optional} value doc
+Same as @code{defvar-setq} above. A very confusing name, so it's
+deprecated now.
+ end defmac
+
 @defmac defconst constant form [doc-string]
 @code{defconst} defines a global constant, the symbol @var{constant}.
 Its value is set to the result of evaluating @var{form}. Note that
@@ -9066,7 +9077,7 @@ Return a list of substrings of @code{string}, each delimited by
 @cindex Calendar date and time
 
 This section describes how time and date values are handled in
-Librep.
+Librep. These function are exported by the @code{rep.system} module:
 
 @menu
 * Timestamps::                  Internal representation of time
@@ -9088,8 +9099,6 @@ using a cons cell. The first integer records the number of whole days
 since the epoch, the second records the number of seconds since the
 start of the day (in universal time).
 
-These function are exported by the @code{rep.system} module:
-
 @defun current-time
 Return the number of seconds since the epoch, in a cons-cell.
 
diff --git a/man/news.texi b/man/news.texi
index 74234da..3ef334c 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -44,6 +44,10 @@ Functions}), @code{table-size} (@pxref{Hash Tables}), @code{setcar},
 @code{setcdr} and @code{cdddr} family (@pxref{Cons Cells}),
 @code{assoc-regexp} (@pxref{Association Lists}).
 
+ item @code{define-special-variable} is replaced by @code{defvar-setq} [Teika kazura]
+
+The former remains, but it's a very confusing name, so the latter is
+introduced.
 @end itemize
 @heading 0.90.6
 @itemize @bullet