1 files changed, 32 insertions, 11 deletions
diff --git a/README b/README
index f30b037f6..9f5195bea 100644
--- a/README
+++ b/README
@@ -136,6 +136,17 @@ The variable HOME is no longer set by the shell if zsh is emulating any
 other shell at startup; it must be present in the environment or set
 subsequently by the user.  It is valid for the variable to be unset.
 
+If the shell starts in a mode where it is emulating another shell
+(typically because the base name of the shell was "sh" or another known
+shell), the "repeat" syntax is not available by default, to avoid clashes
+with external commands, but the "ulimit" command is available by default.
+"limit", "sched" and "unlimit" are not available by default in such modes:
+this has been the case for many versions but is now documented for the
+first time.  (Users should note that emulation modes are not designed for
+backwards compatibility with previous versions of zsh, but to maximise
+compatibility with other shells, hence it is not safe to assume emulation
+modes will behave consistently between zsh versions.)
+
 Parameter substitutions in the form ${param//#%search/replace} match
 against "search" anchored at both ends of the parameter value.  Previously
 this syntax would have matched against "%search", anchored only at the head
@@ -143,23 +154,33 @@ of the value.  The form ${param//#$search/replace} where the value
 $search starts with "%" considers the "%" to be part of the search
 string as before.
 
-The MULTIBYTE option is on by default where it is available; this
-causes many operations to recognise characters as in the current locale.
-Older versions of the shell always assumed a character was one byte.
-In some places the width of the character will be used; this is transparent
-when used for calculations of screen position, but also occurs, for
-example, in calculations of padding width.  Note that MULTIBYTE is
-not automatically set when emulating Bourne- and POSIX-style shells;
-for interative use of these emulations it may be necessary to set
-it by hand.
+Configure attempts to decide if multibyte characters are supported by the
+system and if so sets the effect of --enable-multibyte, unless
+--disable-multibyte was passed on the command line.  When
+--enable-multibyte is in effect, the MULTIBYTE shell option is on by
+default; this causes many operations to recognise characters in the current
+locale.  (Most typically this is used for a UTF-8 character set but the
+shell will work with any character set provided by the system where
+individual octets are either US ASCII characters or have the top bit set.)
+Older versions of the shell always assumed a character was one byte; this
+remains the case if --disable-multibyte is in effect or if the MULTIBYTE
+option is unset.  In some places the width of characters will be taken into
+account where previously a raw string length was used; this is transparent
+in calculations of screen position, but also occurs, for example, in
+calculations of padding width.  Note that MULTIBYTE is not automatically
+set when emulating Bourne- and POSIX-style shells; for interactive use of
+these emulations it may be necessary to set it by hand.  Note also that the
+option COMBINING_CHARS is not set by default due to difficulties detecting
+the ability of the terminal to display combining characters correctly; MAC
+users in particular will probably wish to set this option.
 
 Zsh has previously been lax about whether it allows octets with the
 top bit set to be part of a shell identifier.  Older versions of the shell
 assumed all such octets were allowed in identifiers, however the POSIX
 standard does not allow such characters in identifiers.  The older
 behaviour is still obtained with --disable-multibyte in effect.
-With --enable-multibyte in effect (this is now the default anywhere
-it is supported) there are three possible cases:
+With --enable-multibyte in effect (see previous paragraph) there are three
+possible cases:
   MULTIBYTE option unset:  only ASCII characters are allowed; the
     shell does not attempt to identify non-ASCII characters at all.
   MULTIBYTE option set, POSIX_IDENTIFIERS option unset: in addition