[librep] Doc. * Improved news. Some addition in TODO. Others. * Doc of `structure-exports-p' is given. * Doc

[Christopher Bratusek <chrisb src gnome org>]

commit 250a5a4c6a9d1c27f83b69876d29d2a4671c6d02
Author: Teika kazura <teika lavabit com>
Date:   Tue Sep 7 09:54:48 2010 +0900

    Doc.
    * Improved news. Some addition in TODO. Others.
    * Doc of `structure-exports-p' is given.
    * Doc of `intern-structure' is corrected.
    * Doc on read syntax of character is improved.

 TODO                   |    3 +-
 lisp/rep/lang/doc.jl   |    5 +++-
 lisp/rep/structures.jl |   10 ++++----
 man/lang.texi          |   58 +++++++++++++++++++++++++++++++++++++++--------
 man/news.texi          |   11 +++++----
 src/rep_lisp.h         |    7 +++--
 src/structures.c       |    9 +++----
 7 files changed, 73 insertions(+), 30 deletions(-)
---
diff --git a/TODO b/TODO
index 9aec7c1..5cc2304 100644
--- a/TODO
+++ b/TODO
@@ -230,6 +230,7 @@ General programming tasks:
 Manual tasks:
 =============
 
- + Document the error-mode and interrupt-mode variables
+ + Document: variables `error-mode', `interrupt-mode', `idle-hook',
+   and `program-name'
 
  + Document the internals (i.e. the C interface)
diff --git a/lisp/rep/lang/doc.jl b/lisp/rep/lang/doc.jl
index 2cac6c6..867563f 100644
--- a/lisp/rep/lang/doc.jl
+++ b/lisp/rep/lang/doc.jl
@@ -1,4 +1,4 @@
-#| lisp-doc.jl -- Accessing LISP doc strings
+#| doc.jl -- Accessing LISP doc strings
 
    $Id$
 
@@ -19,6 +19,9 @@
    You should have received a copy of the GNU General Public License
    along with Librep; see the file COPYING.  If not, write to
    the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
+
+   Module 'lisp-doc' is the alias for rep.lang.compat-doc, NOT of
+   this file.
 |#
 
 (declare (unsafe-for-call/cc))
diff --git a/lisp/rep/structures.jl b/lisp/rep/structures.jl
index 21a1b1e..ae28915 100644
--- a/lisp/rep/structures.jl
+++ b/lisp/rep/structures.jl
@@ -51,17 +51,17 @@
   "Create an alias of the structure called FROM as the name TO."
   (name-structure (get-structure from) to))
 
