# HG changeset patch
# User Aidan Kehoe <kehoea@parhasard.net>
# Date 1211748873 -7200
# Node ID c661944aa2597457798ce30bdaa6ac6ddbc8c3b0
# Parent  a78d697ccd2c832f5770b564e944a88b4f1f2549
Fill out docstrings for  #'translate-region, #'make-char-table.

2008-05-25  Aidan Kehoe  <kehoea@parhasard.net>

	* chartab.c (Fmake_char_table):
	Document the default return values for the various char table
	types.
	* editfns.c (Ftranslate_region): Document why `generic' char tables
	are preferable to `char' char tables for this function.

diff -r a78d697ccd2c -r c661944aa259 src/ChangeLog
--- a/src/ChangeLog	Sun May 25 21:11:35 2008 +0200
+++ b/src/ChangeLog	Sun May 25 22:54:33 2008 +0200
@@ -1,3 +1,11 @@
+2008-05-25  Aidan Kehoe  <kehoea@parhasard.net>
+
+	* chartab.c (Fmake_char_table): 
+	Document the default return values for the various char table
+	types. 
+	* editfns.c (Ftranslate_region): Document why `generic' char tables
+	are preferable to `char' char tables for this function. 
+
 2008-05-21  Aidan Kehoe  <kehoea@parhasard.net>
 
 	* fileio.c (Fmake_symbolic_link):
diff -r a78d697ccd2c -r c661944aa259 src/chartab.c
--- a/src/chartab.c	Sun May 25 21:11:35 2008 +0200
+++ b/src/chartab.c	Sun May 25 22:54:33 2008 +0200
@@ -566,25 +566,32 @@
 sorts of values.  The different char table types are
 
 `category'
-	Used for category tables, which specify the regexp categories
-	that a character is in.  The valid values are nil or a
-	bit vector of 95 elements.  Higher-level Lisp functions are
-	provided for working with category tables.  Currently categories
+	Used for category tables, which specify the regexp categories that a
+	character is in.  The valid values are nil or a bit vector of 95
+	elements, and values default to nil.  Higher-level Lisp functions
+	are provided for working with category tables.  Currently categories
 	and category tables only exist when Mule support is present.
 `char'
-	A generalized char table, for mapping from one character to
-	another.  Used for case tables, syntax matching tables,
-	`keyboard-translate-table', etc.  The valid values are characters.
+	A generalized char table, for mapping from one character to another.
+	Used for case tables, syntax matching tables,
+	`keyboard-translate-table', etc.  The valid values are characters,
+	and the default result given by `get-char-table' if a value hasn't
+	been set for a given character or for a range that includes it, is
+	?\x00.
 `generic'
-        An even more generalized char table, for mapping from a
-	character to anything.
+        An even more generalized char table, for mapping from a character to
+	anything. The default result given by `get-char-table' is nil.
 `display'
-	Used for display tables, which specify how a particular character
-	is to appear when displayed.  #### Not yet implemented.
+	Used for display tables, which specify how a particular character is
+	to appear when displayed.  #### Not yet implemented; currently, the
+	display table code uses generic char tables, and it's not clear that
+	implementing this char table type would be useful.
 `syntax'
 	Used for syntax tables, which specify the syntax of a particular
 	character.  Higher-level Lisp functions are provided for
-	working with syntax tables.  The valid values are integers.
+	working with syntax tables.  The valid values are integers, and the
+	default result given by `get-char-table' is the syntax code for
+	`inherit'.
 */
        (type))
 {
diff -r a78d697ccd2c -r c661944aa259 src/editfns.c
--- a/src/editfns.c	Sun May 25 21:11:35 2008 +0200
+++ b/src/editfns.c	Sun May 25 22:54:33 2008 +0200
@@ -1824,8 +1824,12 @@
 nil (nil meaning don't replace.)
 
 If TABLE is a char-table, its elements describe the mapping between
-characters and their replacements.  The char-table should be of type
-`char' or `generic'.
+characters and their replacements.  The char-table should be of type `char'
+or `generic'.  If the value given by `put-char-table' for a given character
+is nil, that character will not be translated by `translate-region'.  Since
+`char' char-tables can never return nil to `put-char-table', and since most
+translation involves a subset of the possible XEmacs characters, not all of
+them, the most generally useful table type here is `generic'.
 
 Returns the number of substitutions performed.
 */