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.

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.
 

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

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}

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

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

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.