summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/emacs/dired.texi11
-rw-r--r--doc/emacs/files.texi7
-rw-r--r--doc/emacs/text.texi7
-rw-r--r--doc/lispref/edebug.texi30
-rw-r--r--doc/lispref/elisp.texi1
-rw-r--r--doc/lispref/eval.texi123
-rw-r--r--doc/lispref/files.texi10
-rw-r--r--doc/lispref/functions.texi31
-rw-r--r--doc/lispref/numbers.texi18
-rw-r--r--doc/lispref/strings.texi9
-rw-r--r--doc/lispref/text.texi118
-rw-r--r--doc/misc/auth.texi15
-rw-r--r--doc/misc/ert.texi14
-rw-r--r--doc/misc/gnus.texi7
-rw-r--r--doc/misc/texinfo.tex5
-rw-r--r--doc/misc/tramp.texi263
-rw-r--r--doc/misc/trampver.texi2
17 files changed, 614 insertions, 57 deletions
diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index b8450ce9982..ff0b2ae3a77 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -648,6 +648,14 @@ Copy the specified files (@code{dired-do-copy}). The argument @var{new}
is the directory to copy into, or (if copying a single file) the new
name. This is like the shell command @code{cp}.
+@vindex dired-create-destination-dirs
+The option @code{dired-create-destination-dirs} controls whether Dired
+should create non-existent directories in the destination while
+copying/renaming files. The default value @code{nil} means Dired
+never creates such missing directories; the value @code{always},
+means Dired automatically creates them; the value @code{ask}
+means Dired asks you for confirmation before creating them.
+
@vindex dired-copy-preserve-time
If @code{dired-copy-preserve-time} is non-@code{nil}, then copying
with this command preserves the modification time of the old file in
@@ -679,6 +687,9 @@ single file, the argument @var{new} is the new name of the file. If
you rename several files, the argument @var{new} is the directory into
which to move the files (this is like the shell command @command{mv}).
+The option @code{dired-create-destination-dirs} controls whether Dired
+should create non-existent directories in @var{new}.
+
Dired automatically changes the visited file name of buffers associated
with renamed files so that they refer to the new names.
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 586086dda28..881210aab9a 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1280,13 +1280,8 @@ default), and @code{list-directory-verbose-switches} is a string
giving the switches to use in a verbose listing (@code{"-l"} by
default).
-@vindex directory-free-space-program
-@vindex directory-free-space-args
In verbose directory listings, Emacs adds information about the
-amount of free space on the disk that contains the directory. To do
-this, it runs the program specified by
-@code{directory-free-space-program} with arguments
-@code{directory-free-space-args}.
+amount of free space on the disk that contains the directory.
The command @kbd{M-x delete-directory} prompts for a directory's name
using the minibuffer, and deletes the directory if it is empty. If
diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index bb837f94d3b..846d9fe8c62 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -457,6 +457,13 @@ non-@code{nil}, and in programming-language strings if
@code{nil} for @code{electric-quote-string} and @code{t} for the other
variables.
+@vindex electric-quote-replace-double
+ You can also set the option @code{electric-quote-replace-double} to
+a non-@code{nil} value. Then, typing @t{"} insert an appropriate
+curved double quote depending on context: @t{“} at the beginning of
+the buffer or after a line break, whitespace, opening parenthesis, or
+quote character, and @t{”} otherwise.
+
Electric Quote mode is disabled by default. To toggle it in a
single buffer, use @kbd{M-x electric-quote-local-mode}.
To toggle it globally, type
diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index 1b0d314ee71..1a883e0f142 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -1702,3 +1702,33 @@ Whether or not to pause for @code{edebug-sit-for-seconds} on reaching
a breakpoint. Set to @code{nil} to prevent the pause, non-@code{nil}
to allow it.
@end defopt
+
+@defopt edebug-behavior-alist
+By default, this alist contains one entry with the key @code{edebug}
+and a list of three functions, which are the default implementations
+of the functions inserted in instrumented code: @code{edebug-enter},
+@code{edebug-before} and @code{edebug-after}. To change Edebug's
+behavior globally, modify the default entry.
+
+Edebug's behavior may also be changed on a per-definition basis by
+adding an entry to this alist, with a key of your choice and three
+functions. Then set the @code{edebug-behavior} symbol property of an
+instrumented definition to the key of the new entry, and Edebug will
+call the new functions in place of its own for that definition.
+@end defopt
+
+@defopt edebug-new-definition-function
+A function run by Edebug after it wraps the body of a definition
+or closure. After Edebug has initialized its own data, this function
+is called with one argument, the symbol associated with the
+definition, which may be the actual symbol defined or one generated by
+Edebug. This function may be used to set the @code{edebug-behavior}
+symbol property of each definition instrumented by Edebug.
+@end defopt
+
+@defopt edebug-after-instrumentation-function
+To inspect or modify Edebug's instrumentation before it is used, set
+this variable to a function which takes one argument, an instrumented
+top-level form, and returns either the same or a replacement form,
+which Edebug will then use as the final result of instrumentation.
+@end defopt
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 6b59e319172..9389aa1ba19 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -455,6 +455,7 @@ Evaluation
the program).
* Backquote:: Easier construction of list structure.
* Eval:: How to invoke the Lisp interpreter explicitly.
+* Deferred Eval:: Deferred and lazy evaluation of forms.
Kinds of Forms
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 2590de30c79..b5d19f20c2d 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -20,11 +20,12 @@ function @code{eval}.
@ifnottex
@menu
-* Intro Eval:: Evaluation in the scheme of things.
-* Forms:: How various sorts of objects are evaluated.
-* Quoting:: Avoiding evaluation (to put constants in the program).
-* Backquote:: Easier construction of list structure.
-* Eval:: How to invoke the Lisp interpreter explicitly.
+* Intro Eval:: Evaluation in the scheme of things.
+* Forms:: How various sorts of objects are evaluated.
+* Quoting:: Avoiding evaluation (to put constants in the program).
+* Backquote:: Easier construction of list structure.
+* Eval:: How to invoke the Lisp interpreter explicitly.
+* Deferred Eval:: Deferred and lazy evaluation of forms.
@end menu
@node Intro Eval
@@ -877,3 +878,115 @@ particular elements, like this:
@end group
@end example
@end defvar
+
+@node Deferred Eval
+@section Deferred and Lazy Evaluation
+
+@cindex deferred evaluation
+@cindex lazy evaluation
+
+
+ Sometimes it is useful to delay the evaluation of an expression, for
+example if you want to avoid performing a time-consuming calculation
+if it turns out that the result is not needed in the future of the
+program. The @file{thunk} library provides the following functions
+and macros to support such @dfn{deferred evaluation}:
+
+@cindex thunk
+@defmac thunk-delay forms@dots{}
+Return a @dfn{thunk} for evaluating the @var{forms}. A thunk is a
+closure (@pxref{Closures}) that inherits the lexical environment of the
+@code{thunk-delay} call. Using this macro requires
+@code{lexical-binding}.
+@end defmac
+
+@defun thunk-force thunk
+Force @var{thunk} to perform the evaluation of the forms specified in
+the @code{thunk-delay} that created the thunk. The result of the
+evaluation of the last form is returned. The @var{thunk} also
+``remembers'' that it has been forced: Any further calls of
+@code{thunk-force} with the same @var{thunk} will just return the same
+result without evaluating the forms again.
+@end defun
+
+@defmac thunk-let (bindings@dots{}) forms@dots{}
+This macro is analogous to @code{let} but creates ``lazy'' variable
+bindings. Any binding has the form @w{@code{(@var{symbol}
+@var{value-form})}}. Unlike @code{let}, the evaluation of any
+@var{value-form} is deferred until the binding of the according
+@var{symbol} is used for the first time when evaluating the
+@var{forms}. Any @var{value-form} is evaluated at most once. Using
+this macro requires @code{lexical-binding}.
+@end defmac
+
+Example:
+
+@example
+@group
+(defun f (number)
+ (thunk-let ((derived-number
+ (progn (message "Calculating 1 plus 2 times %d" number)
+ (1+ (* 2 number)))))
+ (if (> number 10)
+ derived-number
+ number)))
+@end group
+
+@group
+(f 5)
+@result{} 5
+@end group
+
+@group
+(f 12)
+@print{} Calculating 1 plus 2 times 12
+@result{} 25
+@end group
+
+@end example
+
+Because of the special nature of lazily bound variables, it is an error
+to set them (e.g.@: with @code{setq}).
+
+
+@defmac thunk-let* (bindings@dots{}) forms@dots{}
+This is like @code{thunk-let} but any expression in @var{bindings} is allowed
+to refer to preceding bindings in this @code{thunk-let*} form. Using
+this macro requires @code{lexical-binding}.
+@end defmac
+
+@example
+@group
+(thunk-let* ((x (prog2 (message "Calculating x...")
+ (+ 1 1)
+ (message "Finished calculating x")))
+ (y (prog2 (message "Calculating y...")
+ (+ x 1)
+ (message "Finished calculating y")))
+ (z (prog2 (message "Calculating z...")
+ (+ y 1)
+ (message "Finished calculating z")))
+ (a (prog2 (message "Calculating a...")
+ (+ z 1)
+ (message "Finished calculating a"))))
+ (* z x))
+
+@print{} Calculating z...
+@print{} Calculating y...
+@print{} Calculating x...
+@print{} Finished calculating x
+@print{} Finished calculating y
+@print{} Finished calculating z
+@result{} 8
+
+@end group
+@end example
+
+@code{thunk-let} and @code{thunk-let*} use thunks implicitly: their
+expansion creates helper symbols and binds them to thunks wrapping the
+binding expressions. All references to the original variables in the
+body @var{forms} are then replaced by an expression that calls
+@code{thunk-force} with the according helper variable as the argument.
+So, any code using @code{thunk-let} or @code{thunk-let*} could be
+rewritten to use thunks, but in many cases using these macros results
+in nicer code than using thunks explicitly.
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 162fc1eb1ef..021a62a56ab 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2110,7 +2110,7 @@ Note that the @samp{.~3~} in the two last examples is the backup part,
not an extension.
@end defun
-@defun file-name-base &optional filename
+@defun file-name-base filename
This function is the composition of @code{file-name-sans-extension}
and @code{file-name-nondirectory}. For example,
@@ -2118,8 +2118,6 @@ and @code{file-name-nondirectory}. For example,
(file-name-base "/my/home/foo.c")
@result{} "foo"
@end example
-
-The @var{filename} argument defaults to @code{buffer-file-name}.
@end defun
@node Relative File Names
@@ -3140,7 +3138,8 @@ first, before handlers for jobs such as remote file access.
@code{file-ownership-preserved-p},
@code{file-readable-p}, @code{file-regular-p},
@code{file-remote-p}, @code{file-selinux-context},
-@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
+@code{file-symlink-p}, @code{file-system-info},
+@code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},@*
@code{get-file-buffer},
@code{insert-directory},
@@ -3196,7 +3195,8 @@ first, before handlers for jobs such as remote file access.
@code{file-ownership-pre@discretionary{}{}{}served-p},
@code{file-readable-p}, @code{file-regular-p},
@code{file-remote-p}, @code{file-selinux-context},
-@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
+@code{file-symlink-p}, @code{file-system-info},
+@code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
@code{get-file-buffer},
@code{insert-directory},
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index c6188ce466d..c3e5dc0eb5b 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1225,7 +1225,7 @@ This form defines a method like @code{cl-defmethod} does.
@end table
@end defmac
-@defmac cl-defmethod name [qualifier] arguments &rest [docstring] body
+@defmac cl-defmethod name [qualifier] arguments [&context (expr spec)@dots{}] &rest [docstring] body
This macro defines a particular implementation for the generic
function called @var{name}. The implementation code is given by
@var{body}. If present, @var{docstring} is the documentation string
@@ -1246,21 +1246,26 @@ This specializer requires the argument be @code{eql} to the given
@item (head @var{object})
The argument must be a cons cell whose @code{car} is @code{eql} to
@var{object}.
-@item @var{struct-tag}
-The argument must be an instance of a class named @var{struct-tag}
+@item @var{struct-type}
+The argument must be an instance of a class named @var{struct-type}
defined with @code{cl-defstruct} (@pxref{Structures,,, cl, Common Lisp
-Extensions for GNU Emacs Lisp}), or of one of its parent classes.
+Extensions for GNU Emacs Lisp}), or of one of its child classes.
@end table
-Alternatively, the argument specializer can be of the form
-@code{&context (@var{expr} @var{spec})}, in which case the value of
-@var{expr} must be compatible with the specializer provided by
-@var{spec}; @var{spec} can be any of the forms described above. In
-other words, this form of specializer uses the value of @var{expr}
-instead of arguments for the decision whether the method is
-applicable. For example, @code{&context (overwrite-mode (eql t))}
-will make the method compatible only when @code{overwrite-mode} is
-turned on.
+Method definitions can make use of a new argument-list keyword,
+@code{&context}, which introduces extra specializers that test the
+environment at the time the method is run. This keyword should appear
+after the list of required arguments, but before any @code{&rest} or
+@code{&optional} keywords. The @code{&context} specializers look much
+like regular argument specializers---(@var{expr} @var{spec})---except
+that @var{expr} is an expression to be evaluated in the current
+context, and the @var{spec} is a value to compare against. For
+example, @code{&context (overwrite-mode (eql t))} will make the method
+applicable only when @code{overwrite-mode} is turned on. The
+@code{&context} keyword can be followed by any number of context
+specializers. Because the context specializers are not part of the
+generic function's argument signature, they may be omitted in methods
+that don't require them.
The type specializer, @code{(@var{arg} @var{type})}, can specify one
of the @dfn{system types} in the following list. When a parent type
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index c12ffe2cde7..e692ee1cc2f 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -1107,6 +1107,24 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in
@end example
@end defun
+@cindex popcount
+@cindex Hamming weight
+@cindex counting set bits
+@defun logcount integer
+This function returns the @dfn{Hamming weight} of @var{integer}: the
+number of ones in the binary representation of @var{integer}.
+If @var{integer} is negative, it returns the number of zero bits in
+its two's complement binary representation. The result is always
+nonnegative.
+
+@example
+(logcount 43) ; 43 = #b101011
+ @result{} 4
+(logcount -43) ; -43 = #b111...1010101
+ @result{} 3
+@end example
+@end defun
+
@node Math Functions
@section Standard Mathematical Functions
@cindex transcendental functions
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 756e7efb957..c8261e316f2 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -121,7 +121,7 @@ character (i.e., an integer), @code{nil} otherwise.
The following functions create strings, either from scratch, or by
putting strings together, or by taking them apart.
-@defun make-string count character
+@defun make-string count character &optional multibyte
This function returns a string made up of @var{count} repetitions of
@var{character}. If @var{count} is negative, an error is signaled.
@@ -132,6 +132,13 @@ This function returns a string made up of @var{count} repetitions of
@result{} ""
@end example
+ Normally, if @var{character} is an @acronym{ASCII} character, the
+result is a unibyte string. But if the optional argument
+@var{multibyte} is non-@code{nil}, the function will produce a
+multibyte string instead. This is useful when you later need to
+concatenate the result with non-@acronym{ASCII} strings or replace
+some of its characters with non-@acronym{ASCII} characters.
+
Other functions to compare with this one include @code{make-vector}
(@pxref{Vectors}) and @code{make-list} (@pxref{Building Lists}).
@end defun
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index f590a20896f..c62862f2100 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -61,6 +61,7 @@ the character after point.
* Checksum/Hash:: Computing cryptographic hashes.
* GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS.
* Parsing HTML/XML:: Parsing HTML and XML.
+* Parsing JSON:: Parsing and generating JSON values.
* Atomic Changes:: Installing several buffer changes atomically.
* Change Hooks:: Supplying functions to be run when text is changed.
@end menu
@@ -4516,9 +4517,9 @@ It should be somewhat more efficient on larger buffers than
@cindex symmetric cipher
@cindex cipher, symmetric
-If compiled with GnuTLS, Emacs offers built-in cryptographic support.
-Following the GnuTLS API terminology, the available tools are digests,
-MACs, symmetric ciphers, and AEAD ciphers.
+ If compiled with GnuTLS, Emacs offers built-in cryptographic
+support. Following the GnuTLS API terminology, the available tools
+are digests, MACs, symmetric ciphers, and AEAD ciphers.
The terms used herein, such as IV (Initialization Vector), require
some familiarity with cryptography and will not be defined in detail.
@@ -4536,7 +4537,7 @@ structure of the GnuTLS library.
@cindex format of gnutls cryptography inputs
@cindex gnutls cryptography inputs format
-The inputs to GnuTLS cryptographic functions can be specified in
+ The inputs to GnuTLS cryptographic functions can be specified in
several ways, both as primitive Emacs Lisp types or as lists.
The list form is currently similar to how @code{md5} and
@@ -4703,8 +4704,15 @@ IV used.
@section Parsing HTML and XML
@cindex parsing html
-When Emacs is compiled with libxml2 support, the following functions
-are available to parse HTML or XML text into Lisp object trees.
+ Emacs can be compiled with built-in libxml2 support.
+
+@defun libxml-available-p
+This function returns non-@code{nil} if built-in libxml2 support is
+available in this Emacs session.
+@end defun
+
+When libxml2 support is available, the following functions can be used
+to parse HTML or XML text into Lisp object trees.
@defun libxml-parse-html-region start end &optional base-url discard-comments
This function parses the text between @var{start} and @var{end} as
@@ -4771,9 +4779,9 @@ about syntax).
@cindex DOM
@cindex Document Object Model
-The @acronym{DOM} returned by @code{libxml-parse-html-region} (and the
-other @acronym{XML} parsing functions) is a tree structure where each
-node has a node name (called a @dfn{tag}), and optional key/value
+ The @acronym{DOM} returned by @code{libxml-parse-html-region} (and
+the other @acronym{XML} parsing functions) is a tree structure where
+each node has a node name (called a @dfn{tag}), and optional key/value
@dfn{attribute} list, and then a list of @dfn{child nodes}. The child
nodes are either strings or @acronym{DOM} objects.
@@ -4891,6 +4899,98 @@ textual nodes that just contain white-space.
@end table
+@node Parsing JSON
+@section Parsing and generating JSON values
+@cindex JSON
+
+ When Emacs is compiled with JSON support, it provides a couple of
+functions to convert between Lisp objects and JSON values. Any JSON
+value can be converted to a Lisp object, but not vice versa.
+Specifically:
+
+@itemize
+
+@item
+JSON has a couple of keywords: @code{null}, @code{false}, and
+@code{true}. These are represented in Lisp using the keywords
+@code{:null}, @code{:false}, and @code{t}, respectively.
+
+@item
+JSON only has floating-point numbers. They can represent both Lisp
+integers and Lisp floating-point numbers.
+
+@item
+JSON strings are always Unicode strings. Lisp strings can contain
+non-Unicode characters.
+
+@item
+JSON has only one sequence type, the array. JSON arrays are
+represented using Lisp vectors.
+
+@item
+JSON has only one map type, the object. JSON objects are represented
+using Lisp hashtables or alists. When an alist contains several
+elements with the same key, Emacs uses only the first element for
+serialization, in accordance with the behavior of @code{assq}.
+
+@end itemize
+
+@noindent
+Note that @code{nil} is a valid alist and represents the empty JSON
+object, @code{@{@}}, not @code{null}, @code{false}, or an empty array,
+all of which are different JSON values.
+
+ If some Lisp object can't be represented in JSON, the serialization
+functions will signal an error of type @code{wrong-type-argument}.
+The parsing functions will signal the following errors:
+
+@table @code
+
+@item json-end-of-file
+ Signaled when encountering a premature end of the input text.
+
+@item json-trailing-content
+ Signaled when encountering unexpected input after the first JSON
+ object parsed.
+
+@item json-parse-error
+ Signaled when encountering invalid JSON syntax.
+
+@end table
+
+ Only top-level values (arrays and objects) can be serialized to
+JSON. The subobjects within these top-level values can be of any
+type. Likewise, the parsing functions will only return vectors,
+hashtables, and alists.
+
+ The parsing functions accept keyword arguments. Currently only one
+keyword argument, @code{:object-type}, is recognized; its value can be
+either @code{hash-table} to parse JSON objects as hashtables with
+string keys (the default) or @code{alist} to parse them as alists.
+
+@defun json-serialize object
+This function returns a new Lisp string which contains the JSON
+representation of @var{object}.
+@end defun
+
+@defun json-insert object
+This function inserts the JSON representation of @var{object} into the
+current buffer before point.
+@end defun
+
+@defun json-parse-string string &key (object-type @code{hash-table})
+This function parses the JSON value in @var{string}, which must be a
+Lisp string.
+@end defun
+
+@defun json-parse-buffer &key (object-type @code{hash-table})
+This function reads the next JSON value from the current buffer,
+starting at point. It moves point to the position immediately after
+the value if a value could be read and converted to Lisp; otherwise it
+doesn't move point.
+@end defun
+
+
@node Atomic Changes
@section Atomic Change Groups
@cindex atomic changes
diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index f1667c49f1a..9cf16d8ed4f 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -86,7 +86,7 @@ password (known as the secret).
Similarly, the auth-source library supports multiple storage backend,
currently either the classic ``netrc'' backend, examples of which you
-can see later in this document, the Secret Service API, and pass, the
+can see later in this document, JSON files, the Secret Service API, and pass, the
standard unix password manager. This is done with EIEIO-based
backends and you can write your own if you want.
@@ -169,6 +169,9 @@ get fancy, the default and simplest configuration is:
;;; use pass (@file{~/.password-store})
;;; (@pxref{The Unix password store})
(setq auth-sources '(password-store))
+;;; JSON data in format [@{ "machine": "SERVER",
+;;; "login": "USER", "password": "PASSWORD" @}...]
+(setq auth-sources '("~/.authinfo.json.gpg"))
@end lisp
By adding multiple entries to @code{auth-sources} with a particular
@@ -235,6 +238,16 @@ don't use a port entry, you match any Tramp method, as explained
earlier. Since Tramp has about 88 connection methods, this may be
necessary if you have an unusual (see earlier comment on those) setup.
+The netrc format is directly translated into JSON, if you are into
+that sort of thing. Just point to a JSON file with entries like this:
+
+@example
+[
+ @{ "machine": "yourmachine.com", "port": "http",
+ "login": "testuser", "password": "testpass" @}
+]
+@end example
+
@node Multiple GMail accounts with Gnus
@chapter Multiple GMail accounts with Gnus
diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi
index 9efca79e95a..3553560f497 100644
--- a/doc/misc/ert.texi
+++ b/doc/misc/ert.texi
@@ -321,6 +321,20 @@ summary as shown below:
emacs -batch -l ert -f ert-summarize-tests-batch-and-exit output.log
@end example
+@vindex ert-quiet
+By default, ERT in batch mode is quite verbose, printing a line with
+result after each test. This gives you progress information: how many
+tests have been executed and how many there are. However, in some
+cases this much output may be undesirable. In this case, set
+@code{ert-quiet} variable to a non-nil value:
+
+@example
+emacs -batch -l ert -l my-tests.el \
+ --eval "(let ((ert-quiet t)) (ert-run-tests-batch-and-exit))"
+@end example
+
+In quiet mode ERT prints only unexpected results and summary.
+
If ERT is not part of your Emacs distribution, you may need to use
@code{-L /path/to/ert/} so that Emacs can find it. You may need
additional @code{-L} flags to ensure that @code{my-tests.el} and all the
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index 1b941bca2ab..8c2fc56dd6e 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -13216,6 +13216,11 @@ Also @pxref{Formatting Variables}.
@subsection Server Commands
@cindex server commands
+The following keybinding are available in the server buffer. Be aware
+that some of the commands will only work on servers that you've added
+through this interface (with @kbd{a}), not with servers you've defined
+in your init files.
+
@table @kbd
@item v
@@ -18487,7 +18492,7 @@ something along the lines of the following:
(defun my-article-old-p ()
"Say whether an article is old."
(< (time-to-days (date-to-time (mail-header-date gnus-headers)))
- (- (time-to-days (current-time)) gnus-agent-expire-days)))
+ (- (time-to-days nil) gnus-agent-expire-days)))
@end lisp
with the predicate then defined as:
diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex
index b0179d6b007..1987c50ba26 100644
--- a/doc/misc/texinfo.tex
+++ b/doc/misc/texinfo.tex
@@ -5,7 +5,10 @@
%
\def\texinfoversion{2017-12-26.21}
%
-% Copyright 1985-1986, 1988, 1990-2018 Free Software Foundation, Inc.
+% Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
+% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
+% 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017
+% Free Software Foundation, Inc.
%
% This texinfo.tex file is free software: you can redistribute it and/or
% modify it under the terms of the GNU General Public License as
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index c1f941a640f..deaafb3d257 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -164,6 +164,7 @@ Using @value{tramp}
* Ad-hoc multi-hops:: Declaring multiple hops in the file name.
* Remote processes:: Integration with other Emacs packages.
* Cleanup remote connections:: Cleanup remote connections.
+* Archive file names:: Access to files in file archives.
How file names, directories and localnames are mangled and managed
@@ -407,7 +408,8 @@ since April 2007 (and removed in December 2016). GVFS integration
started in February 2009. Remote commands on MS Windows hosts since
September 2011. Ad-hoc multi-hop methods (with a changed syntax)
re-enabled in November 2011. In November 2012, added Juergen
-Hoetzel's @file{tramp-adb.el}.
+Hoetzel's @file{tramp-adb.el}. Archive file names are supported since
+December 2017.
XEmacs support was stopped in January 2016. Since March 2017,
@value{tramp} syntax mandates a method.
@@ -529,24 +531,33 @@ of the local file name is the share exported by the remote host,
@cindex dav method
@cindex davs method
-On systems, which have installed the virtual file system for the Gnome
-Desktop (GVFS), its offered methods could be used by @value{tramp}.
-Examples are @file{@trampfn{sftp,user@@host,/path/to/file}},
+On systems, which have installed the virtual file system for the
+@acronym{GNOME} Desktop (GVFS), its offered methods could be used by
+@value{tramp}. Examples are
+@file{@trampfn{sftp,user@@host,/path/to/file}},
@file{@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP
file system), @file{@trampfn{dav,user@@host,/path/to/file}} and
@file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares).
-@anchor{Quick Start Guide: Google Drive}
-@section Using Google Drive
+@anchor{Quick Start Guide: GNOME Online Accounts based methods}
+@section Using @acronym{GNOME} Online Accounts based methods
+@cindex @acronym{GNOME} Online Accounts
@cindex method gdrive
@cindex gdrive method
@cindex google drive
+@cindex method owncloud
+@cindex owncloud method
+@cindex nextcloud
-Another GVFS-based method allows to access a Google Drive file system.
-The file name syntax is here always
-@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}.
-@samp{john.doe@@gmail.com} stands here for your Google Drive account.
+GVFS-based methods include also @acronym{GNOME} Online Accounts, which
+support the @option{Files} service. These are the Google Drive file
+system, and the OwnCloud/NextCloud file system. The file name syntax
+is here always
+@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}
+(@samp{john.doe@@gmail.com} stands here for your Google Drive
+account), or @file{@trampfn{owncloud,user@@host#8081,/path/to/file}}
+(@samp{8081} stands for the port number) for OwnCloud/NextCloud files.
@anchor{Quick Start Guide: Android}
@@ -1059,7 +1070,7 @@ numbers are not applicable to Android devices connected through USB@.
@cindex gvfs based methods
@cindex dbus
-GVFS is the virtual file system for the Gnome Desktop,
+GVFS is the virtual file system for the @acronym{GNOME} Desktop,
@uref{https://en.wikipedia.org/wiki/GVFS}. Remote files on GVFS are
mounted locally through FUSE and @value{tramp} uses this locally
mounted directory internally.
@@ -1112,6 +1123,18 @@ directory have the same @code{display-name}, such a situation must be avoided.
OBEX is an FTP-like access protocol for cell phones and similar simple
devices. @value{tramp} supports OBEX over Bluetooth.
+@item @option{owncloud}
+@cindex @acronym{GNOME} Online Accounts
+@cindex method owncloud
+@cindex owncloud method
+@cindex nextcloud
+
+As the name indicates, the method @option{owncloud} allows you to
+access OwnCloud or NextCloud hosted files and directories. Like the
+@option{gdrive} method, your credentials must be populated in your
+@command{Online Accounts} application outside Emacs. The method
+supports port numbers.
+
@item @option{sftp}
@cindex method sftp
@cindex sftp method
@@ -1133,8 +1156,11 @@ requires the SYNCE-GVFS plugin.
@defopt tramp-gvfs-methods
This user option is a list of external methods for GVFS@. By default,
this list includes @option{afp}, @option{dav}, @option{davs},
-@option{gdrive}, @option{obex}, @option{sftp} and @option{synce}.
-Other methods to include are: @option{ftp} and @option{smb}.
+@option{gdrive}, @option{obex}, @option{owncloud}, @option{sftp} and
+@option{synce}. Other methods to include are @option{ftp},
+@option{http}, @option{https} and @option{smb}. These methods are not
+intended to be used directly as GVFS based method. Instead, they are
+added here for the benefit of @ref{Archive file names}.
@end defopt
@@ -2284,6 +2310,7 @@ is a feature of Emacs that may cause missed prompts when using
* Ad-hoc multi-hops:: Declaring multiple hops in the file name.
* Remote processes:: Integration with other Emacs packages.
* Cleanup remote connections:: Cleanup remote connections.
+* Archive file names:: Access to files in file archives.
@end menu
@@ -2913,6 +2940,213 @@ that remote connection.
@end deffn
+@node Archive file names
+@section Archive file names
+@cindex file archives
+@cindex archive file names
+@cindex method archive
+@cindex archive method
+
+@value{tramp} offers also transparent access to files inside file
+archives. This is possible only on machines which have installed the
+virtual file system for the @acronym{GNOME} Desktop (GVFS), @ref{GVFS
+based methods}. Internally, file archives are mounted via the GVFS
+@option{archive} method.
+
+A file archive is a regular file of kind @file{/path/to/dir/file.EXT}.
+The extension @samp{.EXT} identifies the type of the file archive. A
+file inside a file archive, called archive file name, has the name
+@file{/path/to/dir/file.EXT/dir/file}.
+
+Most of the @ref{Magic File Names, , magic file name operations,
+elisp}, are implemented for archive file names, exceptions are all
+operations which write into a file archive, and process related
+operations. Therefore, functions like
+
+@lisp
+(copy-file "/path/to/dir/file.tar/dir/file" "/somewhere/else")
+@end lisp
+
+@noindent
+work out of the box. This is also true for file name completion, and
+for libraries like @code{dired} or @code{ediff}, which accept archive
+file names as well.
+
+@vindex tramp-archive-suffixes
+File archives are identified by the file name extension @samp{.EXT}.
+Since GVFS uses internally the library @code{libarchive(3)}, all
+suffixes, which are accepted by this library, work also for archive
+file names. Accepted suffixes are listed in the constant
+@code{tramp-archive-suffixes}. They are
+
+@itemize
+@item @samp{.7z} ---
+7-Zip archives
+@cindex 7z, file archive suffix
+@cindex file archive suffix 7z
+
+@item @samp{.apk} ---
+Android package kits
+@cindex apk, file archive suffix
+@cindex file archive suffix apk
+
+@item @samp{.ar} ---
+UNIX archiver formats
+@cindex ar, file archive suffix
+@cindex file archive suffix ar
+
+@item @samp{.cab}, @samp{.CAB} ---
+Microsoft Windows cabinets
+@cindex cab, file archive suffix
+@cindex CAB, file archive suffix
+@cindex file archive suffix cab
+@cindex file archive suffix CAB
+
+@item @samp{.cpio} ---
+CPIO archives
+@cindex cpio, file archive suffix
+@cindex file archive suffix cpio
+
+@item @samp{.deb} ---
+Debian packages
+@cindex deb, file archive suffix
+@cindex file archive suffix deb
+
+@item @samp{.depot} ---
+HP-UX SD depots
+@cindex depot, file archive suffix
+@cindex file archive suffix depot
+
+@item @samp{.exe} ---
+Self extracting Microsoft Windows EXE files
+@cindex exe, file archive suffix
+@cindex file archive suffix exe
+
+@item @samp{.iso} ---
+ISO 9660 images
+@cindex iso, file archive suffix
+@cindex file archive suffix iso
+
+@item @samp{.jar} ---
+Java archives
+@cindex jar, file archive suffix
+@cindex file archive suffix jar
+
+@item @samp{.lzh}, @samp{LZH} ---
+Microsoft Windows compressed LHA archives
+@cindex lzh, file archive suffix
+@cindex LZH, file archive suffix
+@cindex file archive suffix lzh
+@cindex file archive suffix LZH
+
+@item @samp{.mtree} ---
+BSD mtree format
+@cindex mtree, file archive suffix
+@cindex file archive suffix mtree
+
+@item @samp{.pax} ---
+Posix archives
+@cindex pax, file archive suffix
+@cindex file archive suffix pax
+
+@item @samp{.rar} ---
+RAR archives
+@cindex rar, file archive suffix
+@cindex file archive suffix rar
+
+@item @samp{.rpm} ---
+Red Hat packages
+@cindex rpm, file archive suffix
+@cindex file archive suffix rpm
+
+@item @samp{.shar} ---
+Shell archives
+@cindex shar, file archive suffix
+@cindex file archive suffix shar
+
+@item @samp{.tar}, @samp{tbz}, @samp{tgz}, @samp{tlz}, @samp{txz} ---
+(Compressed) tape archives
+@cindex tar, file archive suffix
+@cindex tbz, file archive suffix
+@cindex tgz, file archive suffix
+@cindex tlz, file archive suffix
+@cindex txz, file archive suffix
+@cindex file archive suffix tar
+@cindex file archive suffix tbz
+@cindex file archive suffix tgz
+@cindex file archive suffix tlz
+@cindex file archive suffix txz
+
+@item @samp{.warc} ---
+Web archives
+@cindex warc, file archive suffix
+@cindex file archive suffix warc
+
+@item @samp{.xar} ---
+macOS XAR archives
+@cindex xar, file archive suffix
+@cindex file archive suffix xar
+
+@item @samp{.xps} ---
+Open XML Paper Specification (OpenXPS) documents
+@cindex xps, file archive suffix
+@cindex file archive suffix xps
+
+@item @samp{.zip}, @samp{.ZIP} ---
+ZIP archives
+@cindex zip, file archive suffix
+@cindex ZIP, file archive suffix
+@cindex file archive suffix zip
+@cindex file archive suffix ZIP
+@end itemize
+
+@vindex tramp-archive-compression-suffixes
+File archives could also be compressed, identified by an additional
+compression suffix. Valid compression suffixes are listed in the
+constant @code{tramp-archive-compression-suffixes}. They are
+@samp{.bz2}, @samp{.gz}, @samp{.lrz}, @samp{.lz}, @samp{.lz4},
+@samp{.lzma}, @samp{.lzo}, @samp{.uu}, @samp{.xz} and @samp{.Z}. A
+valid archive file name would be
+@file{/path/to/dir/file.tar.gz/dir/file}. Even several suffixes in a
+row are possible, like @file{/path/to/dir/file.tar.gz.uu/dir/file}.
+
+@vindex tramp-archive-all-gvfs-methods
+An archive file name could be a remote file name, as in
+@file{/ftp:anonymous@@ftp.gnu.org:/gnu/tramp/tramp-2.3.2.tar.gz/INSTALL}.
+Since all file operations are mapped internally to GVFS operations,
+remote file names supported by @code{tramp-gvfs} perform better,
+because no local copy of the file archive must be downloaded first.
+For example, @samp{/sftp:user@@host:...} performs better than the
+similar @samp{/scp:user@@host:...}. See the constant
+@code{tramp-archive-all-gvfs-methods} for a complete list of
+@code{tramp-gvfs} supported method names.
+
+If @value{tramp} is loaded and @code{url-handler-mode} is enabled,
+archives could be visited via URLs, like
+@file{https://ftp.gnu.org/gnu/tramp/tramp-2.3.2.tar.gz/INSTALL}. This
+allows complex file operations like
+
+@lisp
+@group
+(progn
+ (require 'tramp)
+ (url-handler-mode 1)
+ (ediff-directories
+ "https://ftp.gnu.org/gnu/tramp/tramp-2.3.1.tar.gz/tramp-2.3.1"
+ "https://ftp.gnu.org/gnu/tramp/tramp-2.3.2.tar.gz/tramp-2.3.2" ""))
+@end group
+@end lisp
+
+It is even possible to access file archives in file archives, as
+
+@lisp
+@group
+(find-file
+ "http://ftp.debian.org/debian/pool/main/c/coreutils/coreutils_8.28-1_amd64.deb/control.tar.gz/control")
+@end group
+@end lisp
+
+
@node Bug Reports
@chapter Reporting Bugs and Problems
@cindex bug reports
@@ -2997,7 +3231,8 @@ Where is the latest @value{tramp}?
@item
Which systems does it work on?
-The package works successfully on Emacs 24, Emacs 25, and Emacs 26.
+The package works successfully on Emacs 24, Emacs 25, Emacs 26, and
+Emacs 27.
While Unix and Unix-like systems are the primary remote targets,
@value{tramp} has equal success connecting to other platforms, such as
diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi
index f81593fad37..eef2d9b6907 100644
--- a/doc/misc/trampver.texi
+++ b/doc/misc/trampver.texi
@@ -8,7 +8,7 @@
@c In the Tramp GIT, the version number is auto-frobbed from
@c configure.ac, so you should edit that file and run
@c "autoconf && ./configure" to change the version number.
-@set trampver 2.3.3.26.1
+@set trampver 2.4.0-pre
@c Other flags from configuration
@set instprefix /usr/local
View Lorry Controller Status