@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node System Interface
automatically when Emacs is installed.
@item
-If the library @file{leim-list.el} exists, Emacs loads it. This
-optional library is intended for registering input methods; Emacs
-looks for it in @code{load-path} (@pxref{Library Search}), skipping
-those directories containing the standard Emacs libraries (since
-@file{leim-list.el} should not exist in those directories).
+It loads any @file{leim-list.el} that it finds in the @code{load-path}
+directories. This file is intended for registering input methods.
+The search is only for any personal @file{leim-list.el} files that you
+may have created; it skips the directories containing the standard Emacs
+libraries (these should contain only a single @file{leim-list.el} file,
+which is compiled into the Emacs executable).
@vindex before-init-time
@item
@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
It runs @code{window-setup-hook}. @xref{Window Systems}.
@item
+@cindex startup screen
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{inhibit-startup-screen} or @code{initial-buffer-choice}
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
Do not initialize any display; just start a server in the background.
@item --no-init-file
-@itemx -Q
+@itemx -q
Do not load either the init file, or the @file{default} library.
@item --no-site-file
The value of this variable is @code{t} once the command line has been
processed.
-If you redump Emacs by calling @code{dump-emacs}, you may wish to set
-this variable to @code{nil} first in order to cause the new dumped Emacs
-to process its new command-line arguments.
+If you redump Emacs by calling @code{dump-emacs} (@pxref{Building
+Emacs}), you may wish to set this variable to @code{nil} first in
+order to cause the new dumped Emacs to process its new command-line
+arguments.
@end defvar
@defvar command-switch-alist
In some cases, the option is followed in the command line by an
argument. In these cases, the @var{handler-function} can find all the
remaining command-line arguments in the variable
-@code{command-line-args-left}. (The entire list of command-line
-arguments is in @code{command-line-args}.)
+@code{command-line-args-left} (see below). (The entire list of
+command-line arguments is in @code{command-line-args}.)
The command-line arguments are parsed by the @code{command-line-1}
function in the @file{startup.el} file. See also @ref{Emacs
removes @var{variable} from the environment. Otherwise, @var{value}
should be a string.
+@c FIXME: Document `substitute-env-vars'? --xfq
If the optional argument @var{substitute} is non-@code{nil}, Emacs
calls the function @code{substitute-env-vars} to expand any
environment variables in @var{value}.
Lisp packages that load files of customizations, or any other sort of
user profile, should obey this variable in deciding where to find it.
They should load the profile of the user name found in this variable.
-If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
-option was used, then Lisp packages should not load any customization
-files or user profile.
+If @code{init-file-user} is @code{nil}, meaning that the @samp{-q},
+@samp{-Q}, or @samp{-batch} option was used, then Lisp packages should
+not load any customization files or user profile.
@end defvar
@defopt user-mail-address
variables are also useful for constructing frame titles (@pxref{Frame
Titles}).
+@cindex UID
@defun user-real-uid
This function returns the real @acronym{UID} of the user.
The value may be a floating point number, in the (unlikely) event that
The value may be a floating point number.
@end defun
+@cindex GID
@defun group-gid
This function returns the effective @acronym{GID} of the Emacs process.
The value may be a floating point number.
argument to @code{current-time-string}, two-, three-, and four-integer
lists are accepted. You can convert times from the list
representation into standard human-readable strings using
-@code{current-time}, or to other forms using the @code{decode-time}
-and @code{format-time-string} functions documented in the following
-sections.
+@code{current-time-string}, or to other forms using the
+@code{decode-time} and @code{format-time-string} functions documented
+in the following sections.
@defun current-time-string &optional time-value
This function returns the current time and date as a human-readable
@end defun
@defun current-time-zone &optional time-value
+@cindex time zone, current
This function returns a list describing the time zone that the user is
in.
@node Time Conversion
@section Time Conversion
+@cindex calendrical information
These functions convert time values (lists of two to four integers,
as explained in the previous section) into calendrical information and
@defun seconds-to-time seconds
This function converts @var{seconds}, a floating point number of
seconds since the epoch, to a time value and returns that. To perform
-the inverse conversion, use @code{float-time}.
+the inverse conversion, use @code{float-time} (@pxref{Time of Day}).
@end defun
@defun format-seconds format-string seconds
both elapsed and processor time, used by the Emacs process.
@deffn Command emacs-uptime &optional format
+@cindex uptime of Emacs
This function returns a string representing the Emacs
@dfn{uptime}---the elapsed wall-clock time this instance of Emacs is
running. The string is formatted by @code{format-seconds} according
@defun set-input-mode interrupt flow meta &optional quit-char
This function sets the mode for reading keyboard input. If
-@var{interrupt} is non-null, then Emacs uses input interrupts. If it is
-@code{nil}, then it uses @sc{cbreak} mode. The default setting is
-system-dependent. Some systems always use @sc{cbreak} mode regardless
-of what is specified.
+@var{interrupt} is non-@code{nil}, then Emacs uses input interrupts.
+If it is @code{nil}, then it uses @sc{cbreak} mode. The default
+setting is system-dependent. Some systems always use @sc{cbreak} mode
+regardless of what is specified.
When Emacs communicates directly with X, it ignores this argument and
uses interrupts if that is the way it knows how to communicate.
were actually output, you can determine reliably whether they correspond
to the Termcap specifications in use.
-You close the termscript file by calling this function with an
-argument of @code{nil}.
-
-See also @code{open-dribble-file} in @ref{Recording Input}.
-
@example
@group
(open-termscript "../junk/termscript")
@result{} nil
@end group
@end example
+
+You close the termscript file by calling this function with an
+argument of @code{nil}.
+
+See also @code{open-dribble-file} in @ref{Recording Input}.
@end deffn
@node Sound Output
certain systems are supported; if you call @code{play-sound} on a
system which cannot really do the job, it gives an error.
+@c FIXME: Add indexes for Au and WAV? --xfq
The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
or Sun Audio format (@samp{.au}).
@var{session}}.
@defvar emacs-save-session-functions
+@cindex session file
Emacs supports saving state via a hook called
@code{emacs-save-session-functions}. Emacs runs this hook when the
session manager tells it that the window system is shutting down. The
@node Desktop Notifications
@section Desktop Notifications
@cindex desktop notifications
+@cindex notifications, on desktop
Emacs is able to send @dfn{notifications} on systems that support the
freedesktop.org Desktop Notifications Specification. In order to use
this functionality, Emacs must have been compiled with D-Bus support,
-and the @code{notifications} library must be loaded.
+and the @code{notifications} library must be loaded. @xref{Top, ,
+D-Bus,dbus,D-Bus integration in Emacs}.
@defun notifications-notify &rest params
This function sends a notification to the desktop via D-Bus,
@node File Notifications
@section Notifications on File Changes
@cindex file notifications
+@cindex watch, for filesystem events
Several operating systems support watching of filesystems for changes
of files. If configured properly, Emacs links a respective library