[Emacs-diffs] emacs-25 0e35405: Improve documentation of coding-systems

[Eli Zaretskii]

branch: emacs-25
commit 0e35405a92be502ab3851890fc4eb660842fd3a9
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of coding-systems
    
    * doc/lispref/nonascii.texi (Coding System Basics): Mention
    'prefer-utf-8'.  Index it and 'undecided'.
    (Encoding and I/O): Fix a typo.
    (User-Chosen Coding Systems): Improve the documentation of
    ACCEPT-DEFAULT-P argument to select-safe-coding-system.  Document
    select-safe-coding-system-function.
    (Specifying Coding Systems): Document coding-system-require-warning.
---
 doc/lispref/nonascii.texi |   65 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 51 insertions(+), 14 deletions(-)

diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index ab8f2fc..e3cb5d0 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -1002,10 +1002,14 @@ alternative encodings for the same characters; for 
example, there are
 three coding systems for the Cyrillic (Russian) alphabet: ISO,
 Alternativnyj, and KOI8.
 
address@hidden address@hidden coding system}
address@hidden address@hidden coding system}
   Every coding system specifies a particular set of character code
 conversions, but the coding system @code{undecided} is special: it
 leaves the choice unspecified, to be chosen heuristically for each
-file, based on the file's data.
+file, based on the file's data.  The coding system @code{prefer-utf-8}
+is like @code{undecided}, but it prefers to choose @code{utf-8} when
+possible.
 
   In general, a coding system doesn't guarantee roundtrip identity:
 decoding a byte sequence using coding system, then encoding the
@@ -1109,7 +1113,7 @@ encode the buffer contents.
 (@pxref{Specifying Coding Systems}), or implicitly using a default
 mechanism (@pxref{Default Coding Systems}).  But these methods may not
 completely specify what to do.  For example, they may choose a coding
-system such as @code{undefined} which leaves the character code
+system such as @code{undecided} which leaves the character code
 conversion to be determined from the data.  In these cases, the I/O
 operation finishes the job of choosing a coding system.  Very often
 you will want to find out afterwards which coding system was chosen.
@@ -1411,19 +1415,21 @@ Otherwise, it asks the user to choose from a list of 
coding systems
 which can encode all the text, and returns the user's choice.
 
 @var{default-coding-system} can also be a list whose first element is
-t and whose other elements are coding systems.  Then, if no coding
address@hidden and whose other elements are coding systems.  Then, if no coding
 system in the list can handle the text, @code{select-safe-coding-system}
 queries the user immediately, without trying any of the three
-alternatives described above.
-
-The optional argument @var{accept-default-p}, if address@hidden,
-should be a function to determine whether a coding system selected
-without user interaction is acceptable.  @code{select-safe-coding-system}
-calls this function with one argument, the base coding system of the
-selected coding system.  If @var{accept-default-p} returns @code{nil},
address@hidden rejects the silently selected coding
-system, and asks the user to select a coding system from a list of
-possible candidates.
+alternatives described above.  This is handy for checking only the
+coding systems in the list.
+
+The optional argument @var{accept-default-p} determines whether a
+coding system selected without user interaction is acceptable.  If
+it's omitted or @code{nil}, such a silent selection is always
+acceptable.  If it is address@hidden, it should be a function;
address@hidden calls this function with one
+argument, the base coding system of the selected coding system.  If
+the function returns @code{nil}, @code{select-safe-coding-system}
+rejects the silently selected coding system, and asks the user to
+select a coding system from a list of possible candidates.
 
 @vindex select-safe-coding-system-accept-default-p
 If the variable @code{select-safe-coding-system-accept-default-p} is
@@ -1444,6 +1450,18 @@ similar functions).  If it detects an apparent 
inconsistency,
 coding system.
 @end defun
 
address@hidden select-safe-coding-system-function
+This variable names the function to be called to request the user to
+select a proper coding system for encoding text when the default
+coding system for an output operation cannot safely encode that text.
+The default value of this variable is @code{select-safe-coding-system}.
+Emacs primitives that write text to files, such as
address@hidden, or send text to other processes, such as
address@hidden, normally call the value of this variable,
+unless @code{coding-system-for-write} is bound to a address@hidden
+value (@pxref{Specifying Coding Systems}).
address@hidden defvar
+
   Here are two functions you can use to let the user specify a coding
 system, with completion.  @xref{Completion}.
 
@@ -1704,7 +1722,9 @@ including @code{file-coding-system-alist},
 @defvar coding-system-for-write
 This works much like @code{coding-system-for-read}, except that it
 applies to output rather than input.  It affects writing to files,
-as well as sending output to subprocesses and net connections.
+as well as sending output to subprocesses and net connections.  It
+also applies to encoding command-line arguments with which Emacs
+invokes subprocesses.
 
 When a single operation does both input and output, as do
 @code{call-process-region} and @code{start-process}, both
@@ -1712,6 +1732,23 @@ When a single operation does both input and output, as do
 affect it.
 @end defvar
 
address@hidden coding-system-require-warning
+Binding @code{coding-system-for-write} to a address@hidden value
+prevents output primitives from calling the function specified by
address@hidden (@pxref{User-Chosen Coding
+Systems}).  This is because @kbd{C-x RET c}
+(@code{universal-coding-system-argument}) works by binding
address@hidden, and Emacs should obey user selection.
+If a Lisp program binds @code{coding-system-for-write} to a value that
+might not be safe for encoding the text to be written, it can also bind
address@hidden to a address@hidden value, which
+will force the output primitives to check the encoding by calling the
+value of @code{select-safe-coding-system-function} even though
address@hidden is address@hidden  Alternatively, call
address@hidden explicitly before using the specified
+encoding.
address@hidden defvar
+
 @defopt inhibit-eol-conversion
 When this variable is address@hidden, no end-of-line conversion is done,
 no matter which coding system is specified.  This applies to all the