# HG changeset patch # User Eli Zaretskii # Date 1241860172 0 # Node ID 01f2551ebd1b2f5c08829de574bc3d0ff3720146 # Parent 622683e27798acc41c9d85ecaf14323b62b02641 (Default Coding Systems): Document find-auto-coding, set-auto-coding, and auto-coding-alist. Add indexing. (Lisp and Coding Systems): Add index entries. diff -r 622683e27798 -r 01f2551ebd1b doc/lispref/nonascii.texi --- a/doc/lispref/nonascii.texi Sat May 09 07:19:47 2009 +0000 +++ b/doc/lispref/nonascii.texi Sat May 09 09:09:32 2009 +0000 @@ -1001,6 +1001,7 @@ Here are the Lisp facilities for working with coding systems: +@cindex list all coding systems @defun coding-system-list &optional base-only This function returns a list of all coding system names (symbols). If @var{base-only} is non-@code{nil}, the value includes only the @@ -1013,6 +1014,8 @@ name or @code{nil}. @end defun +@cindex validity of coding system +@cindex coding system, validity check @defun check-coding-system coding-system This function checks the validity of @var{coding-system}. If that is valid, it returns @var{coding-system}. If @var{coding-system} is @@ -1021,6 +1024,7 @@ (@pxref{Signaling Errors, signal}). @end defun +@cindex eol type of coding system @defun coding-system-eol-type coding-system This function returns the type of end-of-line (a.k.a.@: @dfn{eol}) conversion used by @var{coding-system}. If @var{coding-system} @@ -1047,6 +1051,7 @@ appropriate for the underlying platform. @end defun +@cindex eol conversion of coding system @defun coding-system-change-eol-conversion coding-system eol-type This function returns a coding system which is like @var{coding-system} except for its eol conversion, which is specified by @code{eol-type}. @@ -1058,6 +1063,7 @@ @code{dos} and @code{mac}, respectively. @end defun +@cindex text conversion of coding system @defun coding-system-change-text-conversion eol-coding text-coding This function returns a coding system which uses the end-of-line conversion of @var{eol-coding}, and the text conversion of @@ -1065,6 +1071,8 @@ @code{undecided}, or one of its variants according to @var{eol-coding}. @end defun +@cindex safely encode region +@cindex coding systems for encoding region @defun find-coding-systems-region from to This function returns a list of coding systems that could be used to encode a text between @var{from} and @var{to}. All coding systems in @@ -1075,6 +1083,8 @@ list @code{(undecided)}. @end defun +@cindex safely encode a string +@cindex coding systems for encoding a string @defun find-coding-systems-string string This function returns a list of coding systems that could be used to encode the text of @var{string}. All coding systems in the list can @@ -1083,6 +1093,8 @@ @code{(undecided)}. @end defun +@cindex charset, coding systems to encode +@cindex safely encode characters in a charset @defun find-coding-systems-for-charsets charsets This function returns a list of coding systems that could be used to encode all the character sets in the list @var{charsets}. @@ -1130,6 +1142,7 @@ operates on the contents of @var{string} instead of bytes in the buffer. @end defun +@cindex null bytes, and decoding text @defvar inhibit-null-byte-detection If this variable has a non-@code{nil} value, null bytes are ignored when detecting the encoding of a region or a string. This allows to @@ -1146,6 +1159,7 @@ because many files in the Emacs distribution use ISO-2022 encoding.} @end defvar +@cindex charsets supported by a coding system @defun coding-system-charset-list coding-system This function returns the list of character sets (@pxref{Character Sets}) supported by @var{coding-system}. Some coding systems that @@ -1255,6 +1269,8 @@ @node Default Coding Systems @subsection Default Coding Systems +@cindex default coding system +@cindex coding system, automatically determined This section describes variables that specify the default coding system for certain files or when running certain subprograms, and the @@ -1267,6 +1283,7 @@ @code{coding-system-for-read} and @code{coding-system-for-write} (@pxref{Specifying Coding Systems}). +@cindex file contents, and default coding system @defvar auto-coding-regexp-alist This variable is an alist of text patterns and corresponding coding systems. Each element has the form @code{(@var{regexp} @@ -1279,6 +1296,7 @@ reads them with no code conversions. @end defvar +@cindex file name, and default coding system @defvar file-coding-system-alist This variable is an alist that specifies the coding systems to use for reading and writing particular files. Each element has the form @@ -1304,6 +1322,14 @@ @code{undecided}, the normal code-detection is performed. @end defvar +@defvar auto-coding-alist +This variable is an alist that specifies the coding systems to use for +reading and writing particular files. Its form is like that of +@code{file-coding-system-alist}, but, unlike the latter, this variable +takes priority over any @code{coding:} tags in the file. +@end defvar + +@cindex program name, and default coding system @defvar process-coding-system-alist This variable is an alist specifying which coding systems to use for a subprocess, depending on which program is running in the subprocess. It @@ -1327,6 +1353,8 @@ the end of line conversion---that is, one like @code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}. +@cindex port number, and default coding system +@cindex network service name, and default coding system @defvar network-coding-system-alist This variable is an alist that specifies the coding system to use for network streams. It works much like @code{file-coding-system-alist}, @@ -1346,6 +1374,7 @@ the subprocess, and @var{output-coding} applies to output to it. @end defvar +@cindex default coding system, functions to determine @defvar auto-coding-functions This variable holds a list of functions that try to determine a coding system for a file based on its undecoded contents. @@ -1362,6 +1391,39 @@ functions won't be called. @end defvar +@defun find-auto-coding filename size +This function tries to determine a suitable coding system for +@var{filename}. It examines the buffer visiting the named file, using +the variables documented above in sequence, until it finds a match for +one of the rules specified by these variables. It then returns a cons +cell of the form @code{(@var{coding} . @var{source})}, where +@var{coding} is the coding system to use and @var{source} is a symbol, +one of @code{auto-coding-alist}, @code{auto-coding-regexp-alist}, +@code{:coding}, or @code{auto-coding-functions}, indicating which one +supplied the matching rule. The value @code{:coding} means the coding +system was specified by the @code{coding:} tag in the file +(@pxref{Specify Coding,, coding tag, emacs, The GNU Emacs Manual}). +The order of looking for a matching rule is @code{auto-coding-alist} +first, then @code{auto-coding-regexp-alist}, then the @code{coding:} +tag, and lastly @code{auto-coding-functions}. If no matching rule was +found, the function returns @code{nil}. + +The second argument @var{size} is the size of text, in characters, +following point. The function examines text only within @var{size} +characters after point. Normally, the buffer should be positioned at +the beginning when this function is called, because one of the places +for the @code{coding:} tag is the first one or two lines of the file; +in that case, @var{size} should be the size of the buffer. +@end defun + +@defun set-auto-coding filename size +This function returns a suitable coding system for file +@var{filename}. It uses @code{find-auto-coding} to find the coding +system. If no coding system could be determined, the function returns +@code{nil}. The meaning of the argument @var{size} is like in +@code{find-auto-coding}. +@end defun + @defun find-operation-coding-system operation &rest arguments This function returns the coding system to use (by default) for performing @var{operation} with @var{arguments}. The value has this