comparison doc/lispref/os.texi @ 103024:91ec7dabacb2

* 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.

103023:30ed0fca4cdd

  This chapter is about starting and getting out of Emacs, access to
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.

@menu
* Starting Up::         Customizing Emacs startup processing.
* Getting Out::         How exiting works (permanent or temporary).
* System Environment::  Distinguish the name and kind of system.

  This section describes what Emacs does when it is started, and how you
can customize these actions.

@menu
* Startup Summary::         Sequence of actions Emacs performs at startup.
* Init File::               Details on reading the init file (@file{.emacs}).
* 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.
@end menu

@subsection Summary: Sequence of Actions at Startup
@cindex initialization of Emacs
@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:

@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.

@vindex before-init-time
@item
It records in the variable @code{before-init-time} 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.

@vindex initial-window-system@r{, and startup}
@vindex window-system-initialization-alist
@item
It loads the initialization library for the window system specified by
the variable @code{initial-window-system} (@pxref{Window Systems,
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.

@item
It sets the language environment and the terminal coding system,
if requested by environment variables such as @code{LANG}.

@item
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}.
@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{~}.

@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}.
@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.)

@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
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.

@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.

@item
It displays the initial echo area message, unless you have suppressed
that with @code{inhibit-startup-echo-area-message}.

@item
It processes the action arguments from the command line.

@item
It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.

@item

@item
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}.

@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}).

@item
If started by the X session manager, it calls
@code{emacs-session-restore} passing it as argument the ID of the
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 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.

@code{inhibit-startup-message} is an alias for this variable, for
back-compatibility.
@end defopt

@defopt inhibit-startup-echo-area-message
This variable controls the display of the startup echo area message.
You can suppress the startup echo area message by adding text with this

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.

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

@node Init File
@subsection The Init File, @file{.emacs}
@cindex init file
@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}.

  The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
control whether and where to find the init file; @samp{-q} (and the
stronger @samp{-Q}) says not to load an init file, while @samp{-u
@var{user}} says to load @var{user}'s init file instead of yours.

103024:91ec7dabacb2

  This chapter is about starting and getting out of Emacs, access to
values in the operating system environment, and terminal input, output,
and flow control.

  @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.
* Getting Out::         How exiting works (permanent or temporary).
* System Environment::  Distinguish the name and kind of system.

  This section describes what Emacs does when it is started, and how you
can customize these actions.

@menu
* Startup Summary::         Sequence of actions Emacs performs at startup.
* 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.
@end menu

@subsection Summary: Sequence of Actions at Startup
@cindex initialization of Emacs
@cindex startup of Emacs
@cindex @file{startup.el}

  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 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 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}, which signals to Lisp programs
that Emacs is being initialized.

@vindex initial-window-system@r{, and startup}
@vindex window-system-initialization-alist
@item
It loads the initialization library for the window system specified by
the variable @code{initial-window-system} (@pxref{Window Systems,
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
for each supported window system is specified by
@code{window-system-initialization-alist}.

@item
It sets the language environment and the terminal coding system,
if requested by environment variables such as @code{LANG}.

@item
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 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 (@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 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}, 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 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
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
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
that with @code{inhibit-startup-echo-area-message}.

@item
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

@item
It runs @code{window-setup-hook}.  @xref{Window Systems}.

@item
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
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
@code{emacs-session-restore} passing it as argument the ID of the
previous session.  @c FIXME: add an xref to the Emacs manual!
@end enumerate

@defopt inhibit-startup-screen
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.

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} 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
This variable controls the display of the startup echo area message.
You can suppress the startup echo area message by adding text with this

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.  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

@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
@subsection The Init File, @file{.emacs}
@cindex init file
@cindex @file{.emacs}

  When you start Emacs, it normally attempts to load your @dfn{init
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
stronger @samp{-Q}) says not to load an init file, while @samp{-u
@var{user}} says to load @var{user}'s init file instead of yours.