@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node System Interface
@item
It now exits if the option @code{--batch} was specified.
+@item
+If the @file{*scratch*} buffer exists and is empty, it inserts
+@code{(substitute-command-keys initial-scratch-message)} into that buffer.
+
@item
If @code{initial-buffer-choice} is a string, it visits the file (or
directory) with that name. If it is a function, it calls the function
-with no arguments and selects the buffer that it returns.
+with no arguments and selects the buffer that it returns. If one file
+is given as a command line argument, that file is visited and its
+buffer displayed alongside @code{initial-buffer-choice}. If more than
+one file is given, all of the files are visited and the @file{*Buffer
+List*} buffer is displayed alongside @code{initial-buffer-choice}.
+
@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 it is @code{t}, it selects the @file{*scratch*} buffer.
@end ignore
-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
@c called from two places. If displaying a startup screen, they are
@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}.
+@code{server-start}, and on Posix systems also detaches from the
+controlling terminal. @xref{Emacs Server,,, emacs, The GNU Emacs
+Manual}.
@item
If started by the X session manager, it calls
@defopt initial-scratch-message
This variable, if non-@code{nil}, should be a string, which is
+treated as documentation to be
inserted into the @file{*scratch*} buffer when Emacs starts up. If it
is @code{nil}, the @file{*scratch*} buffer is empty.
@end defopt
string.
@end defun
- The symbol @code{system-name} is a variable as well as a function. In
-fact, the function returns whatever value the variable
-@code{system-name} currently holds. Thus, you can set the variable
-@code{system-name} in case Emacs is confused about the name of your
-system. The variable is also useful for constructing frame titles
-(@pxref{Frame Titles}).
-
@c FIXME seems like this section is not the best place for this option?
@defopt mail-host-address
If this variable is non-@code{nil}, it is used instead of
removes @var{variable} from the environment. Otherwise, @var{value}
should be a string.
-@c FIXME: Document `substitute-env-vars'? --xfq
+@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}.
components defaulting to zero.
@cindex time value
- Function arguments, e.g., the @var{time-value} argument to
+ Function arguments, e.g., the @var{time} argument to
@code{current-time-string}, accept a more-general @dfn{time value}
format, which can be a list of integers as above, or a single number
for seconds since the epoch, or @code{nil} for the current time. You
@code{decode-time} and @code{float-time}. These functions are
described in the following sections.
-@defun current-time-string &optional time-value
+@defun current-time-string &optional time zone
This function returns the current time and date as a human-readable
string. The format does not vary for the initial part of the string,
which contains the day of week, month, day of month, and time of day
as the year might not have exactly four digits, and additional
information may some day be added at the end.
-The argument @var{time-value}, if given, specifies a time to format,
-instead of the current time.
+The argument @var{time}, if given, specifies a time to format,
+instead of the current time. The optional argument @var{zone}
+defaults to the current time zone rule.
@example
@group
become available.
@end defun
-@defun float-time &optional time-value
+@defun float-time &optional time
This function returns the current time as a floating-point number of
-seconds since the epoch. The optional argument @var{time-value}, if
+seconds since the epoch. The optional argument @var{time}, if
given, specifies a time to convert instead of the current time.
@emph{Warning}: Since the result is floating point, it may not be
@code{time-to-seconds} is an alias for this function.
@end defun
-@defun seconds-to-time time-value
+@defun seconds-to-time time
This function converts a time value to list-of-integer form.
-For example, if @var{time-value} is a number, @code{(time-to-seconds
-(seconds-to-time @var{time-value}))} equals the number unless overflow
+For example, if @var{time} is a number, @code{(time-to-seconds
+(seconds-to-time @var{time}))} equals the number unless overflow
or rounding errors occur.
@end defun
-@defun current-time-zone &optional time-value
+@defun current-time-zone &optional time zone
@cindex time zone, current
This function returns a list describing the time zone that the user is
in.
If the operating system doesn't supply all the information necessary to
compute the value, the unknown elements of the list are @code{nil}.
-The argument @var{time-value}, if given, specifies a time value to
-analyze instead of the current time.
+The argument @var{time}, if given, specifies a time value to
+analyze instead of the current time. The optional argument @var{zone}
+defaults to the current time zone rule.
@end defun
-The current time zone is determined by the @env{TZ} environment
+@vindex TZ, environment variable
+The default time zone is determined by the @env{TZ} environment
variable. @xref{System Environment}. For example, you can tell Emacs
-to use universal time with @code{(setenv "TZ" "UTC0")}. If @env{TZ}
-is not in the environment, Emacs uses a platform-dependent default
-time zone.
+to default to universal time with @code{(setenv "TZ" "UTC0")}. If
+@env{TZ} is not in the environment, Emacs uses system wall clock time,
+which is a platform-dependent default time zone.
+
+@cindex time zone rule
+Functions that convert to and from local time accept an optional
+@dfn{time zone rule} argument, which specifies the conversion's time
+zone and daylight saving time history. If the time zone rule is
+omitted or @code{nil}, the conversion uses Emacs's default time zone.
+If it is @code{t}, the conversion uses Universal Time. If it is
+@code{wall}, the conversion uses the system wall clock time. If it is
+a string, the conversion uses the time zone rule equivalent to setting
+@env{TZ} to that string.
@node Time Conversion
@section Time Conversion
as traditional Gregorian years do; for example, the year number
@minus{}37 represents the Gregorian year 38 B.C@.
-@defun decode-time &optional time-value
+@defun decode-time &optional time zone
This function converts a time value into calendrical information. If
-you don't specify @var{time-value}, it decodes the current time. The return
+you don't specify @var{time}, it decodes the current time, and similarly
+@var{zone} defaults to the current time zone rule. The return
value is a list of nine elements, as follows:
@example
-(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
+(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{utcoff})
@end example
Here is what the elements mean:
Sunday.
@item dst
@code{t} if daylight saving time is effect, otherwise @code{nil}.
-@item zone
-An integer indicating the time zone, as the number of seconds east of
-Greenwich.
+@item utcoff
+An integer indicating the UTC offset in seconds, i.e., the number of
+seconds east of Greenwich.
@end table
@strong{Common Lisp Note:} Common Lisp has different meanings for
-@var{dow} and @var{zone}.
+@var{dow} and @var{utcoff}.
@end defun
@defun encode-time seconds minutes hour day month year &optional zone
to stand for years above 1900, or years above 2000, you must alter them
yourself before you call @code{encode-time}.
-The optional argument @var{zone} defaults to the current time zone and
-its daylight saving time rules. If specified, it can be either a list
-(as you would get from @code{current-time-zone}), a string as in the
-@env{TZ} environment variable, @code{t} for Universal Time, or an
-integer (as you would get from @code{decode-time}). The specified
-zone is used without any further alteration for daylight saving time.
+The optional argument @var{zone} defaults to the current time zone rule.
+In addition to the usual time zone rule values, it can also be a list
+(as you would get from @code{current-time-zone}) or an integer (as
+from @code{decode-time}), applied without any further alteration for
+daylight saving time.
If you pass more than seven arguments to @code{encode-time}, the first
six are used as @var{seconds} through @var{year}, the last argument is
corresponding time value.
@end defun
-@defun format-time-string format-string &optional time-value universal
+@defun format-time-string format-string &optional time zone
-This function converts @var{time-value} (or the current time, if
-@var{time-value} is omitted) to a string according to
-@var{format-string}. The argument
+This function converts @var{time} (or the current time, if
+@var{time} is omitted) to a string according to
+@var{format-string}. The conversion uses the time zone rule @var{zone}
+(or the current time zone rule, if omitted). The argument
@var{format-string} may contain @samp{%}-sequences which say to
substitute parts of the time. Here is a table of what the
@samp{%}-sequences mean:
@example
(defvar my-resume-timer nil
- "Timer for `my-timer-function' to reschedule itself, or nil.")
+ "Timer for ‘my-timer-function’ to reschedule itself, or nil.")
(defun my-timer-function ()
;; @r{If the user types a command while @code{my-resume-timer}}
@item :sound-name @var{name}
A themable named sound from the freedesktop.org sound naming
specification from @samp{$XDG_DATA_DIRS/sounds}, to play when the
-notification pops up. Similar to the icon name, only for sounds. An
+notification pops up. Similar to the icon name, only for sounds. An
example would be @samp{"message-new-instant"}.
@item :suppress-sound
@item :resident
When set the server will not automatically remove the notification
-when an action has been invoked. The notification will remain resident
+when an action has been invoked. The notification will remain resident
in the server until it is explicitly removed by the user or by the
-sender. This hint is likely only useful when the server has the
+sender. This hint is likely only useful when the server has the
@code{:persistence} capability.
@item :transient