Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-16 17:24:23 +00:00
Code Issues Projects Releases Packages Wiki Activity

Misc manual updates.

Browse source 
* doc/emacs/package.texi (Package Installation): Document use of
package-initialize in init file.

* doc/lispref/os.texi (Startup Summary): Mention package loading.
(Init File): Don't refer to .emacs in section title.  Copyedits.
(Terminal-Specific): Give a realistic example.
(Command-Line Arguments): Reference Entering Emacs instead of
repeating the spiel about not restarting Emacs.
(Time of Day): Discuss time representation at beginning of node.
(Sound Output): Copyedits.

* doc/lispref/package.texi (Packaging Basics): Document package-initialize.
This commit is contained in:
Chong Yidong 2012-03-17 19:11:08 +08:00
parent f761251a43
commit 986bd52a31
5 changed files with 162 additions and 124 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
doc/emacs/ChangeLog
View file

@ -1,3 +1,8 @@
2012-03-17 Chong Yidong <cyd@gnu.org>
* package.texi (Package Installation): Document use of
package-initialize in init file.
2012-03-16 Glenn Morris <rgm@gnu.org>
* help.texi (Language Help):

43
doc/emacs/package.texi
View file

@ -157,25 +157,38 @@ directory name of the package archive. You can alter this list if you
wish to use third party package archives---but do so at your own risk,
and use only third parties that you think you can trust!
Once a package is downloaded and installed, it takes effect in the
current Emacs session. What ``taking effect'' means depends on the
package; most packages just make some new commands available, while
others have more wide-ranging effects on the Emacs session. For such
information, consult the package's help buffer.
Once a package is downloaded and installed, it is @dfn{loaded} into
the current Emacs session. Loading a package is not quite the same as
loading a Lisp library (@pxref{Lisp Libraries}); its effect varies
from package to package. Most packages just make some new commands
available, while others have more wide-ranging effects on the Emacs
session. For such information, consult the package's help buffer.
By default, Emacs also automatically loads all installed packages
(causing them to ``take effect'') in subsequent Emacs sessions. This
happens at startup, after processing the init file (@pxref{Init
File}). As an exception, Emacs does not load packages at startup if
invoked with the @samp{-q} or @samp{--no-init-file} options
(@pxref{Initial Options}).
By default, Emacs also automatically loads all installed packages in
subsequent Emacs sessions. This happens at startup, after processing
the init file (@pxref{Init File}). As an exception, Emacs does not
load packages at startup if invoked with the @samp{-q} or
@samp{--no-init-file} options (@pxref{Initial Options}).
@vindex package-enable-at-startup
@findex package-initialize
To disable automatic package loading, change the variable
@code{package-enable-at-startup} to @code{nil}. If you do this, you
can use the command @kbd{M-x package-initialize} to load your
packages.
@code{package-enable-at-startup} to @code{nil}.
@findex package-initialize
The reason automatic package loading occurs after loading the init
file is that user options only receive their customized values after
loading the init file, including user options which affect the
packaging system. In some circumstances, you may want to load
packages explicitly in your init file (usually because some other code
in your init file depends on a package). In that case, your init file
should call the function @code{package-initialize}. It is up to you
to ensure that relevant user options, such as @code{package-load-list}
(see below), are set up prior to the @code{package-initialize} call.
You should also set @code{package-enable-at-startup} to @code{nil}, to
avoid loading the packages again after processing the init file.
Alternatively, you may choose to completely inhibit package loading at
startup, and invoke the command @kbd{M-x package-initialize} to load
your packages manually.
@vindex package-load-list
For finer control over package loading, you can use the variable

12
doc/lispref/ChangeLog
View file

@ -1,3 +1,15 @@
2012-03-17 Chong Yidong <cyd@gnu.org>
* os.texi (Startup Summary): Mention package loading.
(Init File): Don't refer to .emacs in section title. Copyedits.
(Terminal-Specific): Give a realistic example.
(Command-Line Arguments): Reference Entering Emacs instead of
repeating the spiel about not restarting Emacs.
(Time of Day): Discuss time representation at beginning of node.
(Sound Output): Copyedits.
* package.texi (Packaging Basics): Document package-initialize.
2012-03-17 Eli Zaretskii <eliz@gnu.org>
* frames.texi (Initial Parameters): Add an index entry for

189
doc/lispref/os.texi
View file

