Document `initial-buffer-choice' changes.

* doc/emacs/entering.texi: Document `initial-buffer-choice' changes.

* doc/emacs/misc.texi (arguments): Document `initial-buffer-choice' changes.

* doc/lispref/os.texi: Document `initial-buffer-choice' changes.

6 files changed, 25 insertions, 13 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 2a7a03d5278..f2be12e2002 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,5 +1,9 @@
 2013-12-20  Tassilo Horn  <tsdh@gnu.org>
 
+        * entering.texi: Document `initial-buffer-choice' changes.
+
+        * misc.texi (arguments): Document `initial-buffer-choice' changes.
+
         * help.texi: Document that `?' now also shows subcommands of
         prefix keys.
 
diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi
index bb89e6ffd8b..66b90d14476 100644
--- a/doc/emacs/entering.texi
+++ b/doc/emacs/entering.texi
@@ -74,11 +74,14 @@ up before reading @file{site-start.el}.  @xref{Init File}, for
 information about @file{site-start.el}.}
 
   You can also force Emacs to display a file or directory at startup
-by setting the variable @code{initial-buffer-choice} to a
-non-@code{nil} value.  (In that case, even if you specify one or more
-files on the command line, Emacs opens but does not display them.)
-The value of @code{initial-buffer-choice} should be the name of
-the desired file or directory.
+by setting the variable @code{initial-buffer-choice} to a a string
+naming that file or directory.  The value of
+@code{initial-buffer-choice} may also be a function which should
+return a buffer which is then displayed.  @code{initial-buffer-choice}
+may also be @code{t} in which case the @file{*scratch*} buffer will be
+shown.  In any case, even if you specify one or more files on the
+command line, Emacs opens but does not display them if
+@code{initial-buffer-choice} is non-nil.
 
 @node Exiting
 @section Exiting Emacs
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 73c1c85e2f8..d2dfe281d7c 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -1542,9 +1542,9 @@ option, like the @samp{-t} option, creates a new frame in the server's
 current text terminal.  @xref{Windows Startup}.
 
 If you omit a filename argument while supplying the @samp{-c} option,
-the new frame displays the @file{*scratch*} buffer by default.  If
-@code{initial-buffer-choice} is a string (@pxref{Entering Emacs}), the
-new frame displays that file or directory instead.
+the new frame displays the @file{*scratch*} buffer by default.  This
+behavior can be customized using the variable
+@code{initial-buffer-choice} (@pxref{Entering Emacs}).
 
 @item -F @var{alist}
 @itemx --frame-parameters=@var{alist}
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 3ae7e0040cc..64c3ec42ca6 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2013-12-20  Tassilo Horn  <tsdh@gnu.org>
+
+        * os.texi: Document `initial-buffer-choice' changes.
+
 2013-12-20  Chong Yidong  <cyd@gnu.org>
 
         * text.texi (Changing Properties): Improve documentation for
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 38ebcccb688..bb2a797b637 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -195,7 +195,9 @@ It now exits if the option @code{--batch} was specified.
 
 @item
 If @code{initial-buffer-choice} is a string, it visits the file with
-that name.  If the @file{*scratch*} buffer exists and is
+that name.  If it is a function, it calls the function and selects the
+buffer returned by the function.  It it is @code{t}, it selects the
+@file{*scratch*} buffer.  If the @file{*scratch*} buffer exists and is
 empty, it inserts @code{initial-scratch-message} into that buffer.
 
 @c To make things nice and confusing, the next three items can be
@@ -271,11 +273,9 @@ aliases for this variable.
 If non-@code{nil}, this variable is a string that specifies a file or
 directory for Emacs to display after starting up, instead of the
 startup screen.
-@ignore
-@c I do not think this should be mentioned.  AFAICS it is just a dodge
-@c around inhibit-startup-screen not being settable on a site-wide basis.
+If its value is a function, Emacs calls that function which must
+return a buffer which is then displayed.
 If its value is @code{t}, Emacs displays the @file{*scratch*} buffer.
-@end ignore
 @end defopt
 
 @defopt inhibit-startup-echo-area-message
diff --git a/etc/NEWS b/etc/NEWS
index a533b27d61f..dca067640d0 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -135,6 +135,7 @@ that want to ignore directory-locals while still respecting file-locals.
 This unfinished feature was introduced by accident in Emacs 23.1;
 simply disabling Transient Mark mode does the same thing.
 
++++
 ** `initial-buffer-choice' can now specify a function to set up the
 initial buffer.