diff options
Diffstat (limited to 'doc/misc')
| -rw-r--r-- | doc/misc/calc.texi | 2 | ||||
| -rw-r--r-- | doc/misc/cc-mode.texi | 57 | ||||
| -rw-r--r-- | doc/misc/cl.texi | 78 | ||||
| -rw-r--r-- | doc/misc/ede.texi | 2 | ||||
| -rw-r--r-- | doc/misc/efaq-w32.texi | 2 | ||||
| -rw-r--r-- | doc/misc/efaq.texi | 327 | ||||
| -rw-r--r-- | doc/misc/eieio.texi | 9 | ||||
| -rw-r--r-- | doc/misc/erc.texi | 4 | ||||
| -rw-r--r-- | doc/misc/ert.texi | 217 | ||||
| -rw-r--r-- | doc/misc/eshell.texi | 12 | ||||
| -rw-r--r-- | doc/misc/eww.texi | 37 | ||||
| -rw-r--r-- | doc/misc/flymake.texi | 281 | ||||
| -rw-r--r-- | doc/misc/gnus-faq.texi | 4 | ||||
| -rw-r--r-- | doc/misc/gnus.texi | 101 | ||||
| -rw-r--r-- | doc/misc/mairix-el.texi | 14 | ||||
| -rw-r--r-- | doc/misc/message.texi | 19 | ||||
| -rw-r--r-- | doc/misc/mh-e.texi | 110 | ||||
| -rw-r--r-- | doc/misc/modus-themes.org | 305 | ||||
| -rw-r--r-- | doc/misc/org.org | 904 | ||||
| -rw-r--r-- | doc/misc/pgg.texi | 3 | ||||
| -rw-r--r-- | doc/misc/rcirc.texi | 70 | ||||
| -rw-r--r-- | doc/misc/reftex.texi | 30 | ||||
| -rw-r--r-- | doc/misc/smtpmail.texi | 12 | ||||
| -rw-r--r-- | doc/misc/speedbar.texi | 6 | ||||
| -rw-r--r-- | doc/misc/texinfo.tex | 267 | ||||
| -rw-r--r-- | doc/misc/tramp.texi | 109 | ||||
| -rw-r--r-- | doc/misc/trampver.texi | 2 |
27 files changed, 1942 insertions, 1042 deletions
diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index e11267e7a20..c77ccf766f2 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -2865,7 +2865,7 @@ that always equals one. Let's try to verify this identity. @smallexample @group 2: -64 2: -64 2: -64 2: 9.7192e54 2: 9.7192e54 -1: -64 1: -3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54 +1: -64 1: 3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54 . . . . . 64 n @key{RET} @key{RET} H C 2 ^ @key{TAB} H S 2 ^ diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 98ded68e713..a2ff572a3f4 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -283,6 +283,8 @@ Font Locking * Font Locking Preliminaries:: * Faces:: * Doc Comments:: +* Wrong Comment Style:: +* Found Types:: * Misc Font Locking:: * AWK Mode Font Locking:: @@ -1855,6 +1857,7 @@ sections apply to the other languages. * Faces:: * Doc Comments:: * Wrong Comment Style:: +* Found Types:: * Misc Font Locking:: * AWK Mode Font Locking:: @end menu @@ -2162,6 +2165,60 @@ which aren't of the default style will be fontified with @end defvar @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Found Types +@comment node-name, next, previous, up +@section ``Found Type'' handling. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +In most languages handled by CC Mode, @dfn{found types} are recognized +as types by their context in the source code. These contrast with +types which are basic to a language or are declared as types (e.g. by +@code{typedef} in C). + +In earlier versions of @ccmode{}, when @code{jit-lock-mode} was +enabled in Emacs (which it is by default), found types would +frequently fail to get fontified properly. This happened when the +fontification functions scanned a use of the found type before +scanning the code which caused it to be recognized. + +From @ccmode{} version 5.36, a timer mechanism scans the entire buffer +for found types in the seconds immediately after starting the major +mode. When a found type gets recognized, all its occurrences in the +buffer get marked for (re)fontification. This scanning happens in +short time slices interleaved with other processing, such as keyboard +handling, so that the responsiveness of Emacs should be barely +affected. This mechanism can be disabled (see below). It is only +active when @code{jit-lock-mode} is also active. + +@defvar c-type-finder-time-slot +@vindex type-finder-time-slot (c-) +The approximate time in seconds that CC Mode spends in scanning source +code before relinquishing control to other Emacs activities. The +default value is 0.05. To disable the scanning mechanism, set this +variable to @code{nil}. +@end defvar + +@defvar c-type-finder-repeat-time +@vindex type-finder-repeat-time (c-) +The approximate frequency (in seconds) with which the scanning +mechanism is triggered. This time must be greater than +@code{c-type-finder-time-slot}. Its default value is 0.1. If a less +powerful machine becomes sluggish due to the scanning, increase the +value of @code{c-type-finder-repeat-time} to compensate. +@end defvar + +@defvar c-type-finder-chunk-size +@vindex type-finder-chunk-size (c-) +The approximate size (in characters) of the buffer chunk processed as +a unit before the scanning mechanism checks whether +@code{c-type-finder-time-slot} seconds have passed. The default value +is 1000. A too small value here will cause inefficiencies due to the +initialization which happens for each chunk, whereas a too large value +will cause the processing to consume an excessive proportion of the +@code{c-type-finder-repeat-time}. +@end defvar + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Misc Font Locking @comment node-name, next, previous, up @section Miscellaneous Font Locking diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index c89e0e75f85..55b112cb24a 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -1245,6 +1245,12 @@ blocks for other macros like @code{cl-incf}, and @code{cl-pushnew}. The @code{cl-letf} and @code{cl-letf*} macros are used in the processing of symbol macros; @pxref{Macro Bindings}. +@defmac with-memoization @var{place} @var{code}@dots{} +This macro provides a simple way to do memoization. @var{code} is +evaluated and then stashed in @var{place}. If @var{place}'s value is +non-@code{nil}, return that value instead of evaluating @var{code}. +@end defmac + @node Variable Bindings @section Variable Bindings @@ -3364,9 +3370,13 @@ true for all elements. @end defun @defun cl-reduce function seq @t{&key :from-end :start :end :initial-value :key} -This function combines the elements of @var{seq} using an associative -binary operation. Suppose @var{function} is @code{*} and @var{seq} is -the list @code{(2 3 4 5)}. The first two elements of the list are +This function returns the result of calling @var{function} on the +first and second element of @var{seq}, then calling @var{function} +with that result and the third element of @var{seq}, then with that +result and the third element of @var{seq}, etc. + +Here is an example. Suppose @var{function} is @code{*} and @var{seq} +is the list @code{(2 3 4 5)}. The first two elements of the list are combined with @code{(* 2 3) = 6}; this is combined with the next element, @code{(* 6 4) = 24}, and that is combined with the final element: @code{(* 24 5) = 120}. Note that the @code{*} function happens @@ -3962,22 +3972,22 @@ In the simplest case, @var{name} and each of the @var{slots} are symbols. For example, @example -(cl-defstruct person name age sex) +(cl-defstruct person first-name age sex) @end example @noindent -defines a struct type called @code{person} that contains three -slots. Given a @code{person} object @var{p}, you can access those -slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})}, -and @code{(person-sex @var{p})}. You can also change these slots by -using @code{setf} on any of these place forms, for example: +defines a struct type called @code{person} that contains three slots. +Given a @code{person} object @var{p}, you can access those slots by +calling @code{(person-first-name @var{p})}, @code{(person-age +@var{p})}, and @code{(person-sex @var{p})}. You can also change these +slots by using @code{setf} on any of these place forms, for example: @example (cl-incf (person-age birthday-boy)) @end example You can create a new @code{person} by calling @code{make-person}, -which takes keyword arguments @code{:name}, @code{:age}, and +which takes keyword arguments @code{:first-name}, @code{:age}, and @code{:sex} to specify the initial values of these slots in the new object. (Omitting any of these arguments leaves the corresponding slot ``undefined'', according to the Common Lisp standard; in Emacs @@ -3989,7 +3999,7 @@ object of the same type whose slots are @code{eq} to those of @var{p}. Given any Lisp object @var{x}, @code{(person-p @var{x})} returns true if @var{x} is a @code{person}, and false otherwise. -Accessors like @code{person-name} normally check their arguments +Accessors like @code{person-first-name} normally check their arguments (effectively using @code{person-p}) and signal an error if the argument is the wrong type. This check is affected by @code{(optimize (safety @dots{}))} declarations. Safety level 1, @@ -4002,13 +4012,13 @@ always print a descriptive error message for incorrect inputs. @xref{Declarations}. @example -(setq dave (make-person :name "Dave" :sex 'male)) +(setq dave (make-person :first-name "Dave" :sex 'male)) @result{} [cl-struct-person "Dave" nil male] (setq other (copy-person dave)) @result{} [cl-struct-person "Dave" nil male] (eq dave other) @result{} nil -(eq (person-name dave) (person-name other)) +(eq (person-first-name dave) (person-first-name other)) @result{} t (person-p dave) @result{} t @@ -4021,7 +4031,7 @@ always print a descriptive error message for incorrect inputs. @end example In general, @var{name} is either a name symbol or a list of a name -symbol followed by any number of @dfn{struct options}; each @var{slot} +symbol followed by any number of @dfn{structure options}; each @var{slot} is either a slot symbol or a list of the form @samp{(@var{slot-name} @var{default-value} @var{slot-options}@dots{})}. The @var{default-value} is a Lisp form that is evaluated any time an instance of the @@ -4029,7 +4039,7 @@ structure type is created without specifying that slot's value. @example (cl-defstruct person - (name nil :read-only t) + (first-name nil :read-only t) age (sex 'unknown)) @end example @@ -4062,7 +4072,7 @@ enclosed in lists.) (cl-defstruct (person (:constructor create-person) (:type list) :named) - name age sex) + first-name age sex) @end example The following structure options are recognized. @@ -4108,12 +4118,12 @@ option. (person (:constructor nil) ; no default constructor (:constructor new-person - (name sex &optional (age 0))) - (:constructor new-hound (&key (name "Rover") + (first-name sex &optional (age 0))) + (:constructor new-hound (&key (first-name "Rover") (dog-years 0) &aux (age (* 7 dog-years)) (sex 'canine)))) - name age sex) + first-name age sex) @end example The first constructor here takes its arguments positionally rather @@ -4165,16 +4175,16 @@ slot descriptors for slots in the included structure, possibly with modified default values. Borrowing an example from Steele: @example -(cl-defstruct person name (age 0) sex) +(cl-defstruct person first-name (age 0) sex) @result{} person (cl-defstruct (astronaut (:include person (age 45))) helmet-size (favorite-beverage 'tang)) @result{} astronaut -(setq joe (make-person :name "Joe")) +(setq joe (make-person :first-name "Joe")) @result{} [cl-struct-person "Joe" 0 nil] -(setq buzz (make-astronaut :name "Buzz")) +(setq buzz (make-astronaut :first-name "Buzz")) @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang] (list (person-p joe) (person-p buzz)) @@ -4182,17 +4192,17 @@ modified default values. Borrowing an example from Steele: (list (astronaut-p joe) (astronaut-p buzz)) @result{} (nil t) -(person-name buzz) +(person-first-name buzz) @result{} "Buzz" -(astronaut-name joe) - @result{} error: "astronaut-name accessing a non-astronaut" +(astronaut-first-name joe) + @result{} error: "astronaut-first-name accessing a non-astronaut" @end example Thus, if @code{astronaut} is a specialization of @code{person}, then every @code{astronaut} is also a @code{person} (but not the other way around). Every @code{astronaut} includes all the slots of a @code{person}, plus extra slots that are specific to -astronauts. Operations that work on people (like @code{person-name}) +astronauts. Operations that work on people (like @code{person-first-name}) work on astronauts just like other people. @item :noinline @@ -4230,10 +4240,10 @@ records, which are always tagged. Therefore, @code{:named} is only useful in conjunction with @code{:type}. @example -(cl-defstruct (person1) name age sex) -(cl-defstruct (person2 (:type list) :named) name age sex) -(cl-defstruct (person3 (:type list)) name age sex) -(cl-defstruct (person4 (:type vector)) name age sex) +(cl-defstruct (person1) first-name age sex) +(cl-defstruct (person2 (:type list) :named) first-name age sex) +(cl-defstruct (person3 (:type list)) first-name age sex) +(cl-defstruct (person4 (:type vector)) first-name age sex) (setq p1 (make-person1)) @result{} #s(person1 nil nil nil) @@ -4254,10 +4264,10 @@ useful in conjunction with @code{:type}. Since unnamed structures don't have tags, @code{cl-defstruct} is not able to make a useful predicate for recognizing them. Also, -accessors like @code{person3-name} will be generated but they -will not be able to do any type checking. The @code{person3-name} +accessors like @code{person3-first-name} will be generated but they +will not be able to do any type checking. The @code{person3-first-name} function, for example, will simply be a synonym for @code{car} in -this case. By contrast, @code{person2-name} is able to verify +this case. By contrast, @code{person2-first-name} is able to verify that its argument is indeed a @code{person2} object before proceeding. @@ -5024,7 +5034,7 @@ The above @code{incf} example could be written using @ignore (defmacro concatf (place &rest args) (gv-letplace (getter setter) place - (macroexp-let2 nil v (mapconcat 'identity args "") + (macroexp-let2 nil v (mapconcat 'identity args) (funcall setter `(concat ,getter ,v))))) @end ignore @end defmac diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index a0f316f8480..5e9c3d7eef6 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -1556,7 +1556,7 @@ You can also use TRAMP for use with rcp & scp. @item :web-site-file @* -A file which contains the home page for this project. +A file which contains the website for this project. This file can be relative to slot @code{web-site-directory}. This can be a local file, use ange-ftp, EFS, or TRAMP. diff --git a/doc/misc/efaq-w32.texi b/doc/misc/efaq-w32.texi index 6eff88b76e3..ba1077d0acd 100644 --- a/doc/misc/efaq-w32.texi +++ b/doc/misc/efaq-w32.texi @@ -2278,7 +2278,7 @@ In Emacs, you can browse the manual using Info by typing @kbd{C-h r}, and you can view the FAQ by typing @kbd{C-h C-f}. Other resources include: @itemize -@item @uref{https://www.gnu.org/software/emacs/, The Emacs homepage} +@item @uref{https://www.gnu.org/software/emacs/, The Emacs website} @item @uref{https://www.gnu.org/software/emacs/manual/, Other Emacs manuals} @item @uref{https://www.emacswiki.org/, Emacs Wiki} @end itemize diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index d66c12f9fc3..18342e65b0a 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -7,10 +7,6 @@ @include emacsver.texi -@c This file is maintained by Romain Francoise <rfrancoise@gnu.org>. -@c Feel free to install changes without prior permission (but I'd -@c appreciate a notice if you do). - @copying Copyright @copyright{} 2001--2021 Free Software Foundation, Inc.@* Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2000 @@ -86,7 +82,7 @@ Emacs, the Emacs manual is often the best starting point. * FAQ notation:: * General questions:: * Getting help:: -* Status of Emacs:: +* History of Emacs:: * Common requests:: * Bugs and problems:: * Compiling and installing Emacs:: @@ -215,11 +211,6 @@ completion, @kbd{?} for a list of possibilities, and @kbd{M-p} and @kbd{M-n} (or up-arrow and down-arrow) to see previous commands entered. An Emacs @dfn{command} is an @dfn{interactive} Emacs function. -@cindex @key{Do} key -Your system administrator may have bound other key sequences to invoke -@code{execute-extended-command}. A function key labeled @kbd{Do} is a -good candidate for this, on keyboards that have such a key. - If you need to run non-interactive Emacs functions, see @ref{Evaluating Emacs Lisp code}. @@ -231,7 +222,7 @@ Emacs Lisp code}. @cindex Info, finding topics in When we refer you to some @var{topic} in the Emacs manual, you can -read this manual node inside Emacs (assuming nothing is broken) by +read this manual node inside Emacs by typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}. This invokes Info, the GNU hypertext documentation browser. If you don't @@ -240,9 +231,8 @@ already know how to use Info, type @kbd{?} from within Info. If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}. -If these commands don't work as expected, your system administrator may -not have installed the Info files, or may have installed them -improperly. In this case you should complain. +(If these commands don't work as expected, your system may be missing +the Info files, or they may not be installed properly.) If you are reading this FAQ in Info, you can simply press @key{RET} on a reference to follow it. @@ -304,6 +294,9 @@ Richard Matthew Stallman @item GPL GNU General Public License +See @uref{https://gnu.org/licenses/, the GNU web site} for more +information about the GPL. + @end table The word ``free'' in the title of the Free Software Foundation refers to @@ -322,7 +315,6 @@ This chapter contains general questions having to do with Emacs, the Free Software Foundation, and related organizations. @menu -* Real meaning of copyleft:: * Guidelines for mailing list postings:: * Mailing list archives:: * Reporting bugs:: @@ -330,67 +322,31 @@ Free Software Foundation, and related organizations. * Contacting the FSF:: @end menu -@node Real meaning of copyleft -@section What is the real legal meaning of the GNU copyleft? -@cindex Copyleft, real meaning of -@cindex GPL, real meaning of -@cindex General Public License, real meaning of -@cindex Discussion of the GPL - -The real legal meaning of the GNU General Public License (copyleft) will -only be known if and when a judge rules on its validity and scope. -There has never been a copyright infringement case involving the GPL to -set any precedents. Although legal actions have been brought against -companies for violating the terms of the GPL, so far all have been -settled out of court (in favor of the plaintiffs). Please take any -discussion regarding this issue to -@uref{https://lists.gnu.org/mailman/listinfo/gnu-misc-discuss, the -gnu-misc-discuss mailing list}, which was created to hold the -extensive flame wars on the subject. - -RMS writes: - -@quotation -The legal meaning of the GNU copyleft is less important than the spirit, -which is that Emacs is a free software project and that work pertaining -to Emacs should also be free software. ``Free'' means that all users -have the freedom to study, share, change and improve Emacs. To make -sure everyone has this freedom, pass along source code when you -distribute any version of Emacs or a related program, and give the -recipients the same freedom that you enjoyed. -@end quotation - @node Guidelines for mailing list postings @section What are appropriate messages for the various Emacs mailing lists? -@cindex Newsgroups, appropriate messages for -@cindex GNU newsgroups, appropriate messages for -@cindex GNU mailing lists, appropriate messages for -@cindex Usenet groups, appropriate messages for @cindex Mailing lists, appropriate messages for @cindex Posting messages to mailing lists - @cindex GNU mailing lists -The Emacs mailing lists are described at + +There are various Emacs mailing lists, described at @uref{https://savannah.gnu.org/mail/?group=emacs, the Emacs Savannah page}. -Messages advocating ``non-free'' software are considered unacceptable -on any of the GNU mailing lists, except for -@url{https://lists.gnu.org/mailman/listinfo/gnu-misc-discuss, the -gnu-misc-discuss mailing list} which was created to hold the extensive -flame-wars on the subject. - -``Non-free'' software includes any software for which the end user -can't freely modify the source code and exchange enhancements. Be -careful to remove any GNU mailing lists from @samp{Cc:} when posting a -reply that recommends such software. - -@url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, The -bug-gnu-emacs list} is a place where bug reports appear, but we -recommend using the commands @kbd{M-x report-emacs-bug} or @kbd{M-x -submit-emacs-patch} if at all possible (@pxref{Reporting bugs}). - -Some GNU mailing lists are gatewayed to (Usenet) newsgroups. +The main ones are: @code{help-gnu-emacs}, @code{bug-gnu-emacs}, +and @code{emacs-devel}. + +Messages advocating ``non-free'' software are considered unacceptable on +any of the GNU mailing lists, except for +@url{https://lists.gnu.org/mailman/listinfo/gnu-misc-discuss, +the gnu-misc-discuss mailing list}. +``Non-free'' software includes any software for which the end user can't +freely modify the source code and exchange enhancements. Please +remove GNU mailing lists from the recipients when +posting a reply that recommends such software. + +@cindex newsgroups +Some of the GNU mailing lists are gatewayed to newsgroups (although +the connection is occasionally unreliable). For example, sending an email to @url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, The bug-gnu-emacs list} has the effect of posting on the newsgroup @@ -412,6 +368,8 @@ years, although there may be some unintentional gaps in coverage. The archive can be browsed over the web at @uref{https://lists.gnu.org/r/, the GNU mail archive}. +@cindex Usenet archives for GNU groups +@cindex Old Usenet postings for GNU groups Some web-based Usenet search services also archive the @code{gnu.*} newsgroups. @@ -422,15 +380,8 @@ newsgroups. @cindex How to submit a bug report @cindex Reporting bugs -The correct way to report Emacs bugs is to use the command -@kbd{M-x report-emacs-bug}. It sets up a mail buffer with the -essential information and the correct e-mail address, -@email{bug-gnu-emacs@@gnu.org}. - -Be sure to read the ``Bugs'' section of the Emacs manual before reporting -a bug! The manual describes in detail how to submit a useful bug -report (@pxref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}). -(@xref{Emacs manual}, if you don't know how to read the manual.) +Please see the Emacs manual for information on how to report bugs. +@xref{Checklist, , Checklist for Bug Reports, emacs, The GNU Emacs Manual}. Sending bug reports to @url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs, the @@ -444,7 +395,7 @@ more messages about Emacs than the others. If you have reported a bug and you don't hear about a possible fix, then after a suitable delay (such as a week) it is okay to post on -@code{help-gnu-emacs@@gnu.org} asking if anyone can help you. +the help list asking if anyone can help you. If you are unsure whether you have found a bug, consider the following non-exhaustive list, courtesy of RMS: @@ -863,12 +814,9 @@ Emacs news, a history of recent user-visible changes @end table -More GNU information, including back issues of the @cite{GNU's -Bulletin}, are at - -@uref{https://www.gnu.org/bulletins/bulletins.html} and +More GNU and FSF information is available at -@uref{https://www.cs.pdx.edu/~trent/gnu/gnu.html} +@uref{https://www.gnu.org} and @uref{https://www.fsf.org} @node Help installing Emacs @section Where can I get help in installing Emacs? @@ -894,12 +842,9 @@ C-f} (@kbd{M-x view-emacs-FAQ}). The very latest version is available in the Emacs development repository (@pxref{Latest version of Emacs}). @c ------------------------------------------------------------ -@node Status of Emacs -@chapter Status of Emacs -@cindex Status of Emacs - -This chapter gives you basic information about Emacs, including the -status of its latest version. +@node History of Emacs +@chapter History of Emacs +@cindex History of Emacs @menu * Origin of the term Emacs:: @@ -912,6 +857,7 @@ status of its latest version. * New in Emacs 22:: * New in Emacs 21:: * New in Emacs 20:: +* What was XEmacs?:: @end menu @node Origin of the term Emacs @@ -950,7 +896,6 @@ conventions}). @cindex Latest version of Emacs @cindex Development, Emacs @cindex Repository, Emacs -@cindex Bazaar repository, Emacs Emacs @value{EMACSVER} is the current version as of this writing. A version number with two components (e.g., @samp{24.5}) indicates a released @@ -1475,6 +1420,29 @@ several languages in the same document; the ``Customize'' facility for modifying variables without having to use Lisp; and automatic conversion of files from Macintosh, Microsoft, and Unix platforms. +@node What was XEmacs? +@section What was XEmacs? +@cindex XEmacs + +XEmacs was a branch version of Emacs that is no longer actively +developed. Originally known as ``Lucid Emacs'', XEmacs was forked +from a prerelease version of Emacs 19. XEmacs last released a new +version on January 30, 2009, which lacks many important features that +exist in Emacs. Since its development has stopped, we do not expect +to see any new releases. + +In the past, it was not uncommon for Emacs packages to include code +for compatibility with XEmacs. Nowadays, most built-in and third party +packages have either stopped supporting XEmacs or were developed +exclusively for Emacs. + +If you want to talk about these two versions and distinguish them, +please call them ``Emacs'' and ``XEmacs.'' To contrast ``XEmacs'' +with ``GNU Emacs'' would be misleading, since XEmacs too has its +origin in the work of the GNU Project. Terms such as ``Emacsen'' and +``(X)Emacs'' are not wrong, but they are not very clear, so it +is better to write ``Emacs and XEmacs.'' + @c ------------------------------------------------------------ @node Common requests @chapter Common requests @@ -1598,7 +1566,7 @@ capabilities. The command @kbd{M-x list-colors-display} pops up a window which exhibits all the colors Emacs knows about on the current display. -Syntax highlighting is on by default since version 22.1. +Syntax highlighting is also on by default on text-only terminals. @cindex direct color in terminals Emacs 26.1 and later support direct color mode in terminals. If Emacs @@ -3380,6 +3348,7 @@ dired, @code{directory-listing-before-filename-regexp}. @menu * Installing Emacs:: +* Emacs for other operating systems:: * Problems building Emacs:: @end menu @@ -3392,9 +3361,7 @@ dired, @code{directory-listing-before-filename-regexp}. @cindex Source code, building Emacs from This answer is meant for users of Unix and Unix-like systems. Users of -other operating systems should see the series of questions beginning -with @ref{Emacs for MS-DOS}, which describe where to get non-Unix source -and binaries, and how to install Emacs on those systems. +other operating systems should see @xref{Emacs for other operating systems}. Most GNU/Linux distributions provide pre-built Emacs packages. If Emacs is not installed already, you can install it by running (as @@ -3413,20 +3380,20 @@ a list of sites that make them available. On @url{https://ftp.gnu.org}, the main GNU distribution site, sources are available as @c Don't include VER in the file name, because pretests are not there. -@uref{https://ftp.gnu.org/pub/gnu/emacs/emacs-VERSION.tar.gz} +@uref{https://ftp.gnu.org/pub/gnu/emacs/emacs-VERSION.tar.xz} (Replace @samp{VERSION} with the relevant version number, e.g., @samp{28.1}.) @item Next uncompress and extract the source files. This requires -the @code{gzip} and @code{tar} programs, which are standard utilities. +the @code{xz} and @code{tar} programs, which are standard utilities. If your system does not have them, these can also be downloaded from @url{https://ftp.gnu.org}. GNU @code{tar} can uncompress and extract in a single-step: @example -tar -zxvf emacs-VERSION.tar.gz +tar -axvf emacs-VERSION.tar.xz @end example @item @@ -3440,9 +3407,8 @@ cd emacs-VERSION make # use Makefile to build components, then Emacs @end example -If the @code{make} completes successfully, the odds are fairly good that -the build has gone well. (@xref{Problems building Emacs}, if you weren't -successful.) +If the @code{make} completes successfully, you can go on to install it. +(@xref{Problems building Emacs}, if you weren't successful.) @item By default, Emacs is installed in @file{/usr/local}. To actually @@ -3457,6 +3423,46 @@ and any Emacs Info files that might be in @file{/usr/local/share/info/}. @end itemize +@node Emacs for other operating systems +@section Where can I get Emacs for macOS, MS Windows, etc? + +@cindex Apple computers, Emacs for +@cindex Macintosh, Emacs for +@cindex macOS, Emacs for +Beginning with version 22.1, Emacs supports macOS natively. +See the file @file{nextstep/INSTALL} in the distribution. + +@cindex FAQ for Emacs on MS-Windows +@cindex Emacs for MS-Windows +@cindex Microsoft Windows, Emacs for +There is a separate FAQ for Emacs on MS-Windows, +@pxref{Top,,,efaq-w32,FAQ for Emacs on MS Windows}. + +@cindex GNUstep, Emacs for +Beginning with version 23.1, Emacs supports GNUstep natively. +See the file @file{nextstep/INSTALL} in the distribution. + +@cindex MS-DOS, Emacs for +@cindex DOS, Emacs for +@cindex Compiling Emacs for DOS +@cindex Emacs for MS-DOS +To build Emacs from source for MS-DOS, see the instructions in the file +@file{msdos/INSTALL} in the distribution. The DOS port builds and runs +on plain DOS, and also on all versions of MS-Windows from version 3.X +onwards, including Windows XP and Vista. Pre-built binaries may be +available at +@uref{http://www.delorie.com/pub/djgpp/current/v2gnu/emacs.README} + +For a list of other implementations of Emacs (and Emacs +look-alikes), consult the list of ``Emacs implementations and literature,'' +available at + +@uref{http://www.finseth.com/emacs.html} + +Note that while many of these programs look similar to Emacs, they often +lack certain features, such as the Emacs Lisp extension language. + + @node Problems building Emacs @section What should I do if I have trouble building Emacs? @cindex Problems building Emacs @@ -3480,26 +3486,20 @@ problem (@pxref{Reporting bugs}). @cindex Finding Emacs and related packages @menu -* Finding Emacs on the Internet:: +* Downloading Emacs:: * Finding a package with particular functionality:: * Packages that do not come with Emacs:: * Spell-checkers:: * Current GNU distributions:: -* What was XEmacs?:: * Emacs for minimalists:: -* Emacs for MS-DOS:: -* Emacs for MS-Windows:: -* Emacs for GNUstep:: -* Emacs for macOS:: @end menu -@node Finding Emacs on the Internet -@section Where can I get Emacs on the net? -@cindex Finding Emacs on the Internet +@node Downloading Emacs +@section Downloading Emacs @cindex Downloading Emacs Information on downloading Emacs is available at -@uref{https://www.gnu.org/software/emacs/, the Emacs home-page}. +@uref{https://www.gnu.org/software/emacs/, the Emacs website}. @xref{Installing Emacs}, for information on how to obtain and build the latest version of Emacs, and see @ref{Current GNU distributions}, for a list of @@ -3511,25 +3511,22 @@ archive sites that make GNU software available. @cindex Finding an Emacs Lisp package @cindex Functionality, finding a particular package -First of all, you should check to make sure that the package isn't -already available. For example, typing @kbd{M-x apropos @key{RET} -python @key{RET}} lists all functions and variables containing the -string @samp{python}. - -It is also possible that the package is on your system, but has not been -loaded. To see which packages are available for loading, look through -your computer's lisp directory (@pxref{File-name conventions}). The Lisp -source to most packages contains a short description of how they -should be loaded, invoked, and configured---so before you use or -modify a Lisp package, see if the author has provided any hints in the -source code. - The command @kbd{C-h p} (@code{finder-by-keyword}) allows you to browse -the constituent Emacs packages. +the packages that come with Emacs. For advice on how to find extra packages that are not part of Emacs, see @ref{Packages that do not come with Emacs}. +Other techniques that might be useful: + +Typing @kbd{M-x apropos @key{RET} python @key{RET}} lists all +functions and variables containing the string @samp{python}. + +You can look through your computer's lisp directory (@pxref{File-name +conventions}). The Lisp source to most packages contains a short +description of what they do and how they should be used. + + @c Note that M-x view-external-packages references this node. @node Packages that do not come with Emacs @section Where can I get Emacs Lisp packages that don't come with Emacs? @@ -3619,28 +3616,6 @@ A list of sites mirroring @samp{ftp.gnu.org} can be found at @uref{https://www.gnu.org/prep/ftp} -@node What was XEmacs? -@section What was XEmacs? -@cindex XEmacs - -XEmacs was a branch version of Emacs that is no longer actively -developed. XEmacs last released a new version on January 30, 2009, -and it lacks many important features that exist in Emacs. Since its -development has stopped, we do not expect to see any new releases. - -In the past, it was not uncommon for Emacs packages to include code -for compatibility with XEmacs. Nowadays, most built-in and third party -packages have either stopped supporting XEmacs or were developed -exclusively for Emacs. - -XEmacs was initially derived from a prerelease version of Emacs 19. -If you want to talk about these two versions and distinguish them, -please call them ``Emacs'' and ``XEmacs.'' To contrast ``XEmacs'' -with ``GNU Emacs'' would be misleading, since XEmacs too has its -origin in the work of the GNU Project. Terms such as ``Emacsen'' and -``(X)Emacs'' are not wrong, but they are not very clear, so it -is better to write ``Emacs and XEmacs.'' - @node Emacs for minimalists @section I don't have enough disk space to install Emacs @cindex Zile @@ -3654,63 +3629,6 @@ information is available from @uref{https://www.gnu.org/software/zile/} - -@node Emacs for MS-DOS -@section Where can I get Emacs for MS-DOS? -@cindex MS-DOS, Emacs for -@cindex DOS, Emacs for -@cindex Compiling Emacs for DOS -@cindex Emacs for MS-DOS - -To build Emacs from source for MS-DOS, see the instructions in the file -@file{msdos/INSTALL} in the distribution. The DOS port builds and runs -on plain DOS, and also on all versions of MS-Windows from version 3.X -onwards, including Windows XP and Vista. - -The file @file{etc/PROBLEMS} contains some additional information -regarding Emacs under MS-DOS. - -A pre-built binary distribution of the old Emacs 24 is available, as -described at - -@uref{http://www.delorie.com/pub/djgpp/current/v2gnu/emacs.README} - -For a list of other MS-DOS implementations of Emacs (and Emacs -look-alikes), consult the list of ``Emacs implementations and literature,'' -available at - -@uref{https://www.finseth.com/emacs.html} - -Note that while many of these programs look similar to Emacs, they often -lack certain features, such as the Emacs Lisp extension language. - -@node Emacs for MS-Windows -@section Where can I get Emacs for Microsoft Windows? -@cindex FAQ for Emacs on MS-Windows -@cindex Emacs for MS-Windows -@cindex Microsoft Windows, Emacs for - -There is a separate FAQ for Emacs on MS-Windows, -@pxref{Top,,,efaq-w32,FAQ for Emacs on MS Windows}. -For MS-DOS, @pxref{Emacs for MS-DOS}. - - -@node Emacs for GNUstep -@section Where can I get Emacs for GNUstep? -@cindex GNUstep, Emacs for - -Emacs supports GNUstep natively. See the file @file{nextstep/INSTALL} -in the distribution. - -@node Emacs for macOS -@section Where can I get Emacs for macOS? -@cindex Apple computers, Emacs for -@cindex Macintosh, Emacs for -@cindex macOS, Emacs for - -Emacs supports macOS natively. See the file @file{nextstep/INSTALL} -in the distribution. - @c ------------------------------------------------------------ @node Key bindings @chapter Key bindings @@ -4218,9 +4136,6 @@ You can get the old behavior by binding @kbd{SPC} to @lisp (define-key minibuffer-local-filename-completion-map (kbd "SPC") 'minibuffer-complete-word) - -(define-key minibuffer-local-filename-must-match-map (kbd "SPC") - 'minibuffer-complete-word) @end lisp @c ------------------------------------------------------------ diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index 63b42827311..2b0b1f7fd67 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -700,18 +700,19 @@ slot values, and use the previously mentioned set/ref routines. @defun slot-value object slot @anchor{slot-value} This function retrieves the value of @var{slot} from @var{object}. +It can also be used on objects defined by @code{cl-defstruct}. This is a generalized variable that can be used with @code{setf} to -modify the value stored in @var{slot}. @xref{Generalized -Variables,,,elisp,GNU Emacs Lisp Reference Manual}. +modify the value stored in @var{slot}, tho not for objects defined by +@code{cl-defstruct}. +@xref{Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}. @end defun @defun set-slot-value object slot value @anchor{set-slot-value} This function sets the value of @var{slot} from @var{object}. -This is not a CLOS function, but is the obsolete setter for -@code{slot-value} used by the @code{setf} macro. It is therefore +This is not a CLOS function. It is therefore recommended to use @w{@code{(setf (slot-value @var{object} @var{slot}) @var{value})}} instead. @end defun diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index 10ced678e1d..3b8e231d3a1 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -2,13 +2,15 @@ @c %**start of header @setfilename ../../info/erc.info @settitle ERC Manual +@set ERCVER 5.4.1 +@set ERCDIST as distributed with Emacs @value{EMACSVER} @include docstyle.texi @syncodeindex fn cp @include emacsver.texi @c %**end of header @copying -This manual is for ERC as distributed with Emacs @value{EMACSVER}. +This manual is for ERC @value{ERCVER} @value{ERCDIST}. Copyright @copyright{} 2005--2021 Free Software Foundation, Inc. diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index fafdb8c4eb4..440c61add8e 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -260,36 +260,103 @@ unexpected result. In the example above, there are two failures, both due to failed @code{should} forms. @xref{Understanding Explanations}, for more details. +The following key bindings are available in the ERT results buffer: + +@table @kbd + +@item @key{RET} +@kindex RET@r{, in ert results buffer} +Each name of a function or macro in this buffer is a button; moving +point to it and typing @kbd{@key{RET}} jumps to its definition. + +@item @key{TAB} +@itemx S-@key{TAB} @kindex TAB@r{, in ert results buffer} @kindex S-TAB@r{, in ert results buffer} -In the ERT results buffer, @kbd{@key{TAB}} and @kbd{S-@key{TAB}} cycle between -buttons. Each name of a function or macro in this buffer is a button; -moving point to it and typing @kbd{@key{RET}} jumps to its definition. +Cycle between buttons forward (@code{forward-button}) and backward +(@code{backward-button}). +@item r @kindex r@r{, in ert results buffer} +@findex ert-results-rerun-test-at-point +Re-run the test near point on its own +(@code{ert-results-rerun-test-at-point}). + +@item d @kindex d@r{, in ert results buffer} +@findex ert-results-rerun-test-at-point-debugging-errors +Re-run the test near point on its own with the debugger enabled +(@code{ert-results-rerun-test-at-point-debugging-errors}). + +@item R +@kindex R@r{, in ert results buffer} +@findex ert-results-rerun-all-tests +Re-run all tests (@code{ert-results-rerun-all-tests}). + +@item . @kindex .@r{, in ert results buffer} +@findex ert-results-find-test-at-point-other-window +Jump to the definition of the test near point +(@code{ert-results-find-test-at-point-other-window}). This has the +same effect as @kbd{@key{RET}}, but does not require point to be on +the name of the test. + +@item b @kindex b@r{, in ert results buffer} +@findex ert-results-pop-to-backtrace-for-test-at-point @cindex backtrace of a failed test -Pressing @kbd{r} re-runs the test near point on its own. Pressing -@kbd{d} re-runs it with the debugger enabled. @kbd{.} jumps to the -definition of the test near point (@kbd{@key{RET}} has the same effect -if point is on the name of the test). On a failed test, @kbd{b} shows -the backtrace of the failure. @xref{Debugging,, Backtraces, elisp, -GNU Emacs Lisp Reference Manual}, for more information about -backtraces. +Show the backtrace of a failed test +(@code{ert-results-pop-to-backtrace-for-test-at-point}). +@xref{Debugging,, Backtraces, elisp, GNU Emacs Lisp Reference Manual}, +for more information about backtraces. +@item l @kindex l@r{, in ert results buffer} -@kbd{l} shows the list of @code{should} forms executed in the test. -If any messages were generated (with the Lisp function @code{message}) -in a test or any of the code that it invoked, @kbd{m} will show them. - +@findex ert-results-pop-to-should-forms-for-test-at-point +Show the list of @code{should} forms executed in the test +(@code{ert-results-pop-to-should-forms-for-test-at-point}). + +@item m +@kindex m@r{, in ert results buffer} +@findex ert-results-pop-to-messages-for-test-at-point +Show any messages that were generated (with the Lisp function +@code{message}) in in a test or any of the code that it invoked +(@code{ert-results-pop-to-messages-for-test-at-point}). + +@item L @kindex L@r{, in ert results buffer} +@findex ert-results-toggle-printer-limits-for-test-at-point By default, long expressions in the failure details are abbreviated -using @code{print-length} and @code{print-level}. Pressing @kbd{L} -while point is on a test failure will increase the limits to show more -of the expression. +using @code{print-length} and @code{print-level}. Increase the limits +to show more of the expression by moving point to a test failure with +this command (@code{ert-results-toggle-printer-limits-for-test-at-point}). + +@item D +@kindex D@r{, in ert results buffer} +@findex ert-delete-test +@cindex delete test +Delete a test from the running Emacs session (@code{ert-delete-test}). +@item h +@kindex h@r{, in ert results buffer} +@findex ert-describe-test +Show the documentation of a test (@code{ert-describe-test}). + +@item T +@kindex T@r{, in ert results buffer} +@findex ert-results-pop-to-timings +Display test timings for the last run (@code{ert-results-pop-to-timings}). + +@item M-x ert-delete-all-tests +@findex ert-delete-all-tests +@cindex delete all tests +Delete all tests from the running session. + +@item M-x ert-describe-test +@findex ert-results-describe-test-at-point +Prompt for a test and then show its documentation. + +@end table @node Running Tests in Batch Mode @section Running Tests in Batch Mode @@ -348,7 +415,7 @@ emacs -batch -l ert -l my-tests.el \ @end example By default, ERT test failure summaries are quite brief in batch -mode--only the names of the failed tests are listed. If the +mode---only the names of the failed tests are listed. If the EMACS_TEST_VERBOSE environment variable is set, the failure summaries will also include the data from the failing test. @@ -419,6 +486,7 @@ to find where a test was defined if the test was loaded from a file. * Expected Failures:: Tests for known bugs. * Tests and Their Environment:: Don't depend on customizations; no side effects. * Useful Techniques:: Some examples. +* erts files:: Files containing many buffer tests. @end menu @node The @code{should} Macro @@ -700,6 +768,119 @@ code is to restructure the code slightly to provide better interfaces for testing. Usually, this makes the interfaces easier to use as well. +@node erts files +@section erts files + +@findex ert-test-erts-file +Many relevant Emacs tests depend on comparing the contents of a buffer +before and after executing a particular function. These tests can be +written the normal way---making a temporary buffer, inserting the +``before'' text, running the function, and then comparing with the +expected ``after'' text. However, this often leads to test code +that's pretty difficult to read and write, especially when the text in +question is multi-line. + +So ert provides a function called @code{ert-test-erts-file} that takes +two parameters: The name of a specially-formatted @dfn{erts} file, and +(optionally) a function that performs the transform. + +@findex erts-mode +These erts files can be edited with the @code{erts-mode} major mode. + +An erts file is divided into sections by the (@samp{=-=}) separator. + +Here's an example file containing two tests: + +@example +Name: flet + +=-= +(cl-flet ((bla (x) +(* x x))) +(bla 42)) +=-= +(cl-flet ((bla (x) + (* x x))) + (bla 42)) +=-=-= + +Name: defun + +=-= +(defun x () + (print (quote ( thingy great + stuff)))) +=-=-= +@end example + +A test starts with a line containing just @samp{=-=} and ends with a +line containing just @samp{=-=-=}. The test may be preceded by +freeform text (for instance, comments), and also name/value pairs (see +below for a list of them). + +If there is a line with @samp{=-=} inside the test, that designates +the start of the ``after'' text. Otherwise, the ``before'' and +``after'' texts are assumed to be identical, which you typically see +when writing indentation tests. + +@code{ert-test-erts-file} puts the ``before'' section into a temporary +buffer, calls the transform function, and then compares with the +``after'' section. + +Here's an example usage: + +@lisp +(ert-test-erts-file "elisp.erts" + (lambda () + (emacs-lisp-mode) + (indent-region (point-min) (point-max)))) +@end lisp + +A list of the name/value specifications that can appear before a test +follows. The general syntax is @samp{Name: Value}, but continuation +lines can be used (along the same lines as in mail---subsequent lines +that start with a space are part of the value). + +@example +Name: foo +Code: (indent-region + (point-min) (point-max)) +@end example + +@table @samp +@item Name +All tests should have a name. This name will appear in ERT output if +the test fails, and helps to identify the failing test. + +@item Code +This is the code that will be run to do the transform. This can also +be passed in via the @code{ert-test-erts-file} call, but @samp{Code} +overrides that. It's used not only in the following test, but in all +subsequent tests in the file (until overridden by another @samp{Code} +specification). + +@item No-Before-Newline +@itemx No-After-Newline +These specifications say whether the ``before'' or ``after'' portions +have a newline at the end. (This would otherwise be impossible to +specify.) + +@item Point-Char +Sometimes it's useful to be able to put point at a specific place +before executing the transform function. @samp{Point-Char: |} will +make @code{ert-test-erts-file} place point where @samp{|} is in the +``before'' form (and remove that character), and will check that it's +where the @samp{|} character is in the ``after'' form (and issue a +test failure if that isn't the case). (This is used in all subsequent +tests, unless overridden by a new @samp{Point-Char} spec.) + +@item Skip +If this is present and value is a form that evaluates to a +non-@code{nil} value, the test will be skipped. +@end table + +If you need to use the literal line single line @samp{=-=} in a test +section, you can quote it with a @samp{\} character. @node How to Debug Tests @chapter How to Debug Tests diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index fc2e3f3b111..c01ceb5fb93 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -744,21 +744,33 @@ Eshell module.} You also need to load the following as shown: @node Writing a module @section Writing a module +This section is not yet written. + @node Module testing @section Module testing +This section is not yet written. + @node Directory handling @section Directory handling +This section is not yet written. + @node Key rebinding @section Key rebinding +This section is not yet written. + @node Smart scrolling @section Smart scrolling +This section is not yet written. + @node Terminal emulation @section Terminal emulation +This section is not yet written. + @node Bugs and ideas @chapter Bugs and ideas @cindex reporting bugs and ideas diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index cc546a92d63..ebfdaf546e3 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -228,11 +228,12 @@ in an external browser by customizing @findex eww-retrieve-command EWW normally uses @code{url-retrieve} to fetch the @acronym{HTML} -before rendering it. It can sometimes be convenient to use an -external program to do this, and @code{eww-retrieve-command} should -then be a list that specifies a command and the parameters. For -instance, to use the Chromium browser, you could say something like -this: +before rendering it, and @code{url-retrieve-synchronously} when +the value of @code{eww-retrieve-command} is @code{sync}. It can +sometimes be convenient to use an external program to do this, and +@code{eww-retrieve-command} should then be a list that specifies +a command and the parameters. For instance, to use the Chromium +browser, you could say something like this: @lisp (setq eww-retrieve-command @@ -379,6 +380,32 @@ thus allowing for the use of the usual substitutions, such as @code{\[eww-reload]} for the current key binding of the @code{eww-reload} command. +@vindex eww-auto-rename-buffer + If the @code{eww-auto-rename-buffer} user option is non-@code{nil}, +EWW buffers will be renamed after rendering a document. If this is +@code{title}, rename based on the title of the document. If this is +@code{url}, rename based on the @acronym{URL} of the document. This +can also be a user-defined function, which is called with no +parameters in the EWW buffer, and should return a string. + +@cindex utm +@vindex eww-url-transformers + EWW runs the URLs through @code{eww-url-transformers} before using +them. This user option is a list of functions, where each function is +called with the URL as the parameter, and should return the (possibly) +transformed URL. By default, this variable contains +@code{eww-remove-tracking}, which removes the common @samp{utm_} +trackers from links. + +@cindex video +@vindex shr-use-xwidgets-for-media + If Emacs has been built with xwidget support, EWW can use that to +display @samp{<video>} elements. However, this support is still +experimental, and on some systems doesn't work (and even worse) may +crash your Emacs, so this feature is off by default. If you wish to +switch it on, set @code{shr-use-xwidgets-for-media} to a +non-@code{nil} value. + @node Command Line @chapter Command Line Usage diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index 9c838a8341a..309bed77609 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -1,8 +1,8 @@ \input texinfo @c -*-texinfo; coding: utf-8 -*- @comment %**start of header @setfilename ../../info/flymake.info -@set VERSION 1.0 -@set UPDATED June 2018 +@set VERSION 1.2 +@set UPDATED September 2021 @settitle GNU Flymake @value{VERSION} @include docstyle.texi @syncodeindex pg cp @@ -11,8 +11,7 @@ @comment %**end of header @copying -This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}), -which is a universal on-the-fly syntax checker for GNU Emacs. +This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}). Copyright @copyright{} 2004--2021 Free Software Foundation, Inc. @@ -41,6 +40,7 @@ modify this GNU manual.'' @page @vskip 0pt plus 1filll @insertcopying + @end titlepage @contents @@ -48,6 +48,25 @@ modify this GNU manual.'' @ifnottex @node Top @top GNU Flymake +@end ifnottex + +Flymake is a universal on-the-fly syntax checker for Emacs. When +enabled, Flymake contacts one or more source @dfn{backends} to +collect information about problems in the buffer, called +@dfn{diagnostics}, and visually annotates them with a special face. +The mode line displays overall status including totals for different +types of diagnostics. + +To learn about using Flymake, @pxref{Using Flymake}. + +Flymake is designed to be easily extended to support new backends via +an Elisp interface. @xref{Extending Flymake}. + +Historically, Flymake used to accept diagnostics from a single +backend. Although obsolete, it is still functional. To learn how to +use and customize it, @pxref{The legacy Proc backend}. + +@ifnottex @insertcopying @end ifnottex @@ -64,19 +83,34 @@ modify this GNU manual.'' @cindex overview of flymake @cindex using flymake -Flymake is a universal on-the-fly buffer checker implemented as an -Emacs minor mode. To use Flymake, you must first activate -@code{flymake-mode} by using the command @kbd{flymake-mode}. +Flymake is only useful if at least one @dfn{backend} is configured to +provide the buffer-checking service. This is done via the hook +@code{flymake-diagnostic-functions}. @xref{Hooks,Hooks,, emacs, The +Emacs Editor}. + +It's possible that some major modes or a third-party package has +already setup this hook for you, by adding @dfn{backend functions} to +@code{flymake-diagnostic-functions}. If you know Elisp you may also +write your own Flymake backend functions. @xref{Backend functions}. -When enabled, Flymake collects information about problems in the -buffer, called @dfn{diagnostics}, from one or more different sources, -or @dfn{backends}, and then visually annotates the buffer by -highlighting problematic buffer regions with a special face. +@menu +* Starting Flymake:: +* Finding diagnostics:: +* Mode line status:: +* Troubleshooting:: +* Customizable variables:: +@end menu -It also displays an overall buffer status in the mode line containing -totals for different types of diagnostics. +@node Starting Flymake +@section Starting Flymake +@cindex starting Flymake -Syntax check is done ``on-the-fly''. It is started whenever +To use Flymake, activate the minor-mode @code{flymake-mode}. +Use the command @kbd{flymake-mode} to toggle it on and off. The +mode line should indicate its presence via an indicator (@pxref{Mode +line status}). + +Syntax checks happen ``on-the-fly''. Each check is started whenever: @itemize @bullet @item @@ -90,50 +124,56 @@ nil; @item some changes were made to the buffer more than @code{0.5} seconds ago (the delay is configurable in @code{flymake-no-changes-timeout}). -@end itemize -Syntax check can also be started manually by typing the @kbd{M-x -flymake-start @key{RET}} command. +@item +When the user invokes the command @code{flymake-start}. +@end itemize If the check detected errors or warnings, the respective buffer -regions are highlighted. You can place point on those regions and use -@kbd{C-h .} (@code{display-local-help}) to see what the specific -problem was. Alternatively, hovering the mouse on those regions -should also display a tool-tip with the same information. +regions are highlighted. @xref{Finding diagnostics}, for how to +learn what the problems are. + +@node Finding diagnostics +@section Finding diagnostics +@cindex read diagnostic message +If Flymake has highlighted the buffer, you may hover the mouse on the +highlighted regions to learn what the specific problem +is. Alternatively, place point on the highlighted regions and use the +commands @code{eldoc} or @code{display-local-help}. + +@cindex next and previous diagnostic +If the diagnostics are outside the visible region of the buffer, @code{flymake-goto-next-error} and @code{flymake-goto-prev-error} are -commands that allow easy navigation to the next/previous erroneous -regions, respectively. It might be a good idea to map them to @kbd{M-n} -and @kbd{M-p} in @code{flymake-mode}, by adding to your init file: +let you navigate to the next/previous erroneous regions, +respectively. It might be a good idea to map them to @kbd{M-n} and +@kbd{M-p} in @code{flymake-mode}, by adding to your init file: @lisp (define-key flymake-mode-map (kbd "M-n") 'flymake-goto-next-error) (define-key flymake-mode-map (kbd "M-p") 'flymake-goto-prev-error) @end lisp -Flymake is a universal syntax checker in the sense that it's easily -extended to support new backends (@pxref{Extending Flymake}). - -Historically, Flymake used to accept diagnostics from a single -backend, albeit a reasonably flexible one. - -This backend isn't (yet) obsolete, and so is still available as a -fallback and active by default (@pxref{The legacy Proc backend}). It works by -selecting a syntax check tool from a preconfigured list (compiler for -C@t{++} files, @command{perl} for Perl files, etc.), and executing it in the -background, passing it a temporary file which is a copy of the current -buffer, and parsing the output for known error/warning message -patterns. - -@menu -* Syntax check statuses:: -* Backend exceptions:: -* Customizable variables:: -@end menu - -@node Syntax check statuses -@section Syntax check statuses -@cindex Syntax check statuses +@cindex listing diagnostics +Sometimes it is useful to have a detailed overview of the diagnostics +in your files without having to jump to each one. The commands +@code{flymake-show-buffer-diagnostics} and +@code{flymake-show-project-diagnostics} are designed to handle this +situation. When invoked, they bring up a separate buffer containing a +detailed structured listing of multiple diagnostics in the current +buffer or for the current project, respectively (@pxref{Projects,,, +emacs, The Emacs Editor}). + +The listings is continuously updated as you edit source code, adding or +removing lines as you make or correct mistakes. Each line of this +listing includes the type of the diagnostic, its line and column in +the file, as well as the diagnostic message. You may sort the listing +by each of these columns. + +@node Mode line status +@section Mode line status +@cindex flymake mode line +@cindex syntax check status When enabled, Flymake displays its status in the mode line, which provides a visual summary of diagnostic collection. It may also hint @@ -157,7 +197,7 @@ delay and Flymake will resume normal operation soon. @item @code{!} @tab All the configured Flymake backends have disabled themselves: Flymake cannot annotate the buffer and action from the user is needed to -investigate and remedy the situation (@pxref{Backend exceptions}). +investigate and remedy the situation (@pxref{Troubleshooting}). @item @code{?} @tab There are no applicable Flymake backends for this buffer, thus Flymake @@ -166,17 +206,24 @@ and add a new backend (@pxref{Extending Flymake}). @end multitable -@node Backend exceptions -@section Backend exceptions +If you would like to customize the appearance of the mode-line, you +can use the variables @code{flymake-mode-line-format} and +@code{flymake-mode-line-counter-format} for that purpose. +@xref{Customizable variables}. + +@node Troubleshooting +@section Troubleshooting +@cindex troubleshooting @cindex backend exceptions @cindex disabled backends @cindex backends, disabled -Some backends may take longer than others to respond or complete, and -some may decide to @emph{disable} themselves if they are not suitable -for the current buffer or encounter some unavoidable problem. A -disabled backend is not tried again for future checks of the current -buffer. +As Flymake supports multiple simutaneously active external backends, +is becomes useful to monitor their status. For example, some backends +may take longer than others to respond or complete, and some may +decide to @emph{disable} themselves if they are not suitable for the +current buffer or encounter some unavoidable problem. A disabled +backend is not tried again for future checks of the current buffer. @findex flymake-reporting-backends @findex flymake-running-backends @@ -186,18 +233,23 @@ The commands @code{flymake-reporting-backends}, show the backends currently used and those which are disabled. @cindex reset disabled backends -Toggling @code{flymake-mode} off and on again, or invoking -@code{flymake-start} with a prefix argument is one way to reset the -disabled backend list, so that they will be tried again in the next check. +Sometimes, re-starting a backend that disabled itself is useful after +some external roadblock has been removed (for example after the user +installed a needed syntax-check program). Invoking +@code{flymake-start} with a prefix argument is a way to reset the +disabled backend list, so that they will be tried again in the next +check. Manually toggling @code{flymake-mode} off and on again also +works. @cindex logging @cindex flymake logging -Flymake also uses a simple logging facility for indicating important -points in the control flow. The logging facility sends logging -messages to the @file{*Flymake log*} buffer. The information logged -can be used for resolving various problems related to Flymake. For -convenience, a shortcut to this buffer can be found in Flymake's menu, -accessible from the top menu bar or just left of the status indicator. +Flymake uses a simple logging facility for indicating important points +in the control flow. The logging facility sends logging messages to +the @file{*Flymake log*} buffer. The logged information can be used +for resolving various problems related to Flymake. For convenience, a +shortcut to this buffer can be found in Flymake's menu, accessible +from the top menu bar or just left of the status indicator. The +command @code{flymake-switch-to-log-buffer} is another alternative. @vindex warning-minimum-log-level @vindex warning-minimum-level @@ -217,7 +269,7 @@ configuration of the Flymake user interface. Format to use for the Flymake mode line indicator. @item flymake-mode-line-counter-format -Mode-line construct for formatting Flymake diagnostic counters inside +mode line construct for formatting Flymake diagnostic counters inside the Flymake mode line indicator. @item flymake-no-changes-timeout @@ -270,10 +322,10 @@ Flymake can primarily be extended in one of two ways: @enumerate @item By changing the look and feel of the annotations produced by the -different backends. +different backends. @xref{Flymake error types}. @item -By adding a new buffer-checking backend. +By adding a new buffer-checking backend. @xref{Backend functions}. @end enumerate The following sections discuss each approach in detail. @@ -288,10 +340,12 @@ The following sections discuss each approach in detail. @cindex customizing error types @cindex error types, customization -To customize the appearance of error types, set properties on the -symbols associated with each diagnostic type. The standard diagnostic -symbols are @code{:error}, @code{:warning} and @code{:note} (though -the backend may define more, @pxref{Backend functions}). +To customize the appearance of error types, the user must set +properties on the symbols associated with each diagnostic type. + +The three standard diagnostic keyowrd symbols -- @code{:error}, +@code{:warning} and @code{:note} -- have pre-configured appearances. +However a backend may define more (@pxref{Backend functions}). The following properties can be set: @@ -489,7 +543,7 @@ manual}) or other asynchronous mechanisms. In any case, backend functions are expected to return quickly or signal an error, in which case the backend is disabled -(@pxref{Backend exceptions}). +(@pxref{Troubleshooting}). If the function returns, Flymake considers the backend to be @dfn{running}. If it has not done so already, the backend is expected @@ -540,6 +594,7 @@ reports targeting other parts of the buffer remain valid. @menu * Flymake utility functions:: +* Foreign and list-only diagnostics:: * An annotated example backend:: @end menu @@ -551,20 +606,26 @@ reports targeting other parts of the buffer remain valid. Before delivering them to Flymake, backends create diagnostic objects by calling the function @code{flymake-make-diagnostic}. -@deffn Function flymake-make-diagnostic buffer beg end type text -Make a Flymake diagnostic for @var{buffer}'s region from @var{beg} to -@var{end}. @var{type} is a diagnostic symbol (@pxref{Flymake error -types}), and @var{text} is a description of the problem detected in -this region. Currently, it is unspecified behavior to make -diagnostics for buffers other than the buffer that the Flymake backend -is responsible for. +@deffn Function flymake-make-diagnostic locus beg end type text &optional data +Make a Flymake diagnostic for the region of text in @var{locus}'s +delimited by @var{beg} and @var{end}. @var{type} is a diagnostic +symbol (@pxref{Flymake error types}), and @var{text} is a description +of the problem detected in this region. Most commonly @var{locus} is +the buffer object designating for the current buffer being +syntax-checked. However, it may be a string nameing a file relative +to the current working directory. @xref{Foreign and list-only +diagnostics}, for when this may be useful. Depending on the type of +@var{locus}, @var{beg} and @var{end} are both either buffer positions +or conses (@var{line} . @var{col}) which specify the line and column +of the diagnostic's start and end positions, respectively. @end deffn @cindex access diagnostic object These objects' properties can be accessed with the functions @code{flymake-diagnostic-backend}, @code{flymake-diagnostic-buffer}, @code{flymake-diagnostic-text}, @code{flymake-diagnostic-beg}, -@code{flymake-diagnostic-end} and @code{flymake-diagnostic-type}. +@code{flymake-diagnostic-end}, @code{flymake-diagnostic-type} and +@code{flymake-diagnostic-data}. Additionally, the function @code{flymake-diagnostics} will collect such objects in the region you specify. @@ -595,7 +656,7 @@ elisp, The Emacs Lisp Reference Manual}). @cindex add a log message For troubleshooting purposes, backends may record arbitrary exceptional or erroneous situations into the Flymake log -buffer (@pxref{Backend exceptions}): +buffer (@pxref{Troubleshooting}): @deffn Macro flymake-log level msg &optional args Log, at level @var{level}, the message @var{msg} formatted with @@ -604,6 +665,58 @@ Log, at level @var{level}, the message @var{msg} formatted with used to display the warning in Flymake's log buffer. @end deffn +@node Foreign and list-only diagnostics +@subsection Foreign and list-only diagnostics +@cindex create diagnostic object for other buffer + +It is possible for a given backend's implementation to use +@code{flymake-make-diagnostic} to create diagnostics for buffers or +files other than the ``source'' buffer where Flymake was enabled. For +instance, this is useful when a given backend has access to +information about the health of neighboring files that are not yet +visited or whose diagnostics depend on the current buffer's state. +There are two alternative ways to go about doing this: + +@enumerate + +@item +@cindex foreign diagnostics +@cindex domestic diagnostics +If the information about neighboring diagnostics is obtained +regularly, like when each syntax-checking iteration of a @code{.c} +file also reports a number of associated problems in an neighboring +@code{.h} file, it is better to create so-called ``foreign'' +diagnostics. + +This is done by passing a file name to @code{flymake-make-diagnostic} +(@pxref{Flymake utility functions}). Then, the resulting object is +simply reported along with the other ``domestic'' diagnostics for the +source buffer (@pxref{Backend functions}). When the neighboring file +is visited as a buffer and Flymake is active there, a number of +supplemental annotations will appear and automatically update whenever +as the ``source'' buffer is syntax-checked. + +@item +@cindex list-only diagnostics +@vindex flymake-list-only-diagnostics +If information about neighboring diagnostics is obtained infrequently, +like when running a time-consuming and sporadic check of a large +project, it is easier for the backend to modify the global variable +@code{flymake-list-only-diagnostics}. + +Flymake will look up this variable when asked to compile project-wide +lists of diagnostics. The backend should add one or more alist +entries that look like (@var{file-name} . @var{diags}). +@var{file-name} is the absolute name of the neighboring file presumed +not to be visited in Emacs already, as that would mean that that +buffer contains more up-to-date information on its diagnostics. +@var{diags} is a list of diagnostic objects. When the neighboring +file @var{file-name} is visited as a buffer and Flymake is activated +there, the ``list-only'' diagnostics will @emph{not} produce +annotations for @var{diags}, as Flymake assumes that the Flymake +activation in the new buffer will take care of that. +@end enumerate + @node An annotated example backend @subsection An annotated example backend @cindex example of backend @@ -661,7 +774,7 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active. ;; Check that the process has indeed exited, as it might ;; be simply suspended. ;; - (when (eq 'exit (process-status proc)) + (when (memq (process-status proc) '(exit signal)) (unwind-protect ;; Only proceed if `proc' is the same as ;; `ruby--flymake-proc', which indicates that @@ -1038,7 +1151,7 @@ correct @file{file.h}. First matching master file found stops the search. The master file is then patched and saved to disk. In case no master file is found, syntax check is aborted, and corresponding status (@samp{!}) is reported in the mode line. -@xref{Syntax check statuses}. +@xref{Mode line status}. @node Getting the include directories @section Getting the include directories @@ -1064,7 +1177,7 @@ of every syntax check attempt. @section Locating the buildfile @cindex locating the buildfile @cindex buildfile, locating -@cindex Makefile, locating +@cindex makefile, locating The Proc backend can be configured to use different tools for performing syntax checks. For example, it can use direct compiler diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index 28bee11d2bd..36c402ab35a 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -1443,7 +1443,7 @@ details. However, what you really want is the Insidious Big Brother Database bbdb. Get it from -@uref{http://bbdb.sourceforge.net/, bbdb's homepage}. +@uref{http://bbdb.sourceforge.net/, bbdb's website}. Now place the following in @file{~/.gnus.el}, to activate bbdb for Gnus: @example @@ -1559,7 +1559,7 @@ if you already use Gnus 5.10, if you still use 5.8.8 or "Request confirmation when replying to news." (interactive) (when (or (not (gnus-news-group-p gnus-newsgroup-name)) - (y-or-n-p "Really reply by mail to article author? ")) + (y-or-n-p "Really reply by mail to article author?")) ad-do-it)))) @end example @noindent diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index 9cdcf39ae10..796bb3bac84 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -2318,19 +2318,18 @@ commands listed in @ref{Browse Foreign Server} at hand. @itemx u @kindex S t @r{(Group)} @kindex u @r{(Group)} -@findex gnus-group-unsubscribe-current-group -@c @icon{gnus-group-unsubscribe} -Toggle subscription to the current group -(@code{gnus-group-unsubscribe-current-group}). +@findex gnus-group-toggle-subscription-at-point +@c @icon{gnus-group-toggle-subscription-at-point} +Toggle subscription to group under point +(@code{gnus-group-toggle-subscription-at-point}). @item S s @itemx U @kindex S s @r{(Group)} @kindex U @r{(Group)} -@findex gnus-group-unsubscribe-group -Prompt for a group to subscribe, and then subscribe it. If it was -subscribed already, unsubscribe it instead -(@code{gnus-group-unsubscribe-group}). +@findex gnus-group-toggle-subscription +Prompt for group, and toggle its subscription. +(@code{gnus-group-toggle-subscription}). @item S k @itemx C-k @@ -3736,10 +3735,10 @@ Enter the current group (@code{gnus-browse-select-group}). @item u @kindex u @r{(Browse)} -@findex gnus-browse-unsubscribe-current-group +@findex gnus-browse-toggle-subscription @vindex gnus-browse-subscribe-newsgroup-method -Unsubscribe to the current group, or, as will be the case here, -subscribe to it (@code{gnus-browse-unsubscribe-current-group}). You +Toggle subscription of the current group +(@code{gnus-browse-toggle-subscription}). You can affect the way the new group is entered into the Group buffer using the variable @code{gnus-browse-subscribe-newsgroup-method}. See @pxref{Subscription Methods} for available options. @@ -4146,6 +4145,25 @@ The default is 2. The @code{gnus-topic-display-empty-topics} says whether to display even topics that have no unread articles in them. The default is @code{t}. +@vindex gnus-topic-display-predicate +If @code{gnus-topic-display-predicate} is non-@code{nil}, it should be +a function that says whether the topic is to be displayed or not. +The function will be called with one parameter (the name of the topic) +and should return non-@code{nil} is the topic is to be displayed. + +For instance, if you don't even want to be reminded that work exists +outside of office hours, you can gather all the work-related groups +into a topic called @samp{"Work"}, and then say something like the +following: + +@lisp +(setq gnus-topic-display-predicate + (lambda (name) + (or (not (equal name "Work")) + (< 090000 + (string-to-number (format-time-string "%H%M%S")) + 170000)))) +@end lisp @node Topic Sorting @subsection Topic Sorting @@ -7112,20 +7130,15 @@ as 10, you might consider setting this variable to something sensible: (setq gnus-simplify-ignored-prefixes (concat "\\`\\[?\\(" - (mapconcat - 'identity - '("looking" - "wanted" "followup" "summary\\( of\\)?" - "help" "query" "problem" "question" - "answer" "reference" "announce" - "How can I" "How to" "Comparison of" - ;; ... - ) - "\\|") + (regexp-opt '("looking" + "wanted" "followup" "summary" "summary of" + "help" "query" "problem" "question" + "answer" "reference" "announce" + "How can I" "How to" "Comparison of" + ;; ... + )) "\\)\\s *\\(" - (mapconcat 'identity - '("for" "for reference" "with" "about") - "\\|") + (regexp-opt '("for" "for reference" "with" "about")) "\\)?\\]?:?[ \t]*")) @end lisp @@ -9356,6 +9369,12 @@ Use html2text---a simple @acronym{HTML} converter included with Gnus. @end table +@item W D F +@kindex W D F @r{(Summary)} +@findex gnus-article-toggle-fonts +Toggle proportional fonts for @acronym{HTML} articles. This temporarily +changes the @code{shr-use-fonts} variable in the current article buffer. + @item W b @kindex W b @r{(Summary)} @findex gnus-article-add-buttons @@ -9824,6 +9843,13 @@ Gravatarify the @code{From} header (@code{gnus-treat-from-gravatar}). Gravatarify all mail headers (i.e., @code{Cc}, @code{To}) (@code{gnus-treat-from-gravatar}). +@item W D e +@kindex W D e @r{(Summary)} +@findex gnus-article-emojize-symbols +Some symbols have both a non-emoji presentation and an emoji +presentation. This command will make Gnus choose the emoji presentation +(@code{gnus-article-emojize-symbols}). + @item W D D @kindex W D D @r{(Summary)} @findex gnus-article-remove-images @@ -12166,6 +12192,7 @@ controlling variable is a predicate list, as described above. @vindex gnus-treat-capitalize-sentences @vindex gnus-treat-overstrike @vindex gnus-treat-strip-cr +@vindex gnus-treat-emojize-symbols @vindex gnus-treat-strip-headers-in-body @vindex gnus-treat-strip-leading-blank-lines @vindex gnus-treat-strip-multiple-blank-lines @@ -12218,6 +12245,7 @@ possible but those listed are probably sufficient for most people. @item gnus-treat-capitalize-sentences (t, integer) @item gnus-treat-overstrike (t, integer) @item gnus-treat-strip-cr (t, integer) +@item gnus-treat-emojize-symbols (t, integer) @item gnus-treat-strip-headers-in-body (t, integer) @item gnus-treat-strip-leading-blank-lines (t, first, integer) @item gnus-treat-strip-multiple-blank-lines (t, integer) @@ -13851,11 +13879,9 @@ present in this hook. @item nntp-authinfo-function @vindex nntp-authinfo-function @findex nntp-send-authinfo -@vindex nntp-authinfo-file This function will be used to send @samp{AUTHINFO} to the @acronym{NNTP} server. The default function is @code{nntp-send-authinfo}, which looks -through your @file{~/.authinfo} (or whatever you've set the -@code{nntp-authinfo-file} variable to) for applicable entries. If none +through your @file{~/.authinfo} for applicable entries. If none are found, it will prompt you for a login name and a password. The format of the @file{~/.authinfo} file is (almost) the same as the @code{ftp} @file{~/.netrc} file, which is defined in the @code{ftp} @@ -14517,7 +14543,8 @@ this should be set to @code{anonymous}. If this variable isn't set, the normal login methods will be used. If you wish to specify a specific login method to be used, you can set this variable to either @code{login} (the traditional @acronym{IMAP} login method), -@code{plain} or @code{cram-md5}. +@code{plain}, @code{cram-md5} or @code{xoauth2}. (The latter method +requires using the @file{oauth2.el} library.) @item nnimap-expunge When to expunge deleted messages. If @code{never}, deleted articles @@ -21873,7 +21900,7 @@ bound to mairix searches and are automatically updated. Mairix is a tool for indexing and searching words in locally stored mail. It was written by Richard Curnow and is licensed under the GPL@. Mairix comes with most popular GNU/Linux distributions, but it also -runs under Windows (with cygwin), macOS and Solaris. The homepage can +runs under Windows (with cygwin), macOS and Solaris. The website can be found at @uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} @@ -22702,6 +22729,13 @@ output lines in the various buffers. There's quite a lot of them. Fortunately, they all use the same syntax, so there's not that much to be annoyed by. +Gnus does not use the font locking machinery used by most modes in +Emacs, so switching @code{font-lock-mode} on in the Gnus +group/summary/article buffers usually doesn't do anything +useful---instead it'll just mess up the faces that Gnus has already +put in the buffer. (This is also the case for other minor modes that +use the font locking machinery, like @code{whitespace-mode}.) + Here's an example format spec (from the group buffer): @samp{%M%S%5y: %(%g%)\n}. We see that it is indeed extremely ugly, and that there are lots of percentages everywhere. @@ -26292,7 +26326,7 @@ Fortunately, setting up the Gnus registry is pretty easy: @end lisp This adds registry saves to Gnus newsrc saves (which happen on exit -and when you press @kbd{s} from the @file{*Group*} buffer. It also +and when you press @kbd{s} from the @file{*Group*} buffer). It also adds registry calls to article actions in Gnus (copy, move, etc.)@: so it's not easy to undo the initialization. See @code{gnus-registry-initialize} for the gory details. @@ -26861,9 +26895,10 @@ but at the common table.@* If you want to investigate the person responsible for this outrage, you can point your (feh!) web browser to -@uref{https://quimby.gnus.org/}. This is also the primary -distribution point for the new and spiffy versions of Gnus, and is -known as The Site That Destroys Newsrcs And Drives People Mad. +@uref{https://quimby.gnus.org/}. This used to be the primary +distribution point for the new and spiffy versions of Gnus, and was +known as The Site That Destroys Newsrcs And Drives People Mad, but +these days Gnus is developed in the Emacs repository. During the first extended alpha period of development, the new Gnus was called ``(ding) Gnus''. @dfn{(ding)} is, of course, short for diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi index a571c744870..e57b5ed5422 100644 --- a/doc/misc/mairix-el.texi +++ b/doc/misc/mairix-el.texi @@ -60,6 +60,8 @@ database. * Using:: List of interactive functions * Extending:: Support your favorite mail reader! * GNU Free Documentation License:: The license for this documentation. +* Function Index: Function Index. +* Variable Index: Variable Index. @end menu @node About @@ -68,7 +70,7 @@ database. Mairix is a tool for indexing and searching words in locally stored mail. It was written by Richard Curnow and is licensed under the GPL@. Mairix comes with most popular GNU/Linux distributions, but it also -runs under Windows (with cygwin), macOS and Solaris. The homepage can +runs under Windows (with cygwin), macOS and Solaris. The website can be found at @uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} @@ -339,4 +341,14 @@ And that's it! @appendix GNU Free Documentation License @include doclicense.texi +@node Function Index +@unnumbered Function Index + +@printindex fn + +@node Variable Index +@unnumbered Variable Index + +@printindex vr + @bye diff --git a/doc/misc/message.texi b/doc/misc/message.texi index d2353e6cec6..4136ad859f7 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -1699,14 +1699,15 @@ result is inserted. @cindex Sv @cindex Re Responses to messages have subjects that start with @samp{Re: }. This -is @emph{not} an abbreviation of the English word ``response'', but is -Latin, and means ``in response to''. Some illiterate nincompoops have -failed to grasp this fact, and have ``internationalized'' their software -to use abominations like @samp{Aw: } (``antwort'') or @samp{Sv: } -(``svar'') instead, which is meaningless and evil. However, you may -have to deal with users that use these evil tools, in which case you may -set this variable to a regexp that matches these prefixes. Myself, I -just throw away non-compliant mail. +is @emph{not} an abbreviation of the English word ``response'', but it +comes from the Latin ``res'', and means ``in the matter of''. Some +illiterate nincompoops have failed to grasp this fact, and have +``internationalized'' their software to use abominations like +@samp{Aw: } (``antwort'') or @samp{Sv: } (``svar'') instead, which is +meaningless and evil. However, you may have to deal with users that +use these evil tools, in which case you may set this variable to a +regexp that matches these prefixes. Myself, I just throw away +non-compliant mail. Here's an example of a value to deal with these headers when responding to a message: @@ -2084,7 +2085,7 @@ This optional header will be computed by Message. @vindex user-mail-address @findex system-name @cindex Sun -@cindex i-did-not-set--mail-host-address--so-tickle-me +@cindex mail-host-address-is-not-set This required header will be generated by Message. A unique ID will be created based on the date, time, user name (for the local part) and the domain part. For the domain part, message will look (in this order) at diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi index 62540284312..bc788ebae09 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -7383,8 +7383,8 @@ The name of the MH sequence for ticked messages (default: @samp{'tick}). @item mh-update-sequences-after-mh-show-flag On means flush MH sequences to disk after message is shown (default: @samp{on}). -@item mh-whitelist-preserves-sequences-flag -On means that sequences are preserved when messages are whitelisted +@item mh-allowlist-preserves-sequences-flag +On means that sequences are preserved when messages are allowlisted (default: @samp{on}). @end vtable @@ -7540,17 +7540,17 @@ Marshall Rose once wrote a paper on MH entitled, @cite{How to process could be entitled, @cite{How to process 1000 spams a day and still get some real work done}. -@cindex blacklisting +@cindex blocklisting @cindex ham @cindex viruses -@cindex whitelisting +@cindex allowlisting @cindex worms We use the terms @dfn{junk mail} and @dfn{spam} interchangeably for any unwanted message which includes spam, @dfn{viruses}, and @dfn{worms}. The opposite of spam is @dfn{ham}. The act of classifying -a sender as one who sends junk mail is called @dfn{blacklisting}; the -opposite is called @dfn{whitelisting}. +a sender as one who sends junk mail is called @dfn{blocklisting}; the +opposite is called @dfn{allowlisting}. @table @kbd @kindex J ? @@ -7560,14 +7560,14 @@ Display cheat sheet for the commands of the current prefix in minibuffer (@code{mh-prefix-help}). @c ------------------------- @kindex J b -@findex mh-junk-blacklist +@findex mh-junk-blocklist @item J b -Blacklist range as spam (@code{mh-junk-blacklist}). +Blocklist range as spam (@code{mh-junk-blocklist}). @c ------------------------- -@kindex J w -@findex mh-junk-whitelist -@item J w -Whitelist range as ham (@code{mh-junk-whitelist}). +@kindex J a +@findex mh-junk-allowlist +@item J a +Allowlist range as ham (@code{mh-junk-allowlist}). @c ------------------------- @item @code{mh-spamassassin-identify-spammers} Identify spammers who are repeat offenders. @@ -7597,31 +7597,31 @@ The following option in the @samp{mh-sequences} customization group is also available. @vtable @code -@item mh-whitelist-preserves-sequences-flag -On means that sequences are preserved when messages are whitelisted +@item mh-allowlist-preserves-sequences-flag +On means that sequences are preserved when messages are allowlisted (default: @samp{on}). @end vtable The following hooks are available. @vtable @code -@item mh-blacklist-msg-hook -Hook run by @kbd{J b} (@code{mh-junk-blacklist}) after marking each -message for blacklisting (default: @code{nil}). +@item mh-blocklist-msg-hook +Hook run by @kbd{J b} (@code{mh-junk-blocklist}) after marking each +message for blocklisting (default: @code{nil}). @c ------------------------- -@item mh-whitelist-msg-hook -Hook run by @kbd{J w} (@code{mh-junk-whitelist}) after marking each -message for whitelisting (default @samp{nil}). +@item mh-allowlist-msg-hook +Hook run by @kbd{J a} (@code{mh-junk-allowlist}) after marking each +message for allowlisting (default @samp{nil}). @end vtable The following faces are available. @vtable @code -@item mh-folder-blacklisted -Blacklisted message face. +@item mh-folder-blocklisted +Blocklisted message face. @c ------------------------- -@item mh-folder-whitelisted -Whitelisted message face +@item mh-folder-allowlisted +Allowlisted message face @end vtable @cindex SpamProbe @@ -7647,21 +7647,21 @@ example, you have both SpamAssassin and bogofilter installed and you want to use bogofilter, then you can set this option to @samp{Bogofilter}. -@findex mh-junk-blacklist +@findex mh-junk-blocklist @kindex J b @vindex mh-junk-disposition -The command @kbd{J b} (@code{mh-junk-blacklist}) trains the spam +The command @kbd{J b} (@code{mh-junk-blocklist}) trains the spam program in use with the content of the range (@pxref{Ranges}) and then handles the message(s) as specified by the option @code{mh-junk-disposition}. By default, this option is set to @samp{Delete Spam} but you can also specify the name of the folder which is useful for building a corpus of spam for training purposes. -@findex mh-junk-whitelist -@kindex J w +@findex mh-junk-allowlist +@kindex J a -In contrast, the command @kbd{J w} (@code{mh-junk-whitelist}) +In contrast, the command @kbd{J a} (@code{mh-junk-allowlist}) reclassifies a range of messages (@pxref{Ranges}) as ham if it were incorrectly classified as spam. It then refiles the message into the @file{+inbox} folder. @@ -7671,12 +7671,12 @@ incorrectly classified as spam. It then refiles the message into the @cindex @samp{Previous-Sequence} MH profile component @cindex sequence, @samp{cur} @cindex sequence, @samp{Previous-Sequence} -@vindex mh-whitelist-preserves-sequences-flag +@vindex mh-allowlist-preserves-sequences-flag If a message is in any sequence (except @samp{Previous-Sequence:} and -@samp{cur}) when it is whitelisted, then it will still be in those +@samp{cur}) when it is allowlisted, then it will still be in those sequences in the destination folder. If this behavior is not desired, -then turn off the option @code{mh-whitelist-preserves-sequences-flag}. +then turn off the option @code{mh-allowlist-preserves-sequences-flag}. @cindex @file{*MH-E Log*} @cindex buffers, @file{*MH-E Log*} @@ -7687,7 +7687,7 @@ By default, the programs are run in the foreground, but this can be slow when junking large numbers of messages. If you have enough memory or don't junk that many messages at the same time, you might try turning on the option @code{mh-junk-background}. @footnote{Note that -the option @code{mh-junk-background} is used as the @code{display} +the option @code{mh-junk-background} is used as the @code{destination} argument in the call to @code{call-process}. Therefore, turning on this option means setting its value to @samp{0}. You can also set its value to @samp{t} to direct the programs' output to the @file{*MH-E @@ -7756,33 +7756,33 @@ the @samp{+spam} folder for later review. The major weakness of rules-based filters is a plethora of false positives so it is worthwhile to check. -@findex mh-junk-blacklist -@findex mh-junk-whitelist +@findex mh-junk-blocklist +@findex mh-junk-allowlist @kindex J b -@kindex J w +@kindex J a If SpamAssassin classifies a message incorrectly, or is unsure, you can -use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and -@kbd{J w} (@code{mh-junk-whitelist}). +use the MH-E commands @kbd{J b} (@code{mh-junk-blocklist}) and +@kbd{J a} (@code{mh-junk-allowlist}). @cindex @command{sa-learn} @cindex @file{.spamassassin/user_prefs} @cindex files, @file{.spamassassin/user_prefs} -The command @kbd{J b} (@code{mh-junk-blacklist}) adds a +The command @kbd{J b} (@code{mh-junk-blocklist}) adds a @samp{blacklist_from} entry to @file{~/spamassassin/user_prefs}, deletes the message, and sends the message to the Razor, so that others might not see this spam. If the @command{sa-learn} command is available, the message is also recategorized as spam. -The command@kbd{J w} (@code{mh-junk-whitelist}) adds a +The command@kbd{J a} (@code{mh-junk-allowlist}) adds a @samp{whitelist_from} rule to @samp{~/.spamassassin/user_prefs}. If the @command{sa-learn} command is available, the message is also recategorized as ham. Over time, you'll observe that the same host or domain occurs repeatedly in the @samp{blacklist_from} entries, so you might think -that you could avoid future spam by blacklisting all mail from a +that you could avoid future spam by blocklisting all mail from a particular domain. The utility function @code{mh-spamassassin-identify-spammers} helps you do precisely that. This function displays a frequency count of the hosts and domains in @@ -7796,7 +7796,7 @@ blacklist_from *@@*amazingoffersdirect2u.com @end smallexample In versions of SpamAssassin (2.50 and on) that support a Bayesian -classifier, @kbd{J b} @code{(mh-junk-blacklist}) uses the program +classifier, @kbd{J b} @code{(mh-junk-blocklist}) uses the program @command{sa-learn} to recategorize the message as spam. Neither MH-E, nor SpamAssassin, rebuilds the database after adding words, so you will need to run @samp{sa-learn --rebuild} periodically. This can be @@ -7856,14 +7856,14 @@ spam/. spam/unsure/. @end smallexample -@findex mh-junk-blacklist -@findex mh-junk-whitelist +@findex mh-junk-blocklist +@findex mh-junk-allowlist @kindex J b -@kindex J w +@kindex J a If bogofilter classifies a message incorrectly, or is unsure, you can -use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J -w} (@code{mh-junk-whitelist}) to update bogofilter's training. +use the MH-E commands @kbd{J b} (@code{mh-junk-blocklist}) and +@kbd{J a} (@code{mh-junk-allowlist}) to update bogofilter's training. The @cite{Bogofilter FAQ} suggests that you run the following occasionally to shrink the database: @@ -7908,14 +7908,14 @@ SCORE=| spamprobe receive spam/. @end smallexample -@findex mh-junk-blacklist -@findex mh-junk-whitelist +@findex mh-junk-blocklist +@findex mh-junk-allowlist @kindex J b -@kindex J w +@kindex J a If SpamProbe classifies a message incorrectly, you can use the MH-E -commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J w} -(@code{mh-junk-whitelist}) to update SpamProbe's training. +commands @kbd{J b} (@code{mh-junk-blocklist}) and @kbd{J a} +(@code{mh-junk-allowlist}) to update SpamProbe's training. @subheading Other Things You Can Do @@ -8114,7 +8114,7 @@ width is 4, so you would use @samp{(mh-set-cmd-note 4)}. @vindex mh-scan-format-nmh The default setting for @code{mh-scan-format-file} is @samp{Use MH-E -scan Format}. This means that the format string will be taken from the +scan Format}. This means that the format string will be taken from either @code{mh-scan-format-mh} or @code{mh-scan-format-nmh} depending on whether MH or nmh (or GNU mailutils MH) is in use. This setting also enables you to turn on the option @@ -8816,8 +8816,8 @@ hands several times since then. Jim Larus wanted to do something similar for GNU Emacs, and ended up completely rewriting it that same year. In 1989, Stephen Gildea picked it up and added many improvements. Bill Wohler then took over in 2000 and moved its -development to @uref{https://sourceforge.net/, SourceForge} where it -lives today. +development to @uref{https://sourceforge.net/, SourceForge}. +Since 2016, MH-E development occurs within the Emacs repository. @menu * From Brian Reid:: diff --git a/doc/misc/modus-themes.org b/doc/misc/modus-themes.org index 5bb230f892a..675144d5177 100644 --- a/doc/misc/modus-themes.org +++ b/doc/misc/modus-themes.org @@ -5,9 +5,9 @@ #+options: ':t toc:nil author:t email:t num:t #+startup: content -#+macro: stable-version 1.5.0 -#+macro: release-date 2021-07-15 -#+macro: development-version 1.6.0-dev +#+macro: stable-version 1.6.0 +#+macro: release-date 2021-09-29 +#+macro: development-version 1.7.0-dev #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ #+macro: space @@texinfo:@: @@ #+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ @@ -383,6 +383,7 @@ this manual. modus-themes-no-mixed-fonts nil modus-themes-subtle-line-numbers nil modus-themes-success-deuteranopia t + modus-themes-tabs-accented t modus-themes-inhibit-reload t ; only applies to `customize-set-variable' and related modus-themes-fringes nil ; {nil,'subtle,'intense} @@ -395,9 +396,8 @@ this manual. ;; Options for `modus-themes-mode-line' are either nil, or a list ;; that can combine any of `3d' OR `moody', `borderless', - ;; `accented'. The variable's doc string shows all possible - ;; combinations. - modus-themes-mode-line '(3d accented) + ;; `accented', `padded'. + modus-themes-mode-line '(padded accented borderless) ;; Options for `modus-themes-syntax' are either nil (the default), ;; or a list of properties that may include any of those symbols: @@ -443,6 +443,7 @@ this manual. modus-themes-org-agenda ; this is an alist: read the manual or its doc string '((header-block . (variable-pitch scale-title)) (header-date . (grayscale workaholic bold-today)) + (event . (accented scale-small)) (scheduled . uniform) (habit . traffic-light-deuteranopia)) @@ -473,7 +474,7 @@ Symbol: ~modus-themes-inhibit-reload~ Possible values: -1. ~nil~ +1. ~nil~ 2. ~t~ (default) By default, customizing a theme-related user option through the Custom @@ -803,6 +804,7 @@ effect, color, and border visibility: - ~moody~ + ~accented~ + ~borderless~ ++ ~padded~ The default (a nil value or an empty list) is a two-dimensional rectangle with a border around it. The active and the inactive @@ -829,6 +831,13 @@ the same as the background, effectively creating some padding. The ~accented~ property ensures that the active mode line uses a colored background instead of the standard shade of gray. +The ~padded~ property increases the apparent height of the mode line. +This is done by applying box effects and combining them with an +underline and overline. To ensure that the underline is placed at the +bottom, set ~x-underline-at-descent-line~ to non-nil. The ~padded~ property +has no effect when the ~moody~ property is also used, because Moody +already applies its own padding. + Combinations of any of those properties are expressed as a list, like in these examples: @@ -843,7 +852,7 @@ The order in which the properties are set is not significant. In user configuration files the form may look like this: #+begin_src emacs-lisp -(setq modus-themes-prompts '(borderless accented)) +(setq modus-themes-mode-line '(borderless accented)) #+end_src Note that Moody does not expose any faces that the themes could style @@ -868,6 +877,27 @@ Furthermore, because Moody expects an underline and overline instead of a box style, it is advised to set ~x-underline-at-descent-line~ to a non-nil value. +** Option for accented background in tab interfaces +:properties: +:alt_title: Tab style +:description: Toggle accented background for tabs +:custom_id: h:27cef8f5-dc4e-4c93-ba41-b899e650d936 +:end: +#+vindex: modus-themes-tabs-accented + +Symbol: ~modus-themes-tabs-accented~ + +Possible values: + ++ ~nil~ (default) ++ ~t~ + +By default, all tab interfaces use backgrounds which are shades of gray. +When this option is set to non-nil, the backgrounds become colorful. + +This affects the built-in ~tab-bar-mode~ and ~tab-line-mode~, as well as the +Centaur tabs package. + ** Option for completion framework aesthetics :properties: :alt_title: Completion UIs @@ -1305,6 +1335,7 @@ all possible combinations: (setq modus-themes-org-agenda '((header-block . (variable-pitch scale-title)) (header-date . (grayscale workaholic bold-today)) + (event . (accented scale-small)) (scheduled . uniform) (habit . traffic-light))) #+end_src @@ -1346,6 +1377,11 @@ the following properties: - ~bold-today~ to apply a bold typographic weight to the current date; - ~bold-all~ to render all date headings in a bold weight. +- ~scale-heading~ increases the height of the date headings to the value + of ~modus-themes-scale-1~ (which is the first step in the scale for + regular headings). +- ~underline-today~ applies an underline to the current date while + removing the background it has by default. For example: @@ -1355,6 +1391,31 @@ For example: (header-date . (grayscale bold-all)) (header-date . (grayscale workaholic)) (header-date . (grayscale workaholic bold-today)) +(header-date . (grayscale workaholic bold-today scale-heading)) +#+end_src + +An ~event~ key covers events from the diary and other entries that derive +from a symbolic expression or sexp (e.g. phases of the moon, holidays). +This key accepts a list of values. By default (a nil value or an empty +list) those have a gray foreground, while sexp events are additionally +presented using slanted text (italics). The properties that can form a +list of possible values are: + +- ~scale-small~ reduces the height of the entries to the value of the user + option ~modus-themes-scale-small~ (0.9 the height of the main font size + by default). +- ~accented~ applies an accent value to the event's foreground, replacing + the original gray. +- ~italic~ adds a slant to the font's forms (italic or oblique forms, + depending on the typeface). + +For example: + +#+begin_src emacs-lisp +(event . nil) +(event . (scale-small)) +(event . (scale-small accented)) +(event . (scale-small accented italic)) #+end_src A ~scheduled~ key applies to tasks with a scheduled date. By default (a @@ -1416,6 +1477,7 @@ Putting it all together, the alist can look like this: #+begin_src emacs-lisp '((header-block . (scale-title variable-pitch)) (header-date . (grayscale workaholic bold-today)) + (event . (accented scale-small)) (scheduled . uniform) (habit . traffic-light)) @@ -1423,6 +1485,7 @@ Putting it all together, the alist can look like this: (setq modus-themes-org-agenda '((header-block . (scale-title variable-pitch)) (header-date . (grayscale workaholic bold-today)) + (event . (accented scale-small)) (scheduled . uniform) (habit . traffic-light))) #+end_src @@ -1574,7 +1637,8 @@ resource for finding a consistent scale: modus-themes-scale-2 1.1 modus-themes-scale-3 1.15 modus-themes-scale-4 1.2 - modus-themes-scale-title 1.3) + modus-themes-scale-title 1.3 + modus-themes-scale-small 0.9) #+end_src As for the application of that scale, the variables that range from @@ -1593,6 +1657,11 @@ supposed to signify the primary header. Similarly, the Org Agenda's structure headings are not part of a recognisable scale and so they also get ~modus-themes-scale-title~ ([[#h:68f481bc-5904-4725-a3e6-d7ecfa7c3dbc][Option for Org agenda constructs]]). +Similarly ~modus-themes-scale-small~ is not applied to regular headings, +but reserved for special contexts where the user is presented with an +option to use a smaller font height than the base size. It is only +implemented for the Org agenda. + Users who wish to maintain scaled headings for the normal syntax while preventing special headings from standing out, can assign a value of =1.0= to ~modus-themes-scale-title~ to make it the same as body text (or @@ -2321,8 +2390,8 @@ Using the above has an immediate effect, as it reloads the active Modus theme. The =my-modus-themes-saturate= function stores new color values in the -variables =modus-themes-operandi-color-overrides= and -=modus-themes-vivendi-color-overrides=, meaning that it undoes changes +variables ~modus-themes-operandi-color-overrides~ and +~modus-themes-vivendi-color-overrides~, meaning that it undoes changes implemented by the user on individual colors. To have both automatic saturation adjustment across the board and retain per-case edits to the palette, some tweaks to the above function are required. For example: @@ -2574,9 +2643,9 @@ two): #+begin_src emacs-lisp (setq org-todo-keyword-faces - '(("MEET" . '(font-lock-preprocessor-face org-todo)) - ("STUDY" . '(font-lock-variable-name-face org-todo)) - ("WRITE" . '(font-lock-type-face org-todo)))) + '(("MEET" . '(bold org-todo)) + ("STUDY" . '(warning org-todo)) + ("WRITE" . '(shadow org-todo)))) #+end_src This will refashion the keywords you specify, while letting the other @@ -2607,7 +2676,7 @@ configuration of the priority cookies: #+begin_src emacs-lisp (setq org-priority-faces - '((?A . '(org-scheduled-today org-priority)) + '((?A . '(bold org-priority)) (?B . org-priority) (?C . '(shadow org-priority)))) #+end_src @@ -2700,7 +2769,7 @@ A couple of examples (rounded numbers): ;; Pure black with pure green (modus-themes-contrast "#000000" "#00ff00") ;; => 15.3 -;; That is is a highly accessible combo +;; That is a highly accessible combo #+end_src It does not matter which color value comes first. The ratio is always @@ -2904,6 +2973,7 @@ have lots of extensions, so the "full support" may not be 100% true… + alert + all-the-icons + annotate ++ ansi-color + anzu + apropos + apt-sources-list @@ -2943,6 +3013,7 @@ have lots of extensions, so the "full support" may not be 100% true… + css-mode + csv-mode + ctrlf ++ cursor-flash + custom (what you get with {{{kbd(M-x customize)}}}) + dap-mode + dashboard (emacs-dashboard) @@ -2977,6 +3048,7 @@ have lots of extensions, so the "full support" may not be 100% true… + eldoc-box + elfeed + elfeed-score ++ elpher + embark + emms + enh-ruby-mode (enhanced-ruby-mode) @@ -3033,6 +3105,7 @@ have lots of extensions, so the "full support" may not be 100% true… + highlight-escape-sequences (~hes-mode~) + highlight-indentation + highlight-numbers ++ highlight-parentheses ([[#h:24bab397-dcb2-421d-aa6e-ec5bd622b913][Note on highlight-parentheses.el]]) + highlight-symbol + highlight-tail + highlight-thing @@ -3225,6 +3298,7 @@ These do not require any extra styles because they are configured to inherit from some basic faces or their dependencies which are directly supported by the themes. ++ bufler + counsel-notmuch + edit-indirect + evil-owl @@ -3234,8 +3308,13 @@ supported by the themes. + perl-mode + php-mode + rjsx-mode ++ side-hustle + swift-mode + tab-bar-echo-area ++ tide ++ vertico-indexed ++ vertico-mouse ++ vertico-quick * Notes on individual packages :properties: @@ -3415,6 +3494,135 @@ and have the foreground be indistinguishable from it. For example: [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. +** Note on highlight-parentheses.el +:PROPERTIES: +:CUSTOM_ID: h:24bab397-dcb2-421d-aa6e-ec5bd622b913 +:END: + +The =highlight-parentheses= package provides contextual coloration of +surrounding parentheses, highlighting only those which are around the +point. The package expects users to customize the applicable colors on +their own by configuring certain variables. + +To make the Modus themes work as expected with this, we need to use some +of the techniques that are discussed at length in the various +"Do-It-Yourself" (DIY) sections, which provide insight into the more +advanced customization options of the themes. + +[[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization (do-it-yourself)]]. + +In the following example, we are assuming that the user wants to (i) +re-use color variables provided by the themes, (ii) be able to retain +their tweaks while switching between ~modus-operandi~ and ~modus-vivendi~, +and (iii) have the option to highlight either the foreground of the +parentheses or the background as well. + +We start by defining our own variable, which will serve as a toggle +between foreground and background coloration styles: + +#+begin_src emacs-lisp +(defvar my-highlight-parentheses-use-background t + "Prefer `highlight-parentheses-background-colors'.") +#+end_src + +Then we can update our preference with this: + +#+begin_src emacs-lisp +;; Set to nil to disable backgrounds. +(setq my-highlight-parentheses-use-background nil) +#+end_src + +To re-use colors from the themes, we must wrap our code in the +~modus-themes-with-colors~ macro. Our implementation must interface with +the variables ~highlight-parentheses-background-colors~ and/or +~highlight-parentheses-colors~. + +So we can have something like this (the doc string of +~modus-themes-with-colors~ explains where the names of the colors can be +found): + +#+begin_src emacs-lisp +(modus-themes-with-colors + ;; Our preference for setting either background or foreground + ;; styles, depending on `my-highlight-parentheses-use-background'. + (if my-highlight-parentheses-use-background + + ;; Here we set color combinations that involve both a background + ;; and a foreground value. + (setq highlight-parentheses-background-colors (list cyan-refine-bg + magenta-refine-bg + green-refine-bg + yellow-refine-bg) + highlight-parentheses-colors (list cyan-refine-fg + magenta-refine-fg + green-refine-fg + yellow-refine-fg)) + + ;; And here we pass only foreground colors while disabling any + ;; backgrounds. + (setq highlight-parentheses-colors (list green-intense + magenta-intense + blue-intense + red-intense) + highlight-parentheses-background-colors nil))) + +;; Include this if you also want to make the parentheses bold: +(set-face-attribute 'highlight-parentheses-highlight nil :inherit 'bold) + +;; Our changes must be evaluated before enabling the relevant mode, so +;; this comes last. +(global-highlight-parentheses-mode 1) +#+end_src + +For our changes to persist while switching between the Modus themes, we +need to include them in a function which can then get passed to +~modus-themes-after-load-theme-hook~. This is the complete +implementation: + +#+begin_src emacs-lisp +;; Configurations for `highlight-parentheses': +(require 'highlight-parentheses) + +(defvar my-highlight-parentheses-use-background t + "Prefer `highlight-parentheses-background-colors'.") + +(setq my-highlight-parentheses-use-background nil) ; Set to nil to disable backgrounds + +(defun my-modus-themes-highlight-parentheses () + (modus-themes-with-colors + ;; Our preference for setting either background or foreground + ;; styles, depending on `my-highlight-parentheses-use-background'. + (if my-highlight-parentheses-use-background + + ;; Here we set color combinations that involve both a background + ;; and a foreground value. + (setq highlight-parentheses-background-colors (list cyan-refine-bg + magenta-refine-bg + green-refine-bg + yellow-refine-bg) + highlight-parentheses-colors (list cyan-refine-fg + magenta-refine-fg + green-refine-fg + yellow-refine-fg)) + + ;; And here we pass only foreground colors while disabling any + ;; backgrounds. + (setq highlight-parentheses-colors (list green-intense + magenta-intense + blue-intense + red-intense) + highlight-parentheses-background-colors nil))) + + ;; Include this if you also want to make the parentheses bold: + (set-face-attribute 'highlight-parentheses-highlight nil :inherit 'bold) + + ;; Our changes must be evaluated before enabling the relevant mode, so + ;; this comes last. + (global-highlight-parentheses-mode 1)) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-highlight-parentheses) +#+end_src + ** Note on mmm-mode.el background colors :properties: :custom_id: h:99cf0d6c-e478-4e26-9932-3bf3427d13f6 @@ -3520,7 +3728,7 @@ With 8 colors: :desaturations '(0) ; do not change---may lower the contrast ratio :lightens '(0) ; same :colors (modus-themes-with-colors - (list fg-special-cold + (list blue magenta magenta-alt-other cyan-alt-other @@ -3540,10 +3748,10 @@ to the themes' default aesthetic: :desaturations '(0) ; do not change---may lower the contrast ratio :lightens '(0) ; same :colors (modus-themes-with-colors - (list fg-main - cyan-alt-other + (list blue + magenta magenta-alt-other - magenta))) + green-alt))) #+end_src If you need to apply desaturation and lightening, you can use what the @@ -3958,7 +4166,7 @@ latter case. ~modus-operandi~ is best used outdoors or in a room that either gets direct sunlight or has plenty of light. Whereas ~modus-vivendi~ works better when there is not a lot of sunshine or the room has a source of -light, preferably a faint or warm one. It is possible to use +light that is preferably a faint and/or warm one. It is possible to use ~modus-operandi~ at night and ~modus-vivendi~ during the day, though that will depend on several variables, such as one's overall perception of color, the paint on the walls and how that contributes to the impression @@ -4005,9 +4213,7 @@ in which you can contribute to their ongoing development. :end: #+cindex: Sources of the themes -The ~modus-operandi~ and ~modus-vivendi~ themes are built into Emacs. -Currently they are in Emacs' git main branch (trunk), which is tracking -the next development release target. +The ~modus-operandi~ and ~modus-vivendi~ themes are built into Emacs 28. The source code of the themes is [[https://gitlab.com/protesilaos/modus-themes/][available on Gitlab]], for the time being. A [[https://github.com/protesilaos/modus-themes/][mirror on Github]] is also on offer. @@ -4118,31 +4324,31 @@ The Modus themes are a collective effort. Every bit of work matters. + Contributions to code or documentation :: Anders Johansson, Basil L.{{{space()}}} Contovounesios, Carlo Zancanaro, Eli Zaretskii, Fritz Grabo, - Kostadin Ninev, Madhavan Krishnan, Markus Beppler, Matthew Stevenson, - Mauro Aranda, Nicolas De Jaeghere, Philip Kaludercic, Rudolf - Adamkovič, Shreyas Ragavan, Stefan Kangas, Vincent Murphy, Xinglu - Chen. - -+ Ideas and user feedback :: Aaron Jensen, Adam Spiers, Adrian Manea, - Alex Griffin, Alex Peitsinis, Alexey Shmalko, Alok Singh, Anders - Johansson, André Alexandre Gomes, Arif Rezai, Basil L.{{{space()}}} - Contovounesios, Burgess Chang, Christian Tietze, Christopher Dimech, - Damien Cassou, Daniel Mendler, Dario Gjorgjevski, David Edmondson, - Davor Rotim, Divan Santana, Emanuele Michele Alberto Monterosso, - Farasha Euker, Gautier Ponsinet, Gerry Agbobada, Gianluca Recchia, - Gustavo Barros, Hörmetjan Yiltiz, Ilja Kocken, Iris Garcia, Jeremy - Friesen, Jerry Zhang, John Haman, Joshua O'Connor, Kevin Fleming, - Kévin Le Gouguec, Kostadin Ninev, Len Trigg, Manuel Uberti, Mark - Burton, Markus Beppler, Mauro Aranda, Michael Goldenberg, Morgan - Smith, Murilo Pereira, Nicky van Foreest, Nicolas De Jaeghere, Paul - Poloskov, Pengji Zhang, Pete Kazmier, Peter Wu, Philip Kaludercic, - Pierre Téchoueyres, Roman Rudakov, Ryan Phillips, Rudolf Adamkovič, - Sam Kleinman, Shreyas Ragavan, Simon Pugnet, Tassilo Horn, Thibaut - Verron, Thomas Heartman, Trey Merkley, Togan Muftuoglu, Toon Claes, - Uri Sharf, Utkarsh Singh, Vincent Foley. As well as users: Ben, - CsBigDataHub1, Emacs Contrib, Eugene, Fourchaux, Fredrik, Moesasji, - Nick, TheBlob42, Trey, bepolymathe, doolio, fleimgruber, iSeeU, - jixiuf, okamsn, pRot0ta1p. + Kévin Le Gouguec, Kostadin Ninev, Madhavan Krishnan, Markus Beppler, + Matthew Stevenson, Mauro Aranda, Nicolas De Jaeghere, Philip + Kaludercic, Rudolf Adamkovič, Stephen Gildea, Shreyas Ragavan, Stefan + Kangas, Vincent Murphy, Xinglu Chen. + ++ Ideas and user feedback :: Aaron Jensen, Adam Porter, Adam Spiers, + Adrian Manea, Alex Griffin, Alex Peitsinis, Alexey Shmalko, Alok + Singh, Anders Johansson, André Alexandre Gomes, Arif Rezai, Basil + L.{{{space()}}} Contovounesios, Burgess Chang, Christian Tietze, Christopher + Dimech, Damien Cassou, Daniel Mendler, Dario Gjorgjevski, David + Edmondson, Davor Rotim, Divan Santana, Eliraz Kedmi, Emanuele Michele + Alberto Monterosso, Farasha Euker, Feng Shu, Gautier Ponsinet, Gerry + Agbobada, Gianluca Recchia, Gustavo Barros, Hörmetjan Yiltiz, Ilja + Kocken, Iris Garcia, Jeremy Friesen, Jerry Zhang, John Haman, Joshua + O'Connor, Kevin Fleming, Kévin Le Gouguec, Kostadin Ninev, Len Trigg, + Manuel Uberti, Mark Burton, Markus Beppler, Mauro Aranda, Michael + Goldenberg, Morgan Smith, Murilo Pereira, Nicky van Foreest, Nicolas + De Jaeghere, Paul Poloskov, Pengji Zhang, Pete Kazmier, Peter Wu, + Philip Kaludercic, Pierre Téchoueyres, Roman Rudakov, Ryan Phillips, + Rudolf Adamkovič, Sam Kleinman, Shreyas Ragavan, Simon Pugnet, Tassilo + Horn, Thibaut Verron, Thomas Heartman, Trey Merkley, Togan Muftuoglu, + Toon Claes, Uri Sharf, Utkarsh Singh, Vincent Foley. As well as + users: Ben, CsBigDataHub1, Emacs Contrib, Eugene, Fourchaux, Fredrik, + Moesasji, Nick, TheBlob42, Trey, bepolymathe, doolio, fleimgruber, + iSeeU, jixiuf, okamsn, pRot0ta1p. + Packaging :: Basil L.{{{space()}}} Contovounesios, Eli Zaretskii, Glenn Morris, Mauro Aranda, Richard Stallman, Stefan Kangas (core Emacs), @@ -4178,6 +4384,7 @@ of this sort): + [[https://protesilaos.com/codelog/2020-12-27-modus-themes-review-rainbow-delimiters/][Modus themes: review rainbow-delimiters faces]] (2020-12-27) + [[https://protesilaos.com/codelog/2021-01-11-modus-themes-review-select-faint-colours/][Modus themes: review of select "faint" colours]] (2021-01-11) + [[https://protesilaos.com/codelog/2021-02-25-modus-themes-diffs-deuteranopia/][The Modus themes now cover deuteranopia in diffs]] (2021-02-25) ++ [[https://protesilaos.com/codelog/2021-06-02-modus-themes-org-agenda/][Introducing the variable modus-themes-org-agenda]] (2021-06-02) And here are the canonical sources of this project's documentation: diff --git a/doc/misc/org.org b/doc/misc/org.org index f072b5e00e0..17fd2dc39f7 100644 --- a/doc/misc/org.org +++ b/doc/misc/org.org @@ -82,11 +82,8 @@ probably do not need to install it. Most users will simply activate Org and begin exploring its many features. If, for one reason or another, you want to install Org on top of this -pre-packaged version, there are three ways to do it: - -- by using the Emacs package system; -- by downloading Org as an archive; or -- by using Org's git repository. +pre-packaged version, you can use the Emacs package system or clone +Org's git repository. We *strongly recommend* sticking to a single installation method. @@ -106,32 +103,6 @@ visited, i.e., where no Org built-in function have been loaded. Otherwise autoload Org functions will mess up the installation. #+end_quote -If you want to use Org's package repository, check out the [[https://orgmode.org/elpa.html][Org ELPA -page]]. - -*** Downloading Org as an archive -:PROPERTIES: -:UNNUMBERED: notoc -:END: - -You can download Org latest release from [[https://orgmode.org/][Org's website]]. In this case, -make sure you set the load path correctly in your Emacs init file: - -#+begin_src emacs-lisp -(add-to-list 'load-path "~/path/to/orgdir/lisp") -#+end_src - -The downloaded archive contains contributed libraries that are not -included in Emacs. If you want to use them, add the =contrib/= -directory to your load path: - -#+begin_src emacs-lisp -(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t) -#+end_src - -Optionally, you can compile the files and/or install them in your -system. Run =make help= to list compilation and installation options. - *** Using Org's git repository :PROPERTIES: :UNNUMBERED: notoc @@ -141,7 +112,7 @@ You can clone Org's repository and install Org like this: #+begin_example $ cd ~/src/ -$ git clone https://code.orgmode.org/bzg/org-mode.git +$ git clone https://git.savannah.gnu.org/git/emacs/org-mode.git $ cd org-mode/ $ make autoloads #+end_example @@ -161,6 +132,16 @@ list of compilation/installation options. For more detailed explanations on Org's build system, please check the Org Build System page on [[https://orgmode.org/worg/dev/org-build-system.html][Worg]]. +*** Installing Org's contributed packages +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Org's repository used to contain =contrib/= directory for add-ons +contributed by others. As of Org 9.5, the directory has bee moved to +this new dedicated [[https://git.sr.ht/~bzg/org-contrib][org-contrib]] repository, which you can install +separately. + ** Activation :PROPERTIES: :DESCRIPTION: How to activate Org for certain buffers. @@ -189,9 +170,9 @@ to globally available keys, like the ones reserved for users (see please modify the keys to your own liking. #+begin_src emacs-lisp -(global-set-key (kbd "C-c l") 'org-store-link) -(global-set-key (kbd "C-c a") 'org-agenda) -(global-set-key (kbd "C-c c") 'org-capture) +(global-set-key (kbd "C-c l") #'org-store-link) +(global-set-key (kbd "C-c a") #'org-agenda) +(global-set-key (kbd "C-c c") #'org-capture) #+end_src #+cindex: Org mode, turning on @@ -273,7 +254,6 @@ shown below. ;; Add latest Org mode to load path. (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp")) -(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t)) #+end_src If an error occurs, a "backtrace" can be very useful---see below on @@ -344,7 +324,7 @@ conventions: - =boss=, =ARCHIVE= :: - Tags are case-sensitive. User-defined tags are written in + Tags are case-sensitive. User-defined tags are usually written in lowercase; built-in tags with special meaning are written as they should appear in the document, usually with all capitals. @@ -577,6 +557,10 @@ buffer: ,#+STARTUP: overview ,#+STARTUP: content ,#+STARTUP: showall +,#+STARTUP: show2levels +,#+STARTUP: show3levels +,#+STARTUP: show4levels +,#+STARTUP: show5levels ,#+STARTUP: showeverything #+end_example @@ -656,10 +640,10 @@ The following commands jump to other headlines in the buffer. where you can use the following keys to find your destination: #+attr_texinfo: :columns 0.3 0.7 - | {{{kbd(TAB)}}} | Cycle visibility. | + | {{{kbd(TAB)}}} | Cycle visibility. | | {{{kbd(DOWN)}}} / {{{kbd(UP)}}} | Next/previous visible headline. | - | {{{kbd(RET)}}} | Select this location. | - | {{{kbd(/)}}} | Do a Sparse-tree search | + | {{{kbd(RET)}}} | Select this location. | + | {{{kbd(/)}}} | Do a Sparse-tree search | #+texinfo: @noindent The following keys work if you turn off ~org-goto-auto-isearch~ @@ -667,9 +651,9 @@ The following commands jump to other headlines in the buffer. #+attr_texinfo: :columns 0.3 0.7 | {{{kbd(n)}}} / {{{kbd(p)}}} | Next/previous visible headline. | | {{{kbd(f)}}} / {{{kbd(b)}}} | Next/previous headline same level. | - | {{{kbd(u)}}} | One level up. | + | {{{kbd(u)}}} | One level up. | | {{{kbd(0)}}} ... {{{kbd(9)}}} | Digit argument. | - | {{{kbd(q)}}} | Quit. | + | {{{kbd(q)}}} | Quit. | #+vindex: org-goto-interface #+texinfo: @noindent @@ -932,16 +916,16 @@ commands can be accessed through a dispatcher: #+kindex: C-c / / #+findex: org-occur #+vindex: org-remove-highlights-with-change - Prompts for a regexp and shows a sparse tree with all matches. If - the match is in a headline, the headline is made visible. If the - match is in the body of an entry, headline and body are made - visible. In order to provide minimal context, also the full - hierarchy of headlines above the match is shown, as well as the - headline following the match. Each match is also highlighted; the - highlights disappear when the buffer is changed by an editing - command, or by pressing {{{kbd(C-c C-c)}}}[fn:8]. When called with - a {{{kbd(C-u)}}} prefix argument, previous highlights are kept, so - several calls to this command can be stacked. + Prompts for a regexp (see [[*Regular Expressions]]) and shows a sparse + tree with all matches. If the match is in a headline, the headline + is made visible. If the match is in the body of an entry, headline + and body are made visible. In order to provide minimal context, + also the full hierarchy of headlines above the match is shown, as + well as the headline following the match. Each match is also + highlighted; the highlights disappear when the buffer is changed by + an editing command, or by pressing {{{kbd(C-c C-c)}}}[fn:8]. When + called with a {{{kbd(C-u)}}} prefix argument, previous highlights + are kept, so several calls to this command can be stacked. - {{{kbd(M-g n)}}} or {{{kbd(M-g M-n)}}} (~next-error~) :: @@ -1371,9 +1355,8 @@ you, configure the option ~org-table-auto-blank-field~. Re-align the table, move to the next field. Creates a new row if necessary. -- {{{kbd(C-c SPC)}}} (~org-table-blank-field~) :: +- {{{kbd(M-x org-table-blank-field)}}} :: - #+kindex: C-c SPC #+findex: org-table-blank-field Blank the field at point. @@ -1805,7 +1788,7 @@ mode with {{{kbd(M-x orgtbl-mode)}}}. To turn it on by default, for example in Message mode, use #+begin_src emacs-lisp -(add-hook 'message-mode-hook 'turn-on-orgtbl) +(add-hook 'message-mode-hook #'turn-on-orgtbl) #+end_src Furthermore, with some special setup, it is possible to maintain @@ -2074,6 +2057,14 @@ variable ~org-calc-default-modes~. Fraction and symbolic modes of Calc. +- =u= :: + + Units simplification mode of Calc. Calc is also a symbolic + calculator and is capable of working with values having a unit, + represented with numerals followed by a unit string in Org table + cells. This mode instructs Calc to simplify the units in the + computed expression before returning the result. + - =T=, =t=, =U= :: Duration computations in Calc or Lisp, [[*Durations and time values]]. @@ -2169,38 +2160,54 @@ It is also possible to write a formula in Emacs Lisp. This can be useful for string manipulation and control structures, if Calc's functionality is not enough. -If a formula starts with a single-quote followed by an opening -parenthesis, then it is evaluated as a Lisp form. The evaluation -should return either a string or a number. Just as with Calc -formulas, you can specify modes and a ~printf~ format after -a semicolon. +A formula is evaluated as a Lisp form when it starts with a +single-quote followed by an opening parenthesis. Cell table +references are interpolated into the Lisp form before execution. The +evaluation should return either a string or a number. Evaluation +modes and a ~printf~ format used to render the returned values can be +specified after a semicolon. + +By default, references are interpolated as literal Lisp strings: the +field content is replaced in the Lisp form stripped of leading and +trailing white space and surrounded in double-quotes. For example: -With Emacs Lisp forms, you need to be conscious about the way field -references are interpolated into the form. By default, a reference is -interpolated as a Lisp string (in double-quotes) containing the field. -If you provide the =N= mode switch, all referenced elements are -numbers---non-number fields will be zero---and interpolated as Lisp -numbers, without quotes. If you provide the =L= flag, all fields are -interpolated literally, without quotes. For example, if you want a -reference to be interpreted as a string by the Lisp form, enclose the -reference operator itself in double-quotes, like ="$3"=. Ranges are -inserted as space-separated fields, so you can embed them in list or -vector syntax. +: '(concat $1 $2) -Here are a few examples---note how the =N= mode is used when we do -computations in Lisp: +#+texinfo: @noindent +concatenates the content of columns 1 and column 2. -- ='(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))= :: +When the =N= flag is used, all referenced elements are parsed as +numbers and interpolated as Lisp numbers, without quotes. Fields that +cannot be parsed as numbers are interpolated as zeros. For example: - Swap the first two characters of the content of column 1. +: '(+ $1 $2);N -- ='(+ $1 $2);N= :: +#+texinfo: @noindent +adds columns 1 and 2, equivalent to Calc's =$1+$2=. Ranges are +inserted as space-separated fields, so they can be embedded in list or +vector syntax. For example: - Add columns 1 and 2, equivalent to Calc's =$1+$2=. +: '(apply '+ '($1..$4));N -- ='(apply '+ '($1..$4));N= :: +#+texinfo: @noindent +computes the sum of columns 1 to 4, like Calc's =vsum($1..$4)=. + +When the =L= flag is used, all fields are interpolated literally: the +cell content is replaced in the Lisp form stripped of leading and +trailing white space and without quotes. If a reference is intended +to be interpreted as a string by the Lisp form, the reference operator +itself should be enclosed in double-quotes, like ="$3"=. The =L= flag +is useful when strings and numbers are used in the same Lisp form. For +example: - Compute the sum of columns 1 to 4, like Calc's =vsum($1..$4)=. +: '(substring "$1" $2 $3);L + +#+texinfo: @noindent +extracts the part of the string in column 1 between the character +positions specified in the integers in column 2 and 3 and it is easier +to read than the equivalent: + +: '(substring $1 (string-to-number $2) (string-to-number $3)) *** Durations and time values :PROPERTIES: @@ -2797,7 +2804,7 @@ either graphically or in ASCII art. #+cindex: @samp{PLOT}, keyword Org Plot can produce 2D and 3D graphs of information stored in Org -tables using [[http://www.gnuplot.info/][Gnuplot]] and [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][Gnuplot mode]]. To see this in action, ensure +tables using [[https://www.gnuplot.info/][Gnuplot]] and [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][Gnuplot mode]]. To see this in action, ensure that you have both Gnuplot and Gnuplot mode installed on your system, then call {{{kbd(C-c \quot g)}}} or {{{kbd(M-x org-plot/gnuplot)}}} on the following table. @@ -2813,6 +2820,19 @@ following table. | Morelia | 257.56 | 17.67 | #+end_example +Org Plot supports a range of plot types, and provides the ability to add more. +For example, a radar plot can be generated like so: +#+begin_example +,#+PLOT: title:"An evaluation of plaintext document formats" transpose:yes type:radar min:0 max:4 +| Format | Fine-grained-control | Initial Effort | Syntax simplicity | Editor Support | Integrations | Ease-of-referencing | Versatility | +|-------------------+----------------------+----------------+-------------------+----------------+--------------+---------------------+-------------| +| Word | 2 | 4 | 4 | 2 | 3 | 2 | 2 | +| LaTeX | 4 | 1 | 1 | 3 | 2 | 4 | 3 | +| Org Mode | 4 | 2 | 3.5 | 1 | 4 | 4 | 4 | +| Markdown | 1 | 3 | 3 | 4 | 3 | 3 | 1 | +| Markdown + Pandoc | 2.5 | 2.5 | 2.5 | 3 | 3 | 3 | 2 | +#+end_example + Notice that Org Plot is smart enough to apply the table's headers as labels. Further control over the labels, type, content, and appearance of plots can be exercised through the =PLOT= keyword @@ -2843,9 +2863,15 @@ For more information and examples see the [[https://orgmode.org/worg/org-tutoria the third and fourth columns. Defaults to graphing all other columns aside from the =ind= column. +- transpose :: + + When =y=, =yes=, or =t= attempt to transpose the table data before + plotting. Also recognises the shorthand option =trans=. + - =type= :: - Specify whether the plot is =2d=, =3d=, or =grid=. + Specify the type of the plot, by default one of =2d=, =3d=, =radar=, or =grid=. + Available types can be customised with ~org-plot/preset-plot-types~. - =with= :: @@ -2872,6 +2898,27 @@ For more information and examples see the [[https://orgmode.org/worg/org-tutoria When plotting =3d= or =grid= types, set this to =t= to graph a flat mapping rather than a =3d= slope. +- min :: + + Provides a minimum axis value that may be used by a plot type. + Implicitly assumes the =y= axis is being referred to. Can + explicitly provide a value for a either the =x= or =y= axis with + =xmin= and =ymin=. + +- max :: + + Provides a maximum axis value that may be used by a plot type. + Implicitly assumes the =y= axis is being referred to. Can + explicitly provide a value for a either the =x= or =y= axis with + =xmax= and =ymax=. + +- ticks :: + + Provides a desired number of axis ticks to display, that may be used + by a plot type. If none is given a plot type that requires ticks + will use ~org--plot/sensible-tick-num~ to try to determine a good + value. + - =timefmt= :: Specify format of Org mode timestamps as they will be parsed by @@ -3113,14 +3160,14 @@ Here is the full set of built-in link types: - =file= :: - File links. File name may be remote, absolute, or relative. + File links. File name may be remote, absolute, or relative. - Additionally, you can specify a line number, or a text search. - In Org files, you may link to a headline name, a custom ID, or a - code reference instead. + Additionally, you can specify a line number, or a text search. + In Org files, you may link to a headline name, a custom ID, or a + code reference instead. - As a special case, "file" prefix may be omitted if the file name - is complete, e.g., it starts with =./=, or =/=. + As a special case, "file" prefix may be omitted if the file name + is complete, e.g., it starts with =./=, or =/=. - =attachment= :: @@ -3224,9 +3271,10 @@ options: #+cindex: VM links #+cindex: Wanderlust links On top of these built-in link types, additional ones are available -through the =contrib/= directory (see [[*Installation]]). For example, -these links to VM or Wanderlust messages are available when you load -the corresponding libraries from the =contrib/= directory: +through the =org-contrib= repository (see [[*Installation]]). For +example, these links to VM or Wanderlust messages are available when +you load the corresponding libraries from the =org-contrib= +repository: | =vm:folder= | VM folder link | | =vm:folder#id= | VM message link | @@ -3291,8 +3339,9 @@ current buffer: =ID= property for the link[fn:29]. So using this command in Org buffers potentially creates two links: a human-readable link from the custom ID, and one that is globally unique and works even if the - entry is moved from file to file. Later, when inserting the link, - you need to decide which one to use. + entry is moved from file to file. The =ID= property can be either a + UUID (default) or a timestamp, depending on ~org-id-method~. Later, + when inserting the link, you need to decide which one to use. - /Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus/ :: @@ -3474,8 +3523,8 @@ generally, act on links. #+begin_src emacs-lisp (with-eval-after-load 'org - (define-key org-mode-map (kbd "M-n") 'org-next-link) - (define-key org-mode-map (kbd "M-p") 'org-previous-link)) + (define-key org-mode-map (kbd "M-n") #'org-next-link) + (define-key org-mode-map (kbd "M-p") #'org-previous-link)) #+end_src ** Using Links Outside Org @@ -3516,7 +3565,7 @@ replacement text. Here is an example: #+begin_src emacs-lisp (setq org-link-abbrev-alist '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") - ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h") + ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h") ("duckduckgo" . "https://duckduckgo.com/?q=%s") ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1") ("ads" . "https://ui.adsabs.harvard.edu/search/q=%20author%3A\"%s\""))) @@ -3616,10 +3665,10 @@ link, together with explanations for each: - =/REGEXP/= :: - Do a regular expression search for {{{var(REGEXP)}}}. This uses the - Emacs command ~occur~ to list all matches in a separate window. If - the target file is in Org mode, ~org-occur~ is used to create - a sparse tree with the matches. + Do a regular expression search for {{{var(REGEXP)}}} (see [[*Regular + Expressions]]). This uses the Emacs command ~occur~ to list all + matches in a separate window. If the target file is in Org mode, + ~org-occur~ is used to create a sparse tree with the matches. As a degenerate case, a file link with an empty file name can be used to search the current file. For example, =[[file:::find me]]= does @@ -3944,9 +3993,9 @@ interpretation, but it means the same as =#+TODO=, or A setup for using several sets in parallel would be: #+begin_example -,#+TODO: TODO | DONE -,#+TODO: REPORT BUG KNOWNCAUSE | FIXED -,#+TODO: | CANCELED +,#+TODO: TODO(t) | DONE(d) +,#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) +,#+TODO: | CANCELED(c) #+end_example #+cindex: completion, of option keywords @@ -4070,7 +4119,7 @@ checkboxes is blocked from switching to DONE. If you need more complex dependency structures, for example dependencies between entries in different trees or files, check out -the contributed module =org-depend.el=. +the module =org-depend.el= in the =org-contrib= repository. ** Progress Logging :PROPERTIES: @@ -4158,10 +4207,6 @@ example, with the setting '((sequence "TODO(t)" "WAIT(w@/!)" "|" "DONE(d!)" "CANCELED(c@)"))) #+end_src -#+texinfo: @noindent -To record a timestamp without a note for TODO keywords configured with -=@=, just type {{{kbd(C-c C-c)}}} to enter a blank note when prompted. - #+vindex: org-log-done You not only define global TODO keywords and fast access keys, but also request that a time is recorded when the entry is set to =DONE=, @@ -4181,6 +4226,9 @@ to a buffer: : #+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@) +To record a timestamp without a note for TODO keywords configured with +=@=, just type {{{kbd(C-c C-c)}}} to enter a blank note when prompted. + #+cindex: @samp{LOGGING}, property In order to define logging settings that are local to a subtree or a single item, define a =LOGGING= property in this entry. Any @@ -4443,7 +4491,7 @@ all children are done, you can use the following setup: (let (org-log-done org-log-states) ; turn off logging (org-todo (if (= n-not-done 0) "DONE" "TODO")))) -(add-hook 'org-after-todo-statistics-hook 'org-summary-todo) +(add-hook 'org-after-todo-statistics-hook #'org-summary-todo) #+end_src Another possibility is the use of checkboxes to identify (a hierarchy @@ -4794,9 +4842,10 @@ In this interface, you can also use the following special keys: #+kindex: TAB Enter a tag in the minibuffer, even if the tag is not in the - predefined list. You can complete on all tags present in the - buffer. You can also add several tags: just separate them with - a comma. + predefined list. You can complete on all tags present in the buffer + and globally pre-defined tags from ~org-tag-alist~ and + ~org-tag-persistent-alist~. You can also add several tags: just + separate them with a comma. - {{{kbd(SPC)}}} :: @@ -4931,8 +4980,9 @@ mutually exclusive. Furthermore, the members of a group tag can also be regular expressions, creating the possibility of a more dynamic and rule-based -tag structure. The regular expressions in the group must be specified -within curly brackets. Here is an expanded example: +tag structure (see [[*Regular Expressions]]). The regular expressions in +the group must be specified within curly brackets. Here is an +expanded example: #+begin_example ,#+TAGS: [ Vision : {V@.+} ] @@ -5274,7 +5324,7 @@ single property: tree is created with all entries that define this property with the given value. If you enclose the value in curly braces, it is interpreted as a regular expression and matched against the property - values. + values (see [[*Regular Expressions]]). ** Property Inheritance :PROPERTIES: @@ -5737,8 +5787,8 @@ block. If there is a =TBLFM= keyword after the table, the table is recalculated automatically after an update. An alternative way to capture and process property values into a table -is provided by Eric Schulte's =org-collector.el=, which is -a contributed package[fn:58]. It provides a general API to collect +is provided by Eric Schulte's =org-collector.el=, which is a package +in =org-contrib=[fn:58]. It provides a general API to collect properties from entries in a certain scope, and arbitrary Lisp expressions to process these values before inserting them into a table or a dynamic block. @@ -6022,6 +6072,7 @@ dash(es) as the separator in the former case and use =+= as the separator in the latter case, e.g.: | =11am-1:15pm= | \rArr{} 11:00-13:15 | +| =11h-13h15= | \rArr{} same as above | | =11am--1:15pm= | \rArr{} same as above | | =11am+2:15= | \rArr{} same as above | @@ -7197,6 +7248,16 @@ special command: Copying works like refiling, except that the original note is not deleted. +- {{{kbd(C-c C-M-w)}}} (~org-refile-reverse~) :: + + #+kindex: C-c C-M-w + #+findex: org-refile-reverse + Works like refiling, except that it temporarily toggles how the + value of ~org-reverse-note-order~ applies to the current buffer. So + if ~org-refile~ would append the entry as the last entry under the + target header, ~org-refile-reverse~ will prepend it as the first + entry, and vice-versa. + ** Archiving :PROPERTIES: :DESCRIPTION: What to do with finished products. @@ -7746,6 +7807,9 @@ Now lets look at the elements of a template definition. Each entry in Do not save the target file after finishing the capture. + - ~:refile-targets :: Temporarily set ~org-refile-targets~ to the + value of this property. + **** Template expansion :PROPERTIES: :DESCRIPTION: Filling in information about time and context. @@ -7804,6 +7868,10 @@ here: Like =%a=, but only insert the literal link. +- =%L= :: + + Like =%l=, but without brackets (the link content itself). + - =%c= :: Current kill ring head. @@ -7859,7 +7927,8 @@ here: - =%^{PROP}p= :: - Prompt the user for a value for property {{{var(PROP)}}}. + Prompt the user for a value for property {{{var(PROP)}}}. You may + specify a default value with =%^{PROP|default}=. - =%^{PROMPT}= :: @@ -7912,7 +7981,7 @@ patches. Then you would configure this option like this: #+begin_src emacs-lisp (setq org-capture-templates-contexts - '(("p" (in-mode . "message-mode")))) + '(("p" ((in-mode . "message-mode"))))) #+end_src You can also tell that the command key {{{kbd(p)}}} should refer to @@ -7920,7 +7989,7 @@ another template. In that case, add this command key like this: #+begin_src emacs-lisp (setq org-capture-templates-contexts - '(("p" "q" (in-mode . "message-mode")))) + '(("p" "q" ((in-mode . "message-mode"))))) #+end_src See the docstring of the variable for more information. @@ -8199,7 +8268,7 @@ To make Org mode take care of versioning of attachments for you, add the following to your Emacs config: #+begin_src emacs-lisp - (require 'org-attach-git) +(require 'org-attach-git) #+end_src *** Attach from Dired @@ -8259,7 +8328,7 @@ variable has detailed information. With the following #+begin_src emacs-lisp (setq org-feed-alist '(("Slashdot" - "http://rss.slashdot.org/Slashdot/slashdot" + "https://rss.slashdot.org/Slashdot/slashdot" "~/txt/org/feeds.org" "Slashdot Entries"))) #+end_src @@ -8847,8 +8916,9 @@ only tags. #+cindex: regular expressions, with tags search Instead of a tag, you may also specify a regular expression enclosed -in curly braces. For example, =work+{^boss.*}= matches headlines that -contain the tag =:work:= and any tag /starting/ with =boss=. +in curly braces (see [[*Regular Expressions]]). For example, +=work+{^boss.*}= matches headlines that contain the tag =:work:= and +any tag /starting/ with =boss=. #+cindex: group tags, as regular expressions Group tags (see [[*Tag Hierarchy]]) are expanded as regular expressions. @@ -8888,7 +8958,7 @@ to test the value of a property. Here is a complex example: #+begin_example +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 - +With={Sarah|Denny}+SCHEDULED>="<2008-10-11>" + +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>" #+end_example #+texinfo: @noindent @@ -8918,7 +8988,7 @@ So the search string in the example finds entries tagged =work= but not =boss=, which also have a priority value =A=, a =Coffee= property with the value =unlimited=, an =EFFORT= property that is numerically smaller than 2, a =With= property that is matched by the regular -expression =Sarah|Denny=, and that are scheduled on or after October +expression =Sarah\|Denny=, and that are scheduled on or after October 11, 2008. You can configure Org mode to use property inheritance during @@ -9296,16 +9366,16 @@ filter elements are accumulated. selects entries with category =work= and effort estimates below 10 minutes, and deselects entries with tag =John= or matching the - regexp =plot=. You can leave =+= out if that does not lead to - ambiguities. The sequence of elements is arbitrary. The filter - syntax assumes that there is no overlap between categories and tags. - Otherwise, tags take priority. If you reply to the prompt with the - empty string, all filtering is removed. If a filter is specified, - it replaces all current filters. But if you call the command with - a double prefix argument, or if you add an additional =+= (e.g., - =++work=) to the front of the string, the new filter elements are - added to the active ones. A single prefix argument applies the - entire filter in a negative sense. + regexp =plot= (see [[*Regular Expressions]]). You can leave =+= out if + that does not lead to ambiguities. The sequence of elements is + arbitrary. The filter syntax assumes that there is no overlap + between categories and tags. Otherwise, tags take priority. If you + reply to the prompt with the empty string, all filtering is removed. + If a filter is specified, it replaces all current filters. But if + you call the command with a double prefix argument, or if you add an + additional =+= (e.g., =++work=) to the front of the string, the new + filter elements are added to the active ones. A single prefix + argument applies the entire filter in a negative sense. - {{{kbd(|)}}} (~org-agenda-filter-remove-all~) :: @@ -10863,7 +10933,7 @@ pretty output for a number of export back-ends. Org mode can contain LaTeX math fragments, and it supports ways to process these for several export back-ends. When exporting to LaTeX, the code is left as it is. When exporting to HTML, Org can use either -[[http://www.mathjax.org][MathJax]] (see [[*Math formatting in HTML export]]) or transcode the math +[[https://www.mathjax.org][MathJax]] (see [[*Math formatting in HTML export]]) or transcode the math into images (see [[*Previewing LaTeX fragments]]). LaTeX fragments do not need any special marking at all. The following @@ -10968,7 +11038,7 @@ current buffer with {{{kbd(M-x org-cdlatex-mode)}}}, or for all Org files with #+begin_src emacs-lisp -(add-hook 'org-mode-hook 'turn-on-org-cdlatex) +(add-hook 'org-mode-hook #'turn-on-org-cdlatex) #+end_src When this mode is enabled, the following features are present (for @@ -11304,7 +11374,7 @@ The following command handles footnotes: #+attr_texinfo: :columns 0.1 0.9 | {{{kbd(s)}}} | Sort the footnote definitions by reference sequence. | | {{{kbd(r)}}} | Renumber the simple =fn:N= footnotes. | - | {{{kbd(S)}}} | Short for first {{{kbd(r)}}}, then {{{kbd(s)}}} action. | + | {{{kbd(S)}}} | Short for first {{{kbd(r)}}}, then {{{kbd(s)}}} action. | | {{{kbd(n)}}} | Rename all footnotes into a =fn:1= ... =fn:n= sequence. | | {{{kbd(d)}}} | Delete the footnote at point, including definition and references. | @@ -11361,7 +11431,7 @@ Users can install libraries for additional formats from the Emacs packaging system. For easy discovery, these packages have a common naming scheme: ~ox-NAME~, where {{{var(NAME)}}} is a format. For example, ~ox-koma-letter~ for /koma-letter/ back-end. More libraries -can be found in the =contrib/= directory (see [[*Installation]]). +can be found in the =org-contrib= repository (see [[*Installation]]). #+vindex: org-export-backends Org only loads back-ends for the following formats by default: ASCII, @@ -11452,7 +11522,7 @@ further alter what is exported, and how. Toggle visible-only export. This is useful for exporting only certain parts of an Org document by adjusting the visibility of - particular headings. + particular headings. See also [[*Sparse Trees]]. ** Export Settings :PROPERTIES: @@ -11961,7 +12031,7 @@ example #+texinfo: @noindent becomes -: Rose is red, violet's blue. Life's ordered: Org assists you. +: Rose is red, violet's blue. Life's ordered: Org assists you. As a special case, Org parses any replacement text starting with =(eval= as an Emacs Lisp expression and evaluates it accordingly. @@ -12527,7 +12597,7 @@ compatible with XHTML 1.0 strict standard. #+findex: org-html-export-to-html Export as HTML file with a =.html= extension. For =myfile.org=, Org - exports to =myfile.html=, overwriting without warning. {{{kbd{C-c + exports to =myfile.html=, overwriting without warning. {{{kbd(C-c C-e h o)}}} exports to HTML and opens it in a web browser. - {{{kbd(C-c C-e h H)}}} (~org-html-export-as-html~) :: @@ -12552,6 +12622,9 @@ settings described in [[*Export Settings]]. multiple =DESCRIPTION= lines. The exporter takes care of wrapping the lines properly. + The exporter includes a number of other meta tags, which can be customized + by modifying ~org-html-meta-tags~. + - =HTML_DOCTYPE= :: #+cindex: @samp{HTML_DOCTYPE}, keyword @@ -12693,8 +12766,8 @@ exports to: #+begin_src html <video controls="controls" width="350"> <source src="movie.mp4" type="video/mp4"> - <source src="movie.ogg" type="video/ogg"> - <p>Your browser does not support the video tag.</p> + <source src="movie.ogg" type="video/ogg"> + <p>Your browser does not support the video tag.</p> </video> #+end_src @@ -12925,7 +12998,7 @@ as-is. #+vindex: org-html-mathjax-options~ LaTeX math snippets (see [[*LaTeX fragments]]) can be displayed in two -different ways on HTML pages. The default is to use the [[http://www.mathjax.org][MathJax]], +different ways on HTML pages. The default is to use the [[https://www.mathjax.org][MathJax]], which should work out of the box with Org[fn:129][fn:130]. Some MathJax display options can be configured via ~org-html-mathjax-options~, or in the buffer. For example, with the following settings, @@ -13621,7 +13694,7 @@ placement. #+cindex: image, centering in LaTeX export The LaTeX export back-end centers all images by default. Setting =:center= to =nil= disables centering. To disable centering globally, -set ~org-latex-images-centered~ to =t=. +set ~org-latex-images-centered~ to =nil=. Set the =:comment-include= attribute to non-~nil~ value for the LaTeX export back-end to comment out the =\includegraphics= macro. @@ -13698,7 +13771,7 @@ objects through the attributes =:float= and =:options=. For =:float=: The LaTeX export back-end passes string values in =:options= to LaTeX packages for customization of that specific source block. In the example below, the =:options= are set for Minted. Minted is a source -code highlighting LaTeX package with many configurable options. +code highlighting LaTeX package with many configurable options[fn:134]. #+begin_example ,#+ATTR_LATEX: :options commentstyle=\bfseries @@ -13801,6 +13874,95 @@ The LaTeX export back-end converts horizontal rules by the specified ----- #+end_example +*** Verse blocks in LaTeX export +:PROPERTIES: +:DESCRIPTION: Attributes specific to special blocks. +:END: + +#+cindex: verse blocks, in @LaTeX{} export +#+cindex: @samp{ATTR_LATEX}, keyword + +The LaTeX export back-end accepts four attributes for verse blocks: +=:lines=, =:center=, =:versewidth= and =:latexcode=. The three first +require the external LaTeX package =verse.sty=, which is an extension +of the standard LaTeX environment. + +- =:lines= :: To add marginal verse numbering. Its value is an + integer, the sequence in which the verses should be numbered. +- =:center= :: With value =t= all the verses on the page are optically + centered (a typographic convention for poetry), taking as a + reference the longest verse, which must be indicated by the + attribute =:versewidth=. +- =:versewidth= :: Its value is a literal text string with the longest + verse. +- =:latexcode= :: It accepts any arbitrary LaTeX code that can be + included within a LaTeX =verse= environment. + +A complete example with Shakespeare's first sonnet: + +#+begin_src org +,#+ATTR_LATEX: :center t :latexcode \color{red} :lines 5 +,#+ATTR_LATEX: :versewidth Feed’st thy light’s flame with self-substantial fuel, +,#+BEGIN_VERSE +From fairest creatures we desire increase, +That thereby beauty’s rose might never die, +But as the riper should by time decease +His tender heir might bear his memory +But thou, contracted to thine own bright eyes, +Feed’st thy light’s flame with self-substantial fuel, +Making a famine where abundance lies, +Thyself thy foe, to thy sweet self too cruel. +Thou that art now the world’s fresh ornament, +And only herald to the gaudy spring, +Within thine own bud buriest thy content, +And, tender churl, mak’st waste in niggardly. +Pity the world, or else this glutton be, +To eat the world’s due, by the grave and thee. +,#+END_VERSE +#+end_src + +*** Quote blocks in LaTeX export +:PROPERTIES: +:DESCRIPTION: Attributes specific to quote blocks. +:END: + +#+cindex: quote blocks, in @LaTeX{} export +#+cindex: @samp{ATTR_LATEX}, keyword +#+cindex: org-latex-default-quote-environment + +The LaTeX export back-end accepts two attributes for quote blocks: +=:environment=, for an arbitrary quoting environment (the default +value is that of ~org-latex-default-quote-environment~: ~"quote"~) and +=:options=. For example, to choose the environment =quotation=, +included as an alternative to =quote= in standard LaTeX classes: + +#+begin_example +,#+ATTR_LATEX: :environment quotation +,#+BEGIN_QUOTE +some text... +,#+END_QUOTE +#+end_example + +To choose the =foreigndisplayquote= environment, included in the LaTeX +package =csquotes=, with the =german= option, use this syntax: + +#+begin_example +,#+LATEX_HEADER:\usepackage[autostyle=true]{csquotes} +,#+ATTR_LATEX: :environment foreigndisplayquote :options {german} +,#+BEGIN_QUOTE +some text in German... +,#+END_QUOTE +#+end_example + +#+texinfo: @noindent +which is exported to LaTeX as + +#+begin_example +\begin{foreigndisplayquote}{german} +some text in German... +\end{foreigndisplayquote} +#+end_example + ** Markdown Export :PROPERTIES: :DESCRIPTION: Exporting to Markdown. @@ -13860,7 +14022,7 @@ a limit to a level before the absolute limit (see [[*Export Settings]]). The ODT export back-end handles creating of OpenDocument Text (ODT) format. Documents created by this exporter use the -{{{cite(OpenDocument-v1.2 specification)}}}[fn:134] and are compatible +{{{cite(OpenDocument-v1.2 specification)}}}[fn:135] and are compatible with LibreOffice 3.4. *** Pre-requisites for ODT export @@ -14261,7 +14423,7 @@ document in one of the following ways: variables ~org-latex-to-mathml-convert-command~ and ~org-latex-to-mathml-jar-file~. - If you prefer to use MathToWeb[fn:135] as your converter, you can + If you prefer to use MathToWeb[fn:136] as your converter, you can configure the above variables as shown below. #+begin_src emacs-lisp @@ -14272,7 +14434,7 @@ document in one of the following ways: #+end_src #+texinfo: @noindent - or, to use LaTeXML[fn:136] instead, + or, to use LaTeXML[fn:137] instead, #+begin_src emacs-lisp (setq org-latex-to-mathml-convert-command @@ -14591,7 +14753,7 @@ with the =#+ATTR_ODT= line. For a discussion on default formatting of tables, see [[*Tables in ODT export]]. This feature closely mimics the way table templates are defined in the -OpenDocument-v1.2 specification[fn:137]. +OpenDocument-v1.2 specification[fn:138]. #+vindex: org-odt-table-styles For quick preview of this feature, install the settings below and export the @@ -14625,7 +14787,7 @@ templates, define new styles there. To use this feature proceed as follows: -1. Create a table template[fn:138]. +1. Create a table template[fn:139]. A table template is set of =table-cell= and =paragraph= styles for each of the following table cell categories: @@ -14664,7 +14826,7 @@ To use this feature proceed as follows: =</office:automatic-styles>= element of the content template file (see [[x-orgodtcontenttemplate-xml][Factory styles]]). -2. Define a table style[fn:139]. +2. Define a table style[fn:140]. #+vindex: org-odt-table-styles To define a table style, create an entry for the style in the @@ -15159,7 +15321,7 @@ To specify the author of the quotation, use the =:author= attribute. ,#+BEGIN_QUOTE The Lady of the Lake, her arm clad in the purest shimmering samite, held aloft Excalibur from the bosom of the water, signifying by divine -providence that I, Arthur, was to carry Excalibur. That is why I am +providence that I, Arthur, was to carry Excalibur. That is why I am your king. ,#+END_QUOTE #+end_example @@ -15422,7 +15584,7 @@ BACKEND is the export back-end being used, as a symbol." (org-map-entries (lambda () (delete-region (point) (line-beginning-position 2))))) -(add-hook 'org-export-before-parsing-hook 'my-headline-removal) +(add-hook 'org-export-before-parsing-hook #'my-headline-removal) #+end_src *** Filters @@ -15768,17 +15930,17 @@ following properties Publishing means that a file is copied to the destination directory and possibly transformed in the process. The default transformation is to export Org files as HTML files, and this is done by the function -~org-publish-org-to-html~ which calls the HTML exporter (see [[*HTML +~org-html-publish-to-html~ which calls the HTML exporter (see [[*HTML Export]]). But you can also publish your content as PDF files using -~org-publish-org-to-pdf~, or as ASCII, Texinfo, etc., using the +~org-latex-publish-to-pdf~, or as ASCII, Texinfo, etc., using the corresponding functions. If you want to publish the Org file as an =.org= file but with /archived/, /commented/, and /tag-excluded/ trees removed, use -~org-publish-org-to-org~. This produces =file.org= and put it in the +~org-org-publish-to-org~. This produces =file.org= and puts it in the publishing directory. If you want a htmlized version of this file, set the parameter ~:htmlized-source~ to ~t~. It produces -=file.org.html= in the publishing directory[fn:140]. +=file.org.html= in the publishing directory[fn:141]. Other files like images only need to be copied to the publishing destination; for this you can use ~org-publish-attachment~. For @@ -16247,12 +16409,13 @@ directory on the local machine. (setq org-publish-project-alist '(("org" :base-directory "~/org/" + :publishing-function org-html-publish-to-html :publishing-directory "~/public_html" :section-numbers nil - :table-of-contents nil - :style "<link rel=\"stylesheet\" - href=\"../other/mystyle.css\" - type=\"text/css\"/>"))) + :with-toc nil + :html-head "<link rel=\"stylesheet\" + href=\"../other/mystyle.css\" + type=\"text/css\"/>"))) #+end_src *** Example: complex publishing configuration @@ -16347,6 +16510,127 @@ of the commands above, or by customizing the variable particular if files include other files via =SETUPFILE= or =INCLUDE= keywords. +* Citation handling +:PROPERTIES: +:DESCRIPTION: create, follow and export citations. +:END: +#+cindex: citation + +The =oc.el= library provides tooling to handle citations in Org via +"citation processors" that offer some or all of the following +capabilities: + +- activate :: Fontification, tooltip preview, etc. +- follow :: At-point actions on citations via ~org-open-at-point~. +- insert :: Add and edit citations via ~org-cite-insert~. +- export :: Via different libraries for different target formats. + +The user can configure these with ~org-cite-activate-processor~, +~org-cite-follow-processor~, ~org-cite-insert-processor~, and +~org-cite-export-processors~ respectively. + +The included "basic" processor provides all four capabilities. + +** Citations + +Before adding citations, first set one-or-more bibliographies, either +globally with ~org-cite-global-bibliography~, or locally using one or +more "bibliography" keywords. + +#+begin_example +#+bibliography: SomeFile.bib +#+bibliography: /some/other/file.json +#+bibliography: "/some/file/with spaces/in its name.bib" +#+end_example + +#+kindex: C-c C-x @@ +#+findex: org-cite-insert +One can then insert and edit citations using ~org-cite-insert~, called +with {{{kbd(C-c C-x @)}}}. + +A /citation/ requires one or more citation /key(s)/, elements +identifying a reference in the bibliography. + +- Each citation is surrounded by brackets and uses the =cite= type. + +- Each key starts with the character =@=. + +- Each key can be qualified by a /prefix/ (e.g.\nbsp{}"see ") and/or + a /suffix/ (e.g.\nbsp{}"p.\nbsp{}123"), giving informations useful or necessary + fo the comprehension of the citation but not included in the + reference. + +- A single citation can cite more than one reference ; the keys are + separated by semicolons ; the formatting of such citation groups is + specified by the style. + +- One can also specify a stylistic variation for the citations by + inserting a =/= and a style name between the =cite= keyword and the + colon; this usually makes sense only for the author-year styles. + +: [cite/style:common prefix ;prefix @key suffix; ... ; common suffix] + +The only mandatory elements are: + +- The =cite= keyword and the colon. +- The =@= character immediately preceding each key. +- The brackets surrounding the citation(s) (group). + +** Citation export processors + +Org currently includes the following export processors: + +- Two processors can export to a variety of formats, including =latex= + (and therefore =pdf=), =html=, =odt= and plain (UTF8) text: + + - basic :: a basic export processor, well adapted to situations + where backward compatibility is not a requirement and formatting + needs are minimal; + + - csl :: this export processor uses format files written in [[https://en.wikipedia.org/wiki/Citation_Style_Language][Citation + Style Language]] via [[https://github.com/andras-simonyi/citeproc-el][citeproc-el]]; + +- In contrast, two other processors target LaTeX and LaTeX-derived + formats exclusively: + + - natbib :: this export processor uses BibTeX, the historical + bibliographic processor used with LaTeX, thus allowing the use of + data and style files compatible with this processor (including + a large number of publishers' styles). It uses citation commands + implemented in the LaTeX package =natbib=, allowing more stylistic + variants that LaTeX's =\cite= command. + + - biblatex :: this backend allows the use of data and formats + prepared for BibLaTeX, an alternate bibliographic processor used + with LaTeX, which overcomes some serious BibTeX limitations, but + has not (yet?)\nbsp{}been widely adopted by publishers. + +The =CITE_EXPORT= keyword specifies the export processor and the +citation (and possibly reference) style(s); for example (all arguments +are optional) + +: #+cite_export: basic author author-year + +#+texinfo: @noindent +specifies the "basic" export processor with citations inserted as +author's name and references indexed by author's names and year; + +: #+cite_export: csl /some/path/to/vancouver-brackets.csl + +#+texinfo: @noindent +specifies the "csl" processor and CSL style, which in this case +defines numeric citations and numeric references according to the +=Vancouver= specification (as style used in many medical journals), +following a typesetting variation putting citations between brackets; + +: #+cite_export: natbib kluwer + +#+texinfo: @noindent +specifies the =natbib= export processor with a label citation style +conformant to the Harvard style and the specification of the +Wolkers-Kluwer publisher; since it relies on the ~bibtex~ processor of +your LaTeX installation, it won't export to anything but PDF. + * Working with Source Code :PROPERTIES: :DESCRIPTION: Export, evaluate, and tangle code blocks. @@ -16393,7 +16677,7 @@ extract, export, and publish source code blocks. Org can also compile and execute a source code block, then capture the results. The Org mode literature sometimes refers to source code blocks as /live code/ blocks because they can alter the content of the Org document or the -material that it exports. Users can control how live they want each +material that it exports. Users can control the "liveliness" of each source code block by tweaking the header arguments (see [[*Using Header Arguments]]) for compiling, execution, extraction, and exporting. @@ -16736,7 +17020,11 @@ the =var= header argument. body. {{{var(ASSIGN)}}} is a literal value, such as a string, a number, a reference to a table, a list, a literal example, another code block---with or without arguments---or the results of evaluating -a code block. +a code block. {{{var(ASSIGN)}}} may specify a filename for references +to elements in a different file, using a =:= to separate the filename +from the reference. + +: :var NAME=FILE:REFERENCE Here are examples of passing values by reference: @@ -16815,6 +17103,9 @@ Here are examples of passing values by reference: | two | 16 | 17 | 18 | 19 | 20 | #+end_example +To refer to a table in another file, join the filename and table name with +a colon, for example: =:var table=other-file.org:example-table=. + - list :: A simple named list. @@ -17156,13 +17447,13 @@ See [[*Languages]] to enable other languages. #+kindex: C-c C-v e #+findex: org-babel-execute-src-block Org provides many ways to execute code blocks. {{{kbd(C-c C-c)}}} or -{{{kbd(C-c C-v e)}}} with the point on a code block[fn:141] calls the +{{{kbd(C-c C-v e)}}} with the point on a code block[fn:142] calls the ~org-babel-execute-src-block~ function, which executes the code in the block, collects the results, and inserts them in the buffer. #+cindex: @samp{CALL}, keyword #+vindex: org-babel-inline-result-wrap -By calling a named code block[fn:142] from an Org mode buffer or +By calling a named code block[fn:143] from an Org mode buffer or a table. Org can call the named code blocks from the current Org mode buffer or from the "Library of Babel" (see [[*Library of Babel]]). @@ -17363,7 +17654,7 @@ they are mutually exclusive. - =value= :: - Default for most Babel libraries[fn:142]. Functional mode. Org + Default for most Babel libraries[fn:143]. Functional mode. Org gets the value by wrapping the code in a function definition in the language of the source block. That is why when using =:results value=, code should execute like a function and return a value. For @@ -17488,10 +17779,12 @@ default behavior is to automatically determine the result type. #+end_example #+cindex: @samp{file-desc}, header argument - The =file-desc= header argument defines the description (see - [[*Link Format]]) for the link. If =file-desc= is present but has no value, + The =file-desc= header argument defines the description (see [[*Link + Format]]) for the link. If =file-desc= is present but has no value, the =file= value is used as the link description. When this - argument is not present, the description is omitted. + argument is not present, the description is omitted. If you want to + provide the =file-desc= argument but omit the description, you can + provide it with an empty vector (i.e., :file-desc []). #+cindex: @samp{sep}, header argument By default, Org assumes that a table written to a file has @@ -17549,7 +17842,7 @@ follows from the type specified above. #+begin_example ,#+begin_src shell :results file link :file "download.tar.gz" - wget -c "http://example.com/download.tar.gz" + wget -c "https://example.com/download.tar.gz" ,#+end_src #+end_example @@ -17595,15 +17888,20 @@ value listed above. E.g., Handling options after collecting the results. +- =replace= :: + + Default. Insert results in the Org buffer. Remove previous + results. Usage example: =:results output replace=. + - =silent= :: Do not insert results in the Org mode buffer, but echo them in the minibuffer. Usage example: =:results output silent=. -- =replace= :: +- =none= :: - Default. Insert results in the Org buffer. Remove previous - results. Usage example: =:results output replace=. + Do not process results at all. No inserting in the Org mode buffer + nor echo them in the minibuffer. Usage example: =:results none=. - =append= :: @@ -17929,35 +18227,8 @@ code block header arguments: #+cindex: source code, languages #+cindex: code block, languages -Code blocks in the following languages are supported. - -#+attr_texinfo: :columns 0.25 0.25 0.25 0.20 -| Language | Identifier | Language | Identifier | -|------------+---------------+----------------+--------------| -| Asymptote | =asymptote= | Lisp | =lisp= | -| Awk | =awk= | Lua | =lua= | -| C | =C= | MATLAB | =matlab= | -| C++ | =C++=[fn:143] | Mscgen | =mscgen= | -| Clojure | =clojure= | Objective Caml | =ocaml= | -| CSS | =css= | Octave | =octave= | -| D | =D=[fn:144] | Org mode | =org= | -| ditaa | =ditaa= | Oz | =oz= | -| Emacs Calc | =calc= | Perl | =perl= | -| Emacs Lisp | =emacs-lisp= | Plantuml | =plantuml= | -| Eshell | =eshell= | Processing.js | =processing= | -| Fortran | =fortran= | Python | =python= | -| Gnuplot | =gnuplot= | R | =R= | -| GNU Screen | =screen= | Ruby | =ruby= | -| Graphviz | =dot= | Sass | =sass= | -| Haskell | =haskell= | Scheme | =scheme= | -| Java | =java= | Sed | =sed= | -| Javascript | =js= | shell | =sh= | -| LaTeX | =latex= | SQL | =sql= | -| Ledger | =ledger= | SQLite | =sqlite= | -| Lilypond | =lilypond= | Vala | =vala= | - -Additional documentation for some languages is at -https://orgmode.org/worg/org-contrib/babel/languages.html. +Code blocks in dozens of languages are supported. See Worg for +[[https://orgmode.org/worg/org-contrib/babel/languages/index.html][language specific documentation]]. #+vindex: org-babel-load-languages By default, only Emacs Lisp is enabled for evaluation. To enable or @@ -18071,7 +18342,7 @@ for Python and Emacs Lisp languages. #+cindex: @samp{noweb-ref}, header argument Source code blocks can include references to other source code blocks, -using a noweb[fn:145] style syntax: +using a noweb[fn:144] style syntax: : <<CODE-BLOCK-ID>> @@ -18582,14 +18853,14 @@ Org Tempo expands snippets to structures defined in ~org-structure-template-alist~ and ~org-tempo-keywords-alist~. For example, {{{kbd(< s TAB)}}} creates a code block. Enable it by customizing ~org-modules~ or add =(require 'org-tempo)= to your Emacs -init file[fn:146]. +init file[fn:145]. #+attr_texinfo: :columns 0.1 0.9 | {{{kbd(a)}}} | =#+BEGIN_EXPORT ascii= ... =#+END_EXPORT= | | {{{kbd(c)}}} | =#+BEGIN_CENTER= ... =#+END_CENTER= | | {{{kbd(C)}}} | =#+BEGIN_COMMENT= ... =#+END_COMMENT= | | {{{kbd(e)}}} | =#+BEGIN_EXAMPLE= ... =#+END_EXAMPLE= | -| {{{kbd(E)}}} | =#+BEGIN_EXPORT= ... =#+END_EXPORT= | +| {{{kbd(E)}}} | =#+BEGIN_EXPORT= ... =#+END_EXPORT= | | {{{kbd(h)}}} | =#+BEGIN_EXPORT html= ... =#+END_EXPORT= | | {{{kbd(l)}}} | =#+BEGIN_EXPORT latex= ... =#+END_EXPORT= | | {{{kbd(q)}}} | =#+BEGIN_QUOTE= ... =#+END_QUOTE= | @@ -18616,14 +18887,14 @@ the variable ~org-use-speed-commands~ to a non-~nil~ value. To trigger a Speed Key, point must be at the beginning of an Org headline, before any of the stars. -#+vindex: org-speed-commands-user +#+vindex: org-speed-commands #+findex: org-speed-command-help Org comes with a pre-defined list of Speed Keys. To add or modify -Speed Keys, customize the variable, ~org-speed-commands-user~. For -more details, see the variable's docstring. With Speed Keys -activated, {{{kbd(M-x org-speed-command-help)}}}, or {{{kbd(?)}}} when -point is at the beginning of an Org headline, shows currently active -Speed Keys, including the user-defined ones. +Speed Keys, customize the option ~org-speed-commands~. For more +details, see the variable's docstring. With Speed Keys activated, +{{{kbd(M-x org-speed-command-help)}}}, or {{{kbd(?)}}} when point is at the +beginning of an Org headline, shows currently active Speed Keys, +including the user-defined ones. ** A Cleaner Outline View :PROPERTIES: @@ -18662,7 +18933,7 @@ in the desired amount with hard spaces and hiding leading stars. To display the buffer in the indented view, activate Org Indent minor mode, using {{{kbd(M-x org-indent-mode)}}}. Text lines that are not headlines are prefixed with virtual spaces to vertically align with -the headline text[fn:147]. +the headline text[fn:146]. #+vindex: org-indent-indentation-per-level To make more horizontal space, the headlines are shifted by two @@ -18690,15 +18961,15 @@ use =STARTUP= keyword as follows: It is possible to use hard spaces to achieve the indentation instead, if the bare ASCII file should have the indented look also outside -Emacs[fn:148]. With Org's support, you have to indent all lines to +Emacs[fn:147]. With Org's support, you have to indent all lines to line up with the outline headers. You would use these -settings[fn:149]: +settings[fn:148]: - #+begin_src emacs-lisp - (setq org-adapt-indentation t - org-hide-leading-stars t - org-odd-levels-only t) - #+end_src +#+begin_src emacs-lisp +(setq org-adapt-indentation t + org-hide-leading-stars t + org-odd-levels-only t) +#+end_src - /Indentation of text below headlines/ (~org-adapt-indentation~) :: @@ -18955,11 +19226,15 @@ changes. | =overview= | Top-level headlines only. | | =content= | All headlines. | | =showall= | No folding on any entry. | + | =show2levels= | Headline levels 1-2. | + | =show3levels= | Headline levels 1-3. | + | =show4levels= | Headline levels 1-4. | + | =show5levels= | Headline levels 1-5. | | =showeverything= | Show even drawer contents. | #+vindex: org-startup-indented Dynamic virtual indentation is controlled by the variable - ~org-startup-indented~[fn:150]. + ~org-startup-indented~[fn:149]. | =indent= | Start with Org Indent mode turned on. | | =noindent= | Start with Org Indent mode turned off. | @@ -19095,6 +19370,22 @@ changes. These lines set the TODO keywords and their interpretation in the current file. The corresponding variable is ~org-todo-keywords~. +** Regular Expressions +:PROPERTIES: +:DESCRIPTION: Elisp regular expressions. +:END: +#+cindex: regular expressions syntax +#+cindex: regular expressions, in searches + +Org, as an Emacs mode, makes use of Elisp regular expressions for +searching, matching and filtering. Elisp regular expressions have a +somewhat different syntax then some common standards. Most notably, +alternation is indicated using =\|= and matching groups are denoted by +=\(...\)=. For example the string =home\|work= matches either =home= +or =work=. + +For more information, see [[info:emacs::Regexps][Regular Expressions in Emacs]]. + ** Org Syntax :PROPERTIES: :DESCRIPTION: Formal description of Org's syntax. @@ -19533,7 +19824,7 @@ passed to Emacs through the =emacsclient= command, so you also need to ensure an Emacs server is running. More precisely, when the application calls -: emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2 +: emacsclient "org-protocol://PROTOCOL?key1=val1&key2=val2" #+texinfo: @noindent Emacs calls the handler associated to {{{var(PROTOCOL)}}} with @@ -19556,7 +19847,7 @@ Using the ~store-link~ handler, you can copy links, to that they can be inserted using {{{kbd(M-x org-insert-link)}}} or yanking. More precisely, the command -: emacsclient org-protocol://store-link?url=URL&title=TITLE +: emacsclient "org-protocol://store-link?url=URL&title=TITLE" #+texinfo: @noindent stores the following link: @@ -19571,10 +19862,19 @@ To use this feature from a browser, add a bookmark with an arbitrary name, e.g., =Org: store-link= and enter this as /Location/: #+begin_example +javascript:location.href='org-protocol://store-link?' + + new URLSearchParams({url:location.href, title:document.title}); +#+end_example + +Title is an optional parameter. Another expression was recommended earlier: + +#+begin_example javascript:location.href='org-protocol://store-link?url='+ encodeURIComponent(location.href); #+end_example +The latter form is compatible with older Org versions from 9.0 to 9.4. + *** The ~capture~ protocol :PROPERTIES: :DESCRIPTION: Fill a buffer with external information. @@ -19585,18 +19885,31 @@ javascript:location.href='org-protocol://store-link?url='+ Activating the "capture" handler pops up a =Capture= buffer in Emacs, using acapture template. -: emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY +: emacsclient "org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY" To use this feature, add a bookmark with an arbitrary name, e.g., =Org: capture=, and enter this as =Location=: #+begin_example +javascript:location.href='org-protocol://capture?' + + new URLSearchParams({ + template: 'x', url: window.location.href, + title: document.title, body: window.getSelection()}); +#+end_example + +You might have seen another expression: + +#+begin_example javascript:location.href='org-protocol://capture?template=x'+ '&url='+encodeURIComponent(window.location.href)+ '&title='+encodeURIComponent(document.title)+ '&body='+encodeURIComponent(window.getSelection()); #+end_example +It is a bit more cluttered than the former one, but it is compatible +with previous Org versions 9.0-9.4. In these versions encoding of +space as "+" character was not supported by URI decoder. + #+vindex: org-protocol-default-template-key The capture template to be used can be specified in the bookmark (like =X= above). If unspecified, the template key is set in the variable @@ -19652,13 +19965,13 @@ click the bookmark and start editing. #+cindex: rewritten URL in open-source protocol #+cindex: protocol, open-source rewritten URL However, such mapping may not always yield the desired results. -Suppose you maintain an online store located at =http://example.com/=. +Suppose you maintain an online store located at =https://example.com/=. The local sources reside in =/home/user/example/=. It is common practice to serve all products in such a store through one file and rewrite URLs that do not match an existing file on the server. That -way, a request to =http://example.com/print/posters.html= might be +way, a request to =https://example.com/print/posters.html= might be rewritten on the server to something like -=http://example.com/shop/products.php/posters.html.php=. The +=https://example.com/shop/products.php/posters.html.php=. The ~open-source~ handler probably cannot find a file named =/home/user/example/print/posters.html.php= and fails. @@ -19673,7 +19986,7 @@ adding ~:rewrites~ rules like this: #+begin_src emacs-lisp (setq org-protocol-project-alist '(("example.com" - :base-url "http://example.com/" + :base-url "https://example.com/" :working-directory "/home/user/example/" :online-suffix ".php" :working-suffix ".php" @@ -19704,8 +20017,8 @@ an Org file that is part of a publishing project. :END: Org Crypt encrypts the text of an entry, but not the headline, or -properties. Behind the scene, it uses the Emacs EasyPG library to -encrypt and decrypt files. +properties. Behind the scene, it uses the [[info:epa][Emacs EasyPG Library]] to +encrypt and decrypt files, and EasyPG needs a correct [[info:gnupg][GnuPG]] setup. #+vindex: org-crypt-tag-matcher Any text below a headline that has a =crypt= tag is automatically @@ -19778,7 +20091,7 @@ Tags]]) only for those set in these variables. #+vindex: org-mobile-directory The mobile application needs access to a file directory on -a server[fn:151] to interact with Emacs. Pass its location through +a server[fn:150] to interact with Emacs. Pass its location through the ~org-mobile-directory~ variable. If you can mount that directory locally just set the variable to point to that directory: @@ -19799,7 +20112,7 @@ With a public server, consider encrypting the files. Org also requires OpenSSL installed on the local computer. To turn on encryption, set the same password in the mobile application and in Emacs. Set the password in the variable -~org-mobile-use-encryption~[fn:152]. Note that even after the mobile +~org-mobile-use-encryption~[fn:151]. Note that even after the mobile application encrypts the file contents, the file name remains visible on the file systems of the local computer, the server, and the mobile device. @@ -19815,15 +20128,15 @@ The command ~org-mobile-push~ copies files listed in ~org-mobile-files~ into the staging area. Files include agenda files (as listed in ~org-agenda-files~). Customize ~org-mobile-files~ to add other files. File names are staged with paths relative to -~org-directory~, so all files should be inside this directory[fn:153]. +~org-directory~, so all files should be inside this directory[fn:152]. Push creates a special Org file =agendas.org= with custom agenda views -defined by the user[fn:154]. +defined by the user[fn:153]. Finally, Org writes the file =index.org=, containing links to other files. The mobile application reads this file first from the server to determine what other files to download for agendas. For faster -downloads, it is expected to only read files whose checksums[fn:155] +downloads, it is expected to only read files whose checksums[fn:154] have changed. *** Pulling from the mobile application @@ -19840,7 +20153,7 @@ data in an inbox file format, through the following steps: 1. #+vindex: org-mobile-inbox-for-pull - Org moves all entries found in =mobileorg.org=[fn:156] and appends + Org moves all entries found in =mobileorg.org=[fn:155] and appends them to the file pointed to by the variable ~org-mobile-inbox-for-pull~. It should reside neither in the staging area nor on the server. Each captured entry and each @@ -19904,12 +20217,10 @@ https://orgmode.org/worg/doc.html#hooks. :END: #+cindex: add-on packages -Various authors wrote a large number of add-on packages for Org. - -These packages are not part of Emacs, but they are distributed as -contributed packages with the separate release available at -https://orgmode.org. See the =contrib/README= file in the source code -directory for a list of contributed files. Worg page with more +Various authors wrote a large number of add-on packages for Org. Some +of these packages used to be part of the =org-mode= repository but are +now hosted in a separate =org-contrib= repository +[[https://git.sr.ht/~bzg/org-contrib][here]]. A Worg page with more information is at: https://orgmode.org/worg/org-contrib/. ** Adding Hyperlink Types @@ -20136,9 +20447,9 @@ of these strategies: #+cindex: @LaTeX{}, and Orgtbl mode To wrap a source table in LaTeX, use the =comment= environment -provided by =comment.sty=[fn:157]. To activate it, put +provided by =comment.sty=[fn:156]. To activate it, put ~\usepackage{comment}~ in the document header. Orgtbl mode inserts -a radio table skeleton[fn:158] with the command {{{kbd(M-x +a radio table skeleton[fn:157] with the command {{{kbd(M-x orgtbl-insert-radio-table)}}}, which prompts for a table name. For example, if =salesfigures= is the name, the template inserts: @@ -20157,7 +20468,7 @@ The line =#+ORGTBL: SEND= tells Orgtbl mode to use the function ~orgtbl-to-latex~ to convert the table to LaTeX format, then insert the table at the target (receive) location named =salesfigures=. Now the table is ready for data entry. It can even use spreadsheet -features[fn:159]: +features[fn:158]: #+begin_example % BEGIN RECEIVE ORGTBL salesfigures @@ -20373,7 +20684,7 @@ Dynamic blocks, like any other block, can be narrowed with #+vindex: org-agenda-skip-function #+vindex: org-agenda-skip-function-global Org provides a special hook to further limit items in agenda views: -~agenda~, ~agenda*~[fn:160], ~todo~, ~alltodo~, ~tags~, ~tags-todo~, +~agenda~, ~agenda*~[fn:159], ~todo~, ~alltodo~, ~tags~, ~tags-todo~, ~tags-tree~. Specify a custom function that tests inclusion of every matched item in the view. This function can also skip as much as is needed. @@ -20416,7 +20727,7 @@ meaningful string suitable for the agenda view. #+vindex: org-agenda-skip-function Search for entries with a limit set on levels for the custom search. This is a general approach to creating custom searches in Org. To -include all levels, use =LEVEL>0=[fn:161]. Then to selectively pick +include all levels, use =LEVEL>0=[fn:160]. Then to selectively pick the matched entries, use ~org-agenda-skip-function~, which also accepts Lisp forms, such as ~org-agenda-skip-entry-if~ and ~org-agenda-skip-subtree-if~. For example: @@ -21017,6 +21328,9 @@ be complete if the ones above were not mentioned in this manual. - Charles Cave's suggestion sparked the implementation of templates for Remember, which are now templates for capture. +- Timothy E Chapman worked on a complete overhaul of the orgmode.org + website in 2020 and helped fixing various bugs. + - Pavel Chalmoviansky influenced the agenda treatment of items with specified time. @@ -21106,6 +21420,9 @@ be complete if the ones above were not mentioned in this manual. - Jason\nbsp{}F.\nbsp{}McBrayer suggested agenda export to CSV format. +- Kyle Meyer helped setting up the [[https://public-inbox.org/][public-inbox]] archive of the [[https://orgmode.org/list/][Org + mailing list]] and has been fixing many bugs. + - Max Mikhanosha came up with the idea of refiling. - Dmitri Minaev sent a patch to set priority limits on a per-file @@ -21143,6 +21460,9 @@ be complete if the ones above were not mentioned in this manual. - Martin Pohlack provided the code snippet to bundle character insertion into bundles of 20 for undo. +- Ihor Radchenko helped with fixing bugs and improving the user + experience regarding Org's speed. + - T.\nbsp{}V.\nbsp{}Raman reported bugs and suggested improvements. - Matthias Rempe (Oelde) provided ideas, Windows support, and quality @@ -21173,7 +21493,7 @@ be complete if the ones above were not mentioned in this manual. literal examples, and remote highlighting for referenced code lines. - Stathis Sideris wrote the =ditaa.jar= ASCII to PNG converter that is - now packaged into Org's =contrib/= directory. + now packaged into the [[https://git.sr.ht/~bzg/org-contrib][org-contrib]] repository. - Daniel Sinder came up with the idea of internal archiving by locking subtrees. @@ -21296,7 +21616,7 @@ modify this GNU manual." * Footnotes [fn:1] If you do not use Font Lock globally turn it on in Org buffer -with =(add-hook 'org-mode-hook 'turn-on-font-lock)=. +with =(add-hook 'org-mode-hook #'turn-on-font-lock)=. [fn:2] Please consider subscribing to the mailing list in order to minimize the work the mailing list moderators have to do. @@ -21597,12 +21917,12 @@ lognoteclock-out=. line---the line is broken here only to fit it into the manual. [fn:81] On computers using macOS, idleness is based on actual user -idleness, not just Emacs' idle time. For X11, you can install -a utility program =x11idle.c=, available in the =contrib/scripts/= -directory of the Org Git distribution, or install the xprintidle -package and set it to the variable ~org-clock-x11idle-program-name~ if -you are running Debian, to get the same general treatment of idleness. -On other systems, idle time refers to Emacs idle time only. +idleness, not just Emacs' idle time. For X11, you can install a +utility program =x11idle.c=, available in the =org-contrib/= +repository, or install the xprintidle package and set it to the +variable ~org-clock-x11idle-program-name~ if you are running Debian, +to get the same general treatment of idleness. On other systems, idle +time refers to Emacs idle time only. [fn:82] Please note the pitfalls of summing hierarchical data in a flat list (see [[*Using Column View in the Agenda]]). @@ -21733,7 +22053,7 @@ a fragment, see the documentation of the function version 1.34 of the =htmlize.el= package, which you need to install). Fontified code chunks in LaTeX can be achieved using either the [[https://www.ctan.org/pkg/listings][listings]] package or the [[https://www.ctan.org/pkg/minted][minted]] package. Refer to -~org-export-latex-listings~ for details. +~org-latex-listings~ for details. [fn:115] Source code in code blocks may also be evaluated either interactively or on export. See [[*Working with Source Code]] for more @@ -21762,7 +22082,9 @@ and =#+STARTUP: nofnadjust=. [fn:122] The variable ~org-export-date-timestamp-format~ defines how this timestamp are exported. -[fn:123] DEFINITION NOT FOUND. +[fn:123] For export to LaTeX format---or LaTeX-related formats such as +Beamer---, the =org-latex-package-alist= variable needs further +configuration. See [[LaTeX specific export settings]]. [fn:124] At the moment, some export back-ends do not obey this specification. For example, LaTeX export excludes every unnumbered @@ -21785,7 +22107,7 @@ to make it visible. The tag serves as a visual aid and has no semantic relevance. [fn:129] By default Org loads MathJax from [[https://cdnjs.com][cdnjs.com]] as recommended by -[[http://www.mathjax.org][MathJax]]. +[[https://www.mathjax.org][MathJax]]. [fn:130] Please note that exported formulas are part of an HTML document, and that signs such as =<=, =>=, or =&= have special @@ -21802,93 +22124,89 @@ use the variables ~org-html-todo-kwd-class-prefix~ and for different files. However, "smart" LaTeX compilation systems, such as latexmk, can select the correct bibliography compiler. -[fn:134] See [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][Open Document Format for Office Applications +[fn:134] Minted uses an external Python package for code highlighting, +which requires the flag =-shell-escape= to be added to +~org-latex-pdf-process~. + +[fn:135] See [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][Open Document Format for Office Applications (OpenDocument) Version 1.2]]. -[fn:135] See [[http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl][MathToWeb]]. +[fn:136] See [[http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl][MathToWeb]]. -[fn:136] See [[http://dlmf.nist.gov/LaTeXML/]]. +[fn:137] See [[http://dlmf.nist.gov/LaTeXML/]]. -[fn:137] [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][OpenDocument-v1.2 Specification]] +[fn:138] [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][OpenDocument-v1.2 Specification]] -[fn:138] See the =<table:table-template>= element of the +[fn:139] See the =<table:table-template>= element of the OpenDocument-v1.2 specification. -[fn:139] See the attributes =table:template-name=, +[fn:140] See the attributes =table:template-name=, =table:use-first-row-styles=, =table:use-last-row-styles=, =table:use-first-column-styles=, =table:use-last-column-styles=, =table:use-banding-rows-styles=, and =table:use-banding-column-styles= of the =<table:table>= element in the OpenDocument-v1.2 specification. -[fn:140] If the publishing directory is the same as the source +[fn:141] If the publishing directory is the same as the source directory, =file.org= is exported as =file.org.org=, so you probably do not want to do this. -[fn:141] The option ~org-babel-no-eval-on-ctrl-c-ctrl-c~ can be used +[fn:142] The option ~org-babel-no-eval-on-ctrl-c-ctrl-c~ can be used to remove code evaluation from the {{{kbd(C-c C-c)}}} key binding. -[fn:142] Actually, the constructs =call_<name>()= and =src_<lang>{}= +[fn:143] Actually, the constructs =call_<name>()= and =src_<lang>{}= are not evaluated when they appear in a keyword (see [[*Summary of In-Buffer Settings]]). -[fn:143] C++ language is handled in =ob-C.el=. Even though the -identifier for such source blocks is =C++=, you activate it by loading -the C language. - -[fn:144] D language is handled in =ob-C.el=. Even though the -identifier for such source blocks is =D=, you activate it by loading -the C language. - -[fn:145] For noweb literate programming details, see +[fn:144] For noweb literate programming details, see http://www.cs.tufts.edu/~nr/noweb/. -[fn:146] For more information, please refer to the commentary section +[fn:145] For more information, please refer to the commentary section in =org-tempo.el=. -[fn:147] Org Indent mode also sets ~wrap-prefix~ correctly for +[fn:146] Org Indent mode also sets ~wrap-prefix~ correctly for indenting and wrapping long lines of headlines or text. This minor mode also handles Visual Line mode and directly applied settings through ~word-wrap~. -[fn:148] This works, but requires extra effort. Org Indent mode is +[fn:147] This works, but requires extra effort. Org Indent mode is more convenient for most applications. -[fn:149] ~org-adapt-indentation~ can also be set to ='headline-data=, +[fn:148] ~org-adapt-indentation~ can also be set to ='headline-data=, in which case only data lines below the headline will be indented. -[fn:150] Note that Org Indent mode also sets the ~wrap-prefix~ +[fn:149] Note that Org Indent mode also sets the ~wrap-prefix~ property, such that Visual Line mode (or purely setting ~word-wrap~) wraps long lines, including headlines, correctly indented. -[fn:151] For a server to host files, consider using a WebDAV server, +[fn:150] For a server to host files, consider using a WebDAV server, such as [[https://nextcloud.com][Nextcloud]]. Additional help is at this [[https://orgmode.org/worg/org-faq.html#mobileorg_webdav][FAQ entry]]. -[fn:152] If Emacs is configured for safe storing of passwords, then +[fn:151] If Emacs is configured for safe storing of passwords, then configure the variable ~org-mobile-encryption-password~; please read the docstring of that variable. -[fn:153] Symbolic links in ~org-directory~ need to have the same name +[fn:152] Symbolic links in ~org-directory~ need to have the same name as their targets. -[fn:154] While creating the agendas, Org mode forces =ID= properties +[fn:153] While creating the agendas, Org mode forces =ID= properties on all referenced entries, so that these entries can be uniquely identified if Org Mobile flags them for further action. To avoid setting properties configure the variable ~org-mobile-force-id-on-agenda-items~ to ~nil~. Org mode then relies on outline paths, assuming they are unique. -[fn:155] Checksums are stored automatically in the file +[fn:154] Checksums are stored automatically in the file =checksums.dat=. -[fn:156] The file will be empty after this operation. +[fn:155] The file will be empty after this operation. -[fn:157] https://www.ctan.org/pkg/comment +[fn:156] https://www.ctan.org/pkg/comment -[fn:158] By default this works only for LaTeX, HTML, and Texinfo. +[fn:157] By default this works only for LaTeX, HTML, and Texinfo. Configure the variable ~orgtbl-radio-table-templates~ to install templates for other modes. -[fn:159] If the =TBLFM= keyword contains an odd number of dollar +[fn:158] If the =TBLFM= keyword contains an odd number of dollar characters, this may cause problems with Font Lock in LaTeX mode. As shown in the example you can fix this by adding an extra line inside the =comment= environment that is used to balance the dollar @@ -21896,9 +22214,9 @@ expressions. If you are using AUCTeX with the font-latex library, a much better solution is to add the =comment= environment to the variable ~LaTeX-verbatim-environments~. -[fn:160] The ~agenda*~ view is the same as ~agenda~ except that it +[fn:159] The ~agenda*~ view is the same as ~agenda~ except that it only considers /appointments/, i.e., scheduled and deadline items that have a time specification =[h]h:mm= in their time-stamps. -[fn:161] Note that, for ~org-odd-levels-only~, a level number +[fn:160] Note that, for ~org-odd-levels-only~, a level number corresponds to order in the hierarchy, not to the number of stars. diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi index 82495275fca..e796da6da37 100644 --- a/doc/misc/pgg.texi +++ b/doc/misc/pgg.texi @@ -27,7 +27,8 @@ modify this GNU manual.'' @dircategory Emacs network features @direntry -* PGG: (pgg). Emacs interface to various PGP implementations. +* PGG: (pgg). An obsolete Emacs interface to various + PGP implementations. @end direntry @titlepage diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi index ae3a3b13e62..a4ca54a8b01 100644 --- a/doc/misc/rcirc.texi +++ b/doc/misc/rcirc.texi @@ -254,6 +254,10 @@ To make this permanent, add the following to your init file: Use @kbd{C-c C-@key{SPC}} to switch to these buffers. +@vindex rcirc-track-ignore-server-buffer-flag +If the user wishes to ignore events in the server buffer, set +@code{rcirc-track-ignore-server-buffer-flag} to a non-nil value. + @node Reference @chapter Reference @cindex reference @@ -426,7 +430,13 @@ lost. The simple solution is to use @kbd{M-x rcirc}. The problem is that this opens an @emph{additional} connection, so you'll have two copies of every channel buffer, one dead and one live. -The real answer, therefore, is the @code{/reconnect} command. +One option therefore, is the @code{/reconnect} command. + +An other approach is to set @code{rcirc-reconnect-delay} to a value +greater than 0, and allow rcirc to reconnect when it detects that the +connection has been closed. By default it will try to do this three +times (as specified by @code{rcirc-reconnect-attempts}), before giving +up. @end table @node Useful IRC commands @@ -671,6 +681,12 @@ window is showing them), the mode line will now show you the abbreviated channel or nick name. Use @kbd{C-c C-@key{SPC}} to switch to these buffers. +@cindex rcirc-track-abbrevate-flag +By default the channel names are abbreviated, set +@code{rcirc-track-abbrevate-flag} to a non-nil value. This might be +interesting if the IRC activities are not tracked in the mode line, +but somewhere else. + @vindex rcirc-mode-hook If you prefer not to load @code{rcirc} immediately, you can delay the activation of this mode: @@ -807,6 +823,19 @@ active and only omits a message if the nick has not been active. The window @code{rcirc} considers is controlled by the @code{rcirc-omit-threshold} variable. +@vindex rcirc-omit-unless-requested +Certain messages can be omitted by default, unless the user manual +requests them. For example, if you don't want to display @code{TOPIC} +and @code{NAMES} messages, after reconnecting, you can configure +@code{rcirc-omit-unless-requested} to hide: + +@example +(setq rcirc-omit-unless-requested '("TOPIC" "NAMES")) +@end example + +Now NAMES will only be displayed, after it has been requested via the +@code{rcirc-cmd-name} command. + @node Hacking and Tweaking @chapter Hacking and Tweaking @cindex hacking and tweaking @@ -819,6 +848,7 @@ Here are some examples of stuff you can do to configure @code{rcirc}. * Scrolling conservatively:: * Changing the time stamp format:: * Defining a new command:: +* Using rcirc with bouncers:: @end menu @node Skipping /away messages using handlers @@ -903,20 +933,48 @@ how to include the date in the time stamp: @cindex new commands, defining Here's a simple new command, @code{/sv}. With it, you can boast about -your IRC client. It shows how you can use @code{defun-rcirc-command} to +your IRC client. It shows how you can use @code{rcirc-define-command} to define new commands. +@findex rcirc-define-command We're waiting for the definition of this command until @code{rcirc} is loaded -because @code{defun-rcirc-command} is not yet available, and without +because @code{rcirc-define-command} is not yet available, and without @code{rcirc} loaded, the command wouldn't do us much good anyway. @smallexample (with-eval-after-load 'rcirc - (defun-rcirc-command sv (arg) + (rcirc-define-command sv () "Boast about rcirc." (interactive "i") - (rcirc-send-message process target - (concat "I use " rcirc-id-string)))) + (rcirc-send-message process target "I use " rcirc-id-string))) +@end smallexample + +@node Using rcirc with bouncers +@section Using rcirc with bouncers +@cindex bouncer + +Some bouncers multiplex connections to various servers, but have to +modify nicks and channel names to make this work. The channel +@code{#emacs} on @code{irc.libera.chat} becomes +@code{#emacs/irc.libera.chat}. + +@vindex rcirc-nick-filter +@vindex rcirc-channel-filter +The options @code{rcirc-nick-filter} and @code{rcirc-channel-filter} +can be used to make this feel more natural. When set to functions, +these will be used to change how nicks and channel names are +displayed. A simple configuration to fix the above example might be: + +@smallexample +(defun my/rcirc-remove-suffix (STR) + "Remove suffixes from STR." + (save-match-data + (if (string-match "/[[:alpha:]]+?\\'" str) + (substring str 0 (match-beginning 0)) + str))) + +(setq rcirc-nick-filter #'my/rcirc-remove-suffix + rcirc-channel-filter #'local/rcirc-soju-suffix) @end smallexample @node GNU Free Documentation License diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi index 88ca4450d59..8bde241e18f 100644 --- a/doc/misc/reftex.texi +++ b/doc/misc/reftex.texi @@ -658,9 +658,9 @@ variable @code{reftex-auto-recenter-toc}. @end table -@vindex reftex-toc-map +@vindex reftex-toc-mode-map In order to define additional commands for the @file{*toc*} buffer, the -keymap @code{reftex-toc-map} may be used. +keymap @code{reftex-toc-mode-map} may be used. @findex reftex-toc-recenter @vindex reftex-auto-recenter-toc @@ -1021,9 +1021,9 @@ document and let you select a label from there (@pxref{LaTeX xr Package,,xr}). @end table -@vindex reftex-select-label-map +@vindex reftex-select-label-mode-map In order to define additional commands for the selection process, the -keymap @code{reftex-select-label-map} may be used. +keymap @code{reftex-select-label-mode-map} may be used. @node Builtin Label Environments @section Builtin Label Environments @@ -1871,9 +1871,9 @@ entries. @end table -@vindex reftex-select-bib-map +@vindex reftex-select-bib-mode-map In order to define additional commands for this selection process, the -keymap @code{reftex-select-bib-map} may be used. +keymap @code{reftex-select-bib-mode-map} may be used. Note that if you do not use Emacs to edit the @BibTeX{} database files, @RefTeX{} will ask if the related buffers should be updated once it @@ -3192,7 +3192,7 @@ with the @kbd{g} key. To get this behavior, use instead @AUCTeX{} is without doubt the best major mode for editing @TeX{} and @LaTeX{} files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}). -You can get it from its home page at @value{AUCTEXSITE}, but since +You can get it from its website at @value{AUCTEXSITE}, but since it is available from GNU ELPA, you can simply install it from @kbd{M-x list-packages}. @@ -3565,7 +3565,7 @@ With @i{Viper} mode prior to Vipers version 3.01, you need to protect @cindex Acknowledgments @cindex Thanks @cindex Bug reports -@cindex @code{http}, @RefTeX{} home page +@cindex @code{http}, @RefTeX{} website @cindex @code{ftp}, @RefTeX{} site @c dominik@@science.uva.nl @@ -3960,7 +3960,7 @@ Normal hook which is run when a @file{*toc*} buffer is created. @end deffn -@deffn Keymap reftex-toc-map +@deffn Keymap reftex-toc-mode-map The keymap which is active in the @file{*toc*} buffer. (@pxref{Table of Contents}). @end deffn @@ -4425,7 +4425,7 @@ Normal hook which is run when a selection buffer enters @code{reftex-select-label-mode}. @end deffn -@deffn Keymap reftex-select-label-map +@deffn Keymap reftex-select-label-mode-map The keymap which is active in the labels selection process (@pxref{Referencing Labels}). @end deffn @@ -4586,7 +4586,7 @@ Normal hook which is run when a selection buffer enters @code{reftex-select-bib-mode}. @end deffn -@deffn Keymap reftex-select-bib-map +@deffn Keymap reftex-select-bib-mode-map The keymap which is active in the citation-key selection process (@pxref{Creating Citations}). @end deffn @@ -4792,7 +4792,7 @@ into blocks. Sorting will then preserve blocks, so that lines are re-arranged only within blocks. @end defopt -@defopt reftex-index-phrases-map +@defopt reftex-index-phrases-mode-map Keymap for the Index Phrases buffer. @end defopt @@ -4824,7 +4824,7 @@ the document. This flag can be toggled from within the @file{*Index*} buffer with the @kbd{f} key. @end defopt -@deffn Keymap reftex-index-map +@deffn Keymap reftex-index-mode-map The keymap which is active in the @file{*Index*} buffer (@pxref{Index Support}). @end deffn @@ -5813,8 +5813,8 @@ buffer). @noindent @b{Version 3.12} @itemize @bullet @item -There are 3 new keymaps for customization: @code{reftex-toc-map}, -@code{reftex-select-label-map}, @code{reftex-select-bib-map}. +There are 3 new keymaps for customization: @code{reftex-toc-mode-map}, +@code{reftex-select-label-mode-map}, @code{reftex-select-bib-mode-map}. @item Refontification uses more standard font-lock stuff. @item diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi index ca7dabe6545..f5d567533b6 100644 --- a/doc/misc/smtpmail.texi +++ b/doc/misc/smtpmail.texi @@ -264,12 +264,14 @@ file, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. @cindex CRAM-MD5 @cindex PLAIN @cindex LOGIN -The process by which the SMTP library authenticates you to the server -is known as ``Simple Authentication and Security Layer'' (SASL). -There are various SASL mechanisms, and this library supports three of -them: CRAM-MD5, PLAIN, and LOGIN, where the first uses a form of +The process by which the @acronym{SMTP} library authenticates you to +the server is known as ``Simple Authentication and Security Layer'' +(@acronym{SASL}). There are various @acronym{SASL} mechanisms, and +this library supports three of them: @code{cram-md5}, @code{plain}, +@code{login} and @code{xoauth2}, where the first uses a form of encryption to obscure your password, while the other two do not. It -tries each of them, in that order, until one succeeds. You can +tries each of them, in that order, until one succeeds. +(@code{xoauth2} requires using the @file{oauth2.el} library. You can override this by assigning a specific authentication mechanism to a server by including a key @code{smtp-auth} with the value of your preferred mechanism in the appropriate @file{~/.authinfo} entry. diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index 9991917b3fd..70d4b054166 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -896,7 +896,7 @@ augmented with speedbar. @enumerate @item -Create the keymap variable @code{@var{name}-speedbar-key-map}. +Create the keymap variable @code{@var{name}-speedbar-mode-map}. @item Create a function, named whatever you like, which assigns values into your @@ -904,7 +904,7 @@ keymap. Use this command to create the keymap before assigning bindings: @smallexample - (setq @var{name}-speedbar-key-map (speedbar-make-specialized-keymap)) + (setq @var{name}-speedbar-mode-map (speedbar-make-specialized-keymap)) @end smallexample This function creates a special keymap for use in speedbar. @@ -977,7 +977,7 @@ Next, register your extension like this; @example (speedbar-add-expansion-list '("MyExtension" MyExtension-speedbar-menu-items - MyExtension-speedbar-key-map + MyExtension-speedbar-mode-map MyExtension-speedbar-buttons)) @end example diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index a91181b116e..e48383defc4 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,9 +3,9 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2020-11-25.18} +\def\texinfoversion{2021-04-25.21} % -% Copyright 1985, 1986, 1988, 1990-2020 Free Software Foundation, Inc. +% Copyright 1985, 1986, 1988, 1990-2021 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 @@ -574,7 +574,7 @@ % @end foo calls \checkenv and executes the definition of \Efoo. -\parseargdef\end{ +\parseargdef\end{% \if 1\csname iscond.#1\endcsname \else % The general wording of \badenverr may not be ideal. @@ -1002,6 +1002,14 @@ where each line of input produces a line of output.} \global\everypar = {}% } +% leave vertical mode without cancelling any first paragraph indent +\gdef\imageindent{% + \toks0=\everypar + \everypar={}% + \ptexnoindent + \global\everypar=\toks0 +} + % @refill is a no-op. \let\refill=\relax @@ -1181,7 +1189,7 @@ where each line of input produces a line of output.} % double any backslashes. Otherwise, a name like "\node" will be % interpreted as a newline (\n), followed by o, d, e. Not good. % -% See https://mailman.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html and +% See http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html and % related messages. The final outcome is that it is up to the TeX user % to double the backslashes and otherwise make the string valid, so % that's what we do. pdftex 1.30.0 (ca.2005) introduced a primitive to @@ -1862,19 +1870,23 @@ output) for that.)} \closein 1 \endgroup % - \def\xetexpdfext{pdf}% - \ifx\xeteximgext\xetexpdfext - \XeTeXpdffile "#1".\xeteximgext "" - \else - \def\xetexpdfext{PDF}% + % Putting an \hbox around the image can prevent an over-long line + % after the image. + \hbox\bgroup + \def\xetexpdfext{pdf}% \ifx\xeteximgext\xetexpdfext \XeTeXpdffile "#1".\xeteximgext "" \else - \XeTeXpicfile "#1".\xeteximgext "" + \def\xetexpdfext{PDF}% + \ifx\xeteximgext\xetexpdfext + \XeTeXpdffile "#1".\xeteximgext "" + \else + \XeTeXpicfile "#1".\xeteximgext "" + \fi \fi - \fi - \ifdim \wd0 >0pt width \xeteximagewidth \fi - \ifdim \wd2 >0pt height \xeteximageheight \fi \relax + \ifdim \wd0 >0pt width \xeteximagewidth \fi + \ifdim \wd2 >0pt height \xeteximageheight \fi \relax + \egroup } \fi @@ -3539,7 +3551,7 @@ $$% % We use the free feym* fonts from the eurosym package by Henrik % Theiling, which support regular, slanted, bold and bold slanted (and % "outlined" (blackboard board, sort of) versions, which we don't need). -% It is available from https://www.ctan.org/tex-archive/fonts/eurosym. +% It is available from http://www.ctan.org/tex-archive/fonts/eurosym. % % Although only regular is the truly official Euro symbol, we ignore % that. The Euro is designed to be slightly taller than the regular @@ -4289,82 +4301,8 @@ $$% \doitemize{#1.}\flushcr } -% @alphaenumerate and @capsenumerate are abbreviations for giving an arg -% to @enumerate. -% -\def\alphaenumerate{\enumerate{a}} -\def\capsenumerate{\enumerate{A}} -\def\Ealphaenumerate{\Eenumerate} -\def\Ecapsenumerate{\Eenumerate} - % @multitable macros -% Amy Hendrickson, 8/18/94, 3/6/96 -% -% @multitable ... @end multitable will make as many columns as desired. -% Contents of each column will wrap at width given in preamble. Width -% can be specified either with sample text given in a template line, -% or in percent of \hsize, the current width of text on page. - -% Table can continue over pages but will only break between lines. - -% To make preamble: -% -% Either define widths of columns in terms of percent of \hsize: -% @multitable @columnfractions .25 .3 .45 -% @item ... -% -% Numbers following @columnfractions are the percent of the total -% current hsize to be used for each column. You may use as many -% columns as desired. - - -% Or use a template: -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item ... -% using the widest term desired in each column. - -% Each new table line starts with @item, each subsequent new column -% starts with @tab. Empty columns may be produced by supplying @tab's -% with nothing between them for as many times as empty columns are needed, -% ie, @tab@tab@tab will produce two empty columns. - -% @item, @tab do not need to be on their own lines, but it will not hurt -% if they are. - -% Sample multitable: - -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item first col stuff @tab second col stuff @tab third col -% @item -% first col stuff -% @tab -% second col stuff -% @tab -% third col -% @item first col stuff @tab second col stuff -% @tab Many paragraphs of text may be used in any column. -% -% They will wrap at the width determined by the template. -% @item@tab@tab This will be in third column. -% @end multitable - -% Default dimensions may be reset by user. -% @multitableparskip is vertical space between paragraphs in table. -% @multitableparindent is paragraph indent in table. -% @multitablecolmargin is horizontal space to be left between columns. -% @multitablelinespace is space to leave between table items, baseline -% to baseline. -% 0pt means it depends on current normal line spacing. -% -\newskip\multitableparskip -\newskip\multitableparindent -\newdimen\multitablecolspace -\newskip\multitablelinespace -\multitableparskip=0pt -\multitableparindent=6pt -\multitablecolspace=12pt -\multitablelinespace=0pt % Macros used to set up halign preamble: % @@ -4412,8 +4350,6 @@ $$% \go } -% multitable-only commands. -% % @headitem starts a heading row, which we typeset in bold. Assignments % have to be global since we are inside the implicit group of an % alignment entry. \everycr below resets \everytab so we don't have to @@ -4430,14 +4366,8 @@ $$% % default for tables with no headings. \let\headitemcrhook=\relax % -% A \tab used to include \hskip1sp. But then the space in a template -% line is not enough. That is bad. So let's go back to just `&' until -% we again encounter the problem the 1sp was intended to solve. -% --karl, nathan@acm.org, 20apr99. \def\tab{\checkenv\multitable &\the\everytab}% -% @multitable ... @end multitable definitions: -% \newtoks\everytab % insert after every tab. % \envdef\multitable{% @@ -4452,9 +4382,8 @@ $$% % \tolerance=9500 \hbadness=9500 - \setmultitablespacing - \parskip=\multitableparskip - \parindent=\multitableparindent + \parskip=0pt + \parindent=6pt \overfullrule=0pt \global\colcount=0 % @@ -4484,47 +4413,24 @@ $$% % continue for many paragraphs if desired. \halign\bgroup &% \global\advance\colcount by 1 - \multistrut + \strut \vtop{% - % Use the current \colcount to find the correct column width: + \advance\hsize by -1\leftskip + % Find the correct column width \hsize=\expandafter\csname col\the\colcount\endcsname % - % In order to keep entries from bumping into each other - % we will add a \leftskip of \multitablecolspace to all columns after - % the first one. - % - % If a template has been used, we will add \multitablecolspace - % to the width of each template entry. - % - % If the user has set preamble in terms of percent of \hsize we will - % use that dimension as the width of the column, and the \leftskip - % will keep entries from bumping into each other. Table will start at - % left margin and final column will justify at right margin. - % - % Make sure we don't inherit \rightskip from the outer environment. \rightskip=0pt \ifnum\colcount=1 - % The first column will be indented with the surrounding text. - \advance\hsize by\leftskip + \advance\hsize by\leftskip % Add indent of surrounding text \else - \ifsetpercent \else - % If user has not set preamble in terms of percent of \hsize - % we will advance \hsize by \multitablecolspace. - \advance\hsize by \multitablecolspace - \fi - % In either case we will make \leftskip=\multitablecolspace: - \leftskip=\multitablecolspace + % In order to keep entries from bumping into each other. + \leftskip=12pt + \ifsetpercent \else + % If a template has been used + \advance\hsize by \leftskip + \fi \fi - % Ignoring space at the beginning and end avoids an occasional spurious - % blank line, when TeX decides to break the line at the space before the - % box from the multistrut, so the strut ends up on a line by itself. - % For example: - % @multitable @columnfractions .11 .89 - % @item @code{#} - % @tab Legal holiday which is valid in major parts of the whole country. - % Is automatically provided with highlighting sequences respectively - % marking characters. - \noindent\ignorespaces##\unskip\multistrut + \noindent\ignorespaces##\unskip\strut }\cr } \def\Emultitable{% @@ -4533,31 +4439,6 @@ $$% \global\setpercentfalse } -\def\setmultitablespacing{% - \def\multistrut{\strut}% just use the standard line spacing - % - % Compute \multitablelinespace (if not defined by user) for use in - % \multitableparskip calculation. We used define \multistrut based on - % this, but (ironically) that caused the spacing to be off. - % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100. -\ifdim\multitablelinespace=0pt -\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip -\global\advance\multitablelinespace by-\ht0 -\fi -% Test to see if parskip is larger than space between lines of -% table. If not, do nothing. -% If so, set to same dimension as multitablelinespace. -\ifdim\multitableparskip>\multitablelinespace -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller - % than skip between lines in the table. -\fi% -\ifdim\multitableparskip=0pt -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller - % than skip between lines in the table. -\fi} - \message{conditionals,} @@ -5171,30 +5052,29 @@ $$% \let\lbracechar\{% \let\rbracechar\}% % + % Non-English letters. + \def\AA{AA}% + \def\AE{AE}% + \def\DH{DZZ}% + \def\L{L}% + \def\OE{OE}% + \def\O{O}% + \def\TH{TH}% + \def\aa{aa}% + \def\ae{ae}% + \def\dh{dzz}% + \def\exclamdown{!}% + \def\l{l}% + \def\oe{oe}% + \def\ordf{a}% + \def\ordm{o}% + \def\o{o}% + \def\questiondown{?}% + \def\ss{ss}% + \def\th{th}% % \let\do\indexnofontsdef % - % Non-English letters. - \do\AA{AA}% - \do\AE{AE}% - \do\DH{DZZ}% - \do\L{L}% - \do\OE{OE}% - \do\O{O}% - \do\TH{TH}% - \do\aa{aa}% - \do\ae{ae}% - \do\dh{dzz}% - \do\exclamdown{!}% - \do\l{l}% - \do\oe{oe}% - \do\ordf{a}% - \do\ordm{o}% - \do\o{o}% - \do\questiondown{?}% - \do\ss{ss}% - \do\th{th}% - % \do\LaTeX{LaTeX}% \do\TeX{TeX}% % @@ -8931,7 +8811,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \else \ifhavexrefs % We (should) know the real title if we have the xref values. - \def\printedrefname{\refx{#1-title}{}}% + \def\printedrefname{\refx{#1-title}}% \else % Otherwise just copy the Info node name. \def\printedrefname{\ignorespaces #1}% @@ -9025,7 +8905,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % If the user specified the print name (third arg) to the ref, % print it instead of our usual "Figure 1.2". \ifdim\wd\printedrefnamebox = 0pt - \refx{#1-snt}{}% + \refx{#1-snt}% \else \printedrefname \fi @@ -9060,9 +8940,9 @@ might help (with 'rm \jobname.?? \jobname.??s')% \else % Reference within this manual. % - % Only output a following space if the -snt ref is nonempty; for - % @unnumbered and @anchor, it won't be. - \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% + % Only output a following space if the -snt ref is nonempty, as the ref + % will be empty for @unnumbered and @anchor. + \setbox2 = \hbox{\ignorespaces \refx{#1-snt}}% \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi % % output the `[mynode]' via the macro below so it can be overridden. @@ -9073,7 +8953,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% ,\space % % output the `page 3'. - \turnoffactive \putwordpage\tie\refx{#1-pg}{}% + \turnoffactive \putwordpage\tie\refx{#1-pg}% % Add a , if xref followed by a space \if\space\noexpand\tokenafterxref ,% \else\ifx\ \tokenafterxref ,% @TAB @@ -9150,9 +9030,8 @@ might help (with 'rm \jobname.?? \jobname.??s')% \fi\fi\fi } -% \refx{NAME}{SUFFIX} - reference a cross-reference string named NAME. SUFFIX -% is output afterwards if non-empty. -\def\refx#1#2{% +% \refx{NAME} - reference a cross-reference string named NAME. +\def\refx#1{% \requireauxfile {% \indexnofonts @@ -9179,7 +9058,6 @@ might help (with 'rm \jobname.?? \jobname.??s')% % It's defined, so just use it. \thisrefX \fi - #2% Output the suffix in any case. } % This is the macro invoked by entries in the aux file. Define a control @@ -9289,10 +9167,10 @@ might help (with 'rm \jobname.?? \jobname.??s')% \catcode`\[=\other \catcode`\]=\other \catcode`\"=\other - \catcode`\_=\other - \catcode`\|=\other - \catcode`\<=\other - \catcode`\>=\other + \catcode`\_=\active + \catcode`\|=\active + \catcode`\<=\active + \catcode`\>=\active \catcode`\$=\other \catcode`\#=\other \catcode`\&=\other @@ -9539,7 +9417,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % On the other hand, if we are in the case of @center @image, we don't % want to start a paragraph, which will create a hsize-width box and % eradicate the centering. - \ifx\centersub\centerV\else \noindent \fi + \ifx\centersub\centerV \else \imageindent \fi % % Output the image. \ifpdf @@ -11731,3 +11609,4 @@ directory should work if nowhere else does.} @c vim:sw=2: @enablebackslashhack + diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 088352e8a8a..a17a8d67e5b 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -290,7 +290,7 @@ file's contents. For external transfers, @value{tramp} sends a command as follows: @example -rcp user@@host:/path/to/remote/file /tmp/tramp.4711 +$ rcp user@@host:/path/to/remote/file /tmp/tramp.4711 @end example @value{tramp} reads the local temporary file @file{/tmp/tramp.4711} into a buffer, and then deletes the temporary file. @@ -1071,7 +1071,7 @@ capable of servicing requests from @value{tramp}. This non-native @value{tramp} method connects via the Server Message Block (SMB) networking protocol to hosts running file servers that are -typically based on @url{https://www.samba.org/,,Samba} or MS Windows. +typically based on @uref{https://www.samba.org/,,Samba} or MS Windows. Using @command{smbclient} requires a few tweaks when working with @value{tramp}: @@ -1290,7 +1290,7 @@ they are added here for the benefit of @ref{Archive file names}. If you want to use @acronym{GVFS}-based @option{ftp} or @option{smb} methods, you must add them to @code{tramp-gvfs-methods}, and you must -disable the corresponding Tramp package by setting +disable the corresponding @value{tramp} package by setting @code{tramp-ftp-method} or @code{tramp-smb-method} to @code{nil}, respectively: @@ -1323,7 +1323,7 @@ possible, @value{tramp} emulates those operations otherwise. @vindex tramp-rclone-program The program @command{rclone} allows to access different system -storages in the cloud, see @url{https://rclone.org/} for a list of +storages in the cloud, see @uref{https://rclone.org/} for a list of supported systems. If the @command{rclone} program isn't found in your @env{PATH} environment variable, you can tell @value{tramp} its absolute path via the user option @code{tramp-rclone-program}. @@ -1362,7 +1362,7 @@ for accessing the system storage, you should use it. On local hosts which have installed the @command{sshfs} client for mounting a file system based on @command{sftp}, this method can be used, see -@url{https://github.com/libfuse/sshfs/blob/master/README.rst/}. If +@uref{https://github.com/libfuse/sshfs/blob/master/README.rst/}. If the @command{sshfs} program isn't found in your @env{PATH} environment variable, you can tell @value{tramp} its absolute path via the user option @code{tramp-sshfs-program}. @@ -2122,9 +2122,9 @@ to construct these lists. @item @t{"remote-shell"} -This property tells Tramp which remote shell to apply on the remote -host. It is used in all connection methods of @file{tramp-sh.el}. -The default value is @t{"/bin/sh"}. +This property tells @value{tramp} which remote shell to apply on the +remote host. It is used in all connection methods of +@file{tramp-sh.el}. The default value is @t{"/bin/sh"}. @item @t{"remote-shell-login"} @@ -2310,9 +2310,9 @@ trouble with the shell prompt due to set zle options will be avoided. For @command{bash}, loading @file{~/.editrc} or @file{~/.inputrc} is suppressed. -Similar problems can happen with the local shell Tramp uses to create -a process. By default, it uses the command @command{/bin/sh} for -this, which could also be a link to another shell. In order to +Similar problems can happen with the local shell @value{tramp} uses to +create a process. By default, it uses the command @command{/bin/sh} +for this, which could also be a link to another shell. In order to overwrite this, you might apply @vindex tramp-encoding-shell @@ -2610,7 +2610,7 @@ where @samp{192.168.0.1} is the remote host IP address @node FUSE setup @section @acronym{FUSE} setup hints -The @acronym{FUSE} file systems are mounted per default at +The @acronym{FUSE} file systems are mounted by default at @file{/tmp/tramp.method.user@@host#port}. The user name and port number are optional. If the file system is already mounted, it will be used as it is. If the mount point does not exist yet, @@ -2629,6 +2629,11 @@ Example: @end group @end lisp +@vindex tramp-fuse-unmount-on-cleanup +The user option @code{tramp-fuse-unmount-on-cleanup}, when set to +non-@code{nil}, controls, whether a mount point is unmounted on +connection cleanup or on Emacs exiting. + @anchor{Setup of rclone method} @subsection @option{rclone} setup @@ -3231,7 +3236,10 @@ directory @file{/sbin} on your local host. Type @kbd{s h @value{postfixhop}} for the minibuffer completion to @samp{@value{prefix}ssh@value{postfixhop}}. Typing @kbd{@key{TAB}} shows host names @value{tramp} extracts from @file{~/.ssh/config} -file, for example. +@c bug#50387 +file, for example@footnote{Some completion styles, like +@code{substring} or @code{flex}, require to type at least one +character after the trailing @samp{@value{postfixhop}}.}. @example @group @@ -3734,6 +3742,33 @@ To open @command{powershell} as a remote shell, use this: @end lisp +@subsection Remote process connection type +@vindex process-connection-type +@cindex tramp-process-connection-type + +Asynchronous processes behave differently based on whether they use a +pseudo tty or not. This is controlled by the variable +@code{process-connection-type}, which can be @code{t} or @code{pty} +(use a pseudo tty), or @code{nil} or @code{pipe} (don't use one). +@value{tramp} is based on running shells on the remote host, which +requires a pseudo tty. Therefore, it declares the variable +@code{tramp-process-connection-type}, which carries this information +for remote processes. Its default value is @code{t}, and there is no +need to change it. The name of the remote pseudo tty is returned by +the function @code{process-tty-name}. + +If a remote process, started by @code{start-file-process}, should +@emph{not} use a pseudo tty, this can be requested by setting +@code{process-connection-type} to @code{nil} or @code{pipe}. There is +still a pseudo tty for the started process, but some terminal +properties are changed, like suppressing translation of carriage +return characters into newline. + +The function @code{make-process} allows controlling this explicitly by +using the @code{:connection-type} keyword. If this keyword is not +used, the value of @code{process-connection-type} is applied instead. + + @anchor{Improving performance of asynchronous remote processes} @subsection Improving performance of asynchronous remote processes @cindex Asynchronous remote processes @@ -4255,7 +4290,17 @@ test, @ref{Cleanup remote connections}. Alternatively, and often better for analysis, reproduce the problem in a clean Emacs session started with @command{emacs -Q}. Then, @value{tramp} does not load the persistency file (@pxref{Connection caching}), and it does not use -passwords from @file{auth-source.el} (@pxref{Password handling}). +passwords from @file{auth-source.el} (@pxref{Password handling}). The +latter does not happen for the @option{sudoedit} method, otherwise it +would be unusable. + +If you use the GNU ELPA version of @value{tramp}, you must load it +explicitly, because @command{emacs -Q} ignores installed ELPA +packages. Call (version number adapted) + +@example +$ emacs -Q -l ~/.emacs.d/elpa/tramp-2.4.5.1/tramp-autoloads +@end example When including @value{tramp}'s messages in the bug report, increase the verbosity level to 6 (@pxref{Traces and Profiles, Traces}) in the @@ -4266,6 +4311,11 @@ non-@acronym{ASCII} characters which are relevant for analysis, append the buffers as attachments to the bug report. This is also needed in order to avoid line breaks during mail transfer. +If you send the message from Emacs, you are asked about to append +these buffers to the bug report. If you use an external mail program, +you must save these buffers to files, and append them with that mail +program. + @strong{Note} that a verbosity level greater than 6 is not necessary at this stage. Also note that a verbosity level of 6 or greater, the contents of files and directories will be included in the debug @@ -4576,6 +4626,16 @@ supported on your proxy host. @item +Does @value{tramp} support @acronym{SSH} security keys? + +Yes. @command{OpenSSH} has added support for @acronym{FIDO} hardware +devices via special key types @option{*-sk}. @value{tramp} supports +the additional handshaking messages for them. This requires at least +@command{OpenSSH} 8.2, and a @acronym{FIDO} @acronym{U2F} compatible +security key, like yubikey, solokey, or nitrokey. + + +@item @value{tramp} does not connect to Samba or MS Windows hosts running SMB1 connection protocol @@ -5049,7 +5109,7 @@ location. Then start Emacs Client from the command line: @example -emacsclient @trampfn{ssh,user@@host,/file/to/edit} +$ emacsclient @trampfn{ssh,user@@host,/file/to/edit} @end example @code{user} and @code{host} refer to the local host. @@ -5069,7 +5129,7 @@ Then change the environment variable @env{EDITOR} to point to the wrapper script: @example -export EDITOR=/path/to/emacsclient.sh +$ export EDITOR=/path/to/emacsclient.sh @end example @@ -5132,12 +5192,15 @@ tramp-compat-with-mutex} @value{tramp} comes with compatibility code for different Emacs versions. When you see such a message (the text might differ), you -don't use the Emacs built-in version of @value{tramp}. In case you -have installed @value{tramp} from GNU ELPA, see the package README -file for instructions how to recompile it. +don't use the Emacs built-in version of @value{tramp}, and you must +recompile it. In case you have installed @value{tramp} from GNU ELPA, @ifset installchapter -@xref{Recompilation}. +@xref{ELPA Installation}. Otherwise, @xref{Recompilation}. @end ifset +@ifclear installchapter +see @uref{@value{trampurl}#ELPA-Installation}. Otherwise, see +@uref{@value{trampurl}#Recompilation}. +@end ifclear @item @@ -5266,6 +5329,12 @@ handlers. @node External packages @section Integrating with external Lisp packages + +In general, it is not recommended to use @value{tramp} functions and +variables not described in this manual. They might change their +signature and/or semantics without any announcement. + + @subsection File name completion @vindex non-essential diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index 10c951d3ccf..b11ee39f884 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -8,7 +8,7 @@ @c In the Tramp GIT, the version numbers are auto-frobbed from @c tramp.el, and the bug report address is auto-frobbed from @c configure.ac. -@set trampver 2.5.1 +@set trampver 2.5.2-pre @set trampurl https://www.gnu.org/software/tramp/ @set tramp-bug-report-address tramp-devel@@gnu.org @set emacsver 25.1 |