-(defun locate-binding (var imported)
-  "Return the name of the structure binding VAR, using the list of module
+(defun locate-binding (sym imported)
+  "Return the name of the structure binding of SYM, using the list of module
 names IMPORTED as the search start points."
   (when imported
-    (let ((tem (structure-exports-p (get-structure (car imported)) var)))
+    (let ((tem (structure-exports-p (get-structure (car imported)) sym)))
       (cond ((null tem)
-	     (locate-binding var (cdr imported)))
+	     (locate-binding sym (cdr imported)))
 	    ((eq tem 'external)
 	     ;; this module exports it, but it doesn't define
 	     ;; it, so search its imports
-	     (locate-binding var (structure-imports
+	     (locate-binding sym (structure-imports
 				  (get-structure (car imported)))))
 	    (t (car imported))))))
 
diff --git a/man/lang.texi b/man/lang.texi
index 1907735..05699ed 100644
--- a/man/lang.texi
+++ b/man/lang.texi
@@ -455,6 +455,10 @@ come from Scheme.
 Rep does not have the notion of ``command'', but Sawfish does.
 See @xref{Commands, , Commands, sawfish, The Sawfish Manual}.
 
+If you loop over list elements, then @code{mapc} and @code{mapcar} are
+fast, like Emacs. But ``tail-recursion'' is better than a @code{while}
+loop if byte-compiled (@pxref{Compilation Tips}.)
+
 @node Data Types, Numbers, Crash course for Elisp users, The language
 @section Data Types
 @cindex Data types
@@ -616,6 +620,16 @@ character (@samp{"}) at each end, for more details see @ref{Strings}.
 "This is a string"
 @end lisp
 
+ item Character
+In Librep, a character is an unsigend 8-bit integer. It read syntax
+is a question mark(@samp{?}) and the character itself. For the
+details, see @xref{Characters}.
+
+ lisp
+?a
+    @result{} 97
+ end lisp
+
 @item Cons cells
 A cons cell is written in what is known as @dfn{dotted pair notation},
 an opening left-parenthesis, followed by the read syntax of the first
@@ -1383,6 +1397,16 @@ escape sequences see @ref{Strings}.
 
 ?\177
     @result{} 127
+
+;; Also special escape syntaxes only for character, not for string.
+#\newline
+    @result{} 10  ; = ?\n
+;; also #\backspace, #\tab, #\linefeed, #\return, #\page, 
+;; #\space, and #\rubout are available.
+
+#\s
+    @result{} 115  ; = ?s
+;; Other than above cases, the first character is read.
 @end lisp
 
 Functions below makes sence for ascii characters only.
@@ -4771,7 +4795,7 @@ Variables}.
 @subsection Module Functions
 
 In this section basic module functions are explained. All are defined
-in @code{rep.structure}. Functions related to contruction of modules
+in @code{rep.structures}. Functions related to contruction of modules
 are described in following sections.
 
 @defun structurep str
@@ -4800,6 +4824,9 @@ structure exists.
 @defun intern-structure name
 Returns the structure called @var{name}, or if one doesn't exist,
 attempts to load it.
+
+This is a kind of mixture of @code{require} and @code{load}; the
+grammar is that of @code{require}, but it doesn't import any.
 @end defun
 
 These functions are related to opening other modules.
@@ -4809,6 +4836,15 @@ These functions are related to opening other modules.
 Returns the list of modules @code{str} has opened or accesses.
 @end defun
 
+There's a function for bindings.
+
+ defun structure-exports-p str sym
+Returns non-nil if the structure @var{structure} exports a binding
+of the symbol @var{sym}. More specifically, it returns the symbol
+ code{local} if @var{structure} defines it, and returns the symbol 
+ code{external} if it exports but does not define it.
+ end defun
+
 Functions @code{open-structures} and @code{access-structures} are
 explained in @xref{Using Other Modules}.
 
@@ -6736,17 +6772,17 @@ the variable @code{:pare} is bound to the record type. Following this
 definition, the record type could be used as follows:
 
 @lisp
-(define x (kons 1 2))
+(define my-kons (kons 1 2))
 
-(pare? x)
+(pare? my-kons)
     @result{} t
 
-(kar x)
+(kar my-kons)
     @result{} 1
 
-(set-kar! x 42)
+(set-kar! my-kons 42)
 
-(kar x)
+(kar my-kons)
     @result{} 42
 @end lisp
 
@@ -9712,10 +9748,12 @@ command-line-args
 @cindex Timers, asynchronous
 
 The @code{rep.io.timers} module (@pxref{Modules}) allows a Lisp program
-to create multiple asynchronous timers, each of which is primed to call
-a specified function after a specified period of time. These functions
-only work when the Lisp event loop is being used (i.e. at least one
- code{recursive-edit} is currently in progress).
+to create multiple asynchronous timers, primed to call a specified
+function after some time. 
+
+A timer is not a thread. It works when the event loop is being used,
+i.e. at least one @code{recursive-edit} is currently in progress. A
+timer is called between cycles of event loop.
 
 @defun make-timer function @t{#!optional} seconds milliseconds
 Create and return a new timer object. It will be set to call the Lisp
diff --git a/man/news.texi b/man/news.texi
index efb9d8e..6561689 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -24,7 +24,7 @@ handler. It is not the best, but we can't improve it.
 
 The default value of @code{backtrace-on-error} is now @code{t}.
 
- item When you evaluate a closure, the module it belongs to is printed, too. [Teika kazura]
+ item When you evaluate a closure interactively, the module it belongs to is printed, too. [Teika kazura]
 
 @item Improved @code{documentation} function [Teika Kazura]
 
@@ -40,13 +40,14 @@ Reorganized documentation files. Many capital letter name files were updated
 or merged into the info.
 
 New entries: @xref{Crash course for Elisp users}, @xref{Closures},
-on leading tilde and tarball access (@pxref{File Handlers}),
+on leading tilde in a filename and tarball access (@pxref{File Handlers}),
 fully revised the module section (@pxref{Modules}), improved
 description on invocation (@pxref{Invocation}), improved
-fluid and @code{let} descriptions of (@pxref{Fluid Variables},
-and @pxref{Local Variables}.) Module names are supplied for all functions.
+``fluid'' and @code{let} descriptions (@pxref{Fluid Variables},
+and @pxref{Local Variables}), improved the read syntax of character
+(@pxref{Characters}). Module names are supplied for all functions.
 
-Supplied documentation to some functions. Input stream functions
+Supplied documentation to some functions: Input stream functions
 @code{peek-char}, @code{read-char} (@pxref{Input Functions}), list
 functions @code{remove-if}, @code{remove-if-not} (@pxref{Mapping
 Functions}), @code{table-size} (@pxref{Hash Tables}), @code{setcar},
diff --git a/src/rep_lisp.h b/src/rep_lisp.h
index 0f33893..248a737 100644
--- a/src/rep_lisp.h
+++ b/src/rep_lisp.h
@@ -97,7 +97,8 @@ typedef unsigned rep_PTR_SIZED_INT repv;
 #define rep_NULL	(0)
 
 /* Align the variable or struct member D to the necessary cell alignment.
-   This is used like: ``rep_ALIGN_CELL(rep_cell foo) = ...'' */
+   This is used like: ``rep_ALIGN_CELL(rep_cell foo) = ...''
+   The best examples are the uses for rep_subr and rep_xsubr below. */
 #ifdef __GNUC__
 # define rep_ALIGN_CELL(d) d __attribute__ ((aligned (rep_CELL_ALIGNMENT)))
 #elif defined (__digital__) && defined (__unix__) && defined (__DECC)
@@ -292,7 +293,7 @@ typedef struct rep_type_struct {
 #define rep_Void	0x09
 #define rep_Reserved	0x0b
 #define rep_Number	0x0d
-#define rep_SF		0x0f
+#define rep_SF		0x0f /* Special form */
 #define rep_Subr0	0x11
 #define rep_Subr1	0x13
 #define rep_Subr2	0x15
@@ -300,7 +301,7 @@ typedef struct rep_type_struct {
 #define rep_Subr4	0x19
 #define rep_Subr5	0x1b
 #define rep_SubrN	0x1d
-#define rep_Funarg	0x1f
+#define rep_Funarg	0x1f /* Closure */
 
 /* Assuming that V is a cell, return the type code */
 #define rep_CELL_TYPE(v) (rep_CONSP(v) ? rep_Cons		\
diff --git a/src/structures.c b/src/structures.c
index 6631df6..32832dd 100644
--- a/src/structures.c
+++ b/src/structures.c
@@ -970,10 +970,10 @@ Returns the interface of structure object STRUCTURE.
 DEFUN ("structure-exports-p", Fstructure_exports_p,
        Sstructure_exports_p, (repv structure, repv var), rep_Subr2) /*
 ::doc:rep.structures#structure-exports-p::
-structure-exports-p STRUCTURE VAR
+structure-exports-p STRUCTURE SYM
 
 Returns true if structure object STRUCTURE exports a binding of symbol
-VAR.
+SYM.
 ::end:: */
 {
     rep_struct_node *n;
@@ -1070,8 +1070,7 @@ DEFUN("intern-structure", Fintern_structure,
 intern-structure STRUCT-NAME
 
 Return the structure called STRUCT-NAME. If no such structure exists,
-attempt to load it into the root structure, i.e. it's loaded, but
-the current module is not affected.
+attempt to load it, but it isn't imported to any module.
 ::end:: */
 {
     repv tem;
@@ -1433,7 +1432,7 @@ loaded is either FILE (if given), or the print name of FEATURE.
 
     /* Need to do all this locally, since the file providing the
        feature/module has to be loaded into the _current_ structure
-       (in case it contains bare code). %intern-structure OTOH
+       (in case it contains bare code). intern-structure OTOH
        always loads into *root-structure*, since it's often called
        with only the %meta structure imported */