summaryrefslogtreecommitdiff
path: root/doc/lispref
diff options
context:
space:
mode:
Diffstat (limited to 'doc/lispref')
-rw-r--r--doc/lispref/ChangeLog183
-rw-r--r--doc/lispref/customize.texi6
-rw-r--r--doc/lispref/display.texi47
-rw-r--r--doc/lispref/doclicense.texi29
-rw-r--r--doc/lispref/elisp.texi6
-rw-r--r--doc/lispref/files.texi98
-rw-r--r--doc/lispref/gpl.texi20
-rw-r--r--doc/lispref/internals.texi383
-rw-r--r--doc/lispref/loading.texi2
-rw-r--r--doc/lispref/modes.texi5
-rw-r--r--doc/lispref/nonascii.texi58
-rw-r--r--doc/lispref/os.texi59
-rw-r--r--doc/lispref/symbols.texi2
-rw-r--r--doc/lispref/tips.texi7
-rw-r--r--doc/lispref/windows.texi4
15 files changed, 608 insertions, 301 deletions
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 9d541978cbc..fe61fb4dce1 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -2,7 +2,7 @@
* text.texi (Change Hooks): Fix typo.
-2013-02-14 Glenn Morris <rgm@gnu.org>
+2013-02-15 Glenn Morris <rgm@gnu.org>
* modes.texi (Basic Major Modes): 'z' no longer bound in special-mode.
@@ -12,31 +12,39 @@
* modes.texi (Minor Mode Conventions): Fix typo.
-2013-02-12 Glenn Morris <rgm@gnu.org>
-
* keymaps.texi (Scanning Keymaps): Remove obsolete sentence about
meta characters; this changed in 22.1. (Bug#13684)
-2013-02-11 Glenn Morris <rgm@gnu.org>
-
* objects.texi (Char-Table Type): Add cindex.
* keymaps.texi (Key Binding Commands): Trivial rephrasing.
-2013-02-09 Glenn Morris <rgm@gnu.org>
+2013-02-10 Glenn Morris <rgm@gnu.org>
* keymaps.texi (Creating Keymaps): Update make-keymap result.
+2013-02-09 Eli Zaretskii <eliz@gnu.org>
+
+ * modes.texi (%-Constructs): Remove the description of %t.
+
+ * nonascii.texi (MS-DOS File Types): Delete node.
+
2013-02-08 Glenn Morris <rgm@gnu.org>
* keymaps.texi (Active Keymaps, Searching Keymaps):
Remove confusing mention of "symbolic prefix". (Bug#13643)
-2013-01-16 Glenn Morris <rgm@gnu.org>
+2013-01-19 Glenn Morris <rgm@gnu.org>
* macros.texi (Indenting Macros): Fix order of an indent
symbol's arguments. (Bug#13450)
+2013-01-19 Paul Eggert <eggert@cs.ucla.edu>
+
+ Allow floating-point file offsets.
+ * files.texi (Reading from Files, Writing to Files):
+ Say that file offsets can be numbers, not just integers.
+
2013-01-09 Glenn Morris <rgm@gnu.org>
* commands.texi (Interactive Codes):
@@ -60,10 +68,14 @@
* keymaps.texi (Key Sequences): Remove obsolete sentence
(Bug#13356).
-2013-01-03 Ari Roponen <ari.roponen@gmail.com> (tiny change)
+2013-01-04 Ari Roponen <ari.roponen@gmail.com> (tiny change)
* hash.texi (Defining Hash): Fix typo. (Bug#13345)
+2013-01-04 Stefan Monnier <monnier@iro.umontreal.ca>
+
+ * files.texi (File Attributes): Undocument return format of file-acl.
+
2013-01-03 Glenn Morris <rgm@gnu.org>
* processes.texi (System Processes):
@@ -73,7 +85,7 @@
* elisp.texi (DATE): Bump to Jan 2013.
-2012-12-31 Glenn Morris <rgm@gnu.org>
+2013-01-02 Glenn Morris <rgm@gnu.org>
* customize.texi (Common Keywords, Type Keywords):
Replace "active field" with "button". (Bug#13310)
@@ -81,7 +93,7 @@
* customize.texi (Common Keywords): Add xref. (Bug#13311)
* tips.texi (Library Headers): Add cindex.
-2012-12-29 Wolfgang Jenkner <wjenkner@inode.at>
+2012-12-30 Wolfgang Jenkner <wjenkner@inode.at>
* functions.texi (Declare Form):
* intro.texi (A Sample Function Description):
@@ -89,6 +101,11 @@
* variables.texi (Using Lexical Binding): Don't use @var or CAPS
in @def.. commands. (Bug#13292)
+2012-12-29 Eli Zaretskii <eliz@gnu.org>
+
+ * files.texi (Changing Files): Document the return values of
+ set-file-selinux-context and set-file-acl.
+
2012-12-27 Glenn Morris <rgm@gnu.org>
* files.texi (File Names): Mention Cygwin conversion functions.
@@ -98,6 +115,12 @@
* windows.texi (Selecting Windows): Reword description of
select-window (Bug#13248).
+2012-12-22 Eli Zaretskii <eliz@gnu.org>
+
+ * files.texi (File Attributes, Changing Files): Remove the details
+ about the text returned by file-acl. Instead, just document that
+ it is an opaque string meant to be used by set-file-acl.
+
2012-12-21 Chong Yidong <cyd@gnu.org>
* modes.texi (Auto Major Mode): Fix typo (Bug#13230).
@@ -105,26 +128,71 @@
* customize.texi (Simple Types): Document key-sequence type
(Bug#13048).
-2012-12-15 Chong Yidong <cyd@gnu.org>
-
* strings.texi (Text Comparison): Doc fix for compare-strings.
-2012-12-09 Stefan Monnier <monnier@iro.umontreal.ca>
+2012-12-19 Michael Albinus <michael.albinus@gmx.de>
- * control.texi (Pattern matching case statement): New node.
+ * files.texi (Magic File Names): Add `file-acl',
+ `file-selinux-context', `set-file-acl' and
+ `set-file-selinux-context'. Make the list consistent.
+
+2012-12-19 Jonas Bernoulli <jonas@bernoul.li>
+
+ * tips.texi (Library Headers): New header keyword `Homepage'.
+ Make continuation lines syntax more precise.
+
+2012-12-17 Eli Zaretskii <eliz@gnu.org>
+
+ * files.texi (File Attributes, Changing Files): Update to include
+ MS-Windows support for ACLs.
+
+2012-12-16 Romain Francoise <romain@orebokech.com>
+
+ * files.texi (File Attributes): Document ACL support and new
+ `file-acl' function.
+ (Changing Files): Mention argument name change of `copy-file' and
+ document new function `set-file-acl'.
-2012-12-06 Stefan Monnier <monnier@iro.umontreal.ca>
+2012-12-14 Paul Eggert <eggert@cs.ucla.edu>
+
+ Fix permissions bugs with setgid directories etc. (Bug#13125)
+ * files.texi (Testing Accessibility): Document GROUP arg
+ of file-ownership-preserved-p.
+ (File Attributes): Document that 9th element is now
+ just a placeholder.
+ * os.texi (User Identification): Document new functions group-gid,
+ group-real-gid.
+
+2012-12-11 Paul Eggert <eggert@cs.ucla.edu>
+
+ * internals.texi (C Integer Types): New section.
+ This follows up and records an email in
+ <http://lists.gnu.org/archive/html/emacs-devel/2012-07/msg00496.html>.
+
+2012-12-10 Stefan Monnier <monnier@iro.umontreal.ca>
+
+ * control.texi (Pattern matching case statement): New node.
* customize.texi (Variable Definitions): Mention the default :group
for defcustoms (bug#13093).
-2012-12-05 Chong Yidong <cyd@gnu.org>
+2012-12-09 Glenn Morris <rgm@gnu.org>
+
+ * customize.texi (Variable Definitions): Mention eval-defun
+ on a defcustom calls the :set function when appropriate.
+
+2012-12-06 Paul Eggert <eggert@cs.ucla.edu>
+
+ * doclicense.texi, gpl.texi: Update to latest version from FSF.
+ These are just minor editorial changes.
+
+2012-12-06 Chong Yidong <cyd@gnu.org>
* lists.texi (Plist Access): Move put example to Symbol Plists.
* symbols.texi (Standard Properties): Fix typo.
-2012-12-02 Chong Yidong <cyd@gnu.org>
+2012-12-03 Chong Yidong <cyd@gnu.org>
* symbols.texi (Symbol Properties): New node.
(Symbol Plists): Make it a subsection under Symbol Properties.
@@ -141,7 +209,17 @@
* commands.texi (Using Interactive): Fix index entry.
-2012-11-23 Martin Rudalics <rudalics@gmx.at>
+2012-11-24 Paul Eggert <eggert@cs.ucla.edu>
+
+ * doclicense.texi: Update to latest version from FSF.
+ These are just minor editorial changes.
+ * elisp.texi (GNU Free Documentation License)
+ (GNU General Public Licens):
+ Provide sectioning, since doclicense.texi no longer does that.
+
+ * loading.texi (Named Features): @ -> @@ to fix typo.
+
+2012-11-24 Martin Rudalics <rudalics@gmx.at>
* windows.texi (Basic Windows): Fix typo.
(Windows and Frames): Fix example. Move description of
@@ -156,34 +234,34 @@
dedicatedness affects functions removing buffers or windows.
* buffers.texi (The Buffer List): Fix description of bury-buffer.
-2012-11-23 Chong Yidong <cyd@gnu.org>
+2012-11-24 Chong Yidong <cyd@gnu.org>
* modes.texi (%-Constructs): Fix statement about mode construct
padding (Bug#12866).
-2012-11-21 Stefan Monnier <monnier@iro.umontreal.ca>
+2012-11-24 Stefan Monnier <monnier@iro.umontreal.ca>
* debugging.texi (Profiling): Make it more clear
that --enable-profiling is about profiling the C code.
2012-11-21 Glenn Morris <rgm@gnu.org>
- * debugging.texi (Profiling): Mention --enable-profiling (if !tex).
- Add some basic information about the profile report buffer.
- (Debugging): Mention profiling in the introduction.
-
-2012-11-20 Glenn Morris <rgm@gnu.org>
+ * display.texi (Attribute Functions):
+ Update for set-face-* name changes.
+ Add new "inherit" argument for face-bold-p etc.
+ Move description of this argument to a common section, like "frame".
- * debugging.texi (Profiling): New section, in progress.
+ * debugging.texi (Profiling): New section.
+ (Debugging): Mention profiling in the introduction.
* tips.texi (Compilation Tips): Move profiling to separate section.
* elisp.texi: Add Profiling to detailed menu.
-2012-11-18 Martin Rudalics <rudalics@gmx.at>
+2012-11-21 Martin Rudalics <rudalics@gmx.at>
* windows.texi (Display Action Functions): Fix recently added
example. Suggested by Michael Heerdegen.
-2012-11-18 Paul Eggert <eggert@cs.ucla.edu>
+2012-11-21 Paul Eggert <eggert@cs.ucla.edu>
Minor cleanup for times as lists of four integers.
* os.texi (Time Parsing): Time values can now be four integers.
@@ -193,16 +271,14 @@
* loading.texi (How Programs Do Loading): Add eager macro expansion.
* macros.texi (Expansion): Mention eager macro expansion.
-2012-11-17 Glenn Morris <rgm@gnu.org>
-
* minibuf.texi (Basic Completion): Mention misc completion-table funcs.
-2012-11-17 Leo Liu <sdl.web@gmail.com>
+2012-11-18 Leo Liu <sdl.web@gmail.com>
* minibuf.texi (Programmed Completion): Doc fix for metadata
request (Bug#12850).
-2012-11-17 Glenn Morris <rgm@gnu.org>
+2012-11-18 Glenn Morris <rgm@gnu.org>
* display.texi (Temporary Displays): Document with-temp-buffer-window.
@@ -219,31 +295,35 @@
Fix description of display-buffer-below-selected. Reorder actions.
Add example (Bug#12848).
-2012-11-15 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * keymaps.texi (Translation Keymaps): Add a subsection "Interaction
- with normal keymaps" (bug#12868).
-
-2012-11-15 Glenn Morris <rgm@gnu.org>
+2012-11-16 Glenn Morris <rgm@gnu.org>
* display.texi (Face Attributes): Fix :underline COLOR description.
(Attribute Functions): Update for set-face-underline rename.
Tweak descriptions of face-underline-p, face-inverse-video-p.
-2012-11-14 Glenn Morris <rgm@gnu.org>
-
* keymaps.texi (Searching Keymaps, Tool Bar): Untabify examples,
so they align better in info.
(Active Keymaps, Searching Keymaps, Controlling Active Maps):
Document set-temporary-overlay-map.
-2012-11-12 Glenn Morris <rgm@gnu.org>
+2012-11-15 Stefan Monnier <monnier@iro.umontreal.ca>
+
+ * keymaps.texi (Translation Keymaps): Add a subsection "Interaction
+ with normal keymaps".
+
+2012-11-15 Dmitry Antipov <dmantipov@yandex.ru>
+
+ * internals.texi (Garbage Collection): Update descriptions
+ of vectorlike_header, garbage-collect and gc-cons-threshold.
+ (Object Internals): Explain Lisp_Object layout and the basics
+ of an internal type system.
+ (Buffer Internals): Update description of struct buffer.
+
+2012-11-13 Glenn Morris <rgm@gnu.org>
* variables.texi (Adding Generalized Variables):
At least mention gv-define-expander and gv-letplace.
-2012-11-11 Glenn Morris <rgm@gnu.org>
-
* debugging.texi (Error Debugging): Mention debug-on-message.
(Using Debugger): Mention debugger-bury-or-kill.
@@ -254,14 +334,14 @@
* variables.texi (Adding Generalized Variables):
Use standard formatting for common lisp note about setf functions.
-2012-11-07 Martin Rudalics <rudalics@gmx.at>
+2012-11-10 Martin Rudalics <rudalics@gmx.at>
* elisp.texi (Top): Add Recombining Windows to menu.
* windows.texi (Recombining Windows): New subsection.
(Splitting Windows): Rewrite text on handling of window
combinations and move it to new subsection.
-2012-11-07 Chong Yidong <cyd@gnu.org>
+2012-11-10 Chong Yidong <cyd@gnu.org>
* searching.texi (Replacing Match): Document \? in replace-match.
@@ -274,13 +354,11 @@
* edebug.texi (Specification List): setf is no longer CL-only.
-2012-11-07 Glenn Morris <rgm@gnu.org>
+2012-11-10 Glenn Morris <rgm@gnu.org>
* variables.texi (Adding Generalized Variables):
Update description of FIX-RETURN expansion.
-2012-11-06 Glenn Morris <rgm@gnu.org>
-
* variables.texi (Setting Generalized Variables):
Split most of previous contents into this subsection.
(Adding Generalized Variables): New subsection.
@@ -288,10 +366,17 @@
* elisp.texi: Add Generalized Variables subsections to detailed menu.
-2012-11-05 Chong Yidong <cyd@gnu.org>
+2012-11-10 Chong Yidong <cyd@gnu.org>
* frames.texi (Initial Parameters): Doc fix (Bug#12144).
+2012-11-08 Michael Albinus <michael.albinus@gmx.de>
+
+ * os.texi (Notifications): Update descriptions of
+ notifications-notify, notifications-close-notification and
+ notifications-get-capabilities according to latest code changes.
+ Add notifications-get-server-information.
+
2012-11-03 Chong Yidong <cyd@gnu.org>
* objects.texi (General Escape Syntax): Clarify the explanation of
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 2b375b1bcc3..e9260309057 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -310,8 +310,10 @@ defined with @code{defgroup} in the same file will be used. This way, most
When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
mode (@code{eval-defun}), a special feature of @code{eval-defun}
arranges to set the variable unconditionally, without testing whether
-its value is void. (The same feature applies to @code{defvar}.)
-@xref{Defining Variables}.
+its value is void. (The same feature applies to @code{defvar},
+@pxref{Defining Variables}.) Using @code{eval-defun} on a defcustom
+that is already defined calls the @code{:set} function (see below),
+if there is one.
If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
(@pxref{Building Emacs}), the standard value installed at dump time
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index b7ea39ab69d..cc6e980dadc 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2433,12 +2433,12 @@ This sets the @code{:stipple} attribute of @var{face} to
This sets the @code{:font} attribute of @var{face} to @var{font}.
@end deffn
-@defun set-face-bold-p face bold-p &optional frame
+@defun set-face-bold face bold-p &optional frame
This sets the @code{:weight} attribute of @var{face} to @var{normal}
if @var{bold-p} is @code{nil}, and to @var{bold} otherwise.
@end defun
-@defun set-face-italic-p face italic-p &optional frame
+@defun set-face-italic face italic-p &optional frame
This sets the @code{:slant} attribute of @var{face} to @var{normal} if
@var{italic-p} is @code{nil}, and to @var{italic} otherwise.
@end defun
@@ -2448,7 +2448,7 @@ This sets the @code{:underline} attribute of @var{face} to
@var{underline}.
@end defun
-@defun set-face-inverse-video-p face inverse-video-p &optional frame
+@defun set-face-inverse-video face inverse-video-p &optional frame
This sets the @code{:inverse-video} attribute of @var{face} to
@var{inverse-video-p}.
@end defun
@@ -2461,59 +2461,48 @@ This swaps the foreground and background colors of face @var{face}.
don't specify @var{frame}, they refer to the selected frame; @code{t}
refers to the default data for new frames. They return the symbol
@code{unspecified} if the face doesn't define any value for that
-attribute.
+attribute. If @var{inherit} is @code{nil}, only an attribute directly
+defined by the face is returned. If @var{inherit} is non-@code{nil},
+any faces specified by its @code{:inherit} attribute are considered as
+well, and if @var{inherit} is a face or a list of faces, then they are
+also considered, until a specified attribute is found. To ensure that
+the return value is always specified, use a value of @code{default} for
+@var{inherit}.
+
+@defun face-font face &optional frame
+This function returns the name of the font of face @var{face}.
+@end defun
@defun face-foreground face &optional frame inherit
@defunx face-background face &optional frame inherit
These functions return the foreground color (or background color,
respectively) of face @var{face}, as a string.
-
-If @var{inherit} is @code{nil}, only a color directly defined by the face is
-returned. If @var{inherit} is non-@code{nil}, any faces specified by its
-@code{:inherit} attribute are considered as well, and if @var{inherit}
-is a face or a list of faces, then they are also considered, until a
-specified color is found. To ensure that the return value is always
-specified, use a value of @code{default} for @var{inherit}.
@end defun
@defun face-stipple face &optional frame inherit
This function returns the name of the background stipple pattern of face
@var{face}, or @code{nil} if it doesn't have one.
-
-If @var{inherit} is @code{nil}, only a stipple directly defined by the
-face is returned. If @var{inherit} is non-@code{nil}, any faces
-specified by its @code{:inherit} attribute are considered as well, and
-if @var{inherit} is a face or a list of faces, then they are also
-considered, until a specified stipple is found. To ensure that the
-return value is always specified, use a value of @code{default} for
-@var{inherit}.
-@end defun
-
-@defun face-font face &optional frame
-This function returns the name of the font of face @var{face}.
@end defun
-@defun face-bold-p face &optional frame
+@defun face-bold-p face &optional frame inherit
This function returns a non-@code{nil} value if the @code{:weight}
attribute of @var{face} is bolder than normal (i.e., one of
@code{semi-bold}, @code{bold}, @code{extra-bold}, or
@code{ultra-bold}). Otherwise, it returns @code{nil}.
@end defun
-@defun face-italic-p face &optional frame
+@defun face-italic-p face &optional frame inherit
This function returns a non-@code{nil} value if the @code{:slant}
attribute of @var{face} is @code{italic} or @code{oblique}, and
@code{nil} otherwise.
@end defun
-@c Note the weasel words. A face that inherits from an underlined
-@c face but does not specify :underline will return nil.
-@defun face-underline-p face &optional frame
+@defun face-underline-p face &optional frame inherit
This function returns non-@code{nil} if face @var{face} specifies
a non-@code{nil} @code{:underline} attribute.
@end defun
-@defun face-inverse-video-p face &optional frame
+@defun face-inverse-video-p face &optional frame inherit
This function returns non-@code{nil} if face @var{face} specifies
a non-@code{nil} @code{:inverse-video} attribute.
@end defun
diff --git a/doc/lispref/doclicense.texi b/doc/lispref/doclicense.texi
index 6e7ec924f65..9c3bbe56e91 100644
--- a/doc/lispref/doclicense.texi
+++ b/doc/lispref/doclicense.texi
@@ -1,15 +1,11 @@
-@c -*-texinfo-*-
@c The GNU Free Documentation License.
-@node GNU Free Documentation License
-
-@appendix GNU Free Documentation License
@center Version 1.3, 3 November 2008
@c This file is intended to be included within another document,
@c hence no sectioning command or @node.
@display
-Copyright @copyright{} 2000, 2001, 2002, 2007, 2008, 2009 Free Software Foundation, Inc.
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
@uref{http://fsf.org/}
Everyone is permitted to copy and distribute verbatim copies
@@ -96,16 +92,16 @@ An image format is not Transparent if used for any substantial amount
of text. A copy that is not ``Transparent'' is called ``Opaque''.
Examples of suitable formats for Transparent copies include plain
-@sc{ascii} without markup, Texinfo input format, La@TeX{} input
-format, @acronym{SGML} or @acronym{XML} using a publicly available
-@acronym{DTD}, and standard-conforming simple @acronym{HTML},
-PostScript or @acronym{PDF} designed for human modification. Examples
-of transparent image formats include @acronym{PNG}, @acronym{XCF} and
-@acronym{JPG}. Opaque formats include proprietary formats that can be
-read and edited only by proprietary word processors, @acronym{SGML} or
-@acronym{XML} for which the @acronym{DTD} and/or processing tools are
-not generally available, and the machine-generated @acronym{HTML},
-PostScript or @acronym{PDF} produced by some word processors for
+ASCII without markup, Texinfo input format, La@TeX{} input
+format, SGML or XML using a publicly available
+DTD, and standard-conforming simple HTML,
+PostScript or PDF designed for human modification. Examples
+of transparent image formats include PNG, XCF and
+JPG@. Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, SGML or
+XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML,
+PostScript or PDF produced by some word processors for
output purposes only.
The ``Title Page'' means, for a printed book, the title page itself,
@@ -485,7 +481,7 @@ license notices just after the title page:
@end smallexample
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the ``with@dots{}Texts.'' line with this:
+replace the ``with@dots{}Texts.''@: line with this:
@smallexample
@group
@@ -504,7 +500,6 @@ recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
-
@c Local Variables:
@c ispell-local-pdict: "ispell-dict"
@c End:
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 5ad9e8212a5..3d1c4cf577d 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1209,8 +1209,6 @@ Coding Systems
for a single file operation.
* Explicit Encoding:: Encoding or decoding text without doing I/O.
* Terminal I/O Encoding:: Use of encoding for terminal I/O.
-* MS-DOS File Types:: How DOS "text" and "binary" files
- relate to coding systems.
Searching and Matching
@@ -1593,7 +1591,11 @@ Object Internals
@c appendices
@include anti.texi
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
@include doclicense.texi
+@node GPL
+@appendix GNU General Public License
@include gpl.texi
@include tips.texi
@include internals.texi
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index c976f5b2ec4..be44590f2ec 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -533,9 +533,9 @@ is visiting the file @var{filename}: these include the buffer's visited
file name and its last save file modtime. This feature is used by
@code{find-file-noselect} and you probably should not use it yourself.
-If @var{beg} and @var{end} are non-@code{nil}, they should be integers
-specifying the portion of the file to insert. In this case, @var{visit}
-must be @code{nil}. For example,
+If @var{beg} and @var{end} are non-@code{nil}, they should be numbers
+that are byte offsets specifying the portion of the file to insert.
+In this case, @var{visit} must be @code{nil}. For example,
@example
(insert-file-contents filename nil 0 500)
@@ -605,8 +605,8 @@ that string, rather than text from the buffer. @var{end} is ignored in
this case.
If @var{append} is non-@code{nil}, then the specified text is appended
-to the existing file contents (if any). If @var{append} is an
-integer, @code{write-region} seeks to that byte offset from the start
+to the existing file contents (if any). If @var{append} is a
+number, @code{write-region} seeks to that byte offset from the start
of the file and writes the data from there.
If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
@@ -895,11 +895,14 @@ returns @code{nil}. However, if the open fails, it signals an error
using @var{string} as the error message text.
@end defun
-@defun file-ownership-preserved-p filename
+@defun file-ownership-preserved-p filename &optional group
This function returns @code{t} if deleting the file @var{filename} and
then creating it anew would keep the file's owner unchanged. It also
returns @code{t} for nonexistent files.
+If the optional argument @var{group} is non-@code{nil}, this function
+also checks that the file's group would be unchanged.
+
If @var{filename} is a symbolic link, then, unlike the other functions
discussed here, @code{file-ownership-preserved-p} does @emph{not}
replace @var{filename} with its target. However, it does recursively
@@ -1246,8 +1249,7 @@ The file's modes, as a string of ten letters or dashes,
as in @samp{ls -l}.
@item
-@code{t} if the file's @acronym{GID} would change if file were
-deleted and recreated; @code{nil} otherwise.
+An unspecified value, present for backward compatibility.
@item
The file's inode number. If possible, this is an integer. If the
@@ -1279,7 +1281,7 @@ For example, here are the file attributes for @file{files.texi}:
(20000 23 0 0)
(20614 64555 902289 872000)
122295 "-rw-rw-rw-"
- nil (5888 2 . 43978)
+ t (5888 2 . 43978)
(15479 . 46724))
@end group
@end example
@@ -1318,8 +1320,8 @@ end-of-line format is CR-LF.)
@item "-rw-rw-rw-"
has a mode of read and write access for the owner, group, and world.
-@item nil
-would retain the same @acronym{GID} if it were recreated.
+@item t
+is merely a placeholder; it carries no information.
@item (5888 2 . 43978)
has an inode number of 6473924464520138.
@@ -1350,6 +1352,29 @@ not support SELinux, or if Emacs was not compiled with SELinux
support, then the return value is @code{(nil nil nil nil)}.
@end defun
+@cindex access control list
+@cindex ACL entries
+ If Emacs has been compiled with @dfn{ACL} (access control list)
+support, you can use the function @code{file-acl} to retrieve a file's
+ACL entries. The interface implementation is platform-specific; on
+GNU/Linux and BSD, Emacs uses the POSIX ACL interface, while on
+MS-Windows Emacs emulates the POSIX ACL interface with native file
+security APIs.
+
+@defun file-acl filename
+This function returns the ACL entries of the file @var{filename}. The
+return value is a platform-dependent object containing some
+representation of the ACL entries. Don't use it for anything except
+passing it to the @code{set-file-acl} function (@pxref{Changing Files,
+set-file-acl}).
+
+If the file does not exist or is inaccessible, or if Emacs was unable to
+determine the ACL entries, then the return value is @code{nil}. The
+latter can happen for local files if Emacs was not compiled with ACL
+support, or for remote files if the file handler returns nil for the
+file's ACL entries.
+@end defun
+
@node Locating Files
@subsection How to Locate Files in Standard Places
@cindex locate file in path
@@ -1539,9 +1564,10 @@ non-@code{nil}, we attempt to copy the user and group ownership of the
file. This works only on some operating systems, and only if you have
the correct permissions to do so.
-If the optional argument @var{preserve-selinux} is non-@code{nil}, and
-Emacs has been compiled with SELinux support, this function attempts
-to copy the file's SELinux context (@pxref{File Attributes}).
+If the optional argument @var{preserve-extended-attributes} is
+non-@code{nil}, and Emacs has been built with the appropriate support,
+this function attempts to copy the file's extended attributes, such as
+its SELinux context and ACL entries (@pxref{File Attributes}).
@end deffn
@deffn Command make-symbolic-link filename newname &optional ok-if-exists
@@ -1677,9 +1703,21 @@ This function sets the SELinux security context of the file
@var{filename} to @var{context}. @xref{File Attributes}, for a brief
description of SELinux contexts. The @var{context} argument should be
a list @code{(@var{user} @var{role} @var{type} @var{range})}, like the
-return value of @code{file-selinux-context}. The function does
-nothing if SELinux is disabled, or if Emacs was compiled without
-SELinux support.
+return value of @code{file-selinux-context}. The function returns
+@code{t} if it succeeds to set the SELinux security context of
+@var{filename}, @code{nil} otherwise. The function does nothing and
+returns @code{nil} if SELinux is disabled, or if Emacs was compiled
+without SELinux support.
+@end defun
+
+@defun set-file-acl filename acl-string
+This function sets the ACL entries of the file @var{filename} to
+@var{acl-string}. @xref{File Attributes}, for a brief description of
+ACLs. The @var{acl-string} argument should be a string containing the
+textual representation of the desired ACL entries as returned by
+@code{file-acl} (@pxref{File Attributes, file-acl}). The function
+returns @code{t} if it succeeds to set the ACL entries of
+@var{filename}, @code{nil} otherwise.
@end defun
@node File Names
@@ -2724,9 +2762,12 @@ first, before handlers for jobs such as remote file access.
@code{dired-compress-file}, @code{dired-uncache},@*
@code{expand-file-name},
@code{file-accessible-directory-p},
+@code{file-acl},
@code{file-attributes},
@code{file-directory-p},
+@code{file-equal-p},
@code{file-executable-p}, @code{file-exists-p},
+@code{file-in-directory-p},
@code{file-local-copy}, @code{file-remote-p},
@code{file-modes}, @code{file-name-all-completions},
@code{file-name-as-directory},
@@ -2735,9 +2776,10 @@ first, before handlers for jobs such as remote file access.
@code{file-name-nondirectory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
@code{file-ownership-preserved-p},
-@code{file-readable-p}, @code{file-regular-p}, @code{file-in-directory-p},
+@code{file-readable-p}, @code{file-regular-p},
+@code{file-selinux-context},
@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
-@code{file-equal-p}, @code{find-backup-file-name},
+@code{find-backup-file-name},
@c Not sure why it was here: @code{find-file-noselect},@*
@code{get-file-buffer},
@code{insert-directory},
@@ -2748,7 +2790,8 @@ first, before handlers for jobs such as remote file access.
@code{make-directory-internal},
@code{make-symbolic-link},@*
@code{process-file},
-@code{rename-file}, @code{set-file-modes}, @code{set-file-times},
+@code{rename-file}, @code{set-file-acl}, @code{set-file-modes},
+@code{set-file-selinux-context}, @code{set-file-times},
@code{set-visited-file-modtime}, @code{shell-command},
@code{start-file-process},
@code{substitute-in-file-name},@*
@@ -2771,9 +2814,12 @@ first, before handlers for jobs such as remote file access.
@code{dired-compress-file}, @code{dired-uncache},
@code{expand-file-name},
@code{file-accessible-direc@discretionary{}{}{}tory-p},
+@code{file-acl},
@code{file-attributes},
@code{file-direct@discretionary{}{}{}ory-p},
+@code{file-equal-p},
@code{file-executable-p}, @code{file-exists-p},
+@code{file-in-directory-p},
@code{file-local-copy}, @code{file-remote-p},
@code{file-modes}, @code{file-name-all-completions},
@code{file-name-as-directory},
@@ -2782,18 +2828,22 @@ first, before handlers for jobs such as remote file access.
@code{file-name-nondirec@discretionary{}{}{}tory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
@code{file-ownership-pre@discretionary{}{}{}served-p},
-@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
-@code{file-truename}, @code{file-writable-p},
+@code{file-readable-p}, @code{file-regular-p},
+@code{file-selinux-context},
+@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
@c Not sure why it was here: @code{find-file-noselect},
@code{get-file-buffer},
@code{insert-directory},
@code{insert-file-contents},
-@code{load}, @code{make-direc@discretionary{}{}{}tory},
+@code{load},
+@code{make-auto-save-file-name},
+@code{make-direc@discretionary{}{}{}tory},
@code{make-direc@discretionary{}{}{}tory-internal},
@code{make-symbolic-link},
@code{process-file},
-@code{rename-file}, @code{set-file-modes},
+@code{rename-file}, @code{set-file-acl}, @code{set-file-modes},
+@code{set-file-selinux-context}, @code{set-file-times},
@code{set-visited-file-modtime}, @code{shell-command},
@code{start-file-process},
@code{substitute-in-file-name},
diff --git a/doc/lispref/gpl.texi b/doc/lispref/gpl.texi
index 6dc50a9751c..0e2e212acb1 100644
--- a/doc/lispref/gpl.texi
+++ b/doc/lispref/gpl.texi
@@ -1,12 +1,8 @@
-@c -*-texinfo-*-
-
-@node GPL
-@appendix GNU General Public License
@c The GNU General Public License.
@center Version 3, 29 June 2007
@c This file is intended to be included within another document,
-@c hence no sectioning command or @node.
+@c hence no sectioning command or @node.
@display
Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/}
@@ -226,7 +222,7 @@ terms of section 4, provided that you also meet all of these
conditions:
@enumerate a
-@item
+@item
The work must carry prominent notices stating that you modified it,
and giving a relevant date.
@@ -627,12 +623,12 @@ later version.
@item Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
-APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+APPLICABLE LAW@. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
-PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
+A PARTICULAR PURPOSE@. THE ENTIRE RISK AS TO THE QUALITY AND
+PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE PROGRAM PROVE
DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
CORRECTION.
@@ -674,7 +670,7 @@ state the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.
@smallexample
-@var{one line to give the program's name and a brief idea of what it does.}
+@var{one line to give the program's name and a brief idea of what it does.}
Copyright (C) @var{year} @var{name of author}
This program is free software: you can redistribute it and/or modify
@@ -684,7 +680,7 @@ your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
@@ -697,7 +693,7 @@ If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
@smallexample
-@var{program} Copyright (C) @var{year} @var{name of author}
+@var{program} Copyright (C) @var{year} @var{name of author}
This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}.
This is free software, and you are welcome to redistribute it
under certain conditions; type @samp{show c} for details.
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 14ebde46b04..3269776b626 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -17,6 +17,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers.
* Memory Usage:: Info about total size of Lisp objects made so far.
* Writing Emacs Primitives:: Writing C code for Emacs.
* Object Internals:: Data formats of buffers, windows, processes.
+* C Integer Types:: How C integer types are used inside Emacs.
@end menu
@node Building Emacs
@@ -227,12 +228,11 @@ of 8k bytes, and small vectors are packed into blocks of 4k bytes).
Beyond the basic vector, a lot of objects like window, buffer, and
frame are managed as if they were vectors. The corresponding C data
structures include the @code{struct vectorlike_header} field whose
-@code{next} field points to the next object in the chain:
-@code{header.next.buffer} points to the next buffer (which could be
-a killed buffer), and @code{header.next.vector} points to the next
-vector in a free list. If a vector is small (smaller than or equal to
-@code{VBLOCK_BYTES_MAX} bytes, see @file{alloc.c}), then
-@code{header.next.nbytes} contains the vector size in bytes.
+@code{size} member contains the subtype enumerated by @code{enum pvec_type}
+and an information about how many @code{Lisp_Object} fields this structure
+contains and what the size of the rest data is. This information is
+needed to calculate the memory footprint of an object, and used
+by the vector allocation code while iterating over the vector blocks.
@cindex garbage collection
It is quite common to use some storage for a while, then release it
@@ -285,88 +285,147 @@ the amount of space in use. (Garbage collection can also occur
spontaneously if you use more than @code{gc-cons-threshold} bytes of
Lisp data since the previous garbage collection.)
-@code{garbage-collect} returns a list containing the following
-information:
+@code{garbage-collect} returns a list with information on amount of space in
+use, where each entry has the form @samp{(@var{name} @var{size} @var{used})}
+or @samp{(@var{name} @var{size} @var{used} @var{free})}. In the entry,
+@var{name} is a symbol describing the kind of objects this entry represents,
+@var{size} is the number of bytes used by each one, @var{used} is the number
+of those objects that were found live in the heap, and optional @var{free} is
+the number of those objects that are not live but that Emacs keeps around for
+future allocations. So an overall result is:
@example
-@group
-((@var{used-conses} . @var{free-conses})
- (@var{used-syms} . @var{free-syms})
-@end group
- (@var{used-miscs} . @var{free-miscs})
- @var{used-string-chars}
- @var{used-vector-slots}
- (@var{used-floats} . @var{free-floats})
- (@var{used-intervals} . @var{free-intervals})
- (@var{used-strings} . @var{free-strings}))
+((@code{conses} @var{cons-size} @var{used-conses} @var{free-conses})
+ (@code{symbols} @var{symbol-size} @var{used-symbols} @var{free-symbols})
+ (@code{miscs} @var{misc-size} @var{used-miscs} @var{free-miscs})
+ (@code{strings} @var{string-size} @var{used-strings} @var{free-strings})
+ (@code{string-bytes} @var{byte-size} @var{used-bytes})
+ (@code{vectors} @var{vector-size} @var{used-vectors})
+ (@code{vector-slots} @var{slot-size} @var{used-slots} @var{free-slots})
+ (@code{floats} @var{float-size} @var{used-floats} @var{free-floats})
+ (@code{intervals} @var{interval-size} @var{used-intervals} @var{free-intervals})
+ (@code{buffers} @var{buffer-size} @var{used-buffers})
+ (@code{heap} @var{unit-size} @var{total-size} @var{free-size}))
@end example
Here is an example:
@example
-@group
(garbage-collect)
- @result{} ((106886 . 13184) (9769 . 0)
- (7731 . 4651) 347543 121628
- (31 . 94) (1273 . 168)
- (25474 . 3569))
-@end group
+ @result{} ((conses 16 49126 8058) (symbols 48 14607 0)
+ (miscs 40 34 56) (strings 32 2942 2607)
+ (string-bytes 1 78607) (vectors 16 7247)
+ (vector-slots 8 341609 29474) (floats 8 71 102)
+ (intervals 56 27 26) (buffers 944 8)
+ (heap 1024 11715 2678))
@end example
-Here is a table explaining each element:
+Below is a table explaining each element. Note that last @code{heap} entry
+is optional and present only if an underlying @code{malloc} implementation
+provides @code{mallinfo} function.
@table @var
+@item cons-size
+Internal size of a cons cell, i.e., @code{sizeof (struct Lisp_Cons)}.
+
@item used-conses
The number of cons cells in use.
@item free-conses
-The number of cons cells for which space has been obtained from the
-operating system, but that are not currently being used.
+The number of cons cells for which space has been obtained from
+the operating system, but that are not currently being used.
-@item used-syms
+@item symbol-size
+Internal size of a symbol, i.e., @code{sizeof (struct Lisp_Symbol)}.
+
+@item used-symbols
The number of symbols in use.
-@item free-syms
-The number of symbols for which space has been obtained from the
-operating system, but that are not currently being used.
+@item free-symbols
+The number of symbols for which space has been obtained from
+the operating system, but that are not currently being used.
+
+@item misc-size
+Internal size of a miscellaneous entity, i.e.,
+@code{sizeof (union Lisp_Misc)}, which is a size of the
+largest type enumerated in @code{enum Lisp_Misc_Type}.
@item used-miscs
-The number of miscellaneous objects in use. These include markers and
-overlays, plus certain objects not visible to users.
+The number of miscellaneous objects in use. These include markers
+and overlays, plus certain objects not visible to users.
@item free-miscs
The number of miscellaneous objects for which space has been obtained
from the operating system, but that are not currently being used.
-@item used-string-chars
-The total size of all strings, in characters.
+@item string-size
+Internal size of a string header, i.e., @code{sizeof (struct Lisp_String)}.
+
+@item used-strings
+The number of string headers in use.
+
+@item free-strings
+The number of string headers for which space has been obtained
+from the operating system, but that are not currently being used.
+
+@item byte-size
+This is used for convenience and equals to @code{sizeof (char)}.
+
+@item used-bytes
+The total size of all string data in bytes.
+
+@item vector-size
+Internal size of a vector header, i.e., @code{sizeof (struct Lisp_Vector)}.
+
+@item used-vectors
+The number of vector headers allocated from the vector blocks.
+
+@item slot-size
+Internal size of a vector slot, always equal to @code{sizeof (Lisp_Object)}.
-@item used-vector-slots
-The total number of elements of existing vectors.
+@item used-slots
+The number of slots in all used vectors.
+
+@item free-slots
+The number of free slots in all vector blocks.
+
+@item float-size
+Internal size of a float object, i.e., @code{sizeof (struct Lisp_Float)}.
+(Do not confuse it with the native platform @code{float} or @code{double}.)
@item used-floats
The number of floats in use.
@item free-floats
-The number of floats for which space has been obtained from the
-operating system, but that are not currently being used.
+The number of floats for which space has been obtained from
+the operating system, but that are not currently being used.
+
+@item interval-size
+Internal size of an interval object, i.e., @code{sizeof (struct interval)}.
@item used-intervals
-The number of intervals in use. Intervals are an internal
-data structure used for representing text properties.
+The number of intervals in use.
@item free-intervals
-The number of intervals for which space has been obtained
-from the operating system, but that are not currently being used.
+The number of intervals for which space has been obtained from
+the operating system, but that are not currently being used.
-@item used-strings
-The number of strings in use.
+@item buffer-size
+Internal size of a buffer, i.e., @code{sizeof (struct buffer)}.
+(Do not confuse with the value returned by @code{buffer-size} function.)
-@item free-strings
-The number of string headers for which the space was obtained from the
-operating system, but which are currently not in use. (A string
-object consists of a header and the storage for the string text
-itself; the latter is only allocated when the string is created.)
+@item used-buffers
+The number of buffer objects in use. This includes killed buffers
+invisible to users, i.e., all buffers in @code{all_buffers} list.
+
+@item unit-size
+The unit of heap space measurement, always equal to 1024 bytes.
+
+@item total-size
+Total heap size, in @var{unit-size} units.
+
+@item free-size
+Heap space which is not currently used, in @var{unit-size} units.
@end table
If there was overflow in pure space (@pxref{Pure Storage}),
@@ -389,23 +448,25 @@ careful writing them.
@defopt gc-cons-threshold
The value of this variable is the number of bytes of storage that must
be allocated for Lisp objects after one garbage collection in order to
-trigger another garbage collection. A cons cell counts as eight bytes,
-a string as one byte per character plus a few bytes of overhead, and so
-on; space allocated to the contents of buffers does not count. Note
-that the subsequent garbage collection does not happen immediately when
-the threshold is exhausted, but only the next time the Lisp evaluator is
-called.
-
-The initial threshold value is 800,000. If you specify a larger
-value, garbage collection will happen less often. This reduces the
-amount of time spent garbage collecting, but increases total memory use.
-You may want to do this when running a program that creates lots of
-Lisp data.
-
-You can make collections more frequent by specifying a smaller value,
-down to 10,000. A value less than 10,000 will remain in effect only
-until the subsequent garbage collection, at which time
-@code{garbage-collect} will set the threshold back to 10,000.
+trigger another garbage collection. You can use the result returned by
+@code{garbage-collect} to get an information about size of the particular
+object type; space allocated to the contents of buffers does not count.
+Note that the subsequent garbage collection does not happen immediately
+when the threshold is exhausted, but only the next time the Lisp interpreter
+is called.
+
+The initial threshold value is @code{GC_DEFAULT_THRESHOLD}, defined in
+@file{alloc.c}. Since it's defined in @code{word_size} units, the value
+is 400,000 for the default 32-bit configuration and 800,000 for the 64-bit
+one. If you specify a larger value, garbage collection will happen less
+often. This reduces the amount of time spent garbage collecting, but
+increases total memory use. You may want to do this when running a program
+that creates lots of Lisp data.
+
+You can make collections more frequent by specifying a smaller value, down
+to 1/10th of @code{GC_DEFAULT_THRESHOLD}. A value less than this minimum
+will remain in effect only until the subsequent garbage collection, at which
+time @code{garbage-collect} will set the threshold back to the minimum.
@end defopt
@defopt gc-cons-percentage
@@ -640,7 +701,12 @@ in the file @file{lisp.h}.) If the primitive has no upper limit on
the number of Lisp arguments, it must have exactly two C arguments:
the first is the number of Lisp arguments, and the second is the
address of a block containing their values. These have types
-@code{int} and @w{@code{Lisp_Object *}} respectively.
+@code{int} and @w{@code{Lisp_Object *}} respectively. Since
+@code{Lisp_Object} can hold any Lisp object of any data type, you
+can determine the actual data type only at run time; so if you want
+a primitive to accept only a certain type of argument, you must check
+the type explicitly using a suitable predicate (@pxref{Type Predicates}).
+@cindex type checking internals
@cindex @code{GCPRO} and @code{UNGCPRO}
@cindex protect C variables from garbage collection
@@ -821,23 +887,70 @@ knows about it.
@section Object Internals
@cindex object internals
-@c FIXME Is this still true? Does --with-wide-int affect anything?
- GNU Emacs Lisp manipulates many different types of data. The actual
-data are stored in a heap and the only access that programs have to it
-is through pointers. Each pointer is 32 bits wide on 32-bit machines,
-and 64 bits wide on 64-bit machines; three of these bits are used for
-the tag that identifies the object's type, and the remainder are used
-to address the object.
-
- Because Lisp objects are represented as tagged pointers, it is always
-possible to determine the Lisp data type of any object. The C data type
-@code{Lisp_Object} can hold any Lisp object of any data type. Ordinary
-variables have type @code{Lisp_Object}, which means they can hold any
-type of Lisp value; you can determine the actual data type only at run
-time. The same is true for function arguments; if you want a function
-to accept only a certain type of argument, you must check the type
-explicitly using a suitable predicate (@pxref{Type Predicates}).
-@cindex type checking internals
+ Emacs Lisp provides a rich set of the data types. Some of them, like cons
+cells, integers and strings, are common to nearly all Lisp dialects. Some
+others, like markers and buffers, are quite special and needed to provide
+the basic support to write editor commands in Lisp. To implement such
+a variety of object types and provide an efficient way to pass objects between
+the subsystems of an interpreter, there is a set of C data structures and
+a special type to represent the pointers to all of them, which is known as
+@dfn{tagged pointer}.
+
+ In C, the tagged pointer is an object of type @code{Lisp_Object}. Any
+initialized variable of such a type always holds the value of one of the
+following basic data types: integer, symbol, string, cons cell, float,
+vectorlike or miscellaneous object. Each of these data types has the
+corresponding tag value. All tags are enumerated by @code{enum Lisp_Type}
+and placed into a 3-bit bitfield of the @code{Lisp_Object}. The rest of the
+bits is the value itself. Integer values are immediate, i.e., directly
+represented by those @dfn{value bits}, and all other objects are represented
+by the C pointers to a corresponding object allocated from the heap. Width
+of the @code{Lisp_Object} is platform- and configuration-dependent: usually
+it's equal to the width of an underlying platform pointer (i.e., 32-bit on
+a 32-bit machine and 64-bit on a 64-bit one), but also there is a special
+configuration where @code{Lisp_Object} is 64-bit but all pointers are 32-bit.
+The latter trick was designed to overcome the limited range of values for
+Lisp integers on a 32-bit system by using 64-bit @code{long long} type for
+@code{Lisp_Object}.
+
+ The following C data structures are defined in @file{lisp.h} to represent
+the basic data types beyond integers:
+
+@table @code
+@item struct Lisp_Cons
+Cons cell, an object used to construct lists.
+
+@item struct Lisp_String
+String, the basic object to represent a sequence of characters.
+
+@item struct Lisp_Vector
+Array, a fixed-size set of Lisp objects which may be accessed by an index.
+
+@item struct Lisp_Symbol
+Symbol, the unique-named entity commonly used as an identifier.
+
+@item struct Lisp_Float
+Floating point value.
+
+@item union Lisp_Misc
+Miscellaneous kinds of objects which don't fit into any of the above.
+@end table
+
+ These types are the first-class citizens of an internal type system.
+Since the tag space is limited, all other types are the subtypes of either
+@code{Lisp_Vectorlike} or @code{Lisp_Misc}. Vector subtypes are enumerated
+by @code{enum pvec_type}, and nearly all complex objects like windows, buffers,
+frames, and processes fall into this category. The rest of special types,
+including markers and overlays, are enumerated by @code{enum Lisp_Misc_Type}
+and form the set of subtypes of @code{Lisp_Misc}.
+
+ Below there is a description of a few subtypes of @code{Lisp_Vectorlike}.
+Buffer object represents the text to display and edit. Window is the part
+of display structure which shows the buffer or used as a container to
+recursively place other windows on the same frame. (Do not confuse Emacs Lisp
+window object with the window as an entity managed by the user interface
+system like X; in Emacs terminology, the latter is called frame.) Finally,
+process object is used to manage the subprocesses.
@menu
* Buffer Internals:: Components of a buffer structure.
@@ -913,12 +1026,8 @@ Some of the fields of @code{struct buffer} are:
@table @code
@item header
-A @code{struct vectorlike_header} structure where @code{header.next}
-points to the next buffer, in the chain of all buffers (including
-killed buffers). This chain is used only for garbage collection, in
-order to collect killed buffers properly. Note that vectors, and most
-kinds of objects allocated as vectors, are all on one chain, but
-buffers are on a separate chain of their own.
+A header of type @code{struct vectorlike_header} is common to all
+vectorlike objects.
@item own_text
A @code{struct buffer_text} structure that ordinarily holds the buffer
@@ -929,6 +1038,11 @@ A pointer to the @code{buffer_text} structure for this buffer. In an
ordinary buffer, this is the @code{own_text} field above. In an
indirect buffer, this is the @code{own_text} field of the base buffer.
+@item next
+A pointer to the next buffer, in the chain of all buffers, including
+killed buffers. This chain is used only for allocation and garbage
+collection, in order to collect killed buffers properly.
+
@item pt
@itemx pt_byte
The character and byte positions of point in a buffer.
@@ -1419,4 +1533,91 @@ Symbol indicating the type of process: @code{real}, @code{network},
@end table
+@node C Integer Types
+@section C Integer Types
+@cindex integer types (C programming language)
+
+Here are some guidelines for use of integer types in the Emacs C
+source code. These guidelines sometimes give competing advice; common
+sense is advised.
+
+@itemize @bullet
+@item
+Avoid arbitrary limits. For example, avoid @code{int len = strlen
+(s);} unless the length of @code{s} is required for other reasons to
+fit in @code{int} range.
+
+@item
+Do not assume that signed integer arithmetic wraps around on overflow.
+This is no longer true of Emacs porting targets: signed integer
+overflow has undefined behavior in practice, and can dump core or
+even cause earlier or later code to behave ``illogically''. Unsigned
+overflow does wrap around reliably, modulo a power of two.
+
+@item
+Prefer signed types to unsigned, as code gets confusing when signed
+and unsigned types are combined. Many other guidelines assume that
+types are signed; in the rarer cases where unsigned types are needed,
+similar advice may apply to the unsigned counterparts (e.g.,
+@code{size_t} instead of @code{ptrdiff_t}, or @code{uintptr_t} instead
+of @code{intptr_t}).
+
+@item
+Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF.
+
+@item
+Prefer @code{ptrdiff_t} for sizes, i.e., for integers bounded by the
+maximum size of any individual C object or by the maximum number of
+elements in any C array. This is part of Emacs's general preference
+for signed types. Using @code{ptrdiff_t} limits objects to
+@code{PTRDIFF_MAX} bytes, but larger objects would cause trouble
+anyway since they would break pointer subtraction, so this does not
+impose an arbitrary limit.
+
+@item
+Prefer @code{intptr_t} for internal representations of pointers, or
+for integers bounded only by the number of objects that can exist at
+any given time or by the total number of bytes that can be allocated.
+Currently Emacs sometimes uses other types when @code{intptr_t} would
+be better; fixing this is lower priority, as the code works as-is on
+Emacs's current porting targets.
+
+@item
+Prefer the Emacs-defined type @code{EMACS_INT} for representing values
+converted to or from Emacs Lisp fixnums, as fixnum arithmetic is based
+on @code{EMACS_INT}.
+
+@item
+When representing a system value (such as a file size or a count of
+seconds since the Epoch), prefer the corresponding system type (e.g.,
+@code{off_t}, @code{time_t}). Do not assume that a system type is
+signed, unless this assumption is known to be safe. For example,
+although @code{off_t} is always signed, @code{time_t} need not be.
+
+@item
+Prefer the Emacs-defined type @code{printmax_t} for representing
+values that might be any signed integer value that can be printed,
+using a @code{printf}-family function.
+
+@item
+Prefer @code{intmax_t} for representing values that might be any
+signed integer value.
+
+@item
+In bitfields, prefer @code{unsigned int} or @code{signed int} to
+@code{int}, as @code{int} is less portable: it might be signed, and
+might not be. Single-bit bit fields are invariably @code{unsigned
+int} so that their values are 0 and 1.
+
+@item
+In C, Emacs commonly uses @code{bool}, 1, and 0 for boolean values.
+Using @code{bool} for booleans can make programs easier to read and a
+bit faster than using @code{int}. Although it is also OK to use
+@code{int}, this older style is gradually being phased out. When
+using @code{bool}, respect the limitations of the replacement
+implementation of @code{bool}, as documented in the source file
+@file{lib/stdbool.in.h}, so that Emacs remains portable to pre-C99
+platforms.
+@end itemize
+
@c FIXME Mention src/globals.h somewhere in this file?
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 8c2c8498a5c..51a060bc6c6 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -729,7 +729,7 @@ file should call @code{provide} at the top level to add the feature to
(defun idlwave-complete-filename ()
"Use the comint stuff to complete a file name."
(require 'comint)
- (let* ((comint-file-name-chars "~/A-Za-z0-9+@:_.$#%=@{@}\\-")
+ (let* ((comint-file-name-chars "~/A-Za-z0-9+@@:_.$#%=@{@}\\-")
(comint-completion-addsuffix nil)
...)
(comint-dynamic-complete-filename)))
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 7093f7fe336..7d42d2591d6 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2149,11 +2149,6 @@ visible on screen; or @samp{Bottom} or @samp{All}.
The status of the subprocess belonging to the current buffer, obtained with
@code{process-status}. @xref{Process Information}.
-@item %t
-Whether the visited file is a text file or a binary file. This is a
-meaningful distinction only on certain operating systems (@pxref{MS-DOS
-File Types}).
-
@item %z
The mnemonics of keyboard, terminal, and buffer coding systems.
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index 9ad68be60cb..e462c3b4ce4 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -855,8 +855,6 @@ documented here.
for a single file operation.
* Explicit Encoding:: Encoding or decoding text without doing I/O.
* Terminal I/O Encoding:: Use of encoding for terminal I/O.
-* MS-DOS File Types:: How DOS "text" and "binary" files
- relate to coding systems.
@end menu
@node Coding System Basics
@@ -1775,62 +1773,6 @@ for encoding terminal output from @var{terminal}. If
@code{nil}, that means the currently selected frame's terminal.
@end deffn
-@node MS-DOS File Types
-@subsection MS-DOS File Types
-@cindex DOS file types
-@cindex MS-DOS file types
-@cindex Windows file types
-@cindex file types on MS-DOS and Windows
-@cindex text files and binary files
-@cindex binary files and text files
-
- On MS-DOS and Microsoft Windows, Emacs guesses the appropriate
-end-of-line conversion for a file by looking at the file's name. This
-feature classifies files as @dfn{text files} and @dfn{binary files}. By
-``binary file'' we mean a file of literal byte values that are not
-necessarily meant to be characters; Emacs does no end-of-line conversion
-and no character code conversion for them. On the other hand, the bytes
-in a text file are intended to represent characters; when you create a
-new file whose name implies that it is a text file, Emacs uses DOS
-end-of-line conversion.
-
-@defvar buffer-file-type
-This variable, automatically buffer-local in each buffer, records the
-file type of the buffer's visited file. When a buffer does not specify
-a coding system with @code{buffer-file-coding-system}, this variable is
-used to determine which coding system to use when writing the contents
-of the buffer. It should be @code{nil} for text, @code{t} for binary.
-If it is @code{t}, the coding system is @code{no-conversion}.
-Otherwise, @code{undecided-dos} is used.
-
-Normally this variable is set by visiting a file; it is set to
-@code{nil} if the file was visited without any actual conversion.
-
-Its default value is used to decide how to handle files for which
-@code{file-name-buffer-file-type-alist} says nothing about the type:
-If the default value is non-@code{nil}, then these files are treated as
-binary: the coding system @code{no-conversion} is used. Otherwise,
-nothing special is done for them---the coding system is deduced solely
-from the file contents, in the usual Emacs fashion.
-@end defvar
-
-@defopt file-name-buffer-file-type-alist
-This variable holds an alist for recognizing text and binary files.
-Each element has the form (@var{regexp} . @var{type}), where
-@var{regexp} is matched against the file name, and @var{type} may be
-@code{nil} for text, @code{t} for binary, or a function to call to
-compute which. If it is a function, then it is called with a single
-argument (the file name) and should return @code{t} or @code{nil}.
-
-When running on MS-DOS or MS-Windows, Emacs checks this alist to decide
-which coding system to use when reading a file. For a text file,
-@code{undecided-dos} is used. For a binary file, @code{no-conversion}
-is used.
-
-If no element in this alist matches a given file name, then
-the default value of @code{buffer-file-type} says how to treat the file.
-@end defopt
-
@node Input Methods
@section Input Methods
@cindex input methods
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 6506cdb5da0..b481c330f9f 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1157,6 +1157,16 @@ This function returns the effective @acronym{UID} of the user.
The value may be a floating point number.
@end defun
+@defun group-gid
+This function returns the effective @acronym{GID} of the Emacs process.
+The value may be a floating point number.
+@end defun
+
+@defun group-real-gid
+This function returns the real @acronym{GID} of the Emacs process.
+The value may be a floating point number.
+@end defun
+
@defun system-users
This function returns a list of strings, listing the user names on the
system. If Emacs cannot retrieve this information, the return value
@@ -2276,13 +2286,19 @@ These arguments should consist of alternating keyword and value pairs.
The supported keywords and values are as follows:
@table @code
+@item :bus @var{bus}
+The D-Bus bus. This argument is needed only if a bus other than
+@code{:session} shall be used.
+
@item :title @var{title}
The notification title.
@item :body @var{text}
The notification body text. Depending on the implementation of the
notification server, the text could contain HTML markups, like
-@samp{"<b>bold text</b>"}, hyperlinks, or images.
+@samp{"<b>bold text</b>"}, hyperlinks, or images. Special HTML
+characters must be encoded, as @samp{"Contact
+&lt;postmaster@@localhost&gt;!"}.
@item :app-name @var{name}
The name of the application sending the notification. The default is
@@ -2317,7 +2333,10 @@ When this keyword is given, the @var{title} string of the actions is
interpreted as icon name.
@item :category @var{category}
-The type of notification this is, a string.
+The type of notification this is, a string. See the
+@uref{http://developer.gnome.org/notification-spec/#categories,
+Desktop Notifications Specification} for a list of standard
+categories.
@item :desktop-entry @var{filename}
This specifies the name of the desktop filename representing the
@@ -2420,13 +2439,17 @@ A message window opens on the desktop. Press "I agree"
@end example
@end defun
-@defun notifications-close-notification id
+@defun notifications-close-notification id &optional bus
This function closes a notification with identifier @var{id}.
+@var{bus} can be a string denoting a D-Bus connection, the default is
+@code{:session}.
@end defun
-@defun notifications-get-capabilities
-Returns the capabilities of the notification server, a list of strings.
-The following capabilities can be expected:
+@defun notifications-get-capabilities &optional bus
+Returns the capabilities of the notification server, a list of
+symbols. @var{bus} can be a string denoting a D-Bus connection, the
+default is @code{:session}. The following capabilities can be
+expected:
@table @code
@item :actions
@@ -2463,6 +2486,30 @@ Further vendor-specific caps start with @code{:x-vendor}, like
@code{:x-gnome-foo-cap}.
@end defun
+@defun notifications-get-server-information &optional bus
+Return information on the notification server, a list of strings.
+@var{bus} can be a string denoting a D-Bus connection, the default is
+@code{:session}. The returned list is @code{(@var{name} @var{vendor}
+@var{version} @var{spec-version})}.
+
+@table @var
+@item name
+The product name of the server.
+
+@item vendor
+The vendor name. For example, @samp{"KDE"}, @samp{"GNOME"}.
+
+@item version
+The server's version number.
+
+@item spec-version
+The specification version the server is compliant with.
+@end table
+
+If @var{SPEC_VERSION} is @code{nil}, the server supports a
+specification prior to @samp{"1.0"}.
+@end defun
+
@node Dynamic Libraries
@section Dynamically Loaded Libraries
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 3e6c8266ef9..9f916549902 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -564,7 +564,7 @@ side-effects, for determining function safety (@pxref{Function
Safety}) as well as for byte compiler optimizations. Do not set it.
@item variable-documentation
-If non-@code{nil}, this specifies the named vaariable's documentation
+If non-@code{nil}, this specifies the named variable's documentation
string. This is set automatically by @code{defvar} and related
functions. @xref{Defining Faces}.
@end table
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 4f467f96d71..4c443da3af8 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -942,6 +942,7 @@ explains these conventions, starting with an example:
;; Created: 14 Jul 2010
@group
;; Keywords: languages
+;; Homepage: http://example.com/foo
;; This file is not part of GNU Emacs.
@@ -980,8 +981,7 @@ the conventional possibilities for @var{header-name}:
@item Author
This line states the name and email address of at least the principal
author of the library. If there are multiple authors, list them on
-continuation lines led by @code{;;} and whitespace (this is easier
-for tools to parse than having more than one author on one line).
+continuation lines led by @code{;;} and a tab or at least two spaces.
We recommend including a contact email address, of the form
@samp{<@dots{}>}. For example:
@@ -1028,6 +1028,9 @@ The name of this field is unfortunate, since people often assume it is
the place to write arbitrary keywords that describe their package,
rather than just the relevant Finder keywords.
+@item Homepage
+This line states the homepage of the library.
+
@item Package-Version
If @samp{Version} is not suitable for use by the package manager, then
a package can define @samp{Package-Version}; it will be used instead.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index cca337df4fb..792002add81 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1084,7 +1084,7 @@ including the space earlier stolen from @var{W3}.
@end smallexample
@noindent
-This can be counterintutive, in particular if @var{W4} were used for
+This can be counterintuitive, in particular if @var{W4} were used for
displaying a buffer only temporarily (@pxref{Temporary Displays}), and
you want to continue working with the initial layout.
@@ -2443,7 +2443,7 @@ buffer previously shown no longer exists, this function calls
@code{switch-to-prev-buffer} (@pxref{Window History}) to show some other
buffer instead.
-The optional argument @var{bury-or-kill} specifes how to deal with
+The optional argument @var{bury-or-kill} specifies how to deal with
@var{window}'s buffer. The following values are handled:
@table @code
generated by cgit v1.2.3 (git 2.39.1) at 2025-04-25 23:51:31 +0000