[librep] Doc on recent improvements on docstring and subr. * Related news. * Describes 'documentation' functi

[Christopher Bratusek <chrisb src gnome org>]

commit 0a1e4f8578a13444ce6b3a9fbbf04ea6d08e0e51
Author: Teika kazura <teika lavabit com>
Date:   Tue Sep 7 09:57:24 2010 +0900

    Doc on recent improvements on docstring and subr.
    * Related news.
    * Describes 'documentation' function in info.

 lisp/rep/lang/doc.jl |    4 ++--
 man/lang.texi        |   34 +++++++++++++++++++++++++++++-----
 man/news.texi        |   20 +++++++++++++-------
 3 files changed, 44 insertions(+), 14 deletions(-)
---
diff --git a/lisp/rep/lang/doc.jl b/lisp/rep/lang/doc.jl
index 867563f..e2dd0cf 100644
--- a/lisp/rep/lang/doc.jl
+++ b/lisp/rep/lang/doc.jl
@@ -145,14 +145,14 @@ NAME is true, then it should be the symbol that is associated with VALUE."
       'documentation))
 
   (defun documentation (symbol #!optional structure value)
-    "Returns the documentation-string for SYMBOL which should be the name
+    "Returns the documentation-string for SYMBOL. It should be the name
 of a special variable, function, macro, or a special form.
 If it's not a variable, then VALUE should be the function itself, like
 a closure.
 
 Returns nil when not found.
 
-STRUCTURE is a compatibility argument, and can be nil."
+STRUCTURE can be nil. It was required by the old syntax."
     (catch 'exit
       (when (macrop value)
 	(setq value (cdr value)))
diff --git a/man/lang.texi b/man/lang.texi
index 05699ed..b2508d4 100644
--- a/man/lang.texi
+++ b/man/lang.texi
@@ -30,6 +30,7 @@ The core language.
 * Threads::                     Multi-threaded programs
 * Loading::                     Programs are stored in files
 * Compiled Lisp::               Making programs run faster
+* Docstrings::                  Documentation of variable and function
 
 Data structures and I/O.
 
@@ -3592,8 +3593,7 @@ buffer-local value). If no @var{form} is given the assigned value
 defaults to false.
 
 If the @var{doc-string} argument is defined it is a string documenting
- var{variable}  This string is then stored as the symbol's
- code{documentation} property.
+ var{variable} (@pxref{Docstrings}).
 
 @lisp
 (defvar *my-variable* '(x y)
@@ -3786,7 +3786,7 @@ The general format of a lambda expression is:
 
 @noindent
 Where @var{lambda-list} is a list defining the formal parameters of the
-function, @var{doc} is an optional documentation string,
+function, @var{doc} is an optional documentation string (@pxref{Docstrings}),
 and @var{body-forms} is the sequence of forms making up
 the function body, evaluated using an implicit @code{progn}.
 
@@ -6172,7 +6172,7 @@ should be loaded to provided the actual definition of @var{symbol}.
 ``Magic cookie'' @code{;;;###autoload} comment in the source
 is meaningless. It was supported by Obsolete ``Jade'' editor only.
 
- node Compiled Lisp, Datums, Loading, The language
+ node Compiled Lisp, Docstrings, Loading, The language
 @section Compiled Lisp
 @cindex Compiled Lisp
 
@@ -6618,8 +6618,32 @@ Disassembly of #<closure fib>:
 20   return             ;return the sum of the two calls
 @end example
 
+ node Docstrings, Datums, Compiled Lisp, The language
+ section Documentation Strings
+ cindex Docstrings
+ cindex Documentation Strings
 
- node Datums, Queues, Compiled Lisp, The language
+The ``docstring'', or documentation string, of a variable or function
+gives the description on it, given at its definition.
+
+ defun documentation symbol structure value
+Returns the documentation-string for @var{symbol}. It should be the
+name of a special variable, function, macro, or a special form.  If
+it's not a variable, then @var{value} should be the function itself,
+like a closure.
+
+Returns nil when not found. This function is defined in
+ code{rep lang doc} module.
+
+ var{structure} can be nil. It was required in the old syntax.
+ end defun
+
+Docstring is stored in a very complicated way. Those from installed files
+are stored in @file{DOC} file. Others use the plist for the name. If
+it's a special variable, then docstring is in @code{documentation}
+property, and a closure and a macro, in @code{documentation#MODULE}.
+
+ node Datums, Queues, Docstrings, The language
 @section Datums
 @cindex Datums
 @cindex Data types, datums
diff --git a/man/news.texi b/man/news.texi
index 6561689..20d4991 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -8,8 +8,10 @@
 
 @item Update note [important]:
 
-This release brings an ABI-change, therefore you'll need to rebuild rep-gtk
-and sawfish against this version of librep.
+You need to rebuild rep-gtk and sawfish against this version of librep,
+because of an ABI-change.
+
+Your lisp files have to be byte-compiled again, too.
 
 @item Halfway improved @code{debug-on-error} and @code{backtrace-on-error} [Teika Kazura]
 
@@ -26,13 +28,17 @@ The default value of @code{backtrace-on-error} is now @code{t}.
 
 @item When you evaluate a closure interactively, the module it belongs to is printed, too. [Teika kazura]
 
- item Improved @code{documentation} function [Teika Kazura]
+ item Improved functions' docstring support [Teika Kazura]
+
+Handling of functions' docstring is improved. The revised
+ code{documenation} function is ensured to return the docstring
+of functions, macros, and special forms (@pxref{Docstrings}).
 
-The @code{documenation} function, which returns the docstring of a variable or
-function has been revised. It now works better with docstrings of subrs or macros,
-aswell as docstrings of byte-compiled user-files (eg: pager.jlc).
+Previously, fuctions' docstrings of byte-compiled user-files (eg:
+pager.jlc) were lost, but not now.
 
-** more descriptive docs are comming soon.
+ item New function @code{subr-structure} [Teika Kazura] *
+It returns the module a subr belongs to.
 
 @item Major documentation revision [Teika kazura]