@ -127,6 +127,11 @@ It loads your abbrevs from the file specified by
(@pxref{Abbrev Files, abbrev-file-name}). This is not done if the
option @samp{--batch} was specified.
@item
If @code{package-enable-at-startup} is non-@code{nil}, it calls the
function @code{package-initialize} to activate any optional Emacs Lisp
package that has been installed. @xref{Packaging Basics}.
@vindex after-init-time
@item
It sets the variable @code{after-init-time} to the value of
@ -242,9 +247,10 @@ is @code{nil}, the @samp{*scratch*} buffer is empty.
@end defopt
@node Init File
@subsection The Init File, @file{.emacs}
@subsection The Init File
@cindex init file
@cindex @file{.emacs}
@cindex @file{init.el}
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}
@ -267,13 +273,13 @@ file. If those environment variables are absent, though, Emacs uses
your user-id to find your home directory.
@cindex default init file
A site may have a @dfn{default init file}, which is the library
named @file{default.el}. Emacs finds the @file{default.el} file
through the standard search path for libraries (@pxref{How Programs Do
Loading}). The Emacs distribution does not come with this file; sites
may provide one for local customizations. If the default init file
exists, it is loaded whenever you start Emacs, except in batch mode or
if @samp{-q} (or @samp{-Q}) is specified. But your own personal init
An Emacs installation may have a @dfn{default init file}, which is a
Lisp library named @file{default.el}. Emacs finds this file through
the standard search path for libraries (@pxref{How Programs Do
Loading}). The Emacs distribution does not come with this file; it is
intended for local customizations. If the default init file exists,
it is loaded whenever you start Emacs, except in batch mode or if
@samp{-q} (or @samp{-Q}) is specified. But your own personal init
file, if any, is loaded first; if it sets @code{inhibit-default-init}
to a non-@code{nil} value, then Emacs does not subsequently load the
@file{default.el} file.
@ -343,23 +349,22 @@ in the normal manner, by searching the @code{load-path} directories, and
trying the @samp{.elc} and @samp{.el} suffixes.
@cindex Termcap
The usual function of a terminal-specific library is to enable
special keys to send sequences that Emacs can recognize. It may also
need to set or add to @code{input-decode-map} if the Termcap or
Terminfo entry does not specify all the terminal's function keys.
@xref{Terminal Input}.
The usual role of a terminal-specific library is to enable special
keys to send sequences that Emacs can recognize. It may also need to
set or add to @code{input-decode-map} if the Termcap or Terminfo entry
does not specify all the terminal's function keys. @xref{Terminal
Input}.
When the name of the terminal type contains a hyphen, and no library
is found whose name is identical to the terminal's name, Emacs strips
from the terminal's name the last hyphen and everything that follows
it, and tries again. This process is repeated until Emacs finds a
matching library or until there are no more hyphens in the name (the
latter means the terminal doesn't have any library specific to it).
Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
libraries, Emacs will try the same library @file{term/aaa.el} for
terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the
library can evaluate @code{(getenv "TERM")} to find the full name of
the terminal type.@refill
matching library, or until there are no more hyphens in the name
(i.g.@: there is no terminal-specific library). For example, if the
terminal name is @samp{xterm-256color} and there is no
@file{term/xterm-256color.el} library, Emacs tries to load
@file{term/xterm.el}. If necessary, the terminal library can evaluate
@code{(getenv "TERM")} to find the full name of the terminal type.
Your init file can prevent the loading of the
terminal-specific library by setting the variable
@ -376,8 +381,8 @@ have their own libraries. @xref{Hooks}.
@defvar term-file-prefix
@cindex @code{TERM} environment variable
If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
a terminal-specific initialization file as follows:
If the value of this variable is non-@code{nil}, Emacs loads a
terminal-specific initialization file as follows:
@example
(load (concat term-file-prefix (getenv "TERM")))
@ -409,29 +414,14 @@ feature.
@subsection Command-Line Arguments
@cindex command-line arguments
You can use command-line arguments to request various actions when you
start Emacs. Since you do not need to start Emacs more than once per
day, and will often leave your Emacs session running longer than that,
command-line arguments are hardly ever used. As a practical matter, it
is best to avoid making the habit of using them, since this habit would
encourage you to kill and restart Emacs unnecessarily often. These
options exist for two reasons: to be compatible with other editors (for
invocation by other programs) and to enable shell scripts to run
specific Lisp programs.
This section describes how Emacs processes command-line arguments,
and how you can customize them.
@ignore
(Note that some other editors require you to start afresh each time
you want to edit a file. With this kind of editor, you will probably
specify the file as a command-line argument. The recommended way to
use GNU Emacs is to start it only once, just after you log in, and do
all your editing in the same Emacs process. Each time you want to edit
a different file, you visit it with the existing Emacs, which eventually
comes to have many files in it ready for editing. Usually you do not
kill the Emacs until you are about to log out.)
@end ignore
You can use command-line arguments to request various actions when
you start Emacs. Command-line arguments should not be commonly used,
since the recommended way of using Emacs is to start it just once,
after logging in, and do all editing in the same Emacs session
(@pxref{Entering Emacs,,, emacs, The GNU Emacs Manual}); nonetheless,
they can be useful when invoking Emacs from session scripts or
debugging Emacs itself. This section describes how Emacs processes
command-line arguments.
@defun command-line
This function parses the command line that Emacs was called with,
@ -525,9 +515,7 @@ as a file name to visit.
There are two ways to get out of Emacs: you can kill the Emacs job,
which exits permanently, or you can suspend it, which permits you to
reenter the Emacs process later. As a practical matter, you seldom kill
Emacs---only when you are about to log out. Suspending is much more
common.
reenter the Emacs process later.
@menu
* Killing Emacs:: Exiting Emacs irreversibly.
@ -1105,24 +1093,47 @@ The value may be a floating point number.
@node Time of Day
@section Time of Day
This section explains how to determine the current time and the time
This section explains how to determine the current time and time
zone.
@cindex epoch
Most of these functions represent time as a list of either three
integers, @code{(@var{sec-high} @var{sec-low} @var{microsec})}, or of
two integers, @code{(@var{sec-high} @var{sec-low})}. The integers
@var{sec-high} and @var{sec-low} give the high and low bits of an
integer number of seconds. This integer number,
@ifnottex
@var{high} * 2**16 + @var{low},
@end ifnottex
@tex
$high*2^{16}+low$,
@end tex
is the number of seconds from the @dfn{epoch} (0:00 January 1, 1970
UTC) to the specified time. The third list element @var{microsec}, if
present, gives the number of microseconds from the start of that
second to the specified time.
The return value of @code{current-time} represents time using three
integers, while the timestamps in the return value of
@code{file-attributes} use two integers (@pxref{Definition of
file-attributes}). In function arguments, e.g.@: the @var{time-value}
argument to @code{current-time-string}, both two- and three-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.
@defun current-time-string &optional time-value
This function returns the current time and date as a human-readable
string. The format of the string is unvarying; the number of characters
used for each part is always the same, so you can reliably use
@code{substring} to extract pieces of it. It is wise to count the
characters from the beginning of the string rather than from the end, as
additional information may some day be added at the end.
string. The format of the string is unvarying; the number of
characters used for each part is always the same, so you can reliably
use @code{substring} to extract pieces of it. You should count
characters from the beginning of the string rather than from the end,
as 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. This argument should have the same form
as the times obtained from @code{current-time} (see below) and from
@code{file-attributes} (@pxref{Definition of file-attributes}). It
should be a list whose first two elements are integers; a third
(microsecond) element, if present, is ignored. @var{time-value} can
also be a cons of two integers, but this usage is obsolete.
(represented as a list of integers), instead of the current time.
@example
@group
@ -1133,33 +1144,16 @@ also be a cons of two integers, but this usage is obsolete.
@end defun
@defun current-time
This function returns the system's time value as a list of three
integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
@var{high} and @var{low} combine to give the number of seconds since
0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
@ifnottex
@var{high} * 2**16 + @var{low}.
@end ifnottex
@tex
$high*2^{16}+low$.
@end tex
The third element, @var{microsec}, gives the microseconds since the
start of the current second (or 0 for systems that return time with
the resolution of only one second).
The first two elements can be compared with file time values such as you
get with the function @code{file-attributes}.
@xref{Definition of file-attributes}.
This function returns the current time, represented as a list of three
integers @code{(@var{sec-high} @var{sec-low} @var{microsec})}. On
systems with only one-second time resolutions, @var{microsec} is 0.
@end defun
@defun float-time &optional time-value
This function returns the current time as a floating-point number of
seconds since the epoch. The argument @var{time-value}, if given,
specifies a time to convert instead of the current time. The argument
should have the same form as for @code{current-time-string} (see
above). Thus, it accepts the output of @code{current-time} and
@code{file-attributes} (@pxref{Definition of file-attributes}).
seconds since the epoch. The optional argument @var{time-value}, if
given, specifies a time (represented as a list of integers) to convert
instead of the current time.
@emph{Warning}: Since the result is floating point, it may not be
exact. Do not use this function if precise time stamps are required.
@ -1180,11 +1174,8 @@ adjustment, then the value is constant through time.
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 to analyze
instead of the current time. The argument should have the same form
as for @code{current-time-string} (see above). Thus, you can use
times obtained from @code{current-time} (see above) and from
@code{file-attributes}. @xref{Definition of file-attributes}.
The argument @var{time-value}, if given, specifies a time (represented
as a list of integers) to analyze instead of the current time.
@end defun
The current time zone is determined by the @samp{TZ} environment
@ -1196,16 +1187,15 @@ time zone.
@node Time Conversion
@section Time Conversion
These functions convert time values (lists of two or three integers)
to calendrical information and vice versa. You can get time values
from the functions @code{current-time} (@pxref{Time of Day}) and
@code{file-attributes} (@pxref{Definition of file-attributes}).
These functions convert time values (lists of two or three integers,
as explained in the previous section) into calendrical information and
vice versa.
Many 32-bit operating systems are limited to time values that contain 32 bits
of information; these systems typically handle only the times from
1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, 64-bit
and some 32-bit operating systems have larger time values, and can
represent times far in the past or future.
Many 32-bit operating systems are limited to time values containing
32 bits of information; these systems typically handle only the times
from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC.
However, 64-bit and some 32-bit operating systems have larger time
values, and can represent times far in the past or future.
Time conversion functions always use the Gregorian calendar, even
for dates before the Gregorian calendar was introduced. Year numbers
@ -2014,9 +2004,8 @@ See also @code{open-dribble-file} in @ref{Recording Input}.
@cindex sound
To play sound using Emacs, use the function @code{play-sound}. Only
certain systems are supported; if you call @code{play-sound} on a system
which cannot really do the job, it gives an error. Emacs version 20 and
earlier did not support sound at all.
certain systems are supported; if you call @code{play-sound} on a
system which cannot really do the job, it gives an error.
The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
or Sun Audio format (@samp{.au}).

37
doc/lispref/package.texi
View file

@ -15,6 +15,8 @@ install, uninstall, and upgrade it.
The following sections describe how to create a package, and how to
put it in a @dfn{package archive} for others to download.
@xref{Packages,,, emacs, The GNU Emacs Manual}, for a description of
user-level features of the packaging system.
@menu
* Packaging Basics:: The basic concepts of Emacs Lisp packages.
@ -91,17 +93,34 @@ definitions are saved to a file named @file{@var{name}-autoloads.el}
in the content directory. They are typically used to autoload the
principal user commands defined in the package, but they can also
perform other tasks, such as adding an element to
@code{auto-mode-alist} (@pxref{Auto Major Mode}). During this time,
Emacs will also byte-compile the Lisp files.
@code{auto-mode-alist} (@pxref{Auto Major Mode}). Note that a package
typically does @emph{not} autoload every function and variable defined
within it---only the handful of commands typically called to begin
using the package. Emacs then byte-compiles every Lisp file in the
package.
After installation, and (by default) each time Emacs is started, the
installed package is @dfn{activated}. During activation, Emacs adds
the package's content directory to @code{load-path}, and evaluates the
autoload definitions in @file{@var{name}-autoloads.el}.
After installation, the installed package is @dfn{loaded}: Emacs
adds the package's content directory to @code{load-path}, and
evaluates the autoload definitions in @file{@var{name}-autoloads.el}.
Note that a package typically does @emph{not} autoload every
function and variable defined within it---only the handful of commands
typically called to begin using the package.
Whenever Emacs starts up, it automatically calls the function
@code{package-initialize} to load installed packages. This is done
after loading the init file and abbrev file (if any) and before
running @code{after-init-hook} (@pxref{Startup Summary}). Automatic
package loading is disabled if the user option
@code{package-enable-at-startup} is @code{nil}.
@deffn Command package-initialize &optional no-activate
This function initializes Emacs' internal record of which packages are
installed, and loads them. The user option @code{package-load-list}
specifies which packages to load; by default, all installed packages
are loaded. @xref{Package Installation,,, emacs, The GNU Emacs
Manual}.
The optional argument @var{no-activate}, if non-@code{nil}, causes
Emacs to update its record of installed packages without actually
loading them; it is for internal use only.
@end deffn
@node Simple Packages
@section Simple Packages