* os.texi (Startup Summary): Copyedits. The init file is not

necessarily named .emacs now.  Document initial-buffer-choice and
initial-scratch-message.  Note where Emacs exits in batch mode.
Document inhibit-splash-screen as an alias.
(Init File): Be neutral about which init file name to use.

2 files changed, 96 insertions, 72 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index f5f7727daf7..bc9d3a4c9e9 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,15 @@
+2009-04-20  Chong Yidong  <cyd@stupidchicken.com>
+
+        * os.texi (Startup Summary): Copyedits.  The init file is not
+        necessarily named .emacs now.  Document initial-buffer-choice and
+        initial-scratch-message.  Note where Emacs exits in batch mode.
+        Document inhibit-splash-screen as an alias.
+        (Init File): Be neutral about which init file name to use.
+
+2009-04-16  Chong Yidong  <cyd@stupidchicken.com>
+
+        * os.texi (System Interface): Fix Texinfo usage.
+
 2009-04-15  Chong Yidong  <cyd@stupidchicken.com>
 
         * searching.texi (Regexp Backslash): Also refer to shy groups as
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index c5f0bdb6ffa..041e23a810b 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -11,9 +11,9 @@
 values in the operating system environment, and terminal input, output,
 and flow control.
 
-  @xref{Building Emacs}, for related information.  See also
-@ref{Display}, for additional operating system status information
-pertaining to the terminal and the screen.
+  @xref{Building Emacs}, for related information.  @xref{Display}, for
+additional operating system status information pertaining to the
+terminal and the screen.
 
 @menu
 * Starting Up::         Customizing Emacs startup processing.
@@ -46,7 +46,7 @@ can customize these actions.
 
 @menu
 * Startup Summary::         Sequence of actions Emacs performs at startup.
-* Init File::               Details on reading the init file (@file{.emacs}).
+* Init File::               Details on reading the init file.
 * Terminal-Specific::       How the terminal-specific Lisp file is read.
 * Command-Line Arguments::  How command-line arguments are processed,
                               and how you can customize them.
@@ -58,23 +58,23 @@ can customize these actions.
 @cindex startup of Emacs
 @cindex @file{startup.el}
 
-   The order of operations performed (in @file{startup.el}) by Emacs when
-it is started up is as follows:
+  When Emacs is started up, it performs the following operations
+(which are defined in @file{startup.el}):
 
 @enumerate
 @item
 It adds subdirectories to @code{load-path}, by running the file named
-@file{subdirs.el} in each directory in the list.  Normally this file
-adds the directory's subdirectories to the list, and these will be
-scanned in their turn.  The files @file{subdirs.el} are normally
-generated automatically by Emacs installation.
+@file{subdirs.el} in each directory in the list.  Normally, this file
+adds the directory's subdirectories to the list, and those are scanned
+in their turn.  The files @file{subdirs.el} are normally generated
+automatically when Emacs is installed.
 
 @vindex before-init-time
 @item
-It records in the variable @code{before-init-time} the value of
+It sets the variable @code{before-init-time} to the value of
 @code{current-time} (@pxref{Time of Day}).  It also sets
-@code{after-init-time} to @code{nil}, so as to signal Lisp programs
-that Emacs initialization is in progress.
+@code{after-init-time} to @code{nil}, which signals to Lisp programs
+that Emacs is being initialized.
 
 @vindex initial-window-system@r{, and startup}
 @vindex window-system-initialization-alist
@@ -85,8 +85,8 @@ initial-window-system}).  This library's name is
 @file{term/@var{windowsystem}-win.el}, where @var{windowsystem} is the
 value of @code{initial-window-system}.  From that library, it calls
 the appropriate initialization function.  The initialization function
-is specified by @code{window-system-initialization-alist}, for each
-supported window system.
+for each supported window system is specified by
+@code{window-system-initialization-alist}.
 
 @item
 It sets the language environment and the terminal coding system,
@@ -104,58 +104,49 @@ It initializes the window frame and faces, if appropriate, and turns
 on the menu bar and tool bar, if the initial frame needs them.
 
 @item
-It registers the default colors for text-only terminals.
-
-@item
-It loads the library @file{site-start} (if any), unless the option
-@samp{-Q} (or @samp{--no-site-file}) was specified.  The library's file
-name is usually @file{site-start.el}.
+It loads the library @file{site-start}, if it exists.  This is not
+done if the options @samp{-Q} or @samp{--no-site-file} were specified.
 @cindex @file{site-start.el}
 
 @item
-It loads your init file (usually @file{~/.emacs}), unless the option
-@samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was
-specified on the command line.  The @samp{-u} option can specify
-another user whose home directory should be used instead of @file{~}.
+It loads your init file (@pxref{Init File}).  This is not done if the
+options @samp{-q}, @samp{-Q}, or @samp{--batch} were specified.  If
+the @samp{-u} option was specified, Emacs looks for the init file in
+that user's home directory instead.
 
 @item
-It loads the library @file{default} (if any), unless
-@code{inhibit-default-init} is non-@code{nil}.  (This is not done in
-@samp{-batch} mode, or if @samp{-Q} or @samp{-q} was specified on the
-command line.)  The library's file name is usually @file{default.el}.
+It loads the library @file{default}, if it exists.  This is not done
+if @code{inhibit-default-init} is non-@code{nil}, nor if the options
+@samp{-q}, @samp{-Q}, or @samp{--batch} were specified.
 @cindex @file{default.el}
 
 @item
 It loads your abbrevs from the file specified by
-@code{abbrev-file-name} (@pxref{Abbrev Files, abbrev-file-name}), if
-that file exists and can be read.  (This is not done in @samp{-batch}
-mode.)
+@code{abbrev-file-name}, if that file exists and can be read
+(@pxref{Abbrev Files, abbrev-file-name}).  This is not done if the
+option @samp{--batch} was specified.
 
 @vindex after-init-time
 @item
-It records in the variable @code{after-init-time} the value of
-@code{current-time}.  This variable was set to @code{nil} at the
-beginning of the Emacs session initialization (see above), so setting
-it to the current time both signals that the initialization phase is
-over, and, together with @code{before-init-time}, provides the
+It sets the variable @code{after-init-time} to the value of
+@code{current-time}.  This variable was set to @code{nil} earlier;
+setting it to the current time signals that the initialization phase
+is over, and, together with @code{before-init-time}, provides the
 measurement of how long it took.
 
 @item
 It runs the normal hook @code{after-init-hook}.
 
 @item
-It sets the major mode according to @code{initial-major-mode}, provided
-the buffer @samp{*scratch*} is still current and still in Fundamental
-mode.
+If the buffer @samp{*scratch*} exists and is still in Fundamental mode
+(as it should be by default), it sets its major mode according to
+@code{initial-major-mode}.
 
 @item
-It loads the terminal-specific Lisp library, if any, except when in
-batch mode or when the variable @code{initial-window-system} (see
-above) specifies a non-@code{nil} window system.  The name of this
-library is computed from the value of the variable
-@code{term-file-prefix}; for the details, see @ref{Terminal-Specific}.
-
-If the value of @code{term-file-prefix} is @code{nil}, this step is skipped.
+If started on a text-only terminal, it loads the terminal-specific
+Lisp library, which is specified by the variable
+@code{term-file-prefix} (@pxref{Terminal-Specific}).  This is not done
+in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}.
 
 @item
 It displays the initial echo area message, unless you have suppressed
@@ -165,6 +156,14 @@ that with @code{inhibit-startup-echo-area-message}.
 It processes the action arguments from the command line.
 
 @item
+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.  Furthermore, if the @samp{*scratch*} buffer exists and is
+empty, it inserts @code{initial-scratch-message} into that buffer.
+
+@item
 It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
 
 @item
@@ -176,14 +175,16 @@ specify.
 It runs @code{window-setup-hook}.  @xref{Window Systems}.
 
 @item
-It displays copyleft, nonwarranty, and basic use information, provided
-the value of @code{inhibit-startup-screen} is @code{nil}, you didn't
-specify @samp{--no-splash} or @samp{-Q}.
+If the option @code{--daemon} was specified, it calls
+@code{server-start} and detaches from the controlling terminal.
+@xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
 
 @item
-If the command-line arguments specified @option{--daemon}, @c FIXME: xref
-it calls @code{server-start} (@pxref{Emacs Server,,, emacs, The GNU
-Emacs Manual}).
+It displays the @dfn{startup screen}, which is a special buffer that
+contains information about copyleft and basic Emacs usage.  This is
+not done if @code{initial-buffer-choice} or
+@code{inhibit-startup-screen} are @code{nil}, nor if the
+@samp{--no-splash} or @samp{-Q} command-line options were specified.
 
 @item
 If started by the X session manager, it calls
@@ -192,17 +193,24 @@ previous session.  @c FIXME: add an xref to the Emacs manual!
 @end enumerate
 
 @defopt inhibit-startup-screen
-This variable inhibits the initial startup messages (the nonwarranty,
-etc.).  If it is non-@code{nil}, then the messages are not printed.
+This variable, if non-@code{nil}, inhibits the startup screen.  In
+that case, Emacs typically displays the @samp{*scratch*} buffer; but
+see @code{initial-buffer-choice}, below.
 
-This variable exists so you can set it in your personal init file, once
-you are familiar with the contents of the startup message.  Do not set
-this variable in the init file of a new user, or in a way that affects
-more than one user, because that would prevent new users from receiving
-the information they are supposed to see.
+Do not set this variable in the init file of a new user, or in a way
+that affects more than one user, as that would prevent new users from
+receiving information about copyleft and basic Emacs usage.
 
-@code{inhibit-startup-message} is an alias for this variable, for
-back-compatibility.
+@code{inhibit-startup-message} and @code{inhibit-splash-screen} are
+aliases for this variable.
+@end defopt
+
+@defopt initial-buffer-choice
+This variable, if non-@code{nil}, determines a file or buffer for
+Emacs to display after starting up, instead of the startup screen.  If
+its value is @code{t}, Emacs displays the @samp{*scratch*} buffer.  If
+its value is a string, that specifies the name of a file for Emacs to
+visit.
 @end defopt
 
 @defopt inhibit-startup-echo-area-message
@@ -219,11 +227,15 @@ Emacs explicitly checks for an expression as shown above in your init
 file; your login name must appear in the expression as a Lisp string
 constant.  Other methods of setting
 @code{inhibit-startup-echo-area-message} to the same value do not
-inhibit the startup message.
+inhibit the startup message.  This way, you can easily inhibit the
+message for yourself if you wish, but thoughtless copying of your init
+file will not inhibit the message for someone else.
+@end defopt
 
-This way, you can easily inhibit the message for yourself if you wish,
-but thoughtless copying of your init file will not inhibit the message
-for someone else.
+@defopt initial-scratch-message
+This variable, if non-@code{nil}, should be a string, which is
+inserted into the @samp{*scratch*} buffer when Emacs starts up.  If it
+is @code{nil}, the @samp{*scratch*} buffer is empty.
 @end defopt
 
 @node Init File
@@ -232,12 +244,12 @@ for someone else.
 @cindex @file{.emacs}
 
   When you start Emacs, it normally attempts to load your @dfn{init
-file}, a file in your home directory.  Its normal name is
-@file{.emacs}, but you can also call it @file{.emacs.el}.
-Alternatively, you can use a file named @file{init.el} in a
-subdirectory @file{.emacs.d}.  Whichever place you use, you can also
-compile the file (@pxref{Byte Compilation}); then the actual file
-loaded will be @file{.emacs.elc} or @file{init.elc}.
+file}.  This is either a file named @file{.emacs} or @file{.emacs.el}
+in your home directory, or a file named @file{init.el} in a
+subdirectory named @file{.emacs.d} in your home directory.  Whichever
+place you use, you can also compile the file (@pxref{Byte
+Compilation}); then the actual file loaded will be @file{.emacs.elc}
+or @file{init.elc}.
 
   The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
 control whether and where to find the init file; @samp{-q} (and the