diff options
Diffstat (limited to 'doc/misc')
44 files changed, 5273 insertions, 1449 deletions
diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 1e3398701fc..1d881a5fc7f 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -74,7 +74,7 @@ INFO_COMMON = auth autotype bovine calc ccmode cl \ mairix-el message mh-e modus-themes newsticker nxml-mode octave-mode \ org pcl-cvs pgg rcirc remember reftex sasl \ sc semantic ses sieve smtpmail speedbar srecode todo-mode transient \ - tramp url vhdl-mode vip viper widget wisent woman + tramp url vhdl-mode vip viper vtable widget wisent woman ## Info files to install on current platform. INFO_INSTALL = $(INFO_COMMON) $(DOCMISC_W32) @@ -130,12 +130,12 @@ info: $(INFO_TARGETS) ## Used by top-level Makefile. ## Base file names of output info files. +INFO_BASES = $(patsubst %.info,%,$(notdir $(INFO_INSTALL))) echo-info: - @echo "$(INFO_INSTALL) " | \ - sed -e 's|[^ ]*/||g' -e 's/\.info//g' -e "s/ */.info /g" + @: $(info $(addsuffix .info,$(INFO_BASES))) echo-sources: - @echo ${SOURCES} + @: $(info $(SOURCES)) dvi: $(DVI_TARGETS) @@ -185,7 +185,8 @@ $(foreach ifile,$(filter-out info.info,$(INFO_TARGETS)),$(eval $(call info_templ ## Extra dependencies. -need_emacsver = calc cl dired-x efaq efaq-w32 erc ido reftex woman +## FIXME Updating this list manually is unreliable. +need_emacsver = calc cl dired-x efaq efaq-w32 erc forms ido newsticker reftex remember woman need_emacsver_prefix = $(addprefix ${buildinfodir}/,${need_emacsver}) $(need_emacsver_prefix:=.info) $(need_emacsver:=.dvi) $(need_emacsver:=.pdf) $(need_emacsver:=.html) : ${emacsdir}/emacsver.texi @@ -233,6 +234,10 @@ ${buildinfodir}/tramp.info tramp.html: ${srcdir}/trampver.texi abs_top_builddir = @abs_top_builddir@ + +# Prevent any settings in the user environment causing problems. +unexport EMACSDATA EMACSDOC EMACSLOADPATH EMACSPATH + EMACS = ${abs_top_builddir}/src/emacs emacs = "${EMACS}" -batch --no-site-file --no-site-lisp --eval '(setq load-prefer-newer t)' @@ -243,6 +248,7 @@ emacs = "${EMACS}" -batch --no-site-file --no-site-lisp --eval '(setq load-prefe define org_template $(1:.org=.texi): $(1) ${top_srcdir}/lisp/org/ox-texinfo.el $${AM_V_GEN}cd "$${srcdir}" && $${emacs} -l ox-texinfo \ + --eval '(setq gc-cons-threshold 50000000)' \ -f org-texinfo-export-to-texinfo-batch $$(notdir $$<) $$(notdir $$@) endef diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index e4254faabb9..829d7f4fa03 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -191,7 +191,7 @@ get fancy, the default and simplest configuration is: (setq auth-sources '("secrets:Login")) ;;; use pass (@file{~/.password-store}) ;;; (@pxref{The Unix password store}) -(setq auth-sources '(password-store)) +(auth-source-pass-enable) ;;; JSON data in format [@{ "machine": "SERVER", ;;; "login": "USER", "password": "PASSWORD" @}...] (setq auth-sources '("~/.authinfo.json.gpg")) @@ -305,7 +305,8 @@ The @dfn{Secret Service API} is a standard from to securely store passwords and other confidential information. This API is implemented by system daemons such as the GNOME Keyring and the KDE Wallet (these are GNOME and KDE packages respectively and should -be available on most modern GNU/Linux systems). +be available on most modern GNU/Linux systems). It has been tested +also with KeePassXC. The auth-source library uses the @file{secrets.el} library to connect through the Secret Service API@. You can also use that library in @@ -360,15 +361,19 @@ Collections can be created and deleted by the functions Usually, this is not done from within Emacs. Do not delete standard collections such as @code{"login"}. -The special collection @code{"session"} exists for the lifetime of the -corresponding client session (in our case, Emacs's lifetime). It is -created automatically when Emacs uses the Secret Service interface and -it is deleted when Emacs is killed. Therefore, it can be used to -store and retrieve secret items temporarily. The @code{"session"} -collection is better than a persistent collection when the secret -items should not live longer than Emacs. The session collection can -be specified either by the string @code{"session"}, or by @code{nil}, -whenever a collection parameter is needed in the following functions. +With GNOME Keyring, there exists a special collection called +@code{"session"}, which has the lifetime of the user being logged in. +Its data are not stored on disk and go away when the user logs out. +Therefore, it can be used to store and retrieve secret items +temporarily. The @code{"session"} collection is better than a +persistent collection when the secret items should not live +permanently. The @code{"session"} collection can be addressed either +by the string @code{"session"}, or by @code{nil}, whenever a +collection parameter is needed. + +However, other Secret Service provider don't create this temporary +@code{"session"} collection. You shall check first that this +collection exists, before you use it. @defun secrets-list-items collection Returns all the item labels of @var{collection} as a list. @@ -382,7 +387,7 @@ pairs set for the created item. The keys are keyword symbols, starting with a colon. Example: @example -;;; The session is "session", the label is "my item" +;;; The collection is "session", the label is "my item" ;;; and the secret (password) is "geheim". (secrets-create-item "session" "my item" "geheim" :method "sudo" :user "joe" :host "remote-host") @@ -574,10 +579,7 @@ from Gnus's @code{nnimap.el}. :create t)))) (if found (list (plist-get found :user) - (let ((secret (plist-get found :secret))) - (if (functionp secret) - (funcall secret) - secret)) + (auth-info-password found) (plist-get found :save-function)) nil))) @end example @@ -597,7 +599,7 @@ Later, after a successful login, @code{nnimap.el} calls the @example (when (functionp (nth 2 credentials)) - (funcall (nth 2 credentials))) + (funcall (nth 2 credentials))) @end example This will work whether the @code{:save-function} was provided or not. @@ -632,6 +634,16 @@ This function forgets any cached data matching @var{spec}. It returns the number of items forgotten. @end defun +@defun auth-source-pick-first-password &rest spec +This function returns the password of the first record found by +applying @code{auth-source-search} to @var{spec}. +@end defun + +@defun auth-info-password auth-info +This function extracts the password string from the @var{auth-info} +record. +@end defun + @node GnuPG and EasyPG Assistant Configuration @appendix GnuPG and EasyPG Assistant Configuration diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi index b005c9c34f7..93c65692d01 100644 --- a/doc/misc/autotype.texi +++ b/doc/misc/autotype.texi @@ -92,7 +92,6 @@ completions and expansions of text at point. * Copyrights:: Inserting and updating copyrights. * Executables:: Turning interpreter scripts into executables. * Timestamps:: Updating dates and times in modified files. -* QuickURL:: Inserting URLs based on text at point. * Tempo:: Flexible template insertion. * Hippie Expand:: Expansion of text trying various methods. * Skeleton Language:: Making skeleton commands insert what you want. @@ -478,31 +477,6 @@ The time stamp is written between the brackets or quotes: Time-stamp: <1998-02-18 10:20:51 gildea> @end example -@node QuickURL -@chapter QuickURL: Inserting URLs Based on Text at Point - -@vindex quickurl-url-file -@findex quickurl -@cindex URLs -@kbd{M-x quickurl} can be used to insert a URL into a buffer based on -the text at point. The URLs are stored in an external file defined by -the variable @code{quickurl-url-file} as a list of either cons cells of -the form @code{(@var{key} . @var{URL})} or -lists of the form @code{(@var{key} @var{URL} @var{comment})}. These -specify that @kbd{M-x quickurl} should insert @var{URL} if the word -@var{key} is at point, for example: - -@example -(("FSF" "https://www.fsf.org/" "The Free Software Foundation") - ("emacs" . "https://www.gnu.org/software/emacs/")) -@end example - -@findex quickurl-add-url -@findex quickurl-list -@kbd{M-x quickurl-add-url} can be used to add a new @var{key}/@var{URL} -pair. @kbd{M-x quickurl-list} provides interactive editing of the URL -list. - @node Tempo @chapter Tempo: Flexible Template Insertion diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index d83edc15f30..9bda6af1c5b 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -29877,6 +29877,12 @@ with no argument copies only the number itself into the kill ring, whereas @kbd{C-k} with a prefix argument of 1 copies the number with its trailing newline. +You can customize @code{calc-kill-line-numbering} to nil to exclude +line numbering from kills and copies made by @code{calc-kill} and +@code{calc-copy-as-kill}. This option does not affect calc kill and +copy commands which operate on the region, as that would not make +sense. + @node Yanking Into Stack @section Yanking into the Stack diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 9da18cd9201..1f12c30b1f8 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -283,6 +283,7 @@ Font Locking * Font Locking Preliminaries:: * Faces:: * Doc Comments:: +* Wrong Comment Style:: * Misc Font Locking:: * AWK Mode Font Locking:: @@ -6277,6 +6278,32 @@ expressions for the operands. @comment ------------------------------------------------------------ +@defun c-lineup-argcont-+ +@findex lineup-argcont-+ (c-) +Indent a continued argument @code{c-basic-offset} spaces from the +start of the first argument at the current level of nesting on a +previous line. + +@example +@group +foo (xyz, uvw, aaa + bbb + ccc + + ddd + eee + fff); <- c-lineup-argcont-+ + <--> c-basic-offset +@end group +@end example + +Only continuation lines like this are touched, @code{nil} being +returned on lines which are the start of an argument. + +Within a gcc @code{asm} block, @code{:} is recognized as an argument +separator, but of course only between operand specifications, not in the +expressions for the operands. + +@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. +@end defun + +@comment ------------------------------------------------------------ + @defun c-lineup-arglist-operators @findex lineup-arglist-operators @r{(c-)} Line up lines starting with an infix operator under the open paren. diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 4eb3d85d2ba..07c19e37ce4 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -444,7 +444,7 @@ the ``rest'' argument is bound to the keyword list as it appears in the call. For example: @example -(cl-defun find-thing (thing &rest rest &key need &allow-other-keys) +(cl-defun find-thing (thing thing-list &rest rest &key need &allow-other-keys) (or (apply 'cl-member thing thing-list :allow-other-keys t rest) (if need (error "Thing not found")))) @end example @@ -843,6 +843,7 @@ constructs. * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}. * Loop Facility:: The Common Lisp @code{loop} macro. * Multiple Values:: @code{cl-values}, @code{cl-multiple-value-bind}, etc. +* Macro-Writing Macros:: @code{cl-with-gensyms}, @code{cl-once-only}. @end menu @node Assignment @@ -1245,6 +1246,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 @@ -2507,6 +2514,86 @@ in @code{cl-multiple-value-bind}. Since a perfect emulation is not feasible in Emacs Lisp, this package opts to keep it as simple and predictable as possible. +@node Macro-Writing Macros +@section Macro-Writing Macros + +@noindent +This package includes two classic Common Lisp macro-writing macros to +help render complex macrology easier to read. + +@defmac cl-with-gensyms names@dots{} body +This macro expands to code that executes @var{body} with each of the +variables in @var{names} bound to a fresh uninterned symbol, or +@dfn{gensym}, in Common Lisp parlance. For macros requiring more than +one gensym, use of @code{cl-with-gensyms} shortens the code and +renders one's intentions clearer. Compare: + +@example +(defmacro my-macro (foo) + (let ((bar (gensym "bar")) + (baz (gensym "baz")) + (quux (gensym "quux"))) + `(let ((,bar (+ @dots{}))) + @dots{}))) + +(defmacro my-macro (foo) + (cl-with-gensyms (bar baz quux) + `(let ((,bar (+ @dots{}))) + @dots{}))) +@end example +@end defmac + +@defmac cl-once-only ((variable form)@dots{}) body +This macro is primarily to help the macro programmer ensure that forms +supplied by the user of the macro are evaluated just once by its +expansion even though the result of evaluating the form is to occur +more than once. Less often, this macro is used to ensure that forms +supplied by the macro programmer are evaluated just once. + +Each @var{variable} may be used to refer to the result of evaluating +@var{form} in @var{body}. @code{cl-once-only} binds each +@var{variable} to a fresh uninterned symbol during the evaluation of +@var{body}. Then, @code{cl-once-only} wraps the final expansion in +code to evaluate each @var{form} and bind the result to the +corresponding uninterned symbol. Thus, when the macro writer +substitutes the value for @var{variable} into the expansion they are +effectively referring to the result of evaluating @var{form}, rather +than @var{form} itself. Another way to put this is that each +@var{variable} is bound to an expression for the (singular) result of +evaluating @var{form}. + +The most common case is where @var{variable} is one of the arguments +to the macro being written, so @code{(variable variable)} may be +abbreviated to just @code{variable}. + +For example, consider this macro: + +@example +(defmacro my-list (x y &rest forms) + (let ((x-result (gensym)) + (y-result (gensym))) + `(let ((,x-result ,x) + (,y-result ,y)) + (list ,x-result ,y-result ,x-result ,y-result + (progn ,@@forms)))) +@end example + +In a call like @w{@code{(my-list (pop foo) @dots{})}} the intermediate +binding to @code{x-result} ensures that the @code{pop} is not done +twice. But as a result the code is rather complex: the reader must +keep track of how @code{x-result} really just means the first +parameter of the call to the macro, and the required use of multiple +gensyms to avoid variable capture by @code{(progn ,@@forms)} obscures +things further. @code{cl-once-only} takes care of these details: + +@example +(defmacro my-list (x y &rest forms) + (cl-once-only (x y) + `(list ,x ,y ,x ,y + (progn ,@@forms)))) +@end example +@end defmac + @node Macros @chapter Macros @@ -2862,6 +2949,7 @@ out the property and value cells. @node Creating Symbols @section Creating Symbols +@cindex gensym @noindent These functions create unique symbols, typically for use as @@ -5014,13 +5102,13 @@ The above @code{incf} example could be written using @example (defmacro incf (place &optional n) (gv-letplace (getter setter) place - (macroexp-let2 nil v (or n 1) + (cl-once-only ((v (or n 1))) (funcall setter `(+ ,v ,getter))))) @end example @ignore (defmacro concatf (place &rest args) (gv-letplace (getter setter) place - (macroexp-let2 nil v (mapconcat 'identity args "") + (cl-once-only ((v `(mapconcat 'identity ',args))) (funcall setter `(concat ,getter ,v))))) @end ignore @end defmac diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index 0b4f53ba136..bb97446d127 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -795,13 +795,7 @@ and interface. Example: (dbus-get-all-managed-objects :session "org.gnome.SettingsDaemon" "/") -@result{} (("/org/gnome/SettingsDaemon/MediaKeys" - ("org.gnome.SettingsDaemon.MediaKeys") - ("org.freedesktop.DBus.Peer") - ("org.freedesktop.DBus.Introspectable") - ("org.freedesktop.DBus.Properties") - ("org.freedesktop.DBus.ObjectManager")) - ("/org/gnome/SettingsDaemon/Power" +@result{} (("/org/gnome/SettingsDaemon/Power" ("org.gnome.SettingsDaemon.Power.Keyboard") ("org.gnome.SettingsDaemon.Power.Screen") ("org.gnome.SettingsDaemon.Power" diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index 754ccf4065c..50d9914081c 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -165,10 +165,8 @@ When @file{dired-x.el} is loaded, some standard Dired functions from Dired}), if it is active. @code{dired-find-buffer-nocreate} and @code{dired-initial-position} respect the value of @code{dired-find-subdir} (@pxref{Miscellaneous Commands}). -@code{dired-clean-up-after-deletion} respects the value of -@code{dired-clean-up-buffers-too}. @code{dired-read-shell-command} uses -@code{dired-guess-shell-command} (@pxref{Shell Command Guessing}) to -offer a smarter default command. +@code{dired-read-shell-command} uses @code{dired-guess-shell-command} +(@pxref{Shell Command Guessing}) to offer a smarter default command. @node Installation @chapter Installation @@ -884,15 +882,6 @@ normal and a wildcard buffer for the same directory, @kbd{C-x d @key{RET}} will toggle between those two. @end table -@table @kbd -@findex dired-goto-subdir -@kindex M-G -@item M-G -(@code{dired-goto-subdir}) Go to the header line of an inserted directory. -This command reads its argument, with completion derived from the names of the -inserted subdirectories. -@end table - @table @code @item dired-vm @@ -920,55 +909,6 @@ to @kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound. @findex dired-rmail Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this file (assumed to be mail folder in Rmail format). - -@item dired-info -@kindex I -@cindex running info. -@findex dired-info -Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info -format). - -@vindex dired-bind-info -If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will -not be bound to @kbd{I}. - -@item dired-man -@cindex running man. -@kindex N -@findex dired-man -Bound to @kbd{N}. Run man on this file (assumed to be a file in @code{nroff} -format). - -@vindex dired-bind-man -If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not -be bound to @kbd{N}. - -@item dired-do-relsymlink -@cindex relative symbolic links. -@kindex Y -@findex dired-do-relsymlink -Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a -directory, or make a relative symbolic link to the current file. This creates -relative symbolic links like - -@example - foo -> ../bar/foo -@end example - -@noindent -not absolute ones like - -@example - foo -> /ugly/path/that/may/change/any/day/bar/foo -@end example - -@item dired-do-relsymlink-regexp -@kindex %Y -@findex dired-do-relsymlink-regexp -Bound to @kbd{%Y}. Relative symlink all marked files containing -@var{regexp} to @var{newname}. See functions -@code{dired-do-rename-regexp} and @code{dired-do-relsymlink} for more -info. @end table @node Bugs diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index 518b30fea89..9867883b24a 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -99,7 +99,7 @@ learn and adopt GNU ways of doing things. @chapter @ede{} Project Concepts @ede{} is a generic interface for managing projects. It specifies a -single set of menus and keybindings, while supporting multiple ways to +single set of menus and key bindings, while supporting multiple ways to express a project via a build system. In the subsequent chapters, we will describe the different project @@ -144,7 +144,7 @@ init file: Activating @ede{} adds a menu named @samp{Development} to the menu bar. This menu provides several menu items for high-level @ede{} -commands. These menu items, and their corresponding keybindings, are +commands. These menu items, and their corresponding key bindings, are independent of the type of project you are actually working on. @node Quick Start @@ -271,7 +271,7 @@ Projects. You can create targets either from a buffer, or from a @code{dired} directory buffer. Note: If for some reason a directory list buffer, or file does not have the -@samp{Project} menu item, or if @ede{} keybindings don't work, just +@samp{Project} menu item, or if @ede{} key bindings don't work, just use @kbd{M-x revert-buffer @key{RET}} to force a refresh. Sometimes creating a new project doesn't restart buffers correctly. @@ -958,7 +958,7 @@ The example for Makefiles looks like this: ((buildfile :initform "Makefile")) "Generic Project for makefiles.") -(defmethod ede-generic-setup-configuration ((proj ede-generic-makefile-project) config) +(cl-defmethod ede-generic-setup-configuration ((proj ede-generic-makefile-project) config) "Set up a configuration for Make." (oset config build-command "make -k") (oset config debug-command "gdb ")) @@ -1059,7 +1059,7 @@ examples. @menu * Development Overview:: * Detecting a Project:: -* User interface methods:: Methods associated with keybindings +* User interface methods:: Methods associated with key bindings * Base project methods:: The most basic methods on @ede{} objects. * Sourcecode objects:: Defining new sourcecode classes. * Compiler and Linker objects:: Defining new compilers and linkers. @@ -1551,14 +1551,14 @@ This is a URL to be sent to a web site for documentation. @item :web-site-directory @* A directory where web pages can be found by Emacs. -For remote locations use a path compatible with ange-ftp or EFS@. +For remote locations use a path compatible with ange-ftp. You can also use TRAMP for use with rcp & scp. @item :web-site-file @* 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. +This can be a local file, use ange-ftp or TRAMP. @item :ftp-site Type: @code{string} @* diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index d81ba158a19..39b09b29b3f 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -1866,7 +1866,8 @@ These variables specify the options to pass to the above utilities. In @code{ediff-diff-options}, it may be useful to specify options such as @samp{-w} that ignore certain kinds of changes. However, Ediff does not let you use the option @samp{-c}, as it doesn't recognize this -format yet. +format yet. (If you alter this variable, it should be done via the +Customize interface instead of using @code{setq} directly.) @item ediff-coding-system-for-read @vindex ediff-coding-system-for-read diff --git a/doc/misc/efaq-w32.texi b/doc/misc/efaq-w32.texi index 35ff01a336c..084b5a3254e 100644 --- a/doc/misc/efaq-w32.texi +++ b/doc/misc/efaq-w32.texi @@ -691,9 +691,9 @@ question also. @node CUA @subsection Standard Windows key bindings @findex cua-mode -@cindex CUA keybindings +@cindex CUA key bindings @cindex shift key, selecting with -@cindex standard Windows keybindings +@cindex standard Windows key bindings @cindex paste with C-v @cindex cut with C-x @cindex copy with C-c @@ -701,7 +701,7 @@ question also. @cindex C-x to cut @cindex C-v to paste -The keybindings of Emacs predate modern GUIs, and the keys that were +The key bindings of Emacs predate modern GUIs, and the keys that were chosen by later GUIs for cut and copy were given important functions as extended keymaps in Emacs. CUA mode attempts to let both bindings co-exist by defining C-x and C-c as @code{kill-region} and diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index 373efe9ad5f..a98c4b6a614 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -9,10 +9,9 @@ @copying Copyright @copyright{} 2001--2022 Free Software Foundation, Inc.@* -Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2000 -Reuven M. Lerner@* -Copyright @copyright{} 1992, 1993 Steven Byrnes@* -Copyright @copyright{} 1990, 1991, 1992 Joseph Brian Wells@* +Copyright @copyright{} 1994--2000 Reuven M. Lerner@* +Copyright @copyright{} 1992--1993 Steven Byrnes@* +Copyright @copyright{} 1990--1992 Joseph Brian Wells@* @quotation This list of frequently asked questions about GNU Emacs with answers @@ -151,7 +150,7 @@ and @key{Meta} @item @key{DEL}: @key{Delete}, usually @strong{not} the same as -@key{Backspace}; same as @kbd{C-?} (see @ref{Backspace invokes help}, if +@key{Backspace}; same as @kbd{C-?} (@pxref{Backspace invokes help}, if deleting invokes Emacs help) @item @@ -259,12 +258,13 @@ name displayed by this will be the full pathname of the installed @code{data-directory}, and @kbd{C-h v} displays the value and the documentation of a variable.) -The location of your Info directory (i.e., where Info documentation -is stored) is kept in the variable @code{Info-default-directory-list}. Use -@kbd{C-h v Info-default-directory-list @key{RET}} to see the value of -this variable, which will be a list of directory names. The last -directory in that list is probably where most Info files are stored. By -default, Emacs Info documentation is placed in @file{/usr/local/share/info}. +The location of your Info directory (i.e., where Info documentation is +stored) is kept in the variable @code{Info-directory-list}. Use +@kbd{C-h v Info-directory-list @key{RET}} to see the value of this +variable, which will be a list of directory names (after Info has been +started). The last directory in that list is probably where most Info +files are stored. By default, Emacs Info documentation is placed in +@file{/usr/local/share/info}. For information on some of the files in the @file{etc} directory, @pxref{Informational files for Emacs}. @@ -701,7 +701,7 @@ directory which is a subdirectory of your home directory named @file{Info}, you could put this in your @file{.emacs} file: @lisp -(add-to-list 'Info-default-directory-list "~/Info") +(add-to-list 'Info-default-directory-list "~/Info/") @end lisp You will need a top-level Info file named @file{dir} in this directory @@ -793,7 +793,7 @@ informational files about Emacs and relevant aspects of the GNU project are available for you to read. The following files (and others) are available in the @file{etc} -directory of the Emacs distribution (see @ref{File-name conventions}, if +directory of the Emacs distribution (@pxref{File-name conventions}, if you're not sure where that is). Many of these files are available via the Emacs @samp{Help} menu, or by typing @kbd{C-h ?} (@kbd{M-x help-for-help}). @@ -881,10 +881,11 @@ divergent TECO command sets and key bindings at MIT, and completed by RMS. Many people have said that TECO code looks a lot like line noise; you -can read more at @uref{news:alt.lang.teco}. Someone has written a TECO -implementation in Emacs Lisp (to find it, see @ref{Packages that do not -come with Emacs}); it would be an interesting project to run the -original TECO Emacs inside of Emacs. +can read more on +@uref{https://en.wikipedia.org/wiki/TECO_(text_editor), Wikipedia}. +Someone has written a TECO implementation in Emacs Lisp (to find it, +see @ref{Packages that do not come with Emacs}); it would be an +interesting project to run the original TECO Emacs inside of Emacs. @cindex Why Emacs? For some not-so-serious alternative reasons for Emacs to have that @@ -3376,56 +3377,13 @@ bottom of files by setting the variable @code{enable-local-eval}. @xref{File Variables,,, emacs, The GNU Emacs Manual}. @item -Synthetic X events. (Yes, a risk; use @samp{MIT-MAGIC-COOKIE-1} or -better.) +Browsing the web. -Emacs accepts synthetic X events generated by the @code{SendEvent} -request as though they were regular events. As a result, if you are -using the trivial host-based authentication, other users who can open X -connections to your X workstation can make your Emacs process do -anything, including run other processes with your privileges. - -The only fix for this is to prevent other users from being able to open -X connections. The standard way to prevent this is to use a real -authentication mechanism, such as @samp{MIT-MAGIC-COOKIE-1}. If using -the @code{xauth} program has any effect, then you are probably using -@samp{MIT-MAGIC-COOKIE-1}. Your site may be using a superior -authentication method; ask your system administrator. - -If real authentication is not a possibility, you may be satisfied by -just allowing hosts access for brief intervals while you start your X -programs, then removing the access. This reduces the risk somewhat by -narrowing the time window when hostile users would have access, but -@emph{does not eliminate the risk}. - -On most computers running Unix and X, you enable and disable -access using the @code{xhost} command. To allow all hosts access to -your X server, use - -@example -xhost + -@end example - -@noindent -at the shell prompt, which (on an HP machine, at least) produces the -following message: - -@example -access control disabled, clients can connect from any host -@end example - -To deny all hosts access to your X server (except those explicitly -allowed by name), use - -@example -xhost - -@end example - -On the test HP computer, this command generated the following message: - -@example -access control enabled, only authorized clients can connect -@end example +Emacs relies on C libraries to parse images, and historically, many of +these have had exploitable weaknesses. If you're browsing the web +with the eww browser, it will usually download and display images +using these libraries. If an image library has a weakness, it may be +used by an attacker to gain access. @end itemize @@ -3754,7 +3712,6 @@ information is available from * Compose Character:: * Binding combinations of modifiers and function keys:: * Meta key does not work in xterm:: -* SPC no longer completes file names:: @end menu @node Binding keys to commands @@ -4200,10 +4157,6 @@ If there is an @code{rlogin} connection between @code{xterm} and Emacs, the of every character. @item -If Emacs is running on Ultrix, it is reported that evaluating -@code{(set-input-mode t nil)} helps. - -@item If all else fails, you can make @code{xterm} generate @kbd{@key{ESC} W} when you type @kbd{M-W}, which is the same conversion Emacs would make if it got the @kbd{M-W} anyway. In X11R4, the following resource @@ -4228,22 +4181,6 @@ You might have to replace @samp{Meta} with @samp{Alt}. @end itemize -@node SPC no longer completes file names -@section Why doesn't @key{SPC} complete file names anymore? -@cindex @kbd{SPC} file name completion - -Starting with Emacs 22.1, @kbd{SPC} no longer completes file names in -the minibuffer, so that file names with embedded spaces could be typed -without the need to quote the spaces. - -You can get the old behavior by binding @kbd{SPC} to -@code{minibuffer-complete-word} in the minibuffer, as follows: - -@lisp -(define-key minibuffer-local-filename-completion-map (kbd "SPC") - 'minibuffer-complete-word) -@end lisp - @c ------------------------------------------------------------ @node Alternate character sets @chapter Alternate character sets diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index a367a83eae9..18a2b74033e 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -700,18 +700,18 @@ 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}. +@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 @@ -856,11 +856,12 @@ You can also create a generic method with @code{cl-defmethod} (@pxref{Methods}). When a method is created and there is no generic method in place with that name, then a new generic will be created, and the new method will use it. -@end defmac -In CLOS, a generic call also be used to provide an argument list and -dispatch precedence for all the arguments. In @eieio{}, dispatching -only occurs for the first argument, so the @var{arglist} is not used. +In CLOS, a generic method can also be used to provide an argument list +and dispatch precedence for all the arguments. In @eieio{}, +dispatching only occurs for the first argument, so the @var{arglist} +is not used. +@end defmac @node Methods @section Methods diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index ed9cccf4899..640712edf33 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -454,7 +454,8 @@ setting this option to non-@code{nil}. The default value is @code{t}. @item mm-external-terminal-program @vindex mm-external-terminal-program -The program used to start an external terminal. +This should be a list of strings; typically something like +@samp{("xterm" "-e")} or @samp{("gnome-terminal" "--")}. @item mm-enable-external @vindex mm-enable-external diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index 46a465aaf4d..3db83197f9e 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--2022 Free Software Foundation, Inc. @@ -88,7 +90,28 @@ Advanced Usage ERC is a powerful, modular, and extensible IRC client for Emacs. It is distributed with Emacs since version 22.1. -It comes with the following capabilities enabled by default. +IRC is short for Internet Relay Chat. When using IRC, you can +communicate with other users on the same IRC network. There are many +different networks---if you search for ``IRC networks'' in your +favorite search engine, you will find up-to-date lists of IRC networks +catering to various interests and topics. + +To use IRC, you need an IRC client such as ERC. Using the client, you +connect to an IRC server. Once you've done that, you will have access +to all available channels on that server's network. A channel is +basically a chat room, and what you type in a channel will be shown to +all other users in that channel. You can be in several channels at +the same time---ERC will show each channel in its own buffer. + +IRC channel names always begin with a @samp{#} character. For +example, the Emacs channel on Libera.Chat is @samp{#emacs}, and the +ERC channel is @samp{#erc}. Do not confuse them with the hashtags +used on many social media platforms. + +You can also send private messages to other IRC users on the same +network, even if they are not in the same channels as you. + +ERC comes with the following capabilities enabled by default. @itemize @bullet @item Flood control @@ -112,7 +135,11 @@ It comes with the following capabilities enabled by default. @cindex settings The command @kbd{M-x erc} will start ERC and prompt for the server to -connect to. +connect to. If you're unsure of which server or network to connect +to, we suggest starting with ``irc.libera.chat''. There you will find +the @samp{#emacs} channels where you can chat with other Emacs users, +and if you're having trouble with ERC, you can join the @samp{#erc} +channel and ask for help there. If you want to place ERC settings in their own file, you can place them in @file{~/.emacs.d/.ercrc.el}, creating it if necessary. @@ -518,20 +545,27 @@ Non-interactively, it takes the following keyword arguments. @item @var{server} @item @var{port} @item @var{nick} +@item @var{user} @item @var{password} @item @var{full-name} +@item @var{id} @end itemize -That is, if called with the following arguments, @var{server} and -@var{full-name} will be set to those values, whereas -@code{erc-compute-port} and @code{erc-compute-nick} will be invoked -for the values of the other parameters. +For example, calling the command like so -@example +@example lisp (erc :server "irc.libera.chat" :full-name "J. Random Hacker") @end example + +@noindent +sets @var{server} and @var{full-name} directly while leaving the rest +up to functions like @code{erc-compute-port}. Note that some +arguments can't be specified interactively. @var{id}, in particular, +is rarely needed (@pxref{Network Identifier}). + @end defun +@noindent To connect securely over an encrypted TLS connection, use @kbd{M-x erc-tls}. @@ -543,21 +577,25 @@ Non-interactively, it takes the following keyword arguments. @item @var{server} @item @var{port} @item @var{nick} +@item @var{user} @item @var{password} @item @var{full-name} +@item @var{id} @item @var{client-certificate} @end itemize -That is, if called with the following arguments, @var{server} and -@var{full-name} will be set to those values, whereas -@code{erc-compute-port} and @code{erc-compute-nick} will be invoked -for the values of the other parameters, and @code{client-certificate} -will be @code{nil}. +That is, if called in the following manner -@example +@example lisp (erc-tls :server "irc.libera.chat" :full-name "J. Random Hacker") @end example +@noindent +the command will set @var{server} and @var{full-name} accordingly, +while helpers, like @code{erc-compute-nick}, will determine other +parameters, and some, like @code{client-certificate}, will just be +@code{nil}. + To use a certificate with @code{erc-tls}, specify the optional @var{client-certificate} keyword argument, whose value should be as described in the documentation of @code{open-network-stream}: if @@ -692,29 +730,139 @@ ERC should automatically attempt to connect with another nickname. You can manually set another nickname with the /NICK command. @end defopt +@subheading User +@defun erc-compute-user &optional user +Determine a suitable value to send as the first argument of the +opening @samp{USER} IRC command by consulting the following sources: + +@itemize +@item +@var{user}, the argument passed to this function +@item +The option @code{erc-email-userid}, assuming @code{erc-anonymous-login} +is non-@code{nil} +@item +The result of calling the function @code{user-login-name} +@end itemize + +@end defun + +@defopt erc-email-userid +A permanent username value to send for all connections. It should be +a string abiding by the rules of the network. +@end defopt + @subheading Password @cindex password @defopt erc-prompt-for-password -If non-@code{nil} (the default), @kbd{M-x erc} prompts for a password. +If non-@code{nil} (the default), @kbd{M-x erc} and @kbd{M-x erc-tls} +prompt for a server password. This only affects interactive +invocations of @code{erc} and @code{erc-tls}. @end defopt +@noindent If you prefer, you can set this option to @code{nil} and use the @code{auth-source} mechanism to store your password. For instance, if -you use @file{~/.authinfo} as your auth-source backend, then put +the option @code{auth-sources} contains @file{~/.authinfo}, put something like the following in that file: @example -machine irc.example.net login "#fsf" password sEcReT +machine irc.example.net login mynick password sEcReT @end example @noindent -ERC also consults @code{auth-source} to find any channel keys required -for the channels that you wish to autojoin, as specified by the -variable @code{erc-autojoin-channels-alist}. +For server passwords, that is, passwords sent for the IRC @samp{PASS} +command, the @samp{host} field (@w{@code{machine irc.example.net}} in +the above example) +corresponds to the @var{server} parameter used by @code{erc} and +@code{erc-tls}. Unfortunately, specifying a network, like +@samp{Libera.Chat}, or a specific network server, like +@samp{platinum.libera.chat}, won't normally work for looking up a server +password because such information isn't available during opening +introductions. (Actually, ERC @emph{can} find entries with arbitrary +@samp{host} values for any context, including server passwords, but +that requires customizing the more advanced options below.) + +If ERC can't find a suitable server password, it will just skip the IRC +@samp{PASS} command altogether, something users may want when using +CertFP or engaging NickServ via ERC's ``services'' module. If that is +what you'd like to do, you can also customize the option +@code{erc-auth-source-server-function} to @code{nil} to skip +server-password lookup for all servers. Note that some networks and +IRCds may accept account-services authentication via server password +using the nonstandard @samp{mynick:sEcReT} convention. + +As just mentioned, you can also use @code{auth-source} to authenticate +to account services the traditional way, through a bot called +@samp{NickServ}. To tell ERC to do that, set +@code{erc-use-auth-source-for-nickserv-password} to @code{t}. For +these and most other queries, entries featuring custom identifiers and +networks are matched first, followed by network-specific servers and +dialed endpoints (typically, the @var{server} argument passed to +@code{erc}). The following netrc-style entries appear in order of +precedence: -For more details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. +@example +machine Libera/cellphone login MyNick password sEcReT +machine Libera.Chat login MyNick password sEcReT +machine zirconium.libera.chat login MyNick password sEcReT +machine irc.libera.chat login MyNick password sEcReT +@end example +@noindent +Remember that field labels vary per backend, so @samp{machine} (in +netrc's case) maps to auth-source's generalized notion of a host, +hence the @samp{:host} keyword property. Also, be sure to mind the +syntax of your chosen backend medium. For example, always quote +channel names in a netrc file. + +If this all seems overly nuanced or just plain doesn't appeal to you, +see options @code{erc-auth-source-services-function} and friends, described +below. These let you query auth-source your way. Most users can +simply ignore the passed-in arguments and get by with something like +the following: + +@lisp +(defun my-fancy-auth-source-func (&rest _) + (let* ((host (read-string "host: " nil nil "default")) + (pass (auth-source-pick-first-password :host host))) + (if (and pass (string-search "libera" host)) + (concat "MyNick:" pass) + pass))) +@end lisp + +Lastly, ERC also consults @code{auth-source} to find ``keys'' that may +be required by certain channels you join. When modifying a +traditional @code{auth-source} entry for this purpose, put the channel +name in the @samp{user} field (for example, @samp{login "#fsf"}, in +netrc's case). The actual key goes in the @samp{password} (or +@samp{secret}) field. + +@noindent +For details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. + +@defopt erc-auth-source-server-function +@end defopt +@defopt erc-auth-source-services-function +@end defopt +@defopt erc-auth-source-join-function + +ERC calls these functions with keyword arguments recognized by +@code{auth-source-search}, namely, those deemed most relevant to the +current context, if any. For example, with NickServ queries, +@code{:user} is the ``desired'' nickname rather than the current one. +Generalized names, like @code{:user} and @code{:host}, are always used +over back-end specific ones, like @code{:login} or @code{:machine}. +ERC expects a string to use as the secret or nil, if the search fails. + +@findex erc-auth-source-search +The default value for all three options is the function +@code{erc-auth-source-search}. It tries to merge relevant contextual +parameters with those provided or discovered from the logical connection +or the underlying transport. Some auth-source back ends may not be +compatible; netrc, plstore, json, and secrets are currently supported. +@end defopt @subheading Full name @@ -725,10 +873,14 @@ This tries a number of increasingly more default methods until a non-@code{nil} value is found. @itemize @bullet -@item @var{full-name} (the argument passed to this function) -@item The @code{erc-user-full-name} option -@item The value of the IRCNAME environment variable -@item The result from the @code{user-full-name} function +@item +@var{full-name} (the argument passed to this function) +@item +The @code{erc-user-full-name} option +@item +The value of the IRCNAME environment variable +@item +The result from the @code{user-full-name} function @end itemize @end defun @@ -739,6 +891,31 @@ User full name. This can be either a string or a function to call. @end defopt + +@subheading ID +@anchor{Network Identifier} + +ERC uses an abstract designation, called @dfn{network context +identifier}, for referring to a connection internally. While normally +derived from a combination of logical and physical connection +parameters, an ID can also be explicitly provided via an entry-point +command (like @code{erc-tls}). Use this in rare situations where ERC +would otherwise have trouble discerning between connections. + +One such situation might arise when using multiple connections to the +same network with the same nick but different (nonstandard) @samp{device} +identifiers, which some bouncers may support. Another might be when +mimicking the experience offered by popular standalone clients, which +normally offer ``named'' persistent configurations with server buffers +reflecting those names. Yet another use case might involve +third-party code needing to identify a connection unequivocally, but in +a human-friendly way suitable for UI components. + +When providing an ID as an entry-point argument, strings and symbols +make the most sense, but any reasonably printable object is +acceptable. + + @node Sample Configuration @section Sample Configuration @cindex configuration, sample @@ -800,12 +977,6 @@ stuff, to the current ERC buffer." (setq erc-autojoin-channels-alist '(("Libera.Chat" "#emacs" "#erc"))) -;; Rename server buffers to reflect the current network name instead -;; of SERVER:PORT (e.g., "Libera.Chat" instead of -;; "irc.libera.chat:6667"). This is useful when using a bouncer like -;; ZNC where you have multiple connections to the same server. -(setq erc-rename-buffers t) - ;; Interpret mIRC-style color commands in IRC chats (setq erc-interpret-mirc-color t) @@ -864,15 +1035,6 @@ lurkers. The function @code{erc-lurker-p} determines whether a given nickname is considered a lurker. @end defopt -@defopt erc-rename-buffers -If non, @code{nil}, this will rename server buffers to reflect the -current network name instead of IP:PORT - -@example -(setq erc-rename-buffers t) -@end example -@end defopt - @node Getting Help and Reporting Bugs @chapter Getting Help and Reporting Bugs @cindex help, getting @@ -897,7 +1059,7 @@ contributors are frequently around and willing to answer your questions. @item -To report a bug in ERC, use @kbd{M-x report-emacs-bug}. +To report a bug in ERC, use @kbd{M-x erc-bug}. @end itemize diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index aeae6aef8c7..1b7f38daadf 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -109,6 +109,7 @@ Appendix @end menu @end ifnottex + @node Introduction @chapter Introduction @cindex introduction to ERT @@ -123,7 +124,7 @@ commands to run them to verify whether the definitions that are currently loaded in Emacs pass the tests. Some Lisp files have comments like the following (adapted from the -package @code{pp.el}): +package @file{pp.el}): @lisp ;; (pp-to-string '(quote quote)) ; expected: "'quote" @@ -320,7 +321,7 @@ Show the list of @code{should} forms executed in the test @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{message}) in a test or any of the code that it invoked (@code{ert-results-pop-to-messages-for-test-at-point}). @item L @@ -358,6 +359,7 @@ Prompt for a test and then show its documentation. @end table + @node Running Tests in Batch Mode @section Running Tests in Batch Mode @cindex running tests in batch mode @@ -375,7 +377,7 @@ emacs -batch -l ert -l my-tests.el -f ert-run-tests-batch-and-exit @end example This command will start up Emacs in batch mode, load ERT, load -@code{my-tests.el}, and run all tests defined in it. It will exit +@file{my-tests.el}, and run all tests defined in it. It will exit with a zero exit status if all tests passed, or nonzero if any tests failed or if anything else went wrong. It will also print progress messages and error diagnostics to standard output. @@ -390,12 +392,37 @@ summary as shown below: emacs -batch -l ert -f ert-summarize-tests-batch-and-exit output.log @end example +@vindex ert-batch-print-level +@vindex ert-batch-print-length +ERT attempts to limit the output size for failed tests by choosing +conservative values for @code{print-level} and @code{print-length} +when printing Lisp values. This can in some cases make it difficult +to see which portions of those values are incorrect. Use +@code{ert-batch-print-level} and @code{ert-batch-print-length} +to customize that: + +@example +emacs -batch -l ert -l my-tests.el \ + --eval "(let ((ert-batch-print-level 10) \ + (ert-batch-print-length 120)) \ + (ert-run-tests-batch-and-exit))" +@end example + +@vindex ert-batch-backtrace-line-length +Even modest settings for @code{print-level} and @code{print-length} can +produce extremely long lines in backtraces, however, with attendant +pauses in execution progress. Set +@code{ert-batch-backtrace-line-length} to t to use the value of +@code{backtrace-line-length}, @code{nil} to stop any limitations on backtrace +line lengths (that is, to get full backtraces), or a positive integer to +limit backtrace line length to that number. + @vindex ert-quiet By default, ERT in batch mode is quite verbose, printing a line with result after each test. This gives you progress information: how many tests have been executed and how many there are. However, in some cases this much output may be undesirable. In this case, set -@code{ert-quiet} variable to a non-nil value: +@code{ert-quiet} variable to a non-@code{nil} value: @example emacs -batch -l ert -l my-tests.el \ @@ -414,10 +441,22 @@ emacs -batch -l ert -l my-tests.el \ -eval '(ert-run-tests-batch-and-exit "to-match")' @end example +@vindex EMACS_TEST_VERBOSE@r{, environment variable} By default, ERT test failure summaries are quite brief in batch 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. +@env{EMACS_TEST_VERBOSE} environment variable is set and is non-empty, +the failure summaries will also include the data from the failing +test. + +@vindex EMACS_TEST_JUNIT_REPORT@r{, environment variable} +ERT can produce JUnit test reports in batch mode. If the environment +variable @env{EMACS_TEST_JUNIT_REPORT} is set, ERT will produce for +every test package @file{my-tests.el} a corresponding JUnit test +report @file{my-tests.xml}. The function +@code{ert-summarize-tests-batch-and-exit} collects all these package +test reports into a new JUnit test report, with the respective name of +that environment variable. + @node Test Selectors @section Test Selectors @@ -486,8 +525,10 @@ 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 @section The @code{should} Macro @@ -768,6 +809,121 @@ 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 @@ -969,6 +1125,7 @@ For information on mocks, stubs, fixtures, or test suites, see below. * Fixtures and Test Suites:: How ERT differs from tools for other languages. @end menu + @node Mocks and Stubs @section Other Tools for Emacs Lisp @cindex mocks and stubs @@ -1043,11 +1200,13 @@ e.g., to run quick tests during interactive development and slow tests less often. This can be achieved with the @code{:tag} argument to @code{ert-deftest} and @code{tag} test selectors. + @node Index @unnumbered Index @printindex cp + @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index f01023a1dca..9f9c88582f3 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -228,15 +228,39 @@ other background process in Emacs. @node Arguments @section Arguments -Command arguments are passed to the functions as either strings or -numbers, depending on what the parser thinks they look like. If you -need to use a function that takes some other data type, you will need to -call it in an Elisp expression (which can also be used with -@ref{Expansion, expansions}). As with other shells, you can -escape special characters and spaces with the backslash (@code{\}) and -apostrophes (@code{''}) and double quotes (@code{""}). This is needed -especially for file names with special characters like pipe -(@code{|}), which could be part of remote file names. +Ordinarily, command arguments are parsed by Eshell as either strings +or numbers, depending on what the parser thinks they look like. To +specify an argument of some other data type, you can use an +@ref{Dollars Expansion, Elisp expression}: + +@example +~ $ echo (list 1 2 3) +(1 2 3) +@end example + +Additionally, many built-in Eshell commands (@pxref{Built-ins, Eshell +commands}) will flatten the arguments they receive, so passing a list +as an argument will ``spread'' the elements into multiple arguments: + +@example +~ $ printnl (list 1 2) 3 +1 +2 +3 +@end example + +@subsection Quoting and escaping + +As with other shells, you can escape special characters and spaces +with by prefixing the character with a backslash (@code{\}), or by +surrounding the string with apostrophes (@code{''}) or double quotes +(@code{""}). This is needed especially for file names with special +characters like pipe (@code{|}), which could be part of remote file +names. + +When using expansions (@pxref{Expansion}) in an Eshell command, the +result may potentially be of any data type. To ensure that the result +is always a string, the expansion can be surrounded by double quotes. @node Built-ins @section Built-in commands @@ -271,8 +295,30 @@ Some of the built-in commands have different behavior from their external counterparts, and some have no external counterpart. Most of these will print a usage message when given the @code{--help} option. +In some cases, a built-in command's behavior can be configured via +user settings, some of which are mentioned below. For example, +certain commands have two user settings to allow them to overwrite +files without warning and to ensure that they always prompt before +overwriting files. If both settings are non-@code{nil}, the commands +always prompt. If both settings are @code{nil} (the default), the +commands signal an error. + +Several commands observe the value of +@code{eshell-default-target-is-dot}. If non-@code{nil}, then the +default target for the commands @command{cp}, @command{mv}, and +@command{ln} is the current directory. + +A few commands are wrappers for more niche Emacs features, and can be +loaded as part of the eshell-xtra module. @xref{Extension modules}. + @table @code +@item . +@cmindex . +Source an Eshell file in the current environment. This is not to be +confused with the command @command{source}, which sources a file in a +subshell environment. + @item addpath @cmindex addpath Adds a given path or set of paths to the PATH environment variable, or, @@ -282,26 +328,144 @@ with no arguments, prints the current paths in this variable. @cmindex alias Define an alias (@pxref{Aliases}). This adds it to the aliases file. +@item basename +@cmindex basename +Return a file name without its directory. + +@item cat +@cmindex cat +Concatenate file contents into standard output. If in a pipeline, or +if the file is not a regular file, directory, or symlink, then this +command reverts to the system's definition of @command{cat}. + +@item cd +@cmindex cd +This command changes the current working directory. Usually, it is +invoked as @kbd{cd @var{dir}} where @file{@var{dir}} is the new +working directory. But @command{cd} knows about a few special +arguments: + +@itemize @minus{} +@item +When it receives no argument at all, it changes to the home directory. + +@item +Giving the command @kbd{cd -} changes back to the previous working +directory (this is the same as @kbd{cd $-}). + +@item +The command @kbd{cd =} shows the directory ring. Each line is +numbered. + +@item +With @kbd{cd =foo}, Eshell searches the directory ring for a directory +matching the regular expression @samp{foo}, and changes to that +directory. + +@item +With @kbd{cd -42}, you can access the directory stack slots by number. + +@item +If @code{eshell-cd-shows-directory} is non-@code{nil}, @command{cd} +will report the directory it changes to. If +@code{eshell-list-files-after-cd} is non-@code{nil}, then @command{ls} +is called with any remaining arguments after changing directories. +@end itemize + @item clear @cmindex clear -Scrolls the contents of the eshell window out of sight, leaving a blank window. -If provided with an optional non-nil argument, the scrollback contents are -cleared instead. +Scrolls the contents of the Eshell window out of sight, leaving a +blank window. If provided with an optional non-@code{nil} argument, +the scrollback contents are cleared instead. + +@item clear-scrollback +@cmindex clear-scrollback +Clear the scrollback contents of the Eshell window. Unlike the +command @command{clear}, this command deletes content in the Eshell +buffer. + +@item cp +@cmindex cp +Copy a file to a new location or copy multiple files to the same +directory. + +If @code{eshell-cp-overwrite-files} is non-@code{nil}, then +@command{cp} will overwrite files without warning. If +@code{eshell-cp-interactive-query} is non-@code{nil}, then +@command{cp} will ask before overwriting anything. @item date @cmindex date -Similar to, but slightly different from, the GNU Coreutils +Print the current local time as a human-readable string. This command +is similar to, but slightly different from, the GNU Coreutils @command{date} command. @item define @cmindex define -Define a varalias. +Define a variable alias. @xref{Variable Aliases, , , elisp, The Emacs Lisp Reference Manual}. @item diff @cmindex diff -Use Emacs's internal @code{diff} (not to be confused with -@code{ediff}). @xref{Comparing Files, , , emacs, The GNU Emacs Manual}. +Compare files using Emacs's internal @code{diff} (not to be confused +with @code{ediff}). @xref{Comparing Files, , , emacs, The GNU Emacs +Manual}. + +If @code{eshell-plain-diff-behavior} is non-@code{nil}, then this +command does not use Emacs's internal @code{diff}. This is the same +as using @samp{alias diff '*diff $*'}. + +@item dirname +@cmindex dirname +Return the directory component of a file name. + +@item dirs +@cmindex dirs +Prints the directory stack. Directories can be added or removed from +the stack using the commands @command{pushd} and @command{popd}, +respectively. + +@item du +@cmindex du +Summarize disk usage for each file. + +@item echo +@cmindex echo +Echoes its input. By default, this prints in a Lisp-friendly fashion +(so that the value is useful to a Lisp command using the result of +@command{echo} as an argument). If a single argument is passed, +@command{echo} prints that; if multiple arguments are passed, it +prints a list of all the arguments; otherwise, it prints the empty +string. + +If @code{eshell-plain-echo-behavior} is non-@code{nil}, @command{echo} +will try to behave more like a plain shell's @command{echo}, printing +each argument as a string, separated by a space. + +@item env +@cmindex env +Prints the current environment variables. Unlike in Bash, this +command does not yet support running commands with a modified +environment. + +@item exit +@cmindex exit +Exit Eshell and save the history. By default, this command kills the +Eshell buffer, but if @code{eshell-kill-on-exit} is @code{nil}, then +the buffer is merely buried instead. + +@item export +@cmindex export +Set environment variables using input like Bash's @command{export}, as +in @samp{export @var{var1}=@var{val1} @var{var2}=@var{val2} @dots{}}. + +@item expr +@cmindex expr +An implementation of @command{expr} using the Calc package. +@xref{Top,,, calc, The GNU Emacs Calculator}. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. @item grep @cmindex grep @@ -313,13 +477,36 @@ Use Emacs's internal @code{diff} (not to be confused with @cmindex fgrep @itemx glimpse @cmindex glimpse -The @command{grep} commands are compatible with GNU @command{grep}, but -use Emacs's internal @code{grep} instead. +The @command{grep} commands are compatible with GNU @command{grep}, +but use Emacs's internal @code{grep} instead. +@xref{Grep Searching, , , emacs, The GNU Emacs Manual}. + +If @code{eshell-plain-grep-behavior} is non-@code{nil}, then these +commands do not use Emacs's internal @code{grep}. This is the same as +using @samp{alias grep '*grep $*'}, though this setting applies to all +of the built-in commands for which you would need to create a separate +alias. + +@item history +@cmindex history +Prints Eshell's input history. With a numeric argument @var{N}, this +command prints the @var{N} most recent items in the history. @item info @cmindex info -Same as the external @command{info} command, but uses Emacs's internal -Info reader. +Browse the available Info documentation. This command is the same as +the external @command{info} command, but uses Emacs's internal Info +reader. +@xref{Misc Help, , , emacs, The GNU Emacs Manual}. + +@item intersection +@cmindex intersection +A wrapper around the function @code{cl-intersection} (@pxref{Lists as +Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command +can be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. @item jobs @cmindex jobs @@ -337,46 +524,152 @@ Eshell version of @code{list}. Allows you to create a list using Eshell syntax, rather than Elisp syntax. For example, @samp{listify foo bar} and @code{("foo" "bar")} both evaluate to @code{("foo" "bar")}. +@item ln +@cmindex ln +Create links to files. + +If @code{eshell-ln-overwrite-files} is non-@code{nil}, @command{ln} +will overwrite files without warning. If +@code{eshell-ln-interactive-query} is non-@code{nil}, then +@command{ln} will ask before overwriting files. + @item locate @cmindex locate Alias to Emacs's @code{locate} function, which simply runs the external @command{locate} command and parses the results. @xref{Dired and Find, , , emacs, The GNU Emacs Manual}. +If @code{eshell-plain-locate-behavior} is non-@code{nil}, then Emacs's +internal @code{locate} is not used. This is the same as using +@samp{alias locate '*locate $*'}. + +@item ls +@cmindex ls +Lists the contents of directories. + +If @code{eshell-ls-use-colors} is non-@code{nil}, the contents of a +directory is color-coded according to file type and status. These +colors and the regexps used to identify their corresponding files can +be customized via @w{@kbd{M-x customize-group @key{RET} eshell-ls @key{RET}}}. + +The user option @code{eshell-ls-date-format} determines how the date +is displayed when using the @option{-l} option. The date is produced +using the function @code{format-time-string} (@pxref{Time Parsing,,, +elisp, GNU Emacs Lisp Reference Manual}). + +The user option @code{eshell-ls-initial-args} contains a list of +arguments to include with any call to @command{ls}. For example, you +can include the option @option{-h} to always use a more human-readable +format. + +The user option @code{eshell-ls-default-blocksize} determines the +default blocksize used when displaying file sizes with the option +@option{-s}. + @item make @cmindex make Run @command{make} through @code{compile} when run asynchronously (e.g., @samp{make &}). @xref{Compilation, , , emacs, The GNU Emacs Manual}. Otherwise call the external @command{make} command. +@item man +@cmindex man +Display Man pages using the Emacs @code{man} command. +@xref{Man Page, , , emacs, The GNU Emacs Manual}. + +@item mismatch +@cmindex mismatch +A wrapper around the function @code{cl-mismatch} (@pxref{Searching +Sequences,,, cl, GNU Emacs Common Lisp Emulation}). This command can +be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item mkdir +@cmindex mkdir +Make new directories. + +@item mv +@cmindex mv +Move or rename files. + +If @code{eshell-mv-overwrite-files} is non-@code{nil}, @command{mv} +will overwrite files without warning. If +@code{eshell-mv-interactive-query} is non-@code{nil}, @command{mv} +will prompt before overwriting anything. + @item occur @cmindex occur Alias to Emacs's @code{occur}. @xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}. +@item popd +@cmindex popd +Pop a directory from the directory stack and switch to a another place +in the stack. + @item printnl @cmindex printnl Print the arguments separated by newlines. -@item cd -@cmindex cd -This command changes the current working directory. Usually, it is -invoked as @samp{cd foo} where @file{foo} is the new working directory. -But @command{cd} knows about a few special arguments: - -When it receives no argument at all, it changes to the home directory. - -Giving the command @samp{cd -} changes back to the previous working -directory (this is the same as @samp{cd $-}). - -The command @samp{cd =} shows the directory stack. Each line is -numbered. - -With @samp{cd =foo}, Eshell searches the directory stack for a directory -matching the regular expression @samp{foo} and changes to that -directory. - -With @samp{cd -42}, you can access the directory stack by number. +@item pushd +@cmindex pushd +Push the current directory onto the directory stack, then change to +another directory. + +If @code{eshell-pushd-dunique} is non-@code{nil}, then only unique +directories will be added to the stack. If +@code{eshell-pushd-dextract} is non-@code{nil}, then @samp{pushd ++@var{n}} will pop the @var{n}th directory to the top of the stack. + +@item pwd +@cmindex pwd +Prints the current working directory. + +@item rm +@cmindex rm +Removes files, buffers, processes, or Emacs Lisp symbols, depending on +the argument. + +If @code{eshell-rm-interactive-query} is non-@code{nil}, @command{rm} +will prompt before removing anything. If +@code{eshell-rm-removes-directories} is non-@code{nil}, then +@command{rm} can also remove directories. Otherwise, @command{rmdir} +is required. + +@item rmdir +@cmindex rmdir +Removes directories if they are empty. + +@item set-difference +@cmindex set-difference +A wrapper around the function @code{cl-set-difference} (@pxref{Lists as +Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command +can be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item set-exclusive-or +@cmindex set-exclusive-or +A wrapper around the function @code{cl-set-exclusive-or} (@pxref{Lists +as Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command can be +used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item setq +@cmindex setq +Set variable values, using the function @code{setq} like a command. +@xref{Setting Variables,,, elisp, GNU Emacs Lisp Reference Manual}. + +@item source +@cmindex source +Source an Eshell file in a subshell environment. This is not to be +confused with the command @command{.}, which sources a file in the +current environment. @item su @cmindex su @@ -386,48 +679,239 @@ Uses TRAMP's @command{su} or @command{sudo} method @pxref{Inline methods, , , tr to run a command via @command{su} or @command{sudo}. These commands are in the eshell-tramp module, which is disabled by default. + +@item substitute +@cmindex substitute +A wrapper around the function @code{cl-substitute} (@pxref{Sequence +Functions,,, cl, GNU Emacs Common Lisp Emulation}). This command can +be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item time +@cmindex time +Show the time elapsed during a command's execution. + +@item umask +@cmindex umask +Set or view the default file permissions for newly created files and +directories. + +@item union +@cmindex union +A wrapper around the function @code{cl-union} (@pxref{Lists as Sets,,, +cl, GNU Emacs Common Lisp Emulation}). This command can be used for +comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item unset +@cmindex unset +Unset an environment variable. + +@item wait +@cmindex wait +Wait until a process has successfully completed. + +@item which +@cmindex which +Identify a command and its location. + +@item whoami +@cmindex whoami +Print the current user. This Eshell version of @command{whoami} +supports Tramp. +@end table + +@subsection Defining new built-in commands +While Eshell can run Lisp functions directly as commands, it may be +more convenient to provide a special built-in command for +Eshell. Built-in commands are just ordinary Lisp functions designed +to be called from Eshell. When defining an Eshell-specific version of +an existing function, you can give that function a name starting with +@code{eshell/} so that Eshell knows to use it. + +@defmac eshell-eval-using-options name macro-args options body@dots{} +This macro processes a list of @var{macro-args} for the command +@var{name} using a set of command line @var{options}. If the +arguments are parsed successfully, it will store the resulting values +in local symbols and execute @var{body}; any remaining arguments will +be available in the locally let-bound variable @code{args}. The +return value is the value of the last form in @var{body}. + +If an unknown option was passed in @var{macro-args} and an external +command was specified (see below), this macro will start a process for +that command and throw the tag @code{eshell-external} with the new +process as its value. + +@var{options} should be a list beginning with one or more elements of +the following form, with each element representing a particular +command-line switch: + +@example +(@var{short} @var{long} @var{value} @var{symbol} @var{help-string}) +@end example + +@table @var +@item short +This element, if non-nil, should be a character to be used as a short +switch, like @code{-@var{short}}. At least one of this element and +@var{long} must be non-nil. + +@item long +This element, if non-nil, should be a string to be used as a long +switch, like @code{--@var{long}}. + +@item value +This element is the value associated with the option. It can be +either: + +@table @asis +@item @code{t} +The option needs a value to be specified after the switch. + +@item @code{nil} +The option is given the value @code{t}. + +@item anything else +The option is given the specified value. @end table +@item symbol +This element is the Lisp symbol that will be bound to @var{value}. If +@var{symbol} is @code{nil}, specifying this switch will instead call +@code{eshell-show-usage}, and so is appropriate for an option like +@code{--help}. + +@item help-string +This element is a documentation string for the option, which will be +displayed when @code{eshell-show-usage} is invoked. +@end table + +After the list of command-line switch elements, @var{options} can +include additional keyword arguments to control how +@code{eshell-eval-using-options} behaves. Some of these take +arguments, while others don't. The recognized keywords are: + +@table @code +@item :external @var{string} +Specify @var{string} as an external command to run if there are +unknown switches in @var{macro-args}. + +@item :usage @var{string} +Set @var{string} as the initial part of the command's documentation +string. It appears before the options are listed. + +@item :post-usage @var{string} +Set @var{string} to be the (optional) trailing part of the command's +documentation string. It appears after the list of options, but +before the final part of the documentation about the associated +external command, if there is one. + +@item :show-usage +If present, then show the usage message if the command is called with +no arguments. + +@item :preserve-args +Normally, @code{eshell-eval-using-options} flattens the list of +arguments in @var{macro-args} and converts each to a string. If this +keyword is present, avoid doing that, instead preserving the original +arguments. This is useful for commands which want to accept arbitrary +Lisp objects. + +@item :parse-leading-options-only +If present, do not parse dash or switch arguments after the first +positional argument. Instead, treat them as positional arguments +themselves. +@end table + +For example, you could handle a subset of the options for the +@code{ls} command like this: + +@example +(eshell-eval-using-options + "ls" macro-args + '((?a nil nil show-all "show all files") + (?I "ignore" t ignore-pattern "ignore files matching pattern") + (nil "help" nil nil "show this help message") + :external "ls" + :usage "[OPTION]... [FILE]... + List information about FILEs (the current directory by default).") + ;; List the files in ARGS somehow... + ) +@end example + +@end defmac + +@node Variables +@section Variables +Since Eshell is just an Emacs @acronym{REPL}@footnote{ +Short for ``Read-Eval-Print Loop''. +} +, it does not have its own scope, and simply stores variables the same +you would in an Elisp program. Eshell provides a command version of +@code{setq} for convenience. + @subsection Built-in variables Eshell knows a few built-in variables: @table @code -@item $+ +@vindex $PWD @vindex $+ +@item $PWD +@itemx $+ This variable always contains the current working directory. -@item $- +@vindex $OLDPWD @vindex $- +@item $OLDPWD +@itemx $- This variable always contains the previous working directory (the current working directory from before the last @code{cd} command). +When using @code{$-}, you can also access older directories in the +directory ring via subscripting, e.g.@: @samp{$-[1]} refers to the +working directory @emph{before} the previous one. -@item $_ @vindex $_ -It refers to the last argument of the last command. +@item $_ +This refers to the last argument of the last command. With a +subscript, you can access any argument of the last command. For +example, @samp{$_[1]} refers to the second argument of the last +command (excluding the command name itself). -@item $$ @vindex $$ +@item $$ This is the result of the last command. In case of an external command, it is @code{t} or @code{nil}. -@item $? @vindex $? -This variable contains the exit code of the last command (0 or 1 for -Lisp functions, based on successful completion). +@item $? +This variable contains the exit code of the last command. If the last +command was a Lisp function, it is 0 for successful completion or 1 +otherwise. + +@vindex $COLUMNS +@vindex $LINES +@item $COLUMNS +@itemx $LINES +These variables tell the number of columns and lines, respectively, +that are currently visible in the Eshell window. They are both +copied to the environment, so external commands invoked from +Eshell can consult them to do the right thing. + +@item $INSIDE_EMACS +This variable indicates to external commands that they are being +invoked from within Emacs so they can adjust their behavior if +necessary. Its value is @code{@var{emacs-version},eshell}. @end table @xref{Aliases}, for the built-in variables @samp{$*}, @samp{$1}, @samp{$2}, @dots{}, in alias definitions. -@node Variables -@section Variables -Since Eshell is just an Emacs REPL@footnote{Read-Eval-Print Loop}, it -does not have its own scope, and simply stores variables the same you -would in an Elisp program. Eshell provides a command version of -@code{setq} for convenience. - @node Aliases @section Aliases @@ -560,15 +1044,42 @@ parsers (such as @command{cpp} and @command{m4}), but in a command shell, they are less often used for constants, and usually for using variables and string manipulation.@footnote{Eshell has no string-manipulation expansions because the Elisp library already -provides many functions for this.} For example, @code{$var} on a line -expands to the value of the variable @code{var} when the line is +provides many functions for this.} For example, @code{$@var{var}} on +a line expands to the value of the variable @var{var} when the line is executed. Expansions are usually passed as arguments, but may also be -used as commands.@footnote{E.g., entering just @samp{$var} at the prompt -is equivalent to entering the value of @code{var} at the prompt.} +used as commands.@footnote{E.g., entering just @samp{$@var{var}} at +the prompt is equivalent to entering the value of @var{var} at the +prompt.} + +You can concatenate expansions with regular string arguments or even +other expansions. In the simplest case, when the expansion returns a +string value, this is equivalent to ordinary string concatenation; for +example, @samp{$@{echo "foo"@}bar} returns @samp{foobar}. The exact +behavior depends on the types of each value being concatenated: + +@table @asis + +@item both strings +Concatenate both values together. + +@item one or both numbers +Concatenate the string representation of each value, converting back to +a number if possible. + +@item one or both (non-@code{nil}) lists +Concatenate ``adjacent'' elements of each value (possibly converting +back to a number as above). For example, @samp{$list("a" "b")c} +returns @samp{("a" "bc")}. + +@item anything else +Concatenate the string representation of each value. + +@end table @menu * Dollars Expansion:: * Globbing:: +* Argument Predication and Modification:: @end menu @node Dollars Expansion @@ -589,67 +1100,423 @@ Expands to the value bound to @var{var}. This is useful to disambiguate the variable name when concatenating it with another value, such as @samp{$"@var{var}"-suffix}. -@item $#@var{var} -Expands to the length of the value bound to @var{var}. Raises an error -if the value is not a sequence -(@pxref{Sequences Arrays Vectors, Sequences, , elisp, The Emacs Lisp Reference Manual}). - @item $(@var{lisp}) Expands to the result of evaluating the S-expression @code{(@var{lisp})}. On its own, this is identical to just @code{(@var{lisp})}, but with the @code{$}, -it can be used in a string, such as @samp{/some/path/$(@var{lisp}).txt}. +it can be used inside double quotes or within a longer string, such as +@samp{/some/path/$(@var{lisp}).txt}. @item $@{@var{command}@} -Returns the output of @command{@var{command}}, which can be any valid Eshell -command invocation, and may even contain expansions. +Returns the output of @command{@var{command}}, which can be any valid +Eshell command invocation, and may even contain expansions. Similar +to @code{$(@var{lisp})}, this is identical to @code{@{@var{command}@}} +when on its own, but the @code{$} allows it to be used inside double +quotes or as part of a string. + +Normally, the output is split line-by-line, returning a list (or the +first element if there's only one line of output); if +@code{eshell-convert-numeric-arguments} is non-@code{nil} and every +line of output looks like a number, convert each line to a number. +However, when this expansion is surrounded by double quotes, it +returns the output as a single string instead. @item $<@var{command}> As with @samp{$@{@var{command}@}}, evaluates the Eshell command invocation @command{@var{command}}, but writes the output to a temporary file and returns the file name. -@item $@var{var}[i] -Expands to the @code{i}th element of the value bound to @var{var}. If -the value is a string, it will be split at whitespace to make it a list. -Again, raises an error if the value is not a sequence. +@item $@var{expr}[@var{i...}] +Expands to the @var{i}th element of the result of @var{expr}, an +expression in one of the above forms listed here. If multiple indices +are supplied, this will return a list containing the elements for each +index. The exact behavior depends on the type of @var{expr}'s value: -@item $@var{var}[: i] -As above, but now splitting occurs at the colon character. +@table @asis -@item $@var{var}[: i j] -As above, but instead of returning just a string, it now returns a list -of two strings. If the result is being interpolated into a larger -string, this list will be flattened into one big string, with each -element separated by a space. +@item a sequence +Expands to the element at the (zero-based) index @var{i} of the +sequence (@pxref{Sequences Arrays Vectors, Sequences, , elisp, The +Emacs Lisp Reference Manual}). -@item $@var{var}["\\\\" i] -Separate on backslash characters. Actually, the first argument -- if it -doesn't have the form of a number, or a plain variable name -- can be -any regular expression. So to split on numbers, use -@samp{$@var{var}["[0-9]+" 10 20]}. +@item a string +Split the string at whitespace, and then expand to the @var{i}th +element of the resulting sequence. -@item $@var{var}[hello] -Calls @code{assoc} on @var{var} with @code{"hello"}, expecting it to be -an alist (@pxref{Association List Type, Association Lists, , elisp, -The Emacs Lisp Reference Manual}). +@item an alist +If @var{i} is a non-numeric value, expand to the value associated with +the key @code{"@var{i}"} in the alist. For example, if @var{var} is +@samp{(("dog" . "fido") ("cat" . "felix"))}, then +@samp{$@var{var}[dog]} expands to @code{"fido"}. Otherwise, this +behaves as with sequences; e.g., @samp{$@var{var}[0]} expands to +@code{("dog" . "fido")}. @xref{Association List Type, Association +Lists, , elisp, The Emacs Lisp Reference Manual}. -@item $#@var{var}[hello] -Returns the length of the @code{cdr} of the element of @var{var} whose -car is equal to @code{"hello"}. +@item anything else +Signals an error. + +@end table + +Multiple sets of indices can also be specified. For example, if +@var{var} is @samp{((1 2) (3 4))}, then @samp{$@var{var}[0][1]} will +expand to @code{2}, i.e.@: the second element of the first list member +(all indices are zero-based). + +@item $@var{expr}[@var{regexp} @var{i...}] +As above (when @var{expr} expands to a string), but use @var{regexp} +to split the string. @var{regexp} can be any form other than a +number. For example, @samp{$@var{var}[: 0]} will return the first +element of a colon-delimited string. + +@item $#@var{expr} +Expands to the length of the result of @var{expr}, an expression in +one of the above forms. For example, @samp{$#@var{var}} returns the +length of the variable @var{var} and @samp{$#@var{var}[0]} returns the +length of the first element of @var{var}. Again, signals an error if +the result of @var{expr} is not a string or a sequence. @end table @node Globbing @section Globbing -Eshell's globbing syntax is very similar to that of Zsh. Users coming -from Bash can still use Bash-style globbing, as there are no -incompatibilities. Most globbing is pattern-based expansion, but there -is also predicate-based expansion. @xref{Filename Generation, , , -zsh, The Z Shell Manual}, -for full syntax. To customize the syntax and behavior of globbing in -Eshell see the Customize@footnote{@xref{Easy Customization, , , emacs, -The GNU Emacs Manual}.} -groups ``eshell-glob'' and ``eshell-pred''. +@vindex eshell-glob-case-insensitive +Eshell's globbing syntax is very similar to that of Zsh +(@pxref{Filename Generation, , , zsh, The Z Shell Manual}). Users +coming from Bash can still use Bash-style globbing, as there are no +incompatibilities. + +By default, globs are case sensitive, except on MS-DOS/MS-Windows +systems. You can control this behavior via the +@code{eshell-glob-case-insensitive} option. You can further customize +the syntax and behavior of globbing in Eshell via the Customize group +``eshell-glob'' (@pxref{Easy Customization, , , emacs, The GNU Emacs +Manual}). + +@table @samp + +@item * +Matches any string (including the empty string). For example, +@samp{*.el} matches any file with the @file{.el} extension. + +@item ? +Matches any single character. For example, @samp{?at} matches +@file{cat} and @file{bat}, but not @file{goat}. + +@item **/ +Matches zero or more subdirectories in a file name. For example, +@samp{**/foo.el} matches @file{foo.el}, @file{bar/foo.el}, +@file{bar/baz/foo.el}, etc. Note that this cannot be combined with +any other patterns in the same file name segment, so while +@samp{foo/**/bar.el} is allowed, @samp{foo**/bar.el} is not. + +@item ***/ +Like @samp{**/}, but follows symlinks as well. + +@cindex character sets, in Eshell glob patterns +@cindex character classes, in Eshell glob patterns +@item [ @dots{} ] +Defines a @dfn{character set} (@pxref{Regexps, , , emacs, The GNU +Emacs Manual}). A character set matches characters between the two +brackets; for example, @samp{[ad]} matches @file{a} and @file{d}. You +can also include ranges of characters in the set by separating the +start and end with @samp{-}. Thus, @samp{[a-z]} matches any +lower-case @acronym{ASCII} letter. Note that, unlike in Zsh, +character ranges are interpreted in the Unicode codepoint order, not +in the locale-dependent collation order. + +Additionally, you can include @dfn{character classes} in a character +set. A @samp{[:} and balancing @samp{:]} enclose a character class +inside a character set. For instance, @samp{[[:alnum:]]} +matches any letter or digit. @xref{Char Classes, , , elisp, The Emacs +Lisp Reference Manual}, for a list of character classes. + +@cindex complemented character sets, in Eshell glob patterns +@item [^ @dots{} ] +Defines a @dfn{complemented character set}. This behaves just like a +character set, but matches any character @emph{except} the ones +specified. + +@cindex groups, in Eshell glob patterns +@item ( @dots{} ) +Defines a @dfn{group}. A group matches the pattern between @samp{(} +and @samp{)}. Note that a group can only match a single file name +component, so a @samp{/} inside a group will signal an error. + +@item @var{x}|@var{y} +Inside of a group, matches either @var{x} or @var{y}. For example, +@samp{e(m|sh)-*} matches any file beginning with @file{em-} or +@file{esh-}. + +@item @var{x}# +Matches zero or more copies of the glob pattern @var{x}. For example, +@samp{fo#.el} matches @file{f.el}, @file{fo.el}, @file{foo.el}, etc. + +@item @var{x}## +Matches one or more copies of the glob pattern @var{x}. Thus, +@samp{fo#.el} matches @file{fo.el}, @file{foo.el}, @file{fooo.el}, +etc. + +@item @var{x}~@var{y} +Matches anything that matches the pattern @var{x} but not @var{y}. For +example, @samp{[[:digit:]]#~4?} matches @file{1} and @file{12}, but +not @file{42}. Note that unlike in Zsh, only a single @samp{~} +operator can be used in a pattern, and it cannot be inside of a group +like @samp{(@var{x}~@var{y})}. + +@end table + +@node Argument Predication and Modification +@section Argument Predication and Modification +@cindex argument predication +@cindex argument modification +Eshell supports @dfn{argument predication}, to filter elements of a +glob, and @dfn{argument modification}, to manipulate argument values. +These are similar to glob qualifiers in Zsh (@pxref{Glob Qualifiers, , +, zsh, The Z Shell Manual}). + +Predicates and modifiers are introduced with @samp{(@var{filters})} +after any list argument, where @var{filters} is a list of predicates +or modifiers. For example, @samp{*(.)} expands to all regular files +in the current directory and @samp{*(^@@:U^u0)} expands to all +non-symlinks not owned by @code{root}, upper-cased. + +Some predicates and modifiers accept string parameters, such as +@samp{*(u'@var{user}')}, which matches all files owned by @var{user}. +These parameters must be surrounded by delimiters; you can use any of +the following pairs of delimiters: @code{"@dots{}"}, @code{'@dots{}'}, +@code{/@dots{}/}, @code{|@dots{}|}, @code{(@dots{})}, +@code{[@dots{}]}, @code{<@dots{}>}, or @code{@{@dots{}@}}. + +You can customize the syntax and behavior of predicates and modifiers +in Eshell via the Customize group ``eshell-pred'' (@pxref{Easy +Customization, , , emacs, The GNU Emacs Manual}). + +@menu +* Argument Predicates:: +* Argument Modifiers:: +@end menu + +@node Argument Predicates +@subsection Argument Predicates +You can use argument predicates to filter lists of file names based on +various properties of those files. This is most useful when combined +with globbing, but can be used on any list of files names. Eshell +supports the following argument predicates: + +@table @asis + +@item @samp{/} +Matches directories. + +@item @samp{.} @r{(Period)} +Matches regular files. + +@item @samp{@@} +Matches symbolic links. + +@item @samp{=} +Matches sockets. + +@item @samp{p} +Matches named pipes. + +@item @samp{%} +Matches block or character devices. + +@item @samp{%b} +Matches block devices. + +@item @samp{%c} +Matches character devices. + +@item @samp{*} +Matches regular files that can be executed by the current user. + +@item @samp{r} +@item @samp{A} +@item @samp{R} +Matches files that are readable by their owners (@samp{r}), their +groups (@samp{A}), or the world (@samp{R}). + +@item @samp{w} +@item @samp{I} +@item @samp{W} +Matches files that are writable by their owners (@samp{w}), their +groups (@samp{I}), or the world (@samp{W}). + +@item @samp{x} +@item @samp{E} +@item @samp{X} +Matches files that are executable by their owners (@samp{x}), their +groups (@samp{E}), or the world (@samp{X}). + +@item @samp{s} +Matches files with the setuid flag set. + +@item @samp{S} +Matches files with the setgid flag set. + +@item @samp{t} +Matches files with the sticky bit set. + +@item @samp{U} +Matches files owned by the current effective user ID. + +@item @samp{G} +Matches files owned by the current effective group ID. + +@item @samp{l@option{[+-]}@var{n}} +Matches files with @var{n} links. With @option{+} (or @option{-}), +matches files with more than (or less than) @var{n} links, +respectively. + +@item @samp{u@var{uid}} +@item @samp{u'@var{user-name}'} +Matches files owned by user ID @var{uid} or user name @var{user-name}. + +@item @samp{g@var{gid}} +@item @samp{g'@var{group-name}'} +Matches files owned by group ID @var{gid} or group name +@var{group-name}. + +@item @samp{a@option{[@var{unit}]}@option{[+-]}@var{n}} +@item @samp{a@option{[+-]}'@var{file}'} +Matches files last accessed exactly @var{n} days ago. With @option{+} +(or @option{-}), matches files accessed more than (or less than) +@var{n} days ago, respectively. + +With @var{unit}, @var{n} is a quantity in that unit of time, so +@samp{aw-1} matches files last accessed within one week. @var{unit} +can be @samp{M} (30-day months), @samp{w} (weeks), @samp{h} (hours), +@samp{m} (minutes), or @samp{s} (seconds). + +If @var{file} is specified instead, compare against the modification +time of @file{file}. Thus, @samp{a-'hello.txt'} matches all files +accessed after @file{hello.txt} was last accessed. + +@item @samp{m@option{[@var{unit}]}@option{[+-]}@var{n}} +@item @samp{m@option{[+-]}'@var{file}'} +Like @samp{a}, but examines modification time. + +@item @samp{c@option{[@var{unit}]}@option{[+-]}@var{n}} +@item @samp{c@option{[+-]}'@var{file}'} +Like @samp{a}, but examines status change time. + +@item @samp{L@option{[@var{unit}]}@option{[+-]}@var{n}} +Matches files exactly @var{n} bytes in size. With @option{+} (or +@option{-}), matches files larger than (or smaller than) @var{n} +bytes, respectively. + +With @var{unit}, @var{n} is a quantity in that unit of size, so +@samp{Lm+5} matches files larger than 5 MiB in size. @var{unit} can +be one of the following (case-insensitive) characters: @samp{m} +(megabytes), @samp{k} (kilobytes), or @samp{p} (512-byte blocks). + +@end table + +The @samp{^} and @samp{-} operators are not argument predicates +themselves, but they modify the behavior of all subsequent predicates. +@samp{^} inverts the meaning of subsequent predicates, so +@samp{*(^RWX)} expands to all files whose permissions disallow the +world from accessing them in any way (i.e., reading, writing to, or +modifying them). When examining a symbolic link, @samp{-} applies the +subsequent predicates to the link's target instead of the link itself. + +@node Argument Modifiers +@subsection Argument Modifiers +You can use argument modifiers to manipulate argument values. For +example, you can sort lists, remove duplicate values, capitalize +words, etc. All argument modifiers are prefixed by @samp{:}, so +@samp{$exec-path(:h:u:x/^\/home/)} lists all of the unique parent +directories of the elements in @code{exec-path}, excluding those in +@file{/home}. + +@table @samp + +@item E +Re-evaluates the value as an Eshell argument. For example, if +@var{foo} is @code{"$@{echo hi@}"}, then the result of @samp{$foo(:E)} +is @code{hi}. + +@item L +Converts the value to lower case. + +@item U +Converts the value to upper case. + +@item C +Capitalizes the value. + +@item h +Treating the value as a file name, gets the directory name (the +``head''). For example, @samp{foo/bar/baz.el(:h)} expands to +@samp{foo/bar/}. + +@item t +Treating the value as a file name, gets the base name (the ``tail''). +For example, @samp{foo/bar/baz.el(:h)} expands to @samp{baz.el}. + +@item e +Treating the value as a file name, gets the final extension of the +file, excluding the dot. For example, @samp{foo.tar.gz(:e)} +expands to @code{gz}. + +@item r +Treating the value as a file name, gets the file name excluding the +final extension. For example, @samp{foo/bar/baz.tar.gz(:r)} expands +to @samp{foo/bar/baz.tar}. + +@item q +Marks that the value should be interpreted by Eshell literally, so +that any special characters like @samp{$} no longer have any special +meaning. + +@item s/@var{pattern}/@var{replace}/ +Replaces the first instance of the regular expression @var{pattern} +with @var{replace}. Signals an error if no match is found. + +As with other modifiers taking string parameters, you can use +different delimiters to separate @var{pattern} and @var{replace}, such +as @samp{s'@dots{}'@dots{}'}, @samp{s[@dots{}][@dots{}]}, or even +@samp{s[@dots{}]/@dots{}/}. + +@item gs/@var{pattern}/@var{replace}/ +Replaces all instances of the regular expression @var{pattern} with +@var{replace}. + +@item i/@var{pattern}/ +Filters a list of values to include only the elements matching the +regular expression @var{pattern}. + +@item x/@var{pattern}/ +Filters a list of values to exclude all the elements matching the +regular expression @var{pattern}. + +@item S +@item S/@var{pattern}/ +Splits the value using the regular expression @var{pattern} as a +delimiter. If @var{pattern} is omitted, split on spaces. + +@item j +@item j/@var{delim}/ +Joins a list of values, inserting the string @var{delim} between each +value. If @var{delim} is omitted, use a single space as the +delimiter. + +@item o +Sorts a list of strings in ascending lexicographic order, comparing +pairs of characters according to their character codes (@pxref{Text +Comparison, , , elisp, The Emacs Lisp Reference Manual}). + +@item O +Sorts a list of strings in descending lexicographic order. + +@item u +Removes any duplicate elements from a list of values. + +@item R +Reverses the order of a list of values. + +@end table @node Input/Output @chapter Input/Output @@ -721,6 +1588,48 @@ the output function. The output function is called once on each line of output until @code{nil} is passed, indicating end of output. +@section Running Shell Pipelines Natively +When constructing shell pipelines that will move a lot of data, it is +a good idea to bypass Eshell's own pipelining support and use the +operating system shell's instead. This is especially relevant when +executing commands on a remote machine using Eshell's Tramp +integration: using the remote shell's pipelining avoids copying the +data which will flow through the pipeline to local Emacs buffers and +then right back again. + +Eshell recognizes a special syntax to make it easier to convert +pipelines so as to bypass Eshell's pipelining. Prefixing at least one +@code{|}, @code{<} or @code{>} with an asterisk marks a command as +intended for the operating system shell. To make it harder to invoke +this functionality accidentally, it is also required that the asterisk +be preceded by whitespace or located at the start of input. For +example, + +@example + cat *.ogg *| my-cool-decoder >file +@end example + +Executing this command will not copy all the data in the *.ogg files, +nor the decoded data, into Emacs buffers, as would normally happen. + +The command is interpreted as extending up to the next @code{|} +character which is not preceded by an unescaped asterisk following +whitespace, or the end of the input if there is no such character. +Thus, all @code{<} and @code{>} redirections occurring before the next +asterisk-unprefixed @code{|} are implicitly prefixed with (whitespace +and) asterisks. An exception is that Eshell-specific redirects right +at the end of the command are excluded. This allows input like this: + +@example + foo *| baz >#<buffer quux> +@end example + +@noindent which is equivalent to input like this: + +@example + sh -c "foo | baz" >#<buffer quux> +@end example + @node Extension modules @chapter Extension modules Eshell provides a facility for defining extension modules so that they @@ -751,6 +1660,7 @@ Eshell module.} You also need to load the following as shown: * Key rebinding:: * Smart scrolling:: * Terminal emulation:: +* Electric forward slash:: @end menu @node Writing a module @@ -783,6 +1693,61 @@ This section is not yet written. This section is not yet written. +@node Electric forward slash +@section Electric forward slash + +To help with supplying absolute file name arguments to remote +commands, you can add the @code{eshell-elecslash} module to +@code{eshell-modules-list}. Then, typing @kbd{/} as the first +character of a command line argument will automatically insert the +Tramp prefix @file{/method:host:}. If this is not what you want +(e.g.@: because you want to refer to a local file), you can type +another @kbd{/} to undo the automatic insertion. Typing @kbd{~/} also +inserts the Tramp prefix. The automatic insertion applies only when +@code{default-directory} is remote and the command is a Lisp function. +In particular, typing arguments to external commands doesn't insert +the prefix. + +The result is that in most cases of supplying absolute file name +arguments to commands you should see the Tramp prefix inserted +automatically only when that's what you'd reasonably expect. This +frees you from having to keep track of whether commands are Lisp +functions or external when typing command line arguments. For +example, suppose you execute + +@example + cd /ssh:root@@example.com: + find /etc -name "*gnu*" +@end example + +@noindent and in reviewing the output of the command, you identify a +file @file{/etc/gnugnu} that should be moved somewhere else. So you +type + +@example + mv /etc/gnugnu /tmp +@end example + +@noindent But since @command{mv} refers to the local Lisp function +@code{eshell/mv}, not a remote shell command, to say this is to +request that the local file @file{/etc/gnugnu} be moved into the local +@file{/tmp} directory. After you add @code{eshell-elecslash} to +@code{eshell-modules-list}, then when you type the above @command{mv} +invocation you will get the following input, which is what you +intended: + +@example + mv /ssh:root@@example.com:/etc/gnugnu /ssh:root@@example.com:/tmp +@end example + +The code that determines whether or not the Tramp prefix should be +inserted uses simple heuristics. A limitation of the current +implementation is that it inspects whether only the command at the +very beginning of input is a Lisp function or external program. Thus +when chaining commands with the operators @code{&&}, @code{||}, +@code{|} and @code{;}, the electric forward slash is active only +within the first command. + @node Bugs and ideas @chapter Bugs and ideas @cindex reporting bugs and ideas @@ -820,14 +1785,6 @@ alias arg=blah function arg () @{ blah $* @} @end example -@item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt - -In fact, piping to a process from a looping construct doesn't work in -general. If I change the call to @code{eshell-copy-handles} in -@code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems -to work, but the output occurs after the prompt is displayed. The whole -structured command thing is too complicated at present. - @item Pcomplete sometimes gets stuck You press @key{TAB}, but no completions appear, even though the @@ -972,11 +1929,6 @@ glob match. At the moment, this is not supported. -@item Error if a glob doesn't expand due to a predicate - -An error should be generated only if @code{eshell-error-if-no-glob} is -non-@code{nil}. - @item @samp{(+ @key{RET} @key{SPC} @key{TAB}} does not cause @code{indent-according-to-mode} to occur @item Create @code{eshell-auto-accumulate-list} @@ -1152,11 +2104,10 @@ it). @item Make the shell spawning commands be visual -That is, make (@command{su}, @command{bash}, @command{telnet}, -@command{rlogin}, @command{rsh}, etc.)@: be part of -@code{eshell-visual-commands}. The only exception is if the shell is -being used to invoke a single command. Then, the behavior should be -based on what that command is. +That is, make (@command{su}, @command{bash}, @command{ssh}, etc.)@: be +part of @code{eshell-visual-commands}. The only exception is if the +shell is being used to invoke a single command. Then, the behavior +should be based on what that command is. @item Create a smart viewing command named @command{open} @@ -1186,11 +2137,12 @@ only. That way, it could be listed as a login shell. @item The first keypress after @kbd{M-x watson} triggers @code{eshell-send-input} -@item Make @kbd{/} electric +@item Make @kbd{/} more electric -So that it automatically expands and corrects pathnames. Or make -pathname completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to -@samp{/usr/include/std@key{TAB}}. +@noindent so that it automatically expands and corrects file names, +beyond what the @code{em-elecslash} module is able to do. Or make +file name completion for Pcomplete auto-expand +@samp{/u/i/std@key{TAB}} to @samp{/usr/include/std@key{TAB}}. @item Write the @command{pushd} stack to disk along with @code{last-dir-ring} diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index e9cf4cfade9..0037ba78d3b 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -192,9 +192,9 @@ email composition buffers (@pxref{Inline Query Expansion}) @lisp (with-eval-after-load "message" - (define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) + (define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-try-all)) (with-eval-after-load "sendmail" - (define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) + (define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-try-all)) @end lisp @menu @@ -254,7 +254,9 @@ To: * Smith @noindent will return all LDAP entries with surnames that begin with @code{Smith}. In every LDAP query it makes, EUDC implicitly appends -the wildcard character to the end of the last word. +the wildcard character to the end of the last word, except if the word +corresponds to an attribute which is a member of +`eudc-ldap-no-wildcard-attributes'. @menu * Emacs-only Configuration:: Configure with @file{.emacs} @@ -281,19 +283,20 @@ LDAP: @vindex message-mode-map @findex eudc-expand-inline +@findex eudc-expand-try-all @vindex eudc-server-hotlist @vindex ldap-host-parameters-alist @lisp (with-eval-after-load "message" - (define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) -(customize-set-variable 'eudc-server-hotlist - '(("" . bbdb) - ("ldaps://ldap.gnu.org" . ldap))) -(customize-set-variable 'ldap-host-parameters-alist - '(("ldaps://ldap.gnu.org" - base "ou=people,dc=gnu,dc=org" - binddn "gnu\\emacsuser" - passwd ldap-password-read))) + (define-key message-mode-map (kbd "TAB") 'eudc-expand-try-all)) +(setopt eudc-server-hotlist + '(("" . bbdb) + ("ldaps://ldap.gnu.org" . ldap))) +(setopt ldap-host-parameters-alist + '(("ldaps://ldap.gnu.org" + base "ou=people,dc=gnu,dc=org" + binddn "gnu\\emacsuser" + passwd ldap-password-read))) @end lisp @findex ldap-password-read @@ -337,17 +340,18 @@ configure EUDC for LDAP: @vindex message-mode-map @findex eudc-expand-inline +@findex eudc-expand-try-all @vindex eudc-server-hotlist @vindex ldap-host-parameters-alist @lisp (with-eval-after-load "message" - (define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) -(customize-set-variable 'eudc-server-hotlist - '(("" . bbdb) - ("ldaps://ldap.gnu.org" . ldap))) -(customize-set-variable 'ldap-host-parameters-alist - '(("ldaps://ldap.gnu.org" - auth-source t))) + (define-key message-mode-map (kbd "TAB") 'eudc-expand-try-all)) +(setopt eudc-server-hotlist + '(("" . bbdb) + ("ldaps://ldap.gnu.org" . ldap))) +(setopt ldap-host-parameters-alist + '(("ldaps://ldap.gnu.org" + auth-source t))) @end lisp For this example where we only care about one server, the server name @@ -366,15 +370,16 @@ and the @file{.emacs} expressions become: @vindex message-mode-map @findex eudc-expand-inline +@findex eudc-expand-try-all @vindex eudc-server-hotlist @vindex ldap-host-parameters-alist @lisp (with-eval-after-load "message" - (define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) -(customize-set-variable 'eudc-server-hotlist - '(("" . bbdb) ("" . ldap))) -(customize-set-variable 'ldap-host-parameters-alist - '(("" auth-source t))) + (define-key message-mode-map (kbd "TAB") 'eudc-expand-try-all)) +(setopt eudc-server-hotlist + '(("" . bbdb) ("" . ldap))) +(setopt ldap-host-parameters-alist + '(("" auth-source t))) @end lisp @node Troubleshooting @@ -418,11 +423,12 @@ all macOS versions since 10.0 (which was released 2001). configurations. @file{eudcb-mab.el} reverse engineers the format of the database file -used by the macOS Contacts app, and accesses its contents directly. -While this may promise some performance advantages, it comes at the -cost of using an undocumented interface. Hence, users of -@file{eudcb-mab.el} are recommended to double check the compatibility -of @file{eudcb-mab.el} before upgrading to a new version of macOS. +using the external command-line utility named contacts, which needs to +be installed separately. While this may promise some performance +advantages, it comes at the cost of using an undocumented interface. +Hence, users of @file{eudcb-mab.el} are recommended to double check +the compatibility of @file{eudcb-mab.el} and the required, external +command-line utility before upgrading to a new version of macOS. @file{eudcb-mab.el} is retained for backwards compatibility with existing configurations, and may be removed in a future release. @@ -708,32 +714,49 @@ be passed to the program. @node Inline Query Expansion @section Inline Query Expansion - -Inline query expansion is a powerful method to get completion from your -directory server. The most common usage is for expanding names to email -addresses in mail message buffers. The expansion is performed by the -command @kbd{M-x eudc-expand-inline} which is available from the -@samp{Expand Inline Query} menu item but can also be conveniently -bound to a key shortcut (@pxref{Installation}). The operation is -controlled by the variables @code{eudc-inline-expansion-format}, -@code{eudc-inline-query-format}, +@subsection Inline Query Expansion Using a Key Binding + +Inline query expansion is a powerful method to get completion from +your directory servers. The most common usage is for expanding names +to email addresses in mail message buffers. The expansion is +performed by the command @kbd{M-x eudc-expand-try-all} which is +available from the @samp{Expand Inline Query Trying All Servers} menu +item but can also be conveniently bound to a key shortcut +(@pxref{Installation}). The operation is controlled by the variables +@code{eudc-inline-expansion-format}, @code{eudc-inline-query-format}, @code{eudc-expanding-overwrites-query} and @code{eudc-multiple-match-handling-method}. -If the query fails for a server, other servers may be tried successively -until one of them finds a match (@pxref{Multi-server Queries}). +If the query fails for a server, other servers may be tried +successively until one of them finds a match (@pxref{Multi-server +Queries}), or all servers can be tried and all matches returned. + +@deffn Command eudc-expand-try-all try-all-servers-p +Query some or all servers and expand the query string before point. +The query string consists of the buffer substring from the point back +to the preceding comma, colon or beginning of line. +@code{eudc-inline-query-format} controls how individual words are +mapped onto directory attribute names. After querying the server or +servers for the given string, the expansion specified by +@code{eudc-inline-expansion-format} is inserted in the buffer at +point. If multiple matches are available, a selection window is +displayed. If @var{try-all-servers-p} is non-@code{nil} then all +servers are queried. +@end deffn -@deffn Command eudc-expand-inline replace-p +@deffn Command eudc-expand-inline save-query-as-kill-p Query the server and expand the query string before point. The query string consists of the buffer substring from the point back to the -preceding comma, colon or beginning of -line. @code{eudc-inline-query-format} controls how individual words -are mapped onto directory attribute names. After querying the server -for the given string, the expansion specified by +preceding comma, colon or beginning of line. +@code{eudc-inline-query-format} controls how individual words are +mapped onto directory attribute names. After querying the server for +the given string, the expansion specified by @code{eudc-inline-expansion-format} is inserted in the buffer at -point. If @var{replace-p} is @code{t} then this expansion replaces the -query string in the buffer. If @code{eudc-expanding-overwrites-query} -is non-@code{nil} then the meaning of @var{replace-p} is negated. +point. If multiple matches are available, a selection window is +displayed. If @var{save-query-as-kill-p} is @code{t} then the query +string is saved to the kill ring. If +@code{eudc-expansion-save-query-as-kill} is non-@code{nil} then the +meaning of @var{save-query-as-kill-p} is negated. @end deffn @defvar eudc-inline-query-format @@ -776,12 +799,73 @@ against the @code{cn} attribute of LDAP servers: @end defvar @defvar eudc-inline-expansion-format -This variable lets you control exactly what is inserted into the buffer -upon an inline expansion request. It is a list whose first element is a -string passed to @code{format}. Remaining elements are symbols -corresponding to directory attribute names. The corresponding attribute -values are passed as additional arguments to @code{format}. Default is -@code{("%s %s <%s>" firstname name email)}. +This variable lets you control exactly what is inserted into the +buffer upon an inline expansion request. It can be set to @code{nil}, +to a function, or to a list. Default is @code{nil}. + +When the value is a list, the first element is a string passed to +@code{format}. Remaining elements are symbols corresponding to +directory attribute names. The corresponding attribute values are +passed as additional arguments to @code{format}. + +When the value is @code{nil}, the expansion result will be formatted +according to @url{https://datatracker.ietf.org/doc/html/rfc5322, RFC +5322}. The @var{phrase} part will be formatted as ``firstname name'', +quoting the result if necessary. No @var{comment} part will be added +in this case. This will produce any of the default formats +@center @var{address} +@center @var{first} @code{<}@var{address}@code{>} +@center @var{last} @code{<}@var{address}@code{>} +@center @var{first} @var{last} @code{<}@var{address}@code{>} +depending on whether a first and/or last name are returned by the +query, or not. + +When the value is a function, the expansion result will be formatted +according to @url{https://datatracker.ietf.org/doc/html/rfc5322, RFC +5322}, and the referenced function is called to format the +@var{phrase}, and @var{comment} parts, respectively. The formatted +@var{phrase} part will be quoted if necessary. Thus one can produce +any of the formats: +@center @var{address} +@center @var{phrase} @code{<}@var{address}@code{>} +@center @var{address} @code{(}@var{comment}@code{)} +@center @var{phrase} @code{<}@var{address}@code{>} @code{(}@var{comment}@code{)} + +Email address specifications, as are generated by inline expansion, +need to comply with RFC 5322 in order to be useful in email +messages. When an invalid address specification is present in an email +message header, the message is likely to be rejected by a receiving +MTA. It is hence recommended to switch old configurations, which use +a list value, to the new @code{nil}, or function value type since it +ensures that the inserted address specifications will be in line with +@url{https://datatracker.ietf.org/doc/html/rfc5322, RFC 5322}. At +minimum, and to achieve the same semantics as with the old list +default value, this variable should now be set to @code{nil}: +@lisp +(customize-set-variable 'eudc-inline-expansion-format nil) +@end lisp + +A function value can for example be used to get @emph{``last, first +<address>''} instead of the default @emph{``first last <address>''}: +@lisp +(defun my-phrase-last-comma-first (search-res-alist) + (let* (phrase + (my-attrs (eudc-translate-attribute-list '(firstname name))) + (first-name (cdr (assq (nth 0 my-attrs) search-res-alist))) + (last-name (cdr (assq (nth 1 my-attrs) search-res-alist))) + (comment nil)) + (setq phrase (concat last-name ", " first-name)) + (cons phrase comment))) + +(customize-set-variable 'eudc-inline-expansion-format + #'my-phrase-last-comma-first) +@end lisp +To set the @var{comment} part, too, instead of @code{nil} as in this +example, also provide a string as the @code{cdr} of the @code{cons} +being returned. Do not include any double quotes in the @var{phrase} +part, as they are added automatically if needed. Neither include +parentheses in the @var{comment} part as they, too, are added +automatically. @end defvar @defvar eudc-multiple-match-handling-method @@ -803,6 +887,29 @@ An error is signaled. The expansion aborts. Default is @code{select} @end defvar +@subsection Inline Query Expansion Using completion-at-point + +In addition to providing a dedicated EUDC function for binding to a +key shortcut (@pxref{Inline Query Expansion}), EUDC also provides a +function to contribute search results to the Emacs in-buffer +completion system available via the function +@code{completion-at-point} (@pxref{Identifier +Inquiries,,,maintaining}) in @code{message-mode} buffers +(@pxref{Top,Message,, message, Message}). When using this mechanism, +queries are made in the multi-server query mode of operation +(@pxref{Multi-server Queries}). + +When a buffer in @code{message-mode} is created, EUDC's inline +expansion function is automatically added to the variable +@code{completion-at-point-functions}. As a result, whenever +@code{completion-at-point} is invoked in a @code{message-mode} buffer, +EUDC will be queried for email addresses matching the words before +point. Since this will be useful only when editing specific message +header fields that require specifying one or more email addresses, an +additional check is performed whether point is actually in one of +those header fields. Thus, any matching email addresses will be +offered for completion in suitable message header fields only, and not +in other places, like for example the body of the message. @node The Server Hotlist diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index b3ec52f7ab8..1060cd805ab 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -305,6 +305,7 @@ state the directionality. @vindex shr-max-image-proportion @vindex shr-blocked-images +@vindex shr-allowed-images @cindex Image Display Loading random images from the web can be problematic due to their size or content. By customizing @code{shr-max-image-proportion} you @@ -380,6 +381,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 451d6c76c4b..953e4605e98 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -1,4 +1,4 @@ -\input texinfo @c -*-texinfo; coding: utf-8 -*- +\input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @comment %**start of header @setfilename ../../info/flymake.info @set VERSION 1.2 @@ -265,6 +265,9 @@ This section summarizes customization variables used for the configuration of the Flymake user interface. @vtable @code +@item flymake-mode-line-lighter +The name of the mode. Defaults to @samp{Flymake}. + @item flymake-mode-line-format Format to use for the Flymake mode line indicator. @@ -1145,7 +1148,7 @@ file are parsed. For @file{file.h}, the include directives to look for are @code{#include "file.h"}, @code{#include "../file.h"}, etc. Each include is checked against a list of include directories -(see @ref{Getting the include directories}) to be sure it points to the +(@pxref{Getting the include directories}) to be sure it points to the correct @file{file.h}. First matching master file found stops the search. The master file is then diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index fd961be2f52..4923efb3dbe 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -100,10 +100,9 @@ misprints are the Gnus team's fault, sorry. * FAQ 1-1:: What is the latest version of Gnus? * FAQ 1-2:: What's new in 5.10? * FAQ 1-3:: Where and how to get Gnus? -* FAQ 1-4:: What to do with the tarball now? -* FAQ 1-5:: I sometimes read references to No Gnus and Oort Gnus, +* FAQ 1-4:: I sometimes read references to No Gnus and Oort Gnus, what are those? -* FAQ 1-6:: Which version of Emacs do I need? +* FAQ 1-5:: Which version of Emacs do I need? @end menu @node FAQ 1-1 @@ -165,34 +164,6 @@ Gnus is bundled with Emacs. @node FAQ 1-4 @subsubheading Question 1.4 -What to do with the tarball now? - -@subsubheading Answer - -Untar it via @samp{tar xvzf gnus.tar.gz} and do the common -@samp{./configure; make; make install} circle. -(under MS-Windows either get the Cygwin environment from -@uref{https://www.cygwin.com} -which allows you to do what's described above or unpack the -tarball with some packer (e.g., Winace) -and use the batch-file make.bat included in the tarball to install -Gnus.) If you don't want to (or aren't allowed to) install Gnus -system-wide, you can install it in your home directory and add the -following lines to your ~/.emacs: - -@example -(add-to-list 'load-path "/path/to/gnus/lisp") -(add-to-list 'Info-default-directory-list "/path/to/gnus/texi/") -@end example -@noindent - -Make sure that you don't have any Gnus related stuff -before this line, on MS Windows use something like -"C:/path/to/lisp" (yes, "/"). - -@node FAQ 1-5 -@subsubheading Question 1.5 - I sometimes read references to No Gnus and Oort Gnus, what are those? @@ -205,8 +176,8 @@ once become Gnus 5.12 or Gnus 6. (If you're wondering why not 5.11, the odd version numbers are normally used for the Gnus versions bundled with Emacs) -@node FAQ 1-6 -@subsubheading Question 1.6 +@node FAQ 1-5 +@subsubheading Question 1.5 Which version of Emacs do I need? @@ -653,8 +624,7 @@ about the server there. (add-to-list 'gnus-secondary-select-methods '(nnimap "Give the baby a name" (nnimap-address "imap.yourProvider.net") - (nnimap-port 143) - (nnimap-list-pattern "archive.*"))) + (nnimap-port 143))) @end example @noindent diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index d608f3113fd..7da90dfb1d6 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -1004,7 +1004,7 @@ The fundamental building blocks of Gnus are @dfn{servers}, @dfn{groups}, and @dfn{articles}. Servers can be local or remote. Each server maintains a list of groups, and those groups contain articles. Because Gnus presents a unified interface to a wide variety -of servers, the vocabulary doesn't always quite line up (see @ref{FAQ +of servers, the vocabulary doesn't always quite line up (@pxref{FAQ - Glossary}, for a more complete glossary). Thus a local maildir is referred to as a ``server'' (@pxref{Finding the News}) the same as a Usenet or IMAP server is; ``groups'' (@pxref{Group Buffer}) might mean @@ -4499,7 +4499,7 @@ command or better use it as a prefix key. For example: (gnus-group-jump-to-group "nndraft:drafts"))) @end lisp -On keys reserved for users in Emacs and on keybindings in general +On keys reserved for users in Emacs and on key bindings in general @xref{Keymaps, Keymaps, , emacs, The Emacs Editor}. @item ^ @@ -9843,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 @@ -12185,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 @@ -12236,6 +12244,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) @@ -13465,7 +13474,7 @@ Also @pxref{Formatting Variables}. @subsection Server Commands @cindex server commands -The following keybinding are available in the server buffer. Be aware +The following key bindings are available in the server buffer. Be aware that some of the commands will only work on servers that you've added through this interface (with @kbd{a}), not with servers you've defined in your init files. @@ -14829,12 +14838,17 @@ mail belongs in that group. The last of these groups should always be a general one, and the regular expression should @emph{always} be @samp{""} so that it matches any mails that haven't been matched by any of the other regexps. (These rules are -processed from the beginning of the alist toward the end. The first rule -to make a match will ``win'', unless you have crossposting enabled. In -that case, all matching rules will ``win''.) If no rule matched, the mail -will end up in the @samp{bogus} group. When new groups are created by -splitting mail, you may want to run @code{gnus-group-find-new-groups} to -see the new groups. This also applies to the @samp{bogus} group. +processed from the beginning of the alist toward the end. + +If multiple rules match (excluding the general @samp{""} group), mail +is crossposted to all these groups. However, if +@code{nnmail-crosspost} is set to @code{nil}, the first rule to make a +match will ``win''. + +If no rule matched, the mail will end up in the @samp{bogus} group. +When new groups are created by splitting mail, you may want to run +@code{gnus-group-find-new-groups} to see the new groups. This also +applies to the @samp{bogus} group. If you like to tinker with this yourself, you can set this variable to a function of your choice. This function will be called without any @@ -15435,10 +15449,6 @@ If non-@code{nil}, ask for confirmation before deleting old incoming files. This variable only applies when @code{mail-source-delete-incoming} is a positive number. -@item mail-source-ignore-errors -@vindex mail-source-ignore-errors -If non-@code{nil}, ignore errors when reading mail from a mail source. - @item mail-source-directory @vindex mail-source-directory Directory where incoming mail source files (if any) will be stored. The @@ -17508,16 +17518,16 @@ If you have a directory that has lots of articles in separate files in it, you might treat it as a newsgroup. The files have to have numerical names, of course. -This might be an opportune moment to mention @code{ange-ftp} (and its -successor @code{efs}), that most wonderful of all wonderful Emacs -packages. When I wrote @code{nndir}, I didn't think much about it---a -back end to read directories. Big deal. +This might be an opportune moment to mention @code{ange-ftp}, that +most wonderful of all wonderful Emacs packages. When I wrote +@code{nndir}, I didn't think much about it---a back end to read +directories. Big deal. @code{ange-ftp} changes that picture dramatically. For instance, if you enter the @code{ange-ftp} file name @file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name, -@code{ange-ftp} or @code{efs} will actually allow you to read this -directory over at @samp{sina} as a newsgroup. Distributed news ahoy! +@code{ange-ftp} will actually allow you to read this directory over at +@samp{sina} as a newsgroup. Distributed news ahoy! @code{nndir} will use @acronym{NOV} files if they are present. @@ -18040,7 +18050,7 @@ find all messages that have been received recently from certain groups: (list (cons 'query (format-time-string "SENTSINCE %d-%b-%Y" - (time-subtract (current-time) + (time-subtract nil (days-to-time (car args))))) (cons 'criteria ""))) (group-spec (cadr args))) @@ -18068,6 +18078,17 @@ parameter of @code{nnselect-rescan} will allow automatic refreshing. A refresh can always be invoked manually through @code{gnus-group-get-new-news-this-group}. +By default a compressed version of the selection is stored (for +permanent groups) along with other group information in the newsrc. +For cases where this might be undesirable (for example if the +selection is a very long list that doesn't compress well) a +non-@code{nil} group parameter of @code{nnselect-always-regenerate} +will prevent the list from being stored, and instead regenerate the +list each time it is needed. If more flexibility is desired, +@code{nnselect-get-artlist-override-function} and +@code{nnselect-store-artlist-override-function} may be set to +functions that get and store the list of articles. + Gnus includes engines for searching a variety of backends. While the details of each search engine vary, the result of a search is always a vector of the sort used by the nnselect method, and the results of @@ -21630,6 +21651,9 @@ are: @item @code{gnus-search-namazu} + +@item +@code{gnus-search-mu} @end itemize If you need more granularity, you can specify a search engine in the @@ -21644,7 +21668,7 @@ buffer. That might look like: (config-file "/home/user/.mail/.notmuch_config"))) @end example -Search engines like notmuch, namazu and mairix are similar in +Search engines like notmuch, namazu, mairix and mu are similar in behavior: they use a local executable to create an index of a message store, and run command line search queries against those messages, and return a list of absolute file names of matching messages. @@ -21664,7 +21688,9 @@ engine. @item remove-prefix The directory part to be removed from the filenames returned by the search query. This absolute path should include everything up to the -top level of the message store. +top level of the message store. Note that this is the path to the +location of the actual messages, not to the search engine's indexes +(nor, in the case of Mairix, to its symlink directories). @item switches Additional command-line switches to be fed to the search program. The @@ -21681,8 +21707,8 @@ The customization options are formed on the pattern non-standard notmuch program, you might set @code{gnus-search-notmuch-program} to @file{/usr/local/bin/notmuch}. This would apply to all notmuch engines. The engines that use these -options are: ``notmuch'', ``namazu'', ``mairix'', ``swish-e'' and -``swish++''. +options are: ``notmuch'', ``namazu'', ``mairix'', ``mu'', ``swish-e'' +and ``swish++''. Alternately, the options can be set directly on your Gnus server definitions, for instance, in the @code{nnmaildir} example above. @@ -21723,6 +21749,12 @@ articles are drawn. If you want to create a @emph{persistent} group that sticks around after exit from the summary buffer, you can call @code{gnus-group-make-search-group} (bound to @kbd{G g}). +Unlike persistent groups, ephemeral groups by default do not run +articles through the expiry process on exiting. If you want expiry to +happen in ephemeral search groups you can customize the variable +@code{nnselect-allow-ephemeral-expiry}. In all cases the expiry +process uses the underlying group's expiry parameters. + So you just performed a search whose results are so fabulous you wished you had done a persistent search rather than an ephemeral one? No problem; you can create such a group by calling @@ -24129,37 +24161,19 @@ If you want to see them in the Cc and To fields, set: @end lisp -@subsubsection Toolbar +@subsubsection Tool bar @table @code -@item gnus-use-toolbar -@vindex gnus-use-toolbar -This variable specifies the position to display the toolbar. If -@code{nil}, don't display toolbars. If it is non-@code{nil}, it should -be one of the symbols @code{default}, @code{top}, @code{bottom}, -@code{right}, and @code{left}. @code{default} means to use the default -toolbar, the rest mean to display the toolbar on the place which those -names show. The default is @code{default}. - -@item gnus-toolbar-thickness -@vindex gnus-toolbar-thickness -Cons of the height and the width specifying the thickness of a toolbar. -The height is used for the toolbar displayed on the top or the bottom, -the width is used for the toolbar displayed on the right or the left. -The default is that of the default toolbar. - -@item gnus-group-toolbar -@vindex gnus-group-toolbar -The toolbar in the group buffer. - -@item gnus-summary-toolbar -@vindex gnus-summary-toolbar -The toolbar in the summary buffer. +@item gnus-group-tool-bar +@vindex gnus-group-tool-bar +Specifies the tool bar in the group buffer. It can be either a list +or a symbol referring to a list. -@item gnus-summary-mail-toolbar -@vindex gnus-summary-mail-toolbar -The toolbar in the summary buffer of mail groups. +@item gnus-summary-tool-bar +@vindex gnus-summary-tool-bar +Specifies the tool bar in the summary buffer. It can be either a list +or a symbol referring to a list. @end table @@ -26764,7 +26778,7 @@ on finding a separator line between the head and the body. If this variable is @code{nil}, there is no upper read bound. If it is @code{t}, the back ends won't try to read the articles piece by piece, but read the entire articles. This makes sense with some versions of -@code{ange-ftp} or @code{efs}. +@code{ange-ftp}. @item nnheader-head-chop-length @vindex nnheader-head-chop-length @@ -28878,7 +28892,7 @@ gnus-agent-cache nil)} reverts to the old behavior. @item Dired integration -@code{gnus-dired-minor-mode} (see @ref{Other modes}) installs key +@code{gnus-dired-minor-mode} (@pxref{Other modes}) installs key bindings in dired buffers to send a file as an attachment, open a file using the appropriate mailcap entry, and print a file using the mailcap entry. diff --git a/doc/misc/htmlfontify.texi b/doc/misc/htmlfontify.texi index 71b594b1086..0ab000b70f1 100644 --- a/doc/misc/htmlfontify.texi +++ b/doc/misc/htmlfontify.texi @@ -633,7 +633,7 @@ Convert an Emacs :foreground property to a CSS color property. (hfy-flatten-style @var{style}) @end lisp -Take @var{style} (see @ref{hfy-face-to-style-i}, @ref{hfy-face-to-style}) +Take @var{style} (@pxref{hfy-face-to-style-i}, @pxref{hfy-face-to-style}) and merge any multiple attributes appropriately. Currently only font-size is merged down to a single occurrence---others may need special handling, but I haven't encountered them yet. Returns a @ref{hfy-style-assoc}. @@ -841,7 +841,7 @@ See @ref{hfy-display-class} for details of valid values for @var{class}. @end lisp Find face in effect at point P@. If overlays are to be considered -(see @ref{hfy-optimizations}) then this may return a @code{defface} style +(@pxref{hfy-optimizations}) then this may return a @code{defface} style list of face properties instead of a face symbol. @item hfy-bgcol diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi index 46fe62693ad..26a6e6c7a33 100644 --- a/doc/misc/idlwave.texi +++ b/doc/misc/idlwave.texi @@ -2670,7 +2670,7 @@ As a special case, any error message in the output will be displayed @node Debugging IDL Programs @section Debugging IDL Programs @cindex Debugging -@cindex Keybindings for debugging +@cindex Key bindings for debugging @cindex Toolbar Programs can be compiled, run, and debugged directly from the source diff --git a/doc/misc/ido.texi b/doc/misc/ido.texi index 9e0f8dc8776..c8f9762b553 100644 --- a/doc/misc/ido.texi +++ b/doc/misc/ido.texi @@ -476,13 +476,13 @@ M-x customize-variable @key{RET} ido-xxxxx @key{RET} @end example @vindex ido-setup-hook -To modify the keybindings, use the @code{ido-setup-hook}. For example: +To modify the key bindings, use the @code{ido-setup-hook}. For example: @example (add-hook 'ido-setup-hook 'ido-my-keys) (defun ido-my-keys () - "Add my keybindings for Ido." + "Add my key bindings for Ido." (define-key ido-completion-map " " 'ido-next-match)) @end example diff --git a/doc/misc/info.texi b/doc/misc/info.texi index 98e0dceb5a2..4db35ebf0fc 100644 --- a/doc/misc/info.texi +++ b/doc/misc/info.texi @@ -1083,7 +1083,9 @@ If you aren't sure which manual documents the topic you are looking for, try the @kbd{M-x info-apropos} command in Emacs, or the @kbd{M-x index-apropos} command in the stand-alone reader. It prompts for a string and then looks up that string in all the indices of all the -Info documents installed on your system. +Info documents installed on your system. In Emacs, giving a prefix +argument to the command will try to search for a regular expression +instead of a string. @node Go to node @section @kbd{g} goes to a node by name @@ -1191,8 +1193,9 @@ info-stnd, GNU Info}. The list of directories to search for Info files. Each element is a string (directory name) or @code{nil} (try default directory). If not initialized Info uses the environment variable @env{INFOPATH} to -initialize it, or @code{Info-default-directory-list} if there is no -@env{INFOPATH} variable in the environment. +initialize it, or @code{Info-default-directory-list} in addition to +the value returned by the @code{Info--default-directory-list} function +if there is no @env{INFOPATH} variable in the environment. If you wish to customize the Info directory search list for both Emacs Info and stand-alone Info, it is best to set the @env{INFOPATH} diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi index 4414528f3b3..3632c64bd46 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 @@ -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 b0510f00373..29fbdfe1786 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -2553,6 +2553,22 @@ if @code{nil} let the mailer mail back a message to report errors. When non-@code{nil}, Gnus will ask for confirmation when sending a message. +@item message-server-alist +@vindex message-server-alist +An alist describing the rules for generating the +@code{X-Message-SMTP-Method} header to insert before sending out a new +message, if the message doesn't yet have such a header. Each element +of the alist should be of the form +@w{@code{(@var{cond} . @var{method})}}. If @var{cond} is a string, it +will be compared with the @code{From} header, and if they compare +equal, the corresponding @var{method} will be inserted as a string +into the message headers as the SMTP Method. If @var{cond} is a +function, it will be called in the message buffer without any +arguments, and the corresponding @var{method} will be inserted into +the message headers as the SMTP Method if the function returns a +non-@code{nil} value; if @var{method} is nil, the value returned by +the function @code{cond} is used instead. + @end table diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi index d42f71a022e..c1cf44a0272 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -1018,16 +1018,16 @@ Send multimedia messages (@pxref{Adding Attachments}). Read HTML messages (@pxref{HTML}). @c ------------------------- @item -Use aliases and identities (see @ref{Aliases}, @pxref{Identities}). +Use aliases and identities (@pxref{Aliases}, @pxref{Identities}). @c ------------------------- @item -Create different views of your mail (see @ref{Threading}, @pxref{Limits}). +Create different views of your mail (@pxref{Threading}, @pxref{Limits}). @c ------------------------- @item Deal with junk mail (@pxref{Junk}). @c ------------------------- @item -Handle signed and encrypted messages (see @ref{Reading PGP}, +Handle signed and encrypted messages (@pxref{Reading PGP}, @pxref{Sending PGP}). @c ------------------------- @item @@ -1038,7 +1038,7 @@ Process mail that was sent with @command{shar} or @command{uuencode} Use sequences conveniently (@pxref{Sequences}). @c ------------------------- @item -Use the speedbar, tool bar, and menu bar (see @ref{Speedbar}, see @ref{Tool +Use the speedbar, tool bar, and menu bar (@pxref{Speedbar}, @pxref{Tool Bar}, @pxref{Menu Bar}). @c ------------------------- @item diff --git a/doc/misc/modus-themes.org b/doc/misc/modus-themes.org index 5451f806736..943294b626c 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.6.0 -#+macro: release-date 2021-09-29 -#+macro: development-version 1.7.0-dev +#+macro: stable-version 2.4.0 +#+macro: release-date 2022-06-01 +#+macro: development-version 2.5.0-dev #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ #+macro: space @@texinfo:@: @@ #+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ @@ -15,7 +15,7 @@ #+texinfo_filename: modus-themes.info #+texinfo_dir_category: Emacs misc features #+texinfo_dir_title: Modus Themes: (modus-themes) -#+texinfo_dir_desc: Highly accessible themes (WCAG AAA) +#+texinfo_dir_desc: Elegant, highly legible and customizable themes #+texinfo_header: @set MAINTAINERSITE @uref{https://protesilaos.com,maintainer webpage} #+texinfo_header: @set MAINTAINER Protesilaos Stavrou #+texinfo_header: @set MAINTAINEREMAIL @email{info@protesilaos.com} @@ -34,6 +34,10 @@ explicitly marked as such. Current development target is {{{development-version}}}. ++ Homepage: https://protesilaos.com/emacs/modus-themes. ++ Git repository: https://git.sr.ht/~protesilaos/modus-themes. ++ Mailing list: https://lists.sr.ht/~protesilaos/modus-themes. + #+toc: headlines 8 insert TOC here, with eight headline levels * COPYING @@ -42,7 +46,7 @@ Current development target is {{{development-version}}}. :custom_id: h:b14c3fcb-13dd-4144-9d92-2c58b3ed16d3 :end: -Copyright (C) 2020-2022 Free Software Foundation, Inc. +Copyright (C) 2020-2022 Free Software Foundation, Inc. #+begin_quote Permission is granted to copy, distribute and/or modify this document @@ -82,9 +86,22 @@ themes strive to achieve as close to full face coverage as possible ([[#h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19][Face coverage]]). Furthermore, the themes are designed to empower users with red-green -color deficiency (deuteranopia). This is achieved through customization -options which have the effect of replacing all relevant instances of -green with a variant of blue ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]). +color deficiency (deuteranopia). This is achieved in three ways: + +1. The conformance with the highest legibility standard means that text + is always readable no matter the perception of its hue. + +2. Most contexts use colors on the blue-cyan-magenta-purple side of the + spectrum. Put differently, green and/or red are seldom used, thus + minimizing the potential for confusion. + + [[#h:0b26cb47-9733-4cb1-87d9-50850cb0386e][Why are colors mostly variants of blue, magenta, cyan?]]. + +3. In contexts where a red/green color-coding is unavoidable, we provide + a universal toggle to customize the themes so that a red/blue scheme + is used instead. + + [[#h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe][Option for red-green color deficiency or deuteranopia]]. Starting with version 0.12.0 and onwards, the themes are built into GNU Emacs. @@ -95,7 +112,7 @@ Emacs. :end: #+cindex: Screenshots -Check the web page with [[https://protesilaos.com/modus-themes-pictures/][the screen shots]]. There are lots of scenarios +Check the web page with [[https://protesilaos.com/emacs/modus-themes-pictures/][the screen shots]]. There are lots of scenarios on display that draw attention to details and important aspects in the design of the themes. They also showcase the numerous customization options. @@ -108,7 +125,7 @@ options. :end: #+cindex: Changelog -Please refer to the [[https://protesilaos.com/modus-themes-changelog][web page with the change log]]. It is comprehensive +Please refer to the [[https://protesilaos.com/emacs/modus-themes-changelog][web page with the change log]]. It is comprehensive and covers everything that goes into every tagged release of the themes. * Installation @@ -152,14 +169,10 @@ The themes are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][ The ~modus-themes~ package is available from the GNU ELPA archive, which is configured by default. -Prior to querying any package archive, make sure to have updated the -index, with {{{kbd(M-x package-refresh-contents)}}}. Then all you need to do +Prior to querying any package archive, make sure to update the index, +with {{{kbd(M-x package-refresh-contents)}}}. Then all you need to do is type {{{kbd(M-x package-install)}}} and specify the ~modus-themes~. -Note that older versions of the themes used to be distributed as -standalone packages. This practice has been discontinued starting with -version 1.0.0 of this project. - Once installed, the themes are ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. ** Install on GNU/Linux @@ -198,6 +211,34 @@ guix package -i emacs-modus-themes They are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. +** Dealing with byte compilation errors +:properties: +:custom_id: h:e6268471-e847-4c9d-998f-49a83257b7f1 +:end: + +From time to time, we receive bug reports pertaining to errors with byte +compilation. These seldom have to do with faulty code in the themes: it +might be a shortcoming of =package.el=, some regression in the current +development target of Emacs, a misconfiguration in an otherwise exotic +setup, and the like. + +The common solution with a stable version of Emacs is to: + +1. Delete the =modus-themes= package. +2. Close the current Emacs session. +3. Install the =modus-themes= again. + +For those building Emacs directly from source, the solution may involve +reverting to an earlier commit in emacs.git. + +At any rate, if you encounter such an issue please report it: we will +either fix the bug on our end if it is truly ours, or help forward it to +the relevant upstream maintainer. Whatever you do, please understand +that a build failure does not mean we are necessarily doing something +wrong. + +[[#h:6536c8d5-3f98-43ab-a787-b94120e735e8][Issues you can help with]]. + * Enable and load :properties: :custom_id: h:3f3c3728-1b34-437d-9d0c-b110f5b161a9 @@ -209,16 +250,16 @@ They are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable #+cindex: Essential configuration #+vindex: modus-themes-after-load-theme-hook -Users of the built-in themes can load and automatically enable the theme -of their preference by adding either form to their init file: +Users of the built-in themes cannot ~require~ the package as usual +because there is no package to speak of. Instead, things are simpler as +all one needs is to load the theme of their preference by adding either +form to their init file: #+begin_src emacs-lisp (load-theme 'modus-operandi) ; Light theme (load-theme 'modus-vivendi) ; Dark theme #+end_src -This is all one needs. - Users of packaged variants of the themes must add a few more lines to ensure that everything works as intended. First, one has to require the main library before loading either theme: @@ -247,28 +288,43 @@ a theme with either of the following expressions: Changes to the available customization options must always be evaluated before loading a theme ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]). An exception to this norm is when using the various Custom interfaces or with commands like -{{{kbd(M-x customize-set-variable)}}}, which automatically reload the theme by -default ([[#h:9001527a-4e2c-43e0-98e8-3ef72d770639][Option for inhibiting theme reload]]). This is how a basic setup -could look like: +{{{kbd(M-x customize-set-variable)}}}, which can optionally +automatically reload the theme ([[#h:9001527a-4e2c-43e0-98e8-3ef72d770639][Option for inhibiting theme reload]]). + +This is how a basic setup could look like: #+begin_src emacs-lisp +;;; For the built-in themes which cannot use `require': +;; Add all your customizations prior to loading the themes +(setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-region '(bg-only no-extend)) + +;; Load the theme of your choice: +(load-theme 'modus-operandi) ;; OR (load-theme 'modus-vivendi) + +(define-key global-map (kbd "<f5>") #'modus-themes-toggle) + + + +;;; For packaged versions which must use `require': (require 'modus-themes) -;; Your customisations here. For example: -(setq modus-themes-bold-constructs t - modus-themes-mode-line '3d) +;; Add all your customizations prior to loading the themes +(setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-region '(bg-only no-extend)) -;; Load the theme files before enabling a theme (else you get an error). +;; Load the theme files before enabling a theme (modus-themes-load-themes) -;; Enable the theme of your preference: -(modus-themes-load-operandi) +;; Load the theme of your choice: +(modus-themes-load-operandi) ;; OR (modus-themes-load-vivendi) -;; Optionally add a key binding for the toggle between the themes: (define-key global-map (kbd "<f5>") #'modus-themes-toggle) #+end_src -[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration for use-package]]. +[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration with and without use-package]]. With those granted, bear in mind a couple of technical points on ~modus-themes-load-operandi~ and ~modus-themes-load-vivendi~, as well as @@ -279,29 +335,45 @@ With those granted, bear in mind a couple of technical points on 2. The functions will run the ~modus-themes-after-load-theme-hook~ as their final step. This can be employed for bespoke configurations - ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]). Experienced users may not wish to rely - on such a hook and the functions that run it: they may prefer a - custom solution ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]). + ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]). Experienced users may not wish to rely on + such a hook and the functions that run it: they may prefer a custom + solution ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]). -** Sample configuration for use-package +** Sample configuration with and without use-package :properties: :custom_id: h:e979734c-a9e1-4373-9365-0f2cd36107b8 :end: #+cindex: use-package configuration +#+cindex: sample configuration It is common for Emacs users to rely on ~use-package~ for declaring package configurations in their setup. We use this as an example: #+begin_src emacs-lisp +;;; For the built-in themes which cannot use `require': +(use-package emacs + :init + ;; Add all your customizations prior to loading the themes + (setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-region '(bg-only no-extend)) + :config + ;; Load the theme of your choice: + (load-theme 'modus-operandi) ;; OR (load-theme 'modus-vivendi) + :bind ("<f5>" . modus-themes-toggle) + + + +;;; For packaged versions which must use `require': (use-package modus-themes - :ensure ; omit this to use the built-in themes + :ensure :init ;; Add all your customizations prior to loading the themes (setq modus-themes-italic-constructs t modus-themes-bold-constructs nil modus-themes-region '(bg-only no-extend)) - ;; Load the theme files before enabling a theme (else you get an error). + ;; Load the theme files before enabling a theme (modus-themes-load-themes) :config ;; Load the theme of your choice: @@ -309,6 +381,39 @@ package configurations in their setup. We use this as an example: :bind ("<f5>" . modus-themes-toggle)) #+end_src +The same without ~use-package~: + +#+begin_src emacs-lisp +;;; For the built-in themes which cannot use `require': +;; Add all your customizations prior to loading the themes +(setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-region '(bg-only no-extend)) + +;; Load the theme of your choice: +(load-theme 'modus-operandi) ;; OR (load-theme 'modus-vivendi) + +(define-key global-map (kbd "<f5>") #'modus-themes-toggle) + + + +;;; For packaged versions which must use `require': +(require 'modus-themes) + +;; Add all your customizations prior to loading the themes +(setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-region '(bg-only no-extend)) + +;; Load the theme files before enabling a theme +(modus-themes-load-themes) + +;; Load the theme of your choice: +(modus-themes-load-operandi) ;; OR (modus-themes-load-vivendi) + +(define-key global-map (kbd "<f5>") #'modus-themes-toggle) +#+end_src + [[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Differences between loading and enabling]]. Note: make sure not to customize the variable ~custom-theme-load-path~ @@ -325,7 +430,7 @@ package declaration of the themes. The reason we recommend ~load-theme~ instead of the other option of ~enable-theme~ is that the former does a kind of "reset" on the face -specs. It quite literally loads (or re-loads) the theme. Whereas the +specs. It quite literally loads (or reloads) the theme. Whereas the latter simply puts an already loaded theme at the top of the list of enabled items, re-using whatever state was last loaded. @@ -339,9 +444,9 @@ it might appear to the unsuspecting user that the themes are somehow broken whenever they try to assign a new value to a customization option or some face. -This "reset" that ~load-theme~ conducts does, however, come at the cost -of being somewhat slower than ~enable-theme~. Users who have a stable -setup and who seldom update their variables during a given Emacs +This "reset" that ~load-theme~ brings about does, however, come at the +cost of being somewhat slower than ~enable-theme~. Users who have a +stable setup and who seldom update their variables during a given Emacs session, are better off using something like this: #+begin_src emacs-lisp @@ -352,7 +457,9 @@ session, are better off using something like this: (enable-theme 'modus-operandi) ;; OR (enable-theme 'modus-vivendi) #+end_src -[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration for use-package]]. +[[#h:b40aca50-a3b2-4c43-be58-2c26fcd14237][Toggle themes without reloading them]]. + +[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration with and without use-package]]. With the above granted, other sections of the manual discuss how to configure custom faces, where ~load-theme~ is expected, though @@ -372,7 +479,8 @@ without any further tweaks. By default, all customization options are set to nil, unless otherwise noted in this manual. Remember that all customization options must be evaluated before loading -a theme ([[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]). +a theme ([[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]). If the theme is already active, it must be +reloaded for changes in user options to come into force. Below is a summary of what you will learn in the subsequent sections of this manual. @@ -380,10 +488,12 @@ this manual. #+begin_src emacs-lisp (setq modus-themes-italic-constructs t modus-themes-bold-constructs nil - modus-themes-no-mixed-fonts nil + modus-themes-mixed-fonts nil modus-themes-subtle-line-numbers nil - modus-themes-success-deuteranopia t + modus-themes-intense-mouseovers nil + modus-themes-deuteranopia t modus-themes-tabs-accented t + modus-themes-variable-pitch-ui nil modus-themes-inhibit-reload t ; only applies to `customize-set-variable' and related modus-themes-fringes nil ; {nil,'subtle,'intense} @@ -391,13 +501,24 @@ this manual. ;; Options for `modus-themes-lang-checkers' are either nil (the ;; default), or a list of properties that may include any of those ;; symbols: `straight-underline', `text-also', `background', - ;; `intense' + ;; `intense' OR `faint'. modus-themes-lang-checkers nil ;; Options for `modus-themes-mode-line' are either nil, or a list ;; that can combine any of `3d' OR `moody', `borderless', - ;; `accented', `padded'. - modus-themes-mode-line '(padded accented borderless) + ;; `accented', a natural number for extra padding (or a cons cell + ;; of padding and NATNUM), and a floating point for the height of + ;; the text relative to the base font size (or a cons cell of + ;; height and FLOAT) + modus-themes-mode-line '(accented borderless (padding . 4) (height . 0.9)) + + ;; Same as above: + ;; modus-themes-mode-line '(accented borderless 4 0.9) + + ;; Options for `modus-themes-markup' are either nil, or a list + ;; that can combine any of `bold', `italic', `background', + ;; `intense'. + modus-themes-markup '(background italic) ;; Options for `modus-themes-syntax' are either nil (the default), ;; or a list of properties that may include any of those symbols: @@ -420,46 +541,59 @@ this manual. ;; `bold', `italic', `background' modus-themes-links '(neutral-underline background) + ;; Options for `modus-themes-box-buttons' are either nil (the + ;; default), or a list that can combine any of `flat', `accented', + ;; `faint', `variable-pitch', `underline', `all-buttons', the + ;; symbol of any font weight as listed in `modus-themes-weights', + ;; and a floating point number (e.g. 0.9) for the height of the + ;; button's text. + modus-themes-box-buttons '(variable-pitch flat faint 0.9) + ;; Options for `modus-themes-prompts' are either nil (the ;; default), or a list of properties that may include any of those ;; symbols: `background', `bold', `gray', `intense', `italic' modus-themes-prompts '(intense bold) - modus-themes-completions 'moderate ; {nil,'moderate,'opinionated} - - modus-themes-mail-citations nil ; {nil,'faint,'monochrome} + ;; The `modus-themes-completions' is an alist that reads three + ;; keys: `matches', `selection', `popup'. Each accepts a nil + ;; value (or empty list) or a list of properties that can include + ;; any of the following (for WEIGHT read further below): + ;; + ;; `matches' - `background', `intense', `underline', `italic', WEIGHT + ;; `selection' - `accented', `intense', `underline', `italic', `text-also' WEIGHT + ;; `popup' - same as `selected' + ;; `t' - applies to any key not explicitly referenced (check docs) + ;; + ;; WEIGHT is a symbol such as `semibold', `light', or anything + ;; covered in `modus-themes-weights'. Bold is used in the absence + ;; of an explicit WEIGHT. + modus-themes-completions '((matches . (extrabold)) + (selection . (semibold accented)) + (popup . (accented intense))) + + modus-themes-mail-citations nil ; {nil,'intense,'faint,'monochrome} ;; Options for `modus-themes-region' are either nil (the default), ;; or a list of properties that may include any of those symbols: ;; `no-extend', `bg-only', `accented' modus-themes-region '(bg-only no-extend) - ;; Options for `modus-themes-diffs': nil, 'desaturated, - ;; 'bg-only, 'deuteranopia, 'fg-only-deuteranopia - modus-themes-diffs 'fg-only-deuteranopia + ;; Options for `modus-themes-diffs': nil, 'desaturated, 'bg-only + modus-themes-diffs 'desaturated modus-themes-org-blocks 'gray-background ; {nil,'gray-background,'tinted-background} 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)) + '((header-block . (variable-pitch 1.3)) + (header-date . (grayscale workaholic bold-today 1.1)) + (event . (accented varied)) (scheduled . uniform) - (habit . traffic-light-deuteranopia)) + (habit . traffic-light)) modus-themes-headings ; this is an alist: read the manual or its doc string - '((1 . (overline background)) - (2 . (rainbow overline)) - (t . (no-bold))) - - modus-themes-variable-pitch-ui nil - modus-themes-variable-pitch-headings t - modus-themes-scale-headings t - modus-themes-scale-1 1.1 - modus-themes-scale-2 1.15 - modus-themes-scale-3 1.21 - modus-themes-scale-4 1.27 - modus-themes-scale-title 1.33) + '((1 . (overline background variable-pitch 1.3)) + (2 . (rainbow overline 1.1)) + (t . (semibold)))) #+end_src ** Option for inhibiting theme reload @@ -470,7 +604,10 @@ this manual. :end: #+vindex: modus-themes-inhibit-reload -Symbol: ~modus-themes-inhibit-reload~ +Brief: Toggle reloading of the active theme when an option is changed +through the Customize UI. + +Symbol: ~modus-themes-inhibit-reload~ (=boolean= type) Possible values: @@ -483,35 +620,43 @@ currently active Modus theme. Enable this behavior by setting this variable to ~nil~. -** Option for color-coding success state +Regardless of this option, the active theme must be reloaded for changes +to user options to take effect ([[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]). + +** Option for red-green color deficiency or deuteranopia :properties: -:alt_title: Success' color-code -:description: Toggle blue color for success or done states +:alt_title: Deuteranopia style +:description: Toggle red/blue color-coding instead of red/green :custom_id: h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe :end: -#+vindex: modus-themes-success-deuteranopia +#+vindex: modus-themes-deuteranopia + +Brief: When non-nil use red/blue color-coding instead of red/green, +where appropriate. -Symbol: ~modus-themes-success-deuteranopia~ +Symbol: ~modus-themes-deuteranopia~ (=boolean= type) Possible values: 1. ~nil~ (default) 2. ~t~ -The default is to colorise all faces that denote "success", "done", or -similar with a variant of green. - -With a non-nil value (~t~), use variants of blue instead of green. This -is meant to empower users with red-green color deficiency. +This is to account for red-green color deficiency, also know as +deuteranopia and variants. It applies to all contexts where there can +be a color-coded distinction between failure or success, a to-do or done +state, a mark for deletion versus a mark for selection (e.g. in Dired), +current and lazily highlighted search matches, removed lines in diffs as +opposed to added ones, and so on. -The present customization option should apply to all contexts where -there can be a color-coded distinction between success and failure, -to-do and done, and so on. +Note that this does not change all colors throughout the active theme, +but only applies to cases that have color-coding significance. For +example, regular code syntax highlighting is not affected. There is no +such need because of the themes' overarching commitment to the highest +legibility standard, which ensures that text is readable regardless of +hue, as well as the predominance of colors on the +blue-cyan-magenta-purple side of the spectrum. -Diffs, which have a red/green dichotomy by default, can also be -configured to conform with deuteranopia. - -[[#h:ea7ac54f-5827-49bd-b09f-62424b3b6427][Option for diff buffer looks]]. +[[#h:0b26cb47-9733-4cb1-87d9-50850cb0386e][Why are colors mostly variants of blue, magenta, cyan?]]. ** Option for more bold constructs :properties: @@ -521,7 +666,9 @@ configured to conform with deuteranopia. :end: #+vindex: modus-themes-bold-constructs -Symbol: ~modus-themes-bold-constructs~ +Brief: Use bold for code syntax highlighting and related. + +Symbol: ~modus-themes-bold-constructs~ (=boolean= type) Possible values: @@ -549,7 +696,9 @@ Advanced users may also want to configure the exact attributes of the :end: #+vindex: modus-themes-italic-constructs -Symbol: ~modus-themes-italic-constructs~ +Brief: Use italics for code syntax highlighting and related. + +Symbol: ~modus-themes-italic-constructs~ (=boolean= type) Possible values: @@ -575,7 +724,9 @@ Advanced users may also want to configure the exact attributes of the :end: #+vindex: modus-themes-syntax -Symbol: ~modus-themes-syntax~ +Brief: Set the overall style of code syntax highlighting. + +Symbol: ~modus-themes-syntax~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -629,45 +780,52 @@ weight or italic text: ~modus-themes-bold-constructs~ and [[#h:977c900d-0d6d-4dbb-82d9-c2aae69543d6][Option for more italic constructs]]. -** Option for no font mixing +** Option for font mixing :properties: -:alt_title: No mixed fonts +:alt_title: Mixed fonts :description: Toggle mixing of font families :custom_id: h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b :end: -#+vindex: modus-themes-no-mixed-fonts +#+vindex: modus-themes-mixed-fonts -Symbol: ~modus-themes-no-mixed-fonts~ +Brief: Toggle the use of monospaced fonts for spacing-sensitive +constructs (affects font families). + +Symbol: ~modus-themes-mixed-fonts~ (=boolean= type) Possible values: 1. ~nil~ (default) 2. ~t~ -By default, the themes configure some spacing-sensitive faces like Org +When set to non-nil (~t~), configure some spacing-sensitive faces like Org tables and code blocks to always inherit from the ~fixed-pitch~ face. -This is to ensure that those constructs remain monospaced even when -users opt for a mode that remaps typeface families, such as the built-in -{{{kbd(M-x variable-pitch-mode)}}}. Otherwise the layout would appear -broken, due to how spacing is done. To disable this behavior, set the -option to ~t~. +This is to ensure that certain constructs like code blocks and tables +remain monospaced even when users opt for a mode that remaps typeface +families, such as the built-in {{{kbd(M-x variable-pitch-mode)}}}. Otherwise +the layout would appear broken, due to how spacing is done. -Users may prefer to use another package for handling mixed typeface -configurations, rather than letting the theme do it, perhaps because a -purpose-specific package has extra functionality. Two possible options -are ~org-variable-pitch~ and ~mixed-pitch~. +For a consistent experience, user may need to specify the font family of +the ~fixed-pitch~ face. [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. +Furthermore, users may prefer to use another package for handling mixed +typeface configurations, rather than letting the theme do it, perhaps +because a purpose-specific package has extra functionality. Two +possible options are ~org-variable-pitch~ and ~mixed-pitch~. + ** Option for links :properties: :alt_title: Link styles :description: Choose among several styles, with or without underline -:custom_id: h:c119d7b2-fcd4-4e44-890e-5e25733d5e52 +:custom_id: h:5808be52-361a-4d18-88fd-90129d206f9b :end: #+vindex: modus-themes-links -Symbol: ~modus-themes-links~ +Brief: Control the style of links to web pages, files, buffers... + +Symbol: ~modus-themes-links~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -730,6 +888,101 @@ controlled by ~x-use-underline-position-properties~, ~x-underline-at-descent-line~, ~underline-minimum-offset~. Please refer to their documentation strings. +** Option for box buttons +:properties: +:alt_title: Box buttons +:description: Choose among several styles for buttons +:custom_id: h:8b85f711-ff40-45b0-b7fc-4727503cd2ec +:end: +#+vindex: modus-themes-box-buttons + +Brief: Control the style of buttons in the Custom UI and related. + +Symbol: ~modus-themes-box-buttons~ (=choice= type, list of properties) + +Possible values are expressed as a list of properties (default is ~nil~ or +an empty list). The list can include any of the following symbols: + ++ ~flat~ ++ ~accented~ ++ ~faint~ ++ ~variable-pitch~ ++ ~underline~ ++ A font weight, which must be supported by the underlying typeface: + - ~thin~ + - ~ultralight~ + - ~extralight~ + - ~light~ + - ~semilight~ + - ~regular~ + - ~medium~ + - ~semibold~ + - ~bold~ + - ~heavy~ + - ~extrabold~ + - ~ultrabold~ ++ A floating point as a height multiple of the default or a cons cell in + the form of =(height . FLOAT)= ++ ~all-buttons~ + +The default (a nil value or an empty list) is a gray background combined +with a pseudo three-dimensional effect. + +The ~flat~ property makes the button two dimensional. + +The ~accented~ property changes the background from gray to an accent +color. + +The ~faint~ property reduces the overall coloration. + +The ~variable-pitch~ property applies a proportionately spaced typeface +to the button~s text. + +[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. + +The ~underline~ property draws a line below the affected text and +removes whatever box effect. This is optimal when Emacs runs inside a +terminal emulator ([[#h:fbb5e254-afd6-4313-bb05-93b3b4f67358][More accurate colors in terminal emulators]]). If +~flat~ and ~underline~ are defined together, the latter takes +precedence. + +The symbol of a weight attribute adjusts the font of the button +accordingly, such as ~light~, ~semibold~, etc. Valid symbols are +defined in the variable ~modus-themes-weights~. + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +A number, expressed as a floating point (e.g. =0.9=), adjusts the height +of the button's text to that many times the base font size. The default +height is the same as =1.0=, though it need not be explicitly stated. +Instead of a floating point, an acceptable value can be in the form of a +cons cell like =(height . FLOAT)= or =(height FLOAT)=, where FLOAT is +the given number. + +The ~all-buttons~ property extends the box button effect (or the +aforementioned properties) to the faces of the generic widget library. +By default, those do not look like the buttons of the Custom UI as they +are ordinary text wrapped in square brackets. + +Combinations of any of those properties are expressed as a list, +like in these examples: + +#+begin_src emacs-lisp +(flat) +(variable-pitch flat) +(variable-pitch flat semibold 0.9) +(variable-pitch flat semibold (height 0.9)) ; same as above +(variable-pitch flat semibold (height . 0.9)) ; same as above +#+end_src + +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-box-buttons '(variable-pitch flat 0.9)) +#+end_src + ** Option for command prompt styles :properties: :alt_title: Command prompts @@ -738,7 +991,10 @@ their documentation strings. :end: #+vindex: modus-themes-prompts -Symbol: ~modus-themes-prompts~ +Brief: Control the style of command prompts (e.g. minibuffer, shell, IRC +clients). + +Symbol: ~modus-themes-prompts~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -794,7 +1050,9 @@ In user configuration files the form may look like this: :end: #+vindex: modus-themes-mode-line -Symbol: ~modus-themes-mode-line~ +Brief: Control the style of the mode lines. + +Symbol: ~modus-themes-mode-line~ (=choice= type, list of properties) Possible values, which can be expressed as a list of combinations of box effect, color, and border visibility: @@ -804,42 +1062,58 @@ effect, color, and border visibility: - ~moody~ + ~accented~ + ~borderless~ -+ ~padded~ ++ A natural number > 1 for extra padding or a cons cell in the form of + ~(padding . NATNUM)~. ++ A floating point to set the height of the mode line's text. It can + also be a cons cell in the form of ~(height . FLOAT)~. The default (a nil value or an empty list) is a two-dimensional -rectangle with a border around it. The active and the inactive -mode lines use different shades of grayscale values for the -background, foreground, border. - -The ~3d~ property applies a three-dimensional effect to the -active mode line. The inactive mode lines remain two-dimensional -and are toned down a bit, relative to the default style. - -The ~moody~ property optimizes the mode line for use with the -library of the same name (hereinafter referred to as 'Moody'). -In practice, it removes the box effect and replaces it with -underline and overline properties. It also tones down the -inactive mode lines. Despite its intended purpose, this option -can also be used without the Moody library (please consult the -themes' manual on this point for more details). If both ~3d~ and -~moody~ properties are set, the latter takes precedence. - -The ~borderless~ property removes the color of the borders. It -does not actually remove the borders, but only makes their color -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. +rectangle with a border around it. The active and the inactive mode +lines use different shades of grayscale values for the background, +foreground, border. + +The ~3d~ property applies a three-dimensional effect to the active mode +line. The inactive mode lines remain two-dimensional and are toned down +a bit, relative to the default style. + +The ~moody~ property optimizes the mode line for use with the library of +the same name (hereinafter referred to as 'Moody'). In practice, it +removes the box effect and replaces it with underline and overline +properties. It also tones down the inactive mode lines. Despite its +intended purpose, this option can also be used without the Moody library +(please consult the themes' manual on this point for more details). If +both ~3d~ and ~moody~ properties are set, the latter takes precedence. + +The ~borderless~ property removes the color of the borders. It does not +actually remove the borders, but only makes their color 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. + +A positive integer (natural number or natnum) applies a padding effect +of NATNUM pixels at the boundaries of the mode lines. The default value +is 1 and does not need to be specified explicitly. The padding has no +effect when the ~moody~ property is also used, because Moody already +applies its own tweaks. To ensure that the underline is placed at the +bottom of the mode line, set ~x-underline-at-descent-line~ to non-nil +(this is not needed when the ~borderless~ property is also set). For +users on Emacs 29, the ~x-use-underline-position-properties~ variable must +also be set to nil. + +The padding can also be expressed as a cons cell in the form of +=(padding . NATNUM)= or =(padding NATNUM)= where the key is constant and +NATNUM is the desired natural number. + +A floating point applies an adjusted height to the mode line's text as a +multiple of the main font size. The default rate is 1.0 and does not +need to be specified. Apart from a floating point, the height may also +be expressed as a cons cell in the form of =(height . FLOAT)= or +=(height FLOAT)= where the key is constant and the FLOAT is the desired +number. -Combinations of any of those properties are expressed as a list, -like in these examples: +Combinations of any of those properties are expressed as a list, like in +these examples: #+begin_src emacs-lisp (accented) @@ -847,6 +1121,15 @@ like in these examples: (moody accented borderless) #+end_src +Same as above, using the padding and height as an example (these +all yield the same result): + +#+begin_src emacs-lisp +(accented borderless 4 0.9) +(accented borderless (padding . 4) (height . 0.9)) +(accented borderless (padding 4) (height 0.9)) +#+end_src + The order in which the properties are set is not significant. In user configuration files the form may look like this: @@ -874,8 +1157,12 @@ high, because it has the adverse effect of always overriding the default colors (which have been carefully designed to be highly accessible). 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. +a box style, it is strongly advised to set ~x-underline-at-descent-line~ +to a non-nil value. + +Finally, note that various packages which heavily modify the mode line, +such as =doom-modeline=, =nano-modeline=, =powerline=, =spaceline= may not look +as intended with all possible combinations of this user option. ** Option for accented background in tab interfaces :properties: @@ -885,7 +1172,9 @@ non-nil value. :end: #+vindex: modus-themes-tabs-accented -Symbol: ~modus-themes-tabs-accented~ +Brief: Toggle accent colors for tabbed interfaces. + +Symbol: ~modus-themes-tabs-accented~ (=boolean= type) Possible values: @@ -901,47 +1190,106 @@ Centaur tabs package. ** Option for completion framework aesthetics :properties: :alt_title: Completion UIs -:description: Choose among standard, moderate, or opinionated looks +:description: Choose among several styles for completion UIs :custom_id: h:f1c20c02-7b34-4c35-9c65-99170efb2882 :end: #+vindex: modus-themes-completions -Symbol: ~modus-themes-completions~ +Brief: Set the overall style of completion framework interfaces. -Possible values: +Symbol: ~modus-themes-completions~ (=alist= type properties) -1. ~nil~ (default) -2. ~moderate~ -3. ~opinionated~ - -This is a special option that has different effects depending on the -completion UI. The interfaces can be grouped in two categories, based -on their default aesthetics: (i) those that only or mostly use -foreground colors for their interaction model, and (ii) those that -combine background and foreground values for some of their metaphors. -The former category encompasses Icomplete, Ido, Selectrum, Vertico, as -well as pattern matching styles like Orderless and Flx. The latter -covers Helm, Ivy, and Sallet. - -A value of ~nil~ (the default) will simply respect the metaphors of each -completion framework. - -Option ~moderate~ applies a combination of background and foreground that -is fairly subtle. For Icomplete and friends this constitutes a -departure from their default aesthetics, however the difference is -small. While Helm, Ivy et al appear slightly different than their -original looks, as they are toned down a bit. - -Option ~opinionated~ uses color combinations that refashion the completion -UI. For the Icomplete camp this means that intense background and -foreground combinations are used: in effect their looks emulate those of -Helm, Ivy and co. in their original style. Whereas the other group of -packages will revert to an even more nuanced aesthetic with some -additional changes to the choice of hues. - -To appreciate the scope of this customization option, you should spend -some time with every one of the ~nil~ (default), ~moderate~, and ~opinionated~ -possibilities. +This affects Company, Corfu, Flx, Helm, Icomplete/Fido, Ido, Ivy, Mct, +Orderless, Selectrum, Vertico. The value is an alist that takes the +form of a =(key . properties)= combination. Here is a sample, followed +by a description of the particularities: + +#+begin_src emacs-lisp +(setq modus-themes-completions + '((matches . (extrabold background intense)) + (selection . (semibold accented intense)) + (popup . (accented)))) +#+end_src + +The ~matches~ key refers to the highlighted characters that correspond +to the user's input. By default (nil or an empty list), they have a +bold weight and a colored foreground. The list of properties may +include any of the following symbols regardless of the order they may +appear in: + +- ~background~ to add a background color; + +- ~intense~ to increase the overall coloration (also amplifies + the ~background~, if present); + +- ~underline~ to draw a line below the characters; + +- ~italic~ to use a slanted font (italic or oblique forms); + +- The symbol of a font weight attribute such as ~light~, ~semibold~, et + cetera. Valid symbols are defined in the ~modus-themes-weights~ + variable. The absence of a weight means that bold will be used. + +The ~selection~ key applies to the current line or currently matched +candidate, depending on the specifics of the User Interface. By default +(nil or an empty list), it has a subtle gray background, a bold weight, +and the base foreground value for the text. The list of properties it +accepts is as follows (order is not significant): + +- ~accented~ to make the background colorful instead of gray; + +- ~text-also~ to apply extra color to the text of the selected line; + +- ~intense~ to increase the overall coloration; + +- ~underline~ to draw a line below the characters; + +- ~italic~ to use a slanted font (italic or oblique forms); + +- The symbol of a font weight attribute such as ~light~, ~semibold~, et + cetera. Valid symbols are defined in the ~modus-themes-weights~ + variable. The absence of a weight means that bold will be used. + +The ~popup~ key takes the same values as ~selection~. + +Apart from specifying each key separately, a fallback list is accepted. +This is only useful when the desired aesthetic is the same across all +keys that are not explicitly referenced. For example, this: + +#+begin_src emacs-lisp +(setq modus-themes-completions + '((t . (extrabold intense)))) +#+end_src + +Is the same as: + +#+begin_src emacs-lisp +(setq modus-themes-completions + '((matches . (extrabold intense)) + (selection . (extrabold intense)) + (popup . (extrabold intense)))) +#+end_src + +In the case of the fallback, any property that does not apply to the +corresponding key is simply ignored (~matches~ does not have ~accented~ +and ~text-also~, while ~selection~ and ~popup~ do not have +~background~). + +A concise expression of those associations can be written as follows, +where the ~car~ is always the key and the ~cdr~ is the list of +properties (whatever order they may appear in): + +#+begin_src emacs-lisp +(setq modus-themes-completions + '((matches extrabold background intense) + (selection semibold accented intense) + (popup accented))) +#+end_src + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +Also refer to the Orderless documentation for its intersection with +Company (if you choose to use those in tandem). ** Option for mail citations :properties: @@ -951,22 +1299,29 @@ possibilities. :end: #+vindex: modus-themes-mail-citations -Symbol: ~modus-themes-mail-citations~ +Brief: Set the overall style of citations/quotes when composing +emails. + +Symbol: ~modus-themes-mail-citations~ (=choice= type) Possible values: 1. ~nil~ (default) -2. ~faint~ -3. ~monochrome~ +2. ~intense~ +3. ~faint~ +4. ~monochrome~ -By default, citations in email-related buffers apply contrasting hues to -different levels of depth in cited text. The colors are fairly easy to -tell apart. +By default (a nil value) citations are styled with contrasting hues to +denote their depth. Colors are easy to tell apart because they +complement each other, but they otherwise are not very prominent. -A value of ~faint~ makes all citation levels less intense, while retaining -the default style of contrasting hues (albeit very subtle ones). +Option ~intense~ is similar to the default in terms of using contrasting +and complementary hues, but applies more saturated colors. -Option ~monochrome~ turns all citations in to a uniform shade of gray. +Option ~faint~ maintains the same color-based distinction between citation +levels though the colors it uses have subtle differences between them. + +Option ~monochrome~ turns all quotes into a shade of gray. Whatever the value assigned to this variable, citations in emails are controlled by typographic elements or indentation, which the themes do @@ -980,7 +1335,9 @@ not touch. :end: #+vindex: modus-themes-fringes -Symbol: ~modus-themes-fringes~ +Brief: Control the overall coloration of the fringes. + +Symbol: ~modus-themes-fringes~ (=choice= type) Possible values: @@ -1004,7 +1361,10 @@ names imply. :end: #+vindex: modus-themes-lang-checkers -Symbol: ~modus-themes-lang-checkers~ +Brief: Control the style of in-buffer warnings and errors produced by +spell checkers, code linters, and the like. + +Symbol: ~modus-themes-lang-checkers~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -1012,7 +1372,9 @@ an empty list). The list can include any of the following symbols: + ~straight-underline~ + ~text-also~ + ~background~ -+ ~intense~ ++ Overall coloration: + - ~intense~ + - ~faint~ The default (a ~nil~ value or an empty list) applies a color-coded underline to the affected text, while it leaves the original foreground @@ -1028,15 +1390,15 @@ affected text. The property ~background~ adds a color-coded background. The property ~intense~ amplifies the applicable colors if ~background~ -and/or ~text-only~ are set. If ~intense~ is set on its own, then it implies -~text-only~. +and/or ~text-also~ are set. If ~intense~ is set on its own, then it implies +~text-also~. -To disable fringe indicators for Flymake or Flycheck, refer to variables -~flymake-fringe-indicator-position~ and ~flycheck-indication-mode~, -respectively. +The property ~faint~ uses nuanced colors for the underline and for the +foreground when ~text-also~ is included. If both ~faint~ and ~intense~ are +specified, the former takes precedence. -Combinations of any of those properties can be expressed in a -list, as in those examples: +Combinations of any of those properties can be expressed in a list, as +in those examples: #+begin_src emacs-lisp (background) @@ -1056,6 +1418,10 @@ NOTE: The placement of the straight underline, though not the wave style, is controlled by the built-in variables ~underline-minimum-offset~, ~x-underline-at-descent-line~, ~x-use-underline-position-properties~. +To disable fringe indicators for Flymake or Flycheck, refer to variables +~flymake-fringe-indicator-position~ and ~flycheck-indication-mode~, +respectively. + ** Option for line highlighting :properties: :alt_title: Line highlighting @@ -1064,7 +1430,9 @@ style, is controlled by the built-in variables ~underline-minimum-offset~, :end: #+vindex: modus-themes-hl-line -Symbol: ~modus-themes-hl-line~ +Brief: Control the style of the current line of ~hl-line-mode~. + +Symbol: ~modus-themes-hl-line~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -1116,7 +1484,9 @@ This style affects several packages that enable ~hl-line-mode~, such as :end: #+vindex: modus-themes-subtle-line-numbers -Symbol: ~modus-themes-subtle-line-numbers~ +Brief: Toggle subtle line numbers. + +Symbol: ~modus-themes-subtle-line-numbers~ (=boolean= type) Possible value: @@ -1137,6 +1507,84 @@ Instead they retain the primary background of the theme, blending with the rest of the buffer. Foreground values for all relevant faces are updated to accommodate this aesthetic. +** Option for mouseover effects +:properties: +:alt_title: Mouse hover effects +:description: Toggle intense style for mouseover highlights +:custom_id: h:9b869620-fcc5-4b5f-9ab8-225d73b7f22f +:end: +#+vindex: modus-themes-intense-mouseovers + +Brief: Toggle intense mouse hover effects. + +Symbol: ~modus-themes-intense-mouseovers~ (=boolean= type) + +Possible value: + +1. ~nil~ (default) +2. ~t~ + +By default all mouseover effects apply a highlight with a subtle colored +background. When non-nil, these have a more pronounced effect. + +Note that this affects the generic ~highlight~ which, strictly speaking, +is not limited to mouse usage. + +** Option for markup style in Org and others +:properties: +:alt_title: Markup +:description: Choose style for markup in Org and others +:custom_id: h:9d9a4e64-99ac-4018-8f66-3051b9c43fd7 +:end: +#+vindex: modus-themes-markup + +Brief: Choose style of markup in Org, Markdown, and others (affects +constructs such as Org's ==verbatim== and =~code~=). + +Symbol: ~modus-themes-markup~ (=boolean= type) + +Possible values are expressed as a list of properties (default is ~nil~ or +an empty list). The list can include any of the following symbols: + +1. ~bold~ +2. ~italic~ +3. ~background~ +4. ~intense~ + +The ~italic~ property applies a typographic slant (italics). + +The ~bold~ property applies a heavier typographic weight. + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +The ~background~ property adds a background color. The background is a +shade of gray, unless the ~intense~ property is also set. + +The ~intense~ property amplifies the existing coloration. When +~background~ is used, the background color is enhanced as well and +becomes tinted instead of being gray. + +Combinations of any of those properties are expressed as a list, +like in these examples: + +#+begin_src emacs-lisp +(bold) +(bold italic) +(bold italic intense) +(bold italic intense background) +#+end_src + +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-markup '(bold italic)) +#+end_src + +Also check the variables ~org-hide-emphasis-markers~, +~org-hide-macro-markers~. + ** Option for parenthesis matching :properties: :alt_title: Matching parentheses @@ -1145,7 +1593,10 @@ updated to accommodate this aesthetic. :end: #+vindex: modus-themes-paren-match -Symbol: ~modus-themes-paren-match~ +Brief: Control the style of matching delimiters produced by +~show-paren-mode~. + +Symbol: ~modus-themes-paren-match~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -1192,7 +1643,9 @@ This customization variable affects the built-in ~show-paren-mode~ and the :end: #+vindex: modus-themes-region -Symbol: ~modus-themes-region~ +Brief: Control the style of the region. + +Symbol: ~modus-themes-region~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -1233,23 +1686,24 @@ In user configuration files the form may look like this: ** Option for diff buffer looks :properties: :alt_title: Diffs -:description: Choose among intense, desaturated, or text-only diffs +:description: Choose among intense, desaturated, or background-only diffs :custom_id: h:ea7ac54f-5827-49bd-b09f-62424b3b6427 :end: #+vindex: modus-themes-diffs -Symbol: ~modus-themes-diffs~ +Brief: Set the overall style of diffs. + +Symbol: ~modus-themes-diffs~ (=choice= type) Possible values: 1. ~nil~ (default) 2. ~desaturated~ 3. ~bg-only~ -4. ~deuteranopia~ -5. ~fg-only-deuteranopia~ The default (~nil~) uses fairly intense color combinations for diffs, by -applying prominently colored backgrounds, with appropriate foregrounds. +applying prominently colored backgrounds, with appropriately tinted +foregrounds. Option ~desaturated~ follows the same principles as with the default (~nil~), though it tones down all relevant colors. @@ -1257,24 +1711,24 @@ Option ~desaturated~ follows the same principles as with the default Option ~bg-only~ applies a background but does not override the text's foreground. This makes it suitable for a non-nil value passed to ~diff-font-lock-syntax~ (note: Magit does not support syntax highlighting -in diffs---last checked on 2021-04-21). - -Option ~deuteranopia~ is like the default (~nil~) in terms of using -prominently colored backgrounds, except that it also accounts for -red-green color defficiency by replacing all instances of green with -colors on the blue side of the spectrum. Other stylistic changes are -made in the interest of optimizing for such a use-case. - -Option ~fg-only-deuteranopia~ removes all colored backgrounds, except from -word-wise or refined changes. Instead, it only uses color-coded -foreground values to differentiate between added, removed, and changed -lines. If a background is necessary to denote context, a subtle -grayscale value is applied. The color used for added lines is a variant -of blue to account for red-green color defficiency but also because -green text alone is hard to discern in the diff's context (hard for our -accessibility purposes). The ~fg-only~ option that existed in older -versions of the themes is now an alias of ~fg-only-deuteranopia~, in the -interest of backward compatibility. +in diffs---last checked on 2021-12-02). + +When the user option ~modus-themes-deuteranopia~ is non-nil, all diffs +will use a red/blue color-coding system instead of the standard +red/green. Other stylistic changes are made in the interest of +optimizing for such a use-case. + +[[#h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe][Option for red-green color deficiency or deuteranopia]]. + +In versions before =2.0.0= there was an option for foreground-only diffs. +This is no longer supported at the theme level because there are cases +where the perceived contrast and overall contextuality were not good +enough although the applied colors were technically above the 7:1 +contrast threshold. + +[[#h:e2aed9eb-5e1e-45ec-bbd7-bc4faeab3236][Diffs with only the foreground]]. + +[[#h:b0b31802-0216-427e-b071-1a47adcfe608][Ediff without diff color-coding]]. ** Option for org-mode block styles :properties: @@ -1284,7 +1738,9 @@ interest of backward compatibility. :end: #+vindex: modus-themes-org-blocks -Symbol: ~modus-themes-org-blocks~ +Brief: Set the overall style of Org code blocks, quotes, and the like. + +Symbol: ~modus-themes-org-blocks~ (=choice= type) Possible values: @@ -1292,20 +1748,28 @@ Possible values: 2. ~gray-background~ (value ~grayscale~ exists for backward compatibility) 3. ~tinted-background~ (value ~rainbow~ exists for backward compatibility) -The default means that the block has no distinct background of its own -and uses the one that applies to the rest of the buffer. +Nil (the default) means that the block has no background of its own: it +uses the one that applies to the rest of the buffer. In this case, the +delimiter lines have a gray color for their text, making them look +exactly like all other Org properties. Option ~gray-background~ applies a subtle gray background to the block's -contents. It also affects the begin and end lines of the block: their -background extends to the edge of the window for Emacs version >= 27 -where the ~:extend~ keyword is recognized by ~set-face-attribute~ (this is -contingent on the variable ~org-fontify-whole-block-delimiter-line~). +contents. It also affects the begin and end lines of the block as they +get another shade of gray as their background, which differentiates them +from the contents of the block. All background colors extend to the +edge of the window, giving the area a rectangular, "blocky" +presentation. Option ~tinted-background~ uses a slightly colored background for the contents of the block. The exact color will depend on the programming language and is controlled by the variable ~org-src-block-faces~ (refer to the theme's source code for the current association list). For this to -take effect, Org must be restarted with {{{kbd(M-x org-mode-restart)}}}. +take effect, the Org buffer needs to be restarted with ~org-mode-restart~. +In this scenario, it may be better to inhibit the extension of the +delimiter lines' background to the edge of the window because Org does +not provide a mechanism to update their colors depending on the contents +of the block. Disable the extension of such backgrounds by setting +~org-fontify-whole-block-delimiter-line~ to nil. Code blocks use their major mode's colors only when the variable ~org-src-fontify-natively~ is non-nil. While quote/verse blocks require @@ -1325,7 +1789,10 @@ and ~rainbow~. Those will continue to work as they are aliases for :end: #+vindex: modus-themes-org-agenda -Symbol: ~modus-themes-org-agenda~ +Brief: Control the style of the Org agenda. Multiple parameters are +available, each with its own options. + +Symbol: ~modus-themes-org-agenda~ (=alist= type, multiple styles) This is an alist that accepts a =(key . value)= combination. Some values are specified as a list. Here is a sample, followed by a description of @@ -1333,9 +1800,9 @@ all possible combinations: #+begin_src emacs-lisp (setq modus-themes-org-agenda - '((header-block . (variable-pitch scale-title)) - (header-date . (grayscale workaholic bold-today)) - (event . (accented scale-small)) + '((header-block . (variable-pitch 1.5)) + (header-date . (grayscale workaholic bold-today 1.2)) + (event . (accented italic varied)) (scheduled . uniform) (habit . traffic-light))) #+end_src @@ -1348,20 +1815,37 @@ come in the form of a list that can include either or both of those properties: - ~variable-pitch~ to use a proportionately spaced typeface; -- ~scale-title~ to increase the size to the number assigned to - ~modus-themes-scale-title~ ([[#h:6868baa1-beba-45ed-baa5-5fd68322ccb3][Control the scale of headings]]) or ~no-scale~ - to make the font use the same height as the rest of the buffer. -In case both ~scale-title~ and ~no-scale~ are in the list, the latter takes -precedence. +- A number as a floating point (e.g. 1.5) to set the height of the text + to that many times the default font height. A float of 1.0 or the + symbol ~no-scale~ have the same effect of making the font the same + height as the rest of the buffer. When neither a number nor + `no-scale' are present, the default is a small increase in height (a + value of 1.15). + + Instead of a floating point, an acceptable value can be in the form of + a cons cell like =(height . FLOAT)= or =(height FLOAT)=, where FLOAT + is the given number. + +- The symbol of a weight attribute adjusts the font of the heading + accordingly, such as ~light~, ~semibold~, etc. Valid symbols are + defined in the variable ~modus-themes-weights~. The absence of a + weight means that bold will be used by virtue of inheriting the ~bold~ + face. + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +In case both a number and ~no-scale~ are in the list, the latter takes +precedence. If two numbers are specified, the first one is applied. Example usage: #+begin_src emacs-lisp (header-block . nil) -(header-block . (scale-title)) +(header-block . (1.5)) (header-block . (no-scale)) -(header-block . (variable-pitch scale-title)) +(header-block . (variable-pitch 1.5)) +(header-block . (variable-pitch 1.5 semibold)) #+end_src A ~header-date~ key covers date headings. Dates use only a foreground @@ -1372,16 +1856,24 @@ the following properties: - ~grayscale~ to make weekdays use the main foreground color and weekends a more subtle gray; + - ~workaholic~ to make weekdays and weekends look the same in terms of color; + - ~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). + +- ~bold-all~ to render all date headings in a bold weight; + - ~underline-today~ applies an underline to the current date while - removing the background it has by default. + removing the background it has by default; + +- A number as a floating point (e.g. 1.2) to set the height of the text + to that many times the default font height. The default is the same + as the base font height (the equivalent of 1.0). Instead of a + floating point, an acceptable value can be in the form of a cons cell + like =(height . FLOAT)= or =(height FLOAT)=, where FLOAT is the given + number. For example: @@ -1394,28 +1886,35 @@ For example: (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: +An ~event~ key covers (i) headings with a plain time stamp that are +shown on the agenda, also known as events, (ii) entries imported from +the diary, and (iii) other items that derive from a symbolic expression +or sexp (phases of the moon, holidays, etc.). By default all those look +the same and have a subtle foreground color (the default is a nil value +or an empty list). This key accepts a list of properties. Those 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. +- ~accented~ applies an accent value to the event's foreground, + replacing the original gray. It makes all entries stand out more. - ~italic~ adds a slant to the font's forms (italic or oblique forms, depending on the typeface). +- ~varied~ differentiates between events with a plain time stamp and + entries that are generated from either the diary or a symbolic + expression. It generally puts more emphasis on events. When ~varied~ + is combined with ~accented~, it makes only events use an accent color, + while diary/sexp entries retain their original subtle foreground. + When ~varied~ is used in tandem with ~italic~, it applies a slant only + to diary and sexp entries, not events. And when ~varied~ is the sole + property passed to the ~event~ key, it has the same meaning as the + list (italic varied). The combination of ~varied~, ~accented~, + ~italic~ covers all of the aforementioned cases. For example: #+begin_src emacs-lisp (event . nil) -(event . (scale-small)) -(event . (scale-small accented)) -(event . (scale-small accented italic)) +(event . (italic)) +(event . (accented italic)) +(event . (accented italic varied)) #+end_src A ~scheduled~ key applies to tasks with a scheduled date. By default (a @@ -1460,9 +1959,12 @@ passed as a symbol. Those are: being too late. The difference between ready and clear states is attenuated by painting both of them using shades of green. This option thus highlights the alert and overdue states. -- ~traffic-light-deuteranopia~ is like the ~traffic-light~ except its three - colors are red, yellow, and blue to be suitable for users with - red-green color deficiency (deuteranopia). +- When ~modus-themes-deuteranopia~ is non-nil the exact style of the habit + graph adapts to the needs of users with red-green color deficiency by + substituting every instance of green with blue or cyan (depending on + the specifics). + +[[#h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe][Option for red-green color deficiency or deuteranopia]]. For example: @@ -1475,17 +1977,17 @@ For example: Putting it all together, the alist can look like this: #+begin_src emacs-lisp -'((header-block . (scale-title variable-pitch)) +'((header-block . (1.5 variable-pitch)) (header-date . (grayscale workaholic bold-today)) - (event . (accented scale-small)) + (event . (accented varied)) (scheduled . uniform) (habit . traffic-light)) ;; Or else: (setq modus-themes-org-agenda - '((header-block . (scale-title variable-pitch)) + '((header-block . (1.5 variable-pitch)) (header-date . (grayscale workaholic bold-today)) - (event . (accented scale-small)) + (event . (accented varied)) (scheduled . uniform) (habit . traffic-light))) #+end_src @@ -1498,7 +2000,10 @@ Putting it all together, the alist can look like this: :end: #+vindex: modus-themes-headings -Symbol: ~modus-themes-headings~ +Brief: Control the style of headings. This can be particularised for +each level of heading (e.g. Org has eight levels). + +Symbol: ~modus-themes-headings~ (=alist= type, multiple properties) This is an alist that accepts a =(key . list-of-values)= combination. The key is either a number, representing the heading's level or ~t~, which @@ -1508,8 +2013,9 @@ a presentation of all available properties: #+begin_src emacs-lisp (setq modus-themes-headings - '((1 . (background overline)) - (2 . (overline rainbow)) + '((1 . (background overline variable-pitch 1.5)) + (2 . (overline rainbow 1.3)) + (3 . (overline 1.1)) (t . (monochrome)))) #+end_src @@ -1518,8 +2024,23 @@ Properties: + ~rainbow~ + ~overline~ + ~background~ -+ ~no-bold~ + ~monochrome~ ++ A font weight, which must be supported by the underlying typeface: + - ~thin~ + - ~ultralight~ + - ~extralight~ + - ~light~ + - ~semilight~ + - ~regular~ + - ~medium~ + - ~semibold~ + - ~bold~ + - ~heavy~ + - ~extrabold~ + - ~ultrabold~ ++ ~no-bold~ (deprecated alias of a ~regular~ weight) ++ A floating point as a height multiple of the default or a cons cell in + the form of =(height . FLOAT)=. By default (a ~nil~ value for this variable), all headings have a bold typographic weight and use a desaturated text color. @@ -1531,20 +2052,39 @@ An ~overline~ property draws a line above the area of the heading. A ~background~ property adds a subtle tinted color to the background of the heading. -A ~no-bold~ property removes the bold weight from the heading's text. +A ~monochrome~ property makes the heading the same as the base color, +which is that of the ~default~ face's foreground. When ~background~ is also +set, ~monochrome~ changes its color to gray. If both ~monochrome~ and +~rainbow~ are set, the former takes precedence. + +A ~variable-pitch~ property changes the font family of the heading to that +of the ~variable-pitch~ face (normally a proportionately spaced typeface). + +The symbol of a weight attribute adjusts the font of the heading +accordingly, such as ~light~, ~semibold~, etc. Valid symbols are +defined in the variable ~modus-themes-weights~. The absence of a weight +means that bold will be used by virtue of inheriting the ~bold~ face. +For backward compatibility, the ~no-bold~ value is accepted, though +users are encouraged to specify a ~regular~ weight instead. + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. -A ~monochrome~ property makes all headings the same base color, which is -that of the default for the active theme (black/white). When ~background~ -is also set, ~monochrome~ changes its color to gray. If both ~monochrome~ -and ~rainbow~ are set, the former takes precedence. +A number, expressed as a floating point (e.g. 1.5), adjusts the height +of the heading to that many times the base font size. The default +height is the same as 1.0, though it need not be explicitly stated. +Instead of a floating point, an acceptable value can be in the form of a +cons cell like =(height . FLOAT)= or =(height FLOAT)=, where FLOAT is +the given number. Combinations of any of those properties are expressed as a list, like in these examples: #+begin_src emacs-lisp -(no-bold) +(semibold) (rainbow background) -(overline monochrome no-bold) +(overline monochrome semibold 1.3) +(overline monochrome semibold (height 1.3)) ; same as above +(overline monochrome semibold (height . 1.3)) ; same as above #+end_src The order in which the properties are set is not significant. @@ -1553,9 +2093,9 @@ In user configuration files the form may look like this: #+begin_src emacs-lisp (setq modus-themes-headings - '((1 . (background overline rainbow)) - (2 . (background overline)) - (t . (overline no-bold)))) + '((1 . (background overline rainbow 1.5)) + (2 . (background overline 1.3)) + (t . (overline semibold)))) #+end_src When defining the styles per heading level, it is possible to pass a @@ -1570,7 +2110,7 @@ original aesthetic for that level. For example: (setq modus-themes-headings '((1 . (background overline)) - (2 . (rainbow no-bold)) + (2 . (rainbow semibold)) (t . t))) ; default style for all other levels #+end_src @@ -1579,100 +2119,6 @@ For Org users, the extent of the heading depends on the variable ~background~ properties. Depending on the version of Org, there may be others, such as ~org-fontify-done-headline~. -[[#h:075eb022-37a6-41a4-a040-cc189f6bfa1f][Option for scaled headings]]. - -[[#h:97caca76-fa13-456c-aef1-a2aa165ea274][Option for variable-pitch font in headings]]. - -** Option for scaled headings -:properties: -:alt_title: Scaled headings -:description: Toggle scaling of headings -:custom_id: h:075eb022-37a6-41a4-a040-cc189f6bfa1f -:end: -#+vindex: modus-themes-scale-headings - -Symbol: ~modus-themes-scale-headings~ - -Possible values: - -1. ~nil~ (default) -2. ~t~ - -The default is to use the same size for headings and paragraph text. - -With a non-nil value (~t~) make headings larger in height relative to the -main text. This is noticeable in modes like Org, Markdown, and Info. - -*** Control the scale of headings -:properties: -:alt_title: Scaled heading sizes -:description: Specify rate of increase for scaled headings -:custom_id: h:6868baa1-beba-45ed-baa5-5fd68322ccb3 -:end: - -In addition to the toggle for enabling scaled headings, users can also -specify a number of their own. - -+ If it is a floating point, say, =1.5=, it is interpreted as a multiple - of the base font size. This is the recommended method, because it - will always adapt to changes in the base font size, such as while - using the ~text-scale-adjust~ command. - -+ If it is an integer, it is read as an absolute font height that is - 1/10 of the typographic point size. Thus a value of =18pt= must be - expressed as =180=. Setting an absolute value is discouraged, as it - will break the layout in cases where the base font size must change, - such as with the ~text-scale-adjust~ command ([[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations]]). - While we discourage using absolute values, we still provide for this - option for users who do not need to perform text-scaling operations or - who are content with whatever discrepancies in height. - -Below are the variables in their default values, using the floating -point paradigm. The numbers are very conservative, but one is free to -change them to their liking, such as =1.2=, =1.4=, =1.6=, =1.8=, =2.0=---or use a -resource for finding a consistent scale: - -#+begin_src emacs-lisp -(setq modus-themes-scale-1 1.05 - 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-small 0.9) -#+end_src - -As for the application of that scale, the variables that range from -~modus-themes-scale-1~ up to ~modus-themes-scale-4~ apply to regular -headings within the context of the given major mode. The former is the -smallest, while the latter is the largest. "Regular headings" are those -that have a standard syntax for their scale, such as Org mode's eight -levels of asterisks or Markdown's six columns. - -Whereas ~modus-themes-scale-title~ is applied to special headings that do -not conform with the aforementioned syntax, yet which are expected to be -larger than the largest value on that implied scale or at least have -some unique purpose in the buffer. Put concretely, Org's =#+title= meta -datum is not part of the eight levels of headings in an Org file, yet is -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 -whatever value would render it indistinguishable from the desired point -of reference). - -Note that in earlier versions of Org, scaling would only increase the -size of the heading, but not of keywords that were added to it, like -"TODO". The issue has been fixed upstream: -<https://protesilaos.com/codelog/2020-09-24-org-headings-adapt/>. - ** Option for variable-pitch font in UI elements :properties: :alt_title: UI typeface @@ -1681,7 +2127,10 @@ size of the heading, but not of keywords that were added to it, like :end: #+vindex: modus-themes-variable-pitch-ui -Symbol: ~modus-themes-variable-pitch-ui~ +Brief: Toggle the use of proportionately spaced (~variable-pitch~) fonts +in the User Interface. + +Symbol: ~modus-themes-variable-pitch-ui~ (=boolean= type) Possible values: @@ -1700,29 +2149,6 @@ is done by assigning the ~variable-pitch~ face to the relevant items. [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. -** Option for variable-pitch font in headings -:properties: -:alt_title: Headings' typeface -:description: Toggle the use of variable-pitch in headings -:custom_id: h:97caca76-fa13-456c-aef1-a2aa165ea274 -:end: -#+vindex: modus-themes-variable-pitch-headings - -Symbol: ~modus-themes-variable-pitch-headings~ - -Possible values: - -1. ~nil~ (default) -2. ~t~ - -The default is to use the main font family, which typically is -monospaced. - -With a non-nil value (~t~) apply a proportionately spaced typeface, else -"variable-pitch", to headings (such as in Org mode). - -[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. - * Advanced customization :properties: :custom_id: h:f4651d55-8c07-46aa-b52b-bed1e53463bb @@ -1738,6 +2164,128 @@ their own local tweaks and who are willing to deal with any possible incompatibilities between versioned releases of the themes. As such, they are labeled as "do-it-yourself" or "DIY". +** More accurate colors in terminal emulators +:PROPERTIES: +:CUSTOM_ID: h:fbb5e254-afd6-4313-bb05-93b3b4f67358 +:END: +#+cindex: Color accuracy of terminal emulators + +[ This is based on partial information. Please help verify and/or + expand these findings. ] + +The graphical version of Emacs can reproduce color values accurately. +Whereas things get more tricky when Emacs is used in a terminal +emulator, because the terminals' own capabilities determine the number +of colors that may be displayed: the Modus themes don't look as good in +that case. + +There is, however, a way to instruct supported terminal emulators to use +more accurate colors. In a shell prompt type =toe -a | grep direct= to +get a list of relevant terminfo entries. There should be items such as +=xterm-direct=, =alacritty-direct=, =kitty-direct=. Once you find the one +that corresponds to your terminal, call Emacs with an environment +variable like =TERM=xterm-direct=. Example that can be adapted to shell +aliases: + +: TERM=xterm-direct emacsclient -nw + +Another example that can be bound to a key: + +: TERM=xterm-direct uxterm -e emacsclient -nw + +** Range of color with terminal emulators +:PROPERTIES: +:CUSTOM_ID: h:6b8211b0-d11b-4c00-9543-4685ec3b742f +:END: +#+cindex: Pure white and pure black in terminal emulators + +[ This is based on partial information. Please help verify and/or + expand these findings. ] + +When Emacs runs in a non-windowed session its color reproduction +capacity is framed or determined by the underlying terminal emulator +([[#h:fbb5e254-afd6-4313-bb05-93b3b4f67358][More accurate colors in terminal emulators]]). Emacs cannot produce a +color that lies outside the range of what the terminal's color palette +renders possible. + +This is immediately noticeable when the terminal's first 16 codes do not +include a pure black value for the =termcol0= entry and a pure white for +=termcol15=. Emacs cannot set the correct background (white for +~modus-operandi~; black for ~modus-vivendi~) or foreground (inverse of +the background). It thus falls back to the closest approximation, which +seldom is appropriate for the purposes of the Modus themes. + +In such a case, the user is expected to update their terminal's color +palette such as by adapting these resources: + +#+begin_src emacs-lisp +! Theme: modus-operandi +! Description: XTerm port of modus-operandi (Modus themes for GNU Emacs) +! Author: Protesilaos Stavrou, <https://protesilaos.com> +xterm*background: #ffffff +xterm*foreground: #000000 +xterm*color0: #000000 +xterm*color1: #a60000 +xterm*color2: #005e00 +xterm*color3: #813e00 +xterm*color4: #0031a9 +xterm*color5: #721045 +xterm*color6: #00538b +xterm*color7: #bfbfbf +xterm*color8: #595959 +xterm*color9: #972500 +xterm*color10: #315b00 +xterm*color11: #70480f +xterm*color12: #2544bb +xterm*color13: #5317ac +xterm*color14: #005a5f +xterm*color15: #ffffff + +! Theme: modus-vivendi +! Description: XTerm port of modus-vivendi (Modus themes for GNU Emacs) +! Author: Protesilaos Stavrou, <https://protesilaos.com> +xterm*background: #000000 +xterm*foreground: #ffffff +xterm*color0: #000000 +xterm*color1: #ff8059 +xterm*color2: #44bc44 +xterm*color3: #d0bc00 +xterm*color4: #2fafff +xterm*color5: #feacd0 +xterm*color6: #00d3d0 +xterm*color7: #bfbfbf +xterm*color8: #595959 +xterm*color9: #ef8b50 +xterm*color10: #70b900 +xterm*color11: #c0c530 +xterm*color12: #79a8ff +xterm*color13: #b6a0ff +xterm*color14: #6ae4b9 +xterm*color15: #ffffff +#+end_src + +** Visualize the active Modus theme's palette +:properties: +:custom_id: h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d +:end: +#+findex: modus-themes-list-colors +#+findex: modus-themes-list-colors-current +#+cindex: Preview color values + +The command ~modus-themes-list-colors~ prompts for a choice between +=modus-operandi= and =modus-vivendi= to produce a help buffer that shows a +preview of each variable in the given theme's color palette. The +command ~modus-themes-list-colors-current~ skips the prompt, using the +current Modus theme. + +Each row shows a foreground and background coloration using the +underlying value it references. For example a line with =#a60000= (a +shade of red) will show red text followed by a stripe with that same +color as a backdrop. + +The name of the buffer describes the given Modus theme. It is thus +called =*modus-operandi-list-colors*= or =*modus-vivendi-list-colors*=. + ** Per-theme customization settings :properties: :custom_id: h:a897b302-8e10-4a26-beab-3caaee1e1193 @@ -1813,7 +2361,11 @@ The function always extracts the color value of the active Modus theme. #+end_src Do {{{kbd(C-h v)}}} on the aforementioned variables to check all the available -symbols that can be passed to this function. +symbols that can be passed to this function. Or simply invoke the +command ~modus-themes-list-colors~ to produce a buffer with a preview of +each entry in the palette. + +[[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Visualize the active Modus theme's palette]]. With that granted, let us expand the example to actually change the ~cursor~ face's background property. We employ the built-in function of @@ -1892,7 +2444,10 @@ The ~modus-themes-with-colors~ macro lets you retrieve multiple color values by employing the backquote/backtick and comma notation. The values are stored in the alists ~modus-themes-operandi-colors~ and ~modus-themes-vivendi-colors~, while the macro always queries that of the -active Modus theme. +active Modus theme (preview the current palette with the command +~modus-themes-list-colors~). + +[[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Visualize the active Modus theme's palette]]. Here is an abstract example that just returns a list of color values while ~modus-operandi~ is enabled: @@ -2230,9 +2785,11 @@ The themes provide a mechanism for overriding their color values. This is controlled by the variables ~modus-themes-operandi-color-overrides~ and ~modus-themes-vivendi-color-overrides~, which are alists that should mirror a subset of the associations in ~modus-themes-operandi-colors~ and -~modus-themes-vivendi-colors~ respectively. As with all customisations, +~modus-themes-vivendi-colors~ respectively. As with all customizations, overriding must be done before loading the affected theme. +[[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Visualize the active Modus theme's palette]]. + Let us approach the present topic one step at a time. Here is a simplified excerpt of the default palette for Modus Operandi with some basic background values that apply to buffers and the mode line @@ -2293,8 +2850,7 @@ both themes and expands to some more assosiations in the palette: (bg-header . "#ede3e0") (bg-tab-bar . "#dcd3d3") (bg-tab-active . "#fdf6eb") - (bg-tab-inactive . "#c8bab8") - (fg-unfocused . "#55556f")) + (bg-tab-inactive . "#c8bab8")) modus-themes-vivendi-color-overrides '((bg-main . "#100b17") (bg-dim . "#161129") @@ -2306,17 +2862,34 @@ both themes and expands to some more assosiations in the palette: (bg-header . "#202037") (bg-tab-bar . "#262b41") (bg-tab-active . "#120f18") - (bg-tab-inactive . "#3a3a5a") - (fg-unfocused . "#9a9aab"))) + (bg-tab-inactive . "#3a3a5a"))) (setq modus-themes-operandi-color-overrides nil modus-themes-vivendi-color-overrides nil))) #+end_src -With this in place, one can invoke {{{kbd(M-x my-modus-themes-tinted)}}} and -then load the Modus theme of their choice. The new palette subset will -come into effect: subtle ochre tints for Modus Operandi and night sky -shades for Modus Vivendi. Switching between the two themes, such as -with {{{kbd(M-x modus-themes-toggle)}}} will also use the overrides. +A more neutral style for ~modus-themes-operandi-color-overrides~ can +look like this: + +#+begin_src emacs-lisp +'((bg-main . "#f7f7f7") + (bg-dim . "#f2f2f2") + (bg-alt . "#e8e8e8") + (bg-hl-line . "#eaeaef") + (bg-active . "#e0e0e0") + (bg-inactive . "#e6e6e6") + (bg-region . "#b5b5b5") + (bg-header . "#e4e4e4") + (bg-tab-bar . "#d1d1d4") + (bg-tab-active . "#f5f5f5") + (bg-tab-inactive . "#c0c0c0")) +#+end_src + +With those in place, one can use {{{kbd(M-x my-modus-themes-tinted)}}} +and then load the Modus theme of their choice. The new palette subset +will come into effect: subtle ochre tints (or shades of gray) for Modus +Operandi and night sky blue shades for Modus Vivendi. Switching between +the two themes, such as with {{{kbd(M-x modus-themes-toggle)}}} will +also use the overrides. Given that this is a user-level customization, one is free to implement whatever color values they desire, even if the possible combinations @@ -2454,23 +3027,87 @@ inspiration from the ~modus-themes-toggle~ we already provide: ('modus-vivendi (modus-themes-load-vivendi)))) #+end_src +** Override colors through blending +:properties: +:custom_id: h:80c326bf-fe32-47b2-8c59-58022256fd6e +:end: +#+cindex: Change theme colors through blending + +This is yet another method of overriding color values. + +[[#h:307d95dd-8dbd-4ece-a543-10ae86f155a6][Override colors]]. + +[[#h:4589acdc-2505-41fc-9f5e-699cfc45ab00][Override color saturation]]. + +Building on ideas and concepts from the previous sections, this method +blends the entire palette at once with the chosen colors. The function +~my-modus-themes-interpolate~ blends two colors, taking a value from the +themes and mixing it with a user-defined color to arrive at a midpoint. +This scales to all background and foreground colors with the help of the +~my-modus-themes-tint-palette~ function. + +#+begin_src emacs-lisp +(setq my-modus-operandi-bg-blend "#fbf1c7" + my-modus-operandi-fg-blend "#3a6084" + my-modus-vivendi-bg-blend "#3a4042" + my-modus-vivendi-fg-blend "#d7b765") + +;; Adapted from the `kurecolor-interpolate' function of kurecolor.el +(defun my-modus-themes-interpolate (color1 color2) + (cl-destructuring-bind (r g b) + (mapcar #'(lambda (n) (* (/ n 2) 255.0)) + (cl-mapcar '+ (color-name-to-rgb color1) (color-name-to-rgb color2))) + (format "#%02X%02X%02X" r g b))) + +(defun my-modus-themes-tint-palette (palette bg-blend fg-blend) + "Modify Modus PALETTE programmatically and return a new palette. +Blend background colors with BG-BLEND and foreground colors with FG-BLEND." + (let (name cons colors) + (dolist (cons palette) + (let ((blend (if (string-match "bg" (symbol-name (car cons))) + bg-blend + fg-blend))) + (setq name (my-modus-themes-interpolate (cdr cons) blend))) + (setq name (format "%s" name)) + (setq cons `(,(car cons) . ,name)) + (push cons colors)) + colors)) + +(define-minor-mode modus-themes-tinted-mode + "Tweak some Modus themes colors." + :init-value nil + :global t + (if modus-themes-tinted-mode + (setq modus-themes-operandi-color-overrides + (my-modus-themes-tint-palette modus-themes-operandi-colors + my-modus-operandi-bg-blend + my-modus-operandi-fg-blend) + modus-themes-vivendi-color-overrides + (my-modus-themes-tint-palette modus-themes-vivendi-colors + my-modus-vivendi-bg-blend + my-modus-vivendi-fg-blend)) + (setq modus-themes-operandi-color-overrides nil + modus-themes-vivendi-color-overrides nil))) + +(modus-themes-tinted-mode 1) +#+end_src + ** Font configurations for Org and others :properties: :custom_id: h:defcf4fc-8fa8-4c29-b12e-7119582cc929 :end: #+cindex: Font configurations -The themes are designed to cope well with mixed font configurations. - -[[#h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b][Option for no font mixing]]. +The themes are designed to optionally cope well with mixed font +configurations. This mostly concerns ~org-mode~ and ~markdown-mode~, though +expect to find it elsewhere like in ~Info-mode~. -This mostly concerns ~org-mode~ and ~markdown-mode~, though expect to find -it elsewhere like in ~Info-mode~. +[[#h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b][Option for font mixing]]. In practice it means that the user can safely opt for a more prose-friendly proportionately spaced typeface as their default, while -letting spacing-sensitive elements like tables and inline code always -use a monospaced font, by inheriting from the ~fixed-pitch~ face. +spacing-sensitive elements like tables and inline code always use a +monospaced font, by inheriting from the ~fixed-pitch~ face. Users can try the built-in {{{kbd(M-x variable-pitch-mode)}}} to see the effect in action. @@ -2491,7 +3128,14 @@ reading the doc string of ~set-face-attribute~): (set-face-attribute 'variable-pitch nil :family "DejaVu Serif" :height 1.0) ;; Monospaced typeface -(set-face-attribute 'fixed-pitch nil :family "DejaVu Sans Mono" :height 1.0) +(set-face-attribute 'fixed-pitch nil :family "DejaVu Sans Mono" :height 1.5) +#+end_src + +Or employ the ~face-attribute~ function to read an existing value, such as +if you want to make ~fixed-pitch~ use the font family of the ~default~ face: + +#+begin_src emacs-lisp +(set-face-attribute 'fixed-pitch nil :family (face-attribute 'default :family)) #+end_src The next section shows how to make those work in a more elaborate setup @@ -2504,12 +3148,13 @@ specify an absolute value, which is the point size × 10. So if you want to use a font at point size =11=, you set the height to =110=.[fn:: ~:height~ values do not need to be rounded to multiples of ten: the likes of =115= are perfectly valid—some typefaces will change to account for those -finer increments.] Whereas every other face must have a value that is -relative to the default, represented as a floating point (if you use an -integer, then that means an absolute height). This is of paramount -importance: it ensures that all fonts can scale gracefully when using -something like the ~text-scale-adjust~ command which only operates on the -base font size (i.e. the ~default~ face's absolute height). +finer increments.] Whereas every other face must either not specify a +height or have a value that is relative to the default, represented as a +floating point. If you use an integer, then that means an absolute +height. This is of paramount importance: it ensures that all fonts can +scale gracefully when using something like the ~text-scale-adjust~ command +which only operates on the base font size (i.e. the ~default~ face's +absolute height). [[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note for EWW and Elfeed fonts]]. @@ -2545,7 +3190,7 @@ it means for a construct to be bold/italic, by tweaking the ~bold~ and To achieve those effects, one must first be sure that the fonts they use have support for those features. It then is a matter of following the -instructions for all face tweaks. +instructions for all typeface tweaks. [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. @@ -2573,19 +3218,20 @@ To reset the font family, one can use this: To ensure that the effects persist after switching between the Modus themes (such as with {{{kbd(M-x modus-themes-toggle)}}}), the user needs to -write their configurations to a function and hook it up to the -~modus-themes-after-load-theme-hook~. This is necessary because the -themes set the default styles of faces (otherwise changing themes would -not be possible). +write their configurations to a function and pass it to the +~modus-themes-after-load-theme-hook~. This is necessary because themes +set the styles of faces upon activation, overriding prior values where +conflicts occur between the previous and the current states (otherwise +changing themes would not be possible). [[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]. This is a minimal setup to preserve font configurations across theme -load phases. For a more permanent setup, it is better to employ the +load phases. For a more permanent setup, it is better to rely on the ~custom-set-faces~ function: ~set-face-attribute~ works just fine, though it -is more convenient for quick previews or for smaller scale operations -(~custom-set-faces~ follows the format used in the source code of the -themes). +probably is better suited for quick previews or for smaller scale +operations (~custom-set-faces~ follows the format used in the source code +of the themes, which can make it easier to redefine faces in bulk). #+begin_src emacs-lisp ;; our generic function @@ -2605,11 +3251,13 @@ themes). (add-hook 'modus-themes-after-load-theme-hook #'my-modes-themes-bold-italic-faces) #+end_src -** Custom Org user faces +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + +** Custom Org todo keyword and priority faces :properties: :custom_id: h:89f0678d-c5c3-4a57-a526-668b2bb2d7ad :end: -#+cindex: Org extra faces +#+cindex: Org custom todo faces Users of ~org-mode~ have the option to configure various keywords and priority cookies to better match their workflow. User options are @@ -2693,6 +3341,139 @@ it if you plan to control face attributes. [[#h:02e25930-e71a-493d-828a-8907fc80f874][Check color combinations]]. +** Custom Org emphasis faces +:properties: +:custom_id: h:26026302-47f4-4471-9004-9665470e7029 +:end: +#+cindex: Org custom emphasis faces + +Org provides the user option ~org-emphasis-alist~ which associates a +character with a face, list of faces, or face attributes. The default +specification of that variable looks like this: + +#+begin_src emacs-lisp +(setq org-emphasis-alist + '(("*" bold) + ("/" italic) + ("_" underline) + ("=" org-verbatim verbatim) + ("~" org-code verbatim) + ("+" (:strike-through t)))) +#+end_src + +With the exception of ~org-verbatim~ and ~org-code~ faces, everything else +uses the corresponding type of emphasis: a bold typographic weight, or +italicised, underlined, and struck through text. + +The best way for users to add some extra attributes, such as a +foreground color, is to define their own faces and assign them to the +given emphasis marker/character. + +This is a custom face that extends the standard ~bold~ face with a red +foreground value (so it colorises the text in addition to the bold +weight): + +#+begin_src emacs-lisp +(defface my-org-emphasis-bold + '((default :inherit bold) + (((class color) (min-colors 88) (background light)) + :foreground "#a60000") + (((class color) (min-colors 88) (background dark)) + :foreground "#ff8059")) + "My bold emphasis for Org.") +#+end_src + +This face definition reads as follows: + ++ Always inherit the ~bold~ face ([[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]). ++ For versions of Emacs that support at least 88 colors (graphical + Emacs, for example) and use a light background, apply the =#a60000= + value. ++ For the same kind of Emacs that has a dark background use the =#ff8059= + color instead. + +Same principle for how to extend ~italic~ and ~underline~ with, for example, +green and yellow hues, respectively: + +#+begin_src emacs-lisp +(defface my-org-emphasis-italic + '((default :inherit italic) + (((class color) (min-colors 88) (background light)) + :foreground "#005e00") + (((class color) (min-colors 88) (background dark)) + :foreground "#44bc44")) + "My italic emphasis for Org.") + +(defface my-org-emphasis-underline + '((default :inherit underline) + (((class color) (min-colors 88) (background light)) + :foreground "#813e00") + (((class color) (min-colors 88) (background dark)) + :foreground "#d0bc00")) + "My underline emphasis for Org.") +#+end_src + +In the case of a strike-through effect, we have no generic face to +inherit from, so we can write it as follows to also change the +foreground to a more subtle gray: + +#+begin_src emacs-lisp +(defface my-org-emphasis-strike-through + '((default :strike-through t) + (((class color) (min-colors 88) (background light)) + :foreground "#505050") + (((class color) (min-colors 88) (background dark)) + :foreground "#a8a8a8")) + "My strike-through emphasis for Org.") +#+end_src + +Or we can just change the color of the line that strikes through the +text to, for example, a shade of red: + +#+begin_src emacs-lisp +(defface my-org-emphasis-strike-through + '((((class color) (min-colors 88) (background light)) + :strike-through "#972500") + (((class color) (min-colors 88) (background dark)) + :strike-through "#ef8b50")) + "My strike-through emphasis for Org.") +#+end_src + +It is possible to combine those effects: + +#+begin_src emacs-lisp +(defface my-org-emphasis-strike-through + '((((class color) (min-colors 88) (background light)) + :strike-through "#972500" :foreground "#505050") + (((class color) (min-colors 88) (background dark)) + :strike-through "#ef8b50" :foreground "#a8a8a8")) + "My strike-through emphasis for Org.") +#+end_src + +One may inspect the variables ~modus-themes-operandi-colors~ and +~modus-themes-vivendi-colors~ for possible color values. Or call the +command ~modus-themes-list-colors~ to show a buffer that previews each +entry in the palette. + +[[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Visualize the active Modus theme's palette]]. + +Once we have defined the faces we need, we must update the +~org-emphasis-alist~. Given that ~org-verbatim~ and ~org-code~ are already +styled by the themes, it probably is best not to edit them: + +#+begin_src emacs-lisp +(setq org-emphasis-alist + '(("*" my-org-emphasis-bold) + ("/" my-org-emphasis-italic) + ("_" my-org-emphasis-underline) + ("=" org-verbatim verbatim) + ("~" org-code verbatim) + ("+" my-org-emphasis-strike-through))) +#+end_src + +That's it! For changes to take effect in already visited Org files, +invoke {{{kbd(M-x org-mode-restart)}}}. + ** Update Org block delimiter fontification :properties: :custom_id: h:f44cc6e3-b0f1-4a5e-8a90-9e48fa557b50 @@ -2889,13 +3670,144 @@ at something like the following, which builds on the above example: (pdf-view-midnight-minor-mode -1)) (my-pdf-tools-backdrop))) +(defun my-pdf-tools-themes-toggle () + (mapc + (lambda (buf) + (with-current-buffer buf + (my-pdf-tools-midnight-mode-toggle))) + (buffer-list))) + (add-hook 'pdf-tools-enabled-hook #'my-pdf-tools-midnight-mode-toggle) -(add-hook 'modus-themes-after-load-theme-hook #'my-pdf-tools-midnight-mode-toggle) +(add-hook 'modus-themes-after-load-theme-hook #'my-pdf-tools-themes-toggle) #+end_src With those in place, PDFs have a distinct backdrop for their page, while -they automatically switch to their dark mode when ~modus-themes-toggle~ is -called from inside a buffer whose major-mode is ~pdf-view-mode~. +buffers with major-mode as ~pdf-view-mode~ automatically switches to dark +mode when ~modus-themes-toggle~ is called. + +** Decrease mode line height +:properties: +:custom_id: h:03be4438-dae1-4961-9596-60a307c070b5 +:end: +#+cindex: Decrease mode line height + +By default, the mode line of the Modus themes is set to 1 pixel width +for its =:box= attribute. In contrast, the mode line of stock Emacs is -1 +pixel. This small difference is considered necessary for the purposes +of accessibility as our out-of-the-box design has a prominent color +around the mode line (a border) to make its boundaries clear. With a +negative width the border and the text on the mode line can feel a bit +more difficult to read under certain scenaria. + +Furthermore, the user option ~modus-themes-mode-line~ ([[#h:27943af6-d950-42d0-bc23-106e43f50a24][Mode line]]) does not +allow for such a negative value because there are many edge cases that +simply make for a counter-intuitive set of possibilities, such as a =0= +value not being acceptable by the underlying face infrastructure, and +negative values greater than =-2= not being particularly usable. + +For these reasons, users who wish to decrease the overall height of the +mode line must handle things on their own by implementing the methods +for face customization documented herein. + +[[#h:1487c631-f4fe-490d-8d58-d72ffa3bd474][Basic face customization]]. + +One such method is to create a function that configures the desired +faces and hook it to ~modus-themes-after-load-theme-hook~ so that it +persists while switching between the Modus themes with the command +~modus-themes-toggle~. + +This one simply disables the box altogether, which will reduce the +height of the mode lines, but also remove their border: + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (set-face-attribute 'mode-line nil :box nil) + (set-face-attribute 'mode-line-inactive nil :box nil)) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +The above relies on the ~set-face-attribute~ function, though users who +plan to re-use colors from the theme and do so at scale are better off +with the more streamlined combination of the ~modus-themes-with-colors~ +macro and ~custom-set-faces~. + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face customization at scale]]. + +As explained before in this document, this approach has a syntax that is +consistent with the source code of the themes, so it probably is easier +to re-use parts of the design. + +The following emulates the stock Emacs style, while still using the +colors of the Modus themes (whichever attribute is not explicitly stated +is inherited from the underlying theme): + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(mode-line ((,class :box (:line-width -1 :style released-button)))) + `(mode-line-inactive ((,class :box (:line-width -1 :color ,bg-region))))))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +And this one is like the out-of-the-box style of the Modus themes, but +with the -1 height instead of 1: + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(mode-line ((,class :box (:line-width -1 :color ,fg-alt)))) + `(mode-line-inactive ((,class :box (:line-width -1 :color ,bg-region))))))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +Finally, to also change the background color of the active mode line, +such as that it looks like the "accented" variant which is possible via +the user option ~modus-themes-mode-line~, the =:background= attribute needs +to be specified as well: + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(mode-line ((,class :box (:line-width -1 :color ,fg-alt) :background ,bg-active-accent))) + `(mode-line-inactive ((,class :box (:line-width -1 :color ,bg-region))))))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +** Toggle themes without reloading them +:properties: +:custom_id: h:b40aca50-a3b2-4c43-be58-2c26fcd14237 +:end: +#+cindex: Switch themes without load-theme + +Users who have a stable setup and who only ever need to toggle between +the themes without triggering a full reload, are better off defining +their own command which calls ~enable-theme~ instead of ~load-theme~: + +#+begin_src emacs-lisp +(defun my-modus-themes-toggle () + "Toggle between `modus-operandi' and `modus-vivendi' themes. +This uses `enable-theme' instead of the standard method of +`load-theme'. The technicalities are covered in the Modus themes +manual." + (interactive) + (pcase (modus-themes--current-theme) + ('modus-operandi (progn (enable-theme 'modus-vivendi) + (disable-theme 'modus-operandi))) + ('modus-vivendi (progn (enable-theme 'modus-operandi) + (disable-theme 'modus-vivendi))) + (_ (error "No Modus theme is loaded; evaluate `modus-themes-load-themes' first")))) +#+end_src + +[[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Differences between loading and enabling]]. + +Recall that ~modus-themes-toggle~ uses ~load-theme~. ** A theme-agnostic hook for theme loading :properties: @@ -2946,6 +3858,267 @@ user. Hence our hesitation to recommend it as part of the standard setup of the Modus themes (it is generally a good idea to understand what the implications are of advising a function). +** Diffs with only the foreground +:properties: +:custom_id: h:e2aed9eb-5e1e-45ec-bbd7-bc4faeab3236 +:end: +#+cindex: Foreground-only diffs + +Buffers that show differences between versions of a file or buffer, such +as in ~diff-mode~ and ~ediff~ always use color-coded background and +foreground combinations. + +[[#h:ea7ac54f-5827-49bd-b09f-62424b3b6427][Option for diff buffer looks]]. + +User may, however, prefer a style that removes the color-coded +backgrounds from regular changes while keeping them for word-wise (aka +"refined") changes---backgrounds for word-wise diffs are helpful in +context. To make this happen, one can use the ~modus-themes-with-colors~ +macro ([[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]): + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(modus-themes-diff-added ((,class :background unspecified :foreground ,green))) ; OR ,blue for deuteranopia + `(modus-themes-diff-changed ((,class :background unspecified :foreground ,yellow))) + `(modus-themes-diff-removed ((,class :background unspecified :foreground ,red))) + + `(modus-themes-diff-refine-added ((,class :background ,bg-diff-added :foreground ,fg-diff-added))) + ;; `(modus-themes-diff-refine-added ((,class :background ,bg-diff-added-deuteran :foreground ,fg-diff-added-deuteran))) + `(modus-themes-diff-refine-changed ((,class :background ,bg-diff-changed :foreground ,fg-diff-changed))) + `(modus-themes-diff-refine-removed ((,class :background ,bg-diff-removed :foreground ,fg-diff-removed))) + + `(modus-themes-diff-focus-added ((,class :background ,bg-dim :foreground ,green))) ; OR ,blue for deuteranopia + `(modus-themes-diff-focus-changed ((,class :background ,bg-dim :foreground ,yellow))) + `(modus-themes-diff-focus-removed ((,class :background ,bg-dim :foreground ,red))) + + `(modus-themes-diff-heading ((,class :background ,bg-alt :foreground ,fg-main))) + + `(diff-indicator-added ((,class :foreground ,green))) ; OR ,blue for deuteranopia + `(diff-indicator-changed ((,class :foreground ,yellow))) + `(diff-indicator-removed ((,class :foreground ,red))) + + `(magit-diff-added ((,class :background unspecified :foreground ,green-faint))) + `(magit-diff-changed ((,class :background unspecified :foreground ,yellow-faint))) + `(magit-diff-removed ((,class :background unspecified :foreground ,red-faint))) + `(magit-diff-context-highlight ((,class :background ,bg-dim :foreground ,fg-dim)))))) + +;; This is so that the changes persist when switching between +;; `modus-operandi' and `modus-vivendi'. +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +This used to be an optional style of ~modus-themes-diffs~, but has been +removed since version =2.0.0= to ensure that the accessibility standard +and aesthetic quality of the themes is not compromised. + +** Ediff without diff color-coding +:properties: +:custom_id: h:b0b31802-0216-427e-b071-1a47adcfe608 +:end: + +Ediff uses the same color-coding as ordinary diffs in ~diff-mode~, Magit, +etc. ([[#h:ea7ac54f-5827-49bd-b09f-62424b3b6427][Option for diff buffer looks]]). This is consistent with the +principle of least surprise. + +Users may, however, prefer to treat Ediff differently on the premise +that it does not need any particular color-coding to show added or +removed lines/words: it does not use the =+= or =-= markers, after all. + +This can be achieved by customizing the Ediff faces with color +combinations that do not carry the same connotations as those of diffs. +Consider this example, which leverages the ~modus-themes-with-colors~ +macro ([[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]): + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(ediff-current-diff-A ((,class :inherit unspecified :background ,bg-special-faint-cold :foreground ,fg-special-cold))) + `(ediff-current-diff-B ((,class :inherit unspecified :background ,bg-special-faint-warm :foreground ,fg-special-warm))) + `(ediff-current-diff-C ((,class :inherit unspecified :background ,bg-special-faint-calm :foreground ,fg-special-calm))) + `(ediff-fine-diff-A ((,class :inherit unspecified :background ,bg-special-cold :foreground ,fg-special-cold))) + `(ediff-fine-diff-B ((,class :inherit unspecified :background ,bg-special-warm :foreground ,fg-special-warm))) + `(ediff-fine-diff-C ((,class :inherit unspecified :background ,bg-special-calm :foreground ,fg-special-calm)))))) + +;; This is so that the changes persist when switching between +;; `modus-operandi' and `modus-vivendi'. +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +Remove the =:foreground= and its value to preserve the underlying +coloration. + +[[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Visualize the active Modus theme's palette]]. + +** Near-monochrome syntax highlighting +:properties: +:custom_id: h:c1f3fa8e-7a63-4a6f-baf3-a7febc0661f0 +:end: +#+cindex: Monochrome code syntax + +While the Modus themes do provide a user option to control the overall +style of syntax highlighting in programming major modes, they do not +cover the possibility of a monochromatic or near-monochromatic design +([[#h:c119d7b2-fcd4-4e44-890e-5e25733d5e52][Option for syntax highlighting]]). This is due to the multitude of +preferences involved: one may like comments to be styled with an accent +value, another may want certain constructs to be bold, a third may apply +italics to doc strings but not comments... The possibilities are +virtually endless. As such, this sort of design is best handled at the +user level in accordance with the information furnished elsewhere in +this manual. + +[[#h:1487c631-f4fe-490d-8d58-d72ffa3bd474][Case-by-case face specs using the themes' palette]]. + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + +The gist is that we want to override the font-lock faces. For our +changes to persist while switching between ~modus-operandi~ and +~modus-vivendi~ we wrap our face overrides in a function that we hook to +~modus-themes-after-load-theme-hook~. + +Users who want to replicate the structure of the themes' source code are +advised to use the examples with ~custom-set-faces~. Those who prefer a +different approach can use the snippets which call ~set-face-attribute~. +Below are the code blocks. + +The following uses a yellow accent value for comments and green hues for +strings. Regexp grouping constructs have color values that work in the +context of a green string. All other elements use the main foreground +color, except warnings such as the ~user-error~ function in Elisp +buffers which gets a subtle red tint (not to be confused with the +~warning~ face which is used for genuine warnings). Furthermore, notice +the ~modus-themes-bold~ and ~modus-themes-slant~ which apply the +preference set in the user options ~modus-themes-bold-constructs~ and +~modus-themes-italic-constructs~, respectively. Users who do not want +this conditionally must replace these faces with ~bold~ and ~italic~ +respectively (or ~unspecified~ to disable the effect altogether). + +#+begin_src emacs-lisp +;; This is the hook. It will not be replicated across all code samples. +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-subtle-syntax) + +(defun my-modus-themes-subtle-syntax () + (modus-themes-with-colors + (custom-set-faces + `(font-lock-builtin-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-comment-delimiter-face ((,class :inherit font-lock-comment-face))) + `(font-lock-comment-face ((,class :inherit unspecified :foreground ,fg-comment-yellow))) + `(font-lock-constant-face ((,class :foreground unspecified))) + `(font-lock-doc-face ((,class :inherit modus-themes-slant :foreground ,fg-special-mild))) + `(font-lock-function-name-face ((,class :foreground unspecified))) + `(font-lock-keyword-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-negation-char-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-preprocessor-face ((,class :foreground unspecified))) + `(font-lock-regexp-grouping-backslash ((,class :inherit bold :foreground ,yellow))) + `(font-lock-regexp-grouping-construct ((,class :inherit bold :foreground ,blue-alt-other))) + `(font-lock-string-face ((,class :foreground ,green-alt-other))) + `(font-lock-type-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-variable-name-face ((,class :foreground unspecified))) + `(font-lock-warning-face ((,class :inherit modus-themes-bold :foreground ,red-nuanced-fg)))))) + +;; Same as above with `set-face-attribute' instead of `custom-set-faces' +(defun my-modus-themes-subtle-syntax () + (modus-themes-with-colors + (set-face-attribute 'font-lock-builtin-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-comment-delimiter-face nil :inherit 'font-lock-comment-face) + (set-face-attribute 'font-lock-comment-face nil :inherit 'unspecified :foreground fg-comment-yellow) + (set-face-attribute 'font-lock-constant-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-doc-face nil :inherit 'modus-themes-slant :foreground fg-special-mild) + (set-face-attribute 'font-lock-function-name-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-keyword-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-negation-char-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-preprocessor-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-regexp-grouping-backslash nil :inherit 'bold :foreground yellow) + (set-face-attribute 'font-lock-regexp-grouping-construct nil :inherit 'bold :foreground blue-alt-other) + (set-face-attribute 'font-lock-string-face nil :foreground green-alt-other) + (set-face-attribute 'font-lock-type-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-variable-name-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-warning-face nil :inherit 'modus-themes-bold :foreground red-nuanced-fg))) +#+end_src + +The following sample is the same as above, except strings are blue and +comments are gray. Regexp constructs are adapted accordingly. + +#+begin_src emacs-lisp +(defun my-modus-themes-subtle-syntax () + (modus-themes-with-colors + (custom-set-faces + `(font-lock-builtin-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-comment-delimiter-face ((,class :inherit font-lock-comment-face))) + `(font-lock-comment-face ((,class :inherit unspecified :foreground ,fg-alt))) + `(font-lock-constant-face ((,class :foreground unspecified))) + `(font-lock-doc-face ((,class :inherit modus-themes-slant :foreground ,fg-docstring))) + `(font-lock-function-name-face ((,class :foreground unspecified))) + `(font-lock-keyword-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-negation-char-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-preprocessor-face ((,class :foreground unspecified))) + `(font-lock-regexp-grouping-backslash ((,class :inherit bold :foreground ,fg-escape-char-backslash))) + `(font-lock-regexp-grouping-construct ((,class :inherit bold :foreground ,fg-escape-char-construct))) + `(font-lock-string-face ((,class :foreground ,blue-alt))) + `(font-lock-type-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-variable-name-face ((,class :foreground unspecified))) + `(font-lock-warning-face ((,class :inherit modus-themes-bold :foreground ,red-nuanced-fg)))))) + +;; Same as above with `set-face-attribute' instead of `custom-set-faces' +(defun my-modus-themes-subtle-syntax () + (modus-themes-with-colors + (set-face-attribute 'font-lock-builtin-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-comment-delimiter-face nil :inherit 'font-lock-comment-face) + (set-face-attribute 'font-lock-comment-face nil :inherit 'unspecified :foreground fg-alt) + (set-face-attribute 'font-lock-constant-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-doc-face nil :inherit 'modus-themes-slant :foreground fg-docstring) + (set-face-attribute 'font-lock-function-name-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-keyword-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-negation-char-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-preprocessor-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-regexp-grouping-backslash nil :inherit 'bold :foreground fg-escape-char-backslash) + (set-face-attribute 'font-lock-regexp-grouping-construct nil :inherit 'bold :foreground fg-escape-char-construct) + (set-face-attribute 'font-lock-string-face nil :foreground blue-alt) + (set-face-attribute 'font-lock-type-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-variable-name-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-warning-face nil :inherit 'modus-themes-bold :foreground red-nuanced-fg))) +#+end_src + +** Custom hl-todo colors +:PROPERTIES: +:CUSTOM_ID: h:2ef83a21-2f0a-441e-9634-473feb940743 +:END: + +The =hl-todo= package provides the user option ~hl-todo-keyword-faces~: +it specifies a pair of keyword and corresponding color value. The Modus +themes configure that option in the interest of legibility. While this +works for our purposes, users may still prefer to apply their custom +values, in which case the following approach is necessary: + +#+begin_src emacs-lisp +(defun my-modus-themes-hl-todo-faces () + (setq hl-todo-keyword-faces '(("TODO" . "#ff0000") + ("HACK" . "#ffff00") + ("XXX" . "#00ffff") + ("NOTE" . "#ff00ff")))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-hl-todo-faces) +#+end_src + +Or include a ~let~ form, if needed: + +#+begin_src emacs-lisp +(defun my-modus-themes-hl-todo-faces () + (let ((red "#ff0000") + (blue "#0000ff")) + (setq hl-todo-keyword-faces `(("TODO" . ,blue) + ("HACK" . ,red) + ("XXX" . ,red) + ("NOTE" . ,blue))))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-hl-todo-faces) +#+end_src + +Normally, we do not touch user options, though this is an exception: +otherwise the defaults are not always legible. + * Face coverage :properties: :custom_id: h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19 @@ -2969,14 +4142,14 @@ affected face groups. The items with an appended asterisk =*= tend to have lots of extensions, so the "full support" may not be 100% true… + ace-window -+ ag + alert + all-the-icons ++ all-the-icons-dired ++ all-the-icons-ibuffer + annotate + ansi-color + anzu + apropos -+ apt-sources-list + artbollocks-mode + auctex and TeX + auto-dim-other-buffers @@ -2989,14 +4162,15 @@ have lots of extensions, so the "full support" may not be 100% true… + boon + bookmark + breakpoint (provided by the built-in {{{file(gdb-mi.el)}}} library) -+ buffer-expose + calendar and diary + calfw ++ calibredb + centaur-tabs + cfrs + change-log and log-view (such as ~vc-print-log~, ~vc-print-root-log~) + cider + circe ++ citar + color-rg + column-enforce-mode + company-mode* @@ -3005,9 +4179,9 @@ have lots of extensions, so the "full support" may not be 100% true… + completions + consult + corfu ++ corfu-quick + counsel* + counsel-css -+ counsel-org-capture-string + cov + cperl-mode + css-mode @@ -3019,8 +4193,8 @@ have lots of extensions, so the "full support" may not be 100% true… + dashboard (emacs-dashboard) + deadgrep + debbugs -+ define-word + deft ++ devdocs + dictionary + diff-hl + diff-mode @@ -3032,17 +4206,15 @@ have lots of extensions, so the "full support" may not be 100% true… + dired-git-info + dired-narrow + dired-subtree -+ diredc + diredfl + diredp (dired+) -+ disk-usage + display-fill-column-indicator-mode + doom-modeline + dynamic-ruler + easy-jekyll -+ easy-kill + ebdb + ediff ++ ein (Emacs IPython Notebook) + eglot + el-search + eldoc-box @@ -3050,6 +4222,7 @@ have lots of extensions, so the "full support" may not be 100% true… + elfeed-score + elpher + embark ++ ement + emms + enh-ruby-mode (enhanced-ruby-mode) + epa @@ -3076,7 +4249,6 @@ have lots of extensions, so the "full support" may not be 100% true… + flycheck-posframe + flymake + flyspell -+ flyspell-correct + flx + freeze-it + frog-menu @@ -3088,10 +4260,8 @@ have lots of extensions, so the "full support" may not be 100% true… + geiser + git-commit + git-gutter (and variants) -+ git-lens + git-rebase + git-timemachine -+ git-walktree + gnus + gotest + golden-ratio-scroll-screen @@ -3100,27 +4270,22 @@ have lots of extensions, so the "full support" may not be 100% true… + helm-switch-shell + helm-xref + helpful -+ highlight-blocks -+ highlight-defined -+ 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 + hl-defined + hl-fill-column + hl-line-mode + hl-todo + hydra -+ hyperlist + ibuffer + icomplete + icomplete-vertical + ido-mode + iedit + iflipb ++ image-dired + imenu-list + indium + info @@ -3128,7 +4293,6 @@ have lots of extensions, so the "full support" may not be 100% true… + interaction-log + ioccur + isearch, occur, etc. -+ isl (isearch-light) + ivy* + ivy-posframe + jira (org-jira) @@ -3150,9 +4314,10 @@ have lots of extensions, so the "full support" may not be 100% true… + marginalia + markdown-mode + markup-faces (~adoc-mode~) ++ mct + mentor + messages -+ minibuffer-line ++ mini-modeline + minimap + mmm-mode + mode-line @@ -3160,14 +4325,12 @@ have lots of extensions, so the "full support" may not be 100% true… + moody + mpdel + mu4e -+ mu4e-conversation + multiple-cursors ++ nano-modeline + neotree -+ no-emoji + notmuch + num3-mode + nxml-mode -+ objed + orderless + org* + org-journal @@ -3187,14 +4350,11 @@ have lots of extensions, so the "full support" may not be 100% true… + pandoc-mode + paradox + paren-face -+ parrot + pass + pdf-tools + persp-mode + perspective + phi-grep -+ phi-search -+ pkgbuild-mode + pomidor + popup + powerline @@ -3203,10 +4363,10 @@ have lots of extensions, so the "full support" may not be 100% true… + proced + prodigy + pulse ++ pyim + quick-peek + racket-mode + rainbow-blocks -+ rainbow-identifiers + rainbow-delimiters + rcirc + recursion-indicator @@ -3215,7 +4375,6 @@ have lots of extensions, so the "full support" may not be 100% true… + ripgrep + rmail + ruler-mode -+ sallet + selectrum + selectrum-prescient + semantic @@ -3227,19 +4386,18 @@ have lots of extensions, so the "full support" may not be 100% true… + side-notes + sieve-mode + skewer-mode ++ slime (slbd) ++ sly + smart-mode-line + smartparens + smerge + solaire + spaceline + speedbar -+ spell-fu -+ spray + stripes + suggest + switch-window + swiper -+ swoop + sx + symbol-overlay + syslog-mode @@ -3251,9 +4409,11 @@ have lots of extensions, so the "full support" may not be 100% true… + telephone-line + terraform-mode + term ++ textsec + tomatinho + transient (pop-up windows such as Magit's) + trashed ++ tree-sitter + treemacs + tty-menu + tuareg @@ -3261,13 +4421,13 @@ have lots of extensions, so the "full support" may not be 100% true… + undo-tree + vc (vc-dir.el, vc-hooks.el) + vc-annotate (the output of {{{kbd(C-x v g)}}}) -+ vdiff + vertico ++ vertico-quick + vimish-fold + visible-mark + visual-regexp -+ volatile-highlights + vterm ++ vundo + wcheck-mode + web-mode + wgrep @@ -3298,23 +4458,43 @@ 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. ++ ag ++ apt-sources-list ++ buffer-expose + bufler + counsel-notmuch ++ counsel-org-capture-string ++ define-word ++ disk-usage ++ dtache ++ easy-kill + edit-indirect ++ egerrit ++ elfeed-summary + evil-owl ++ flyspell-correct + fortran-mode ++ git-walktree + goggles ++ highlight-defined ++ highlight-escape-sequences (~hes-mode~) + i3wm-config-mode ++ minibuffer-line ++ no-emoji ++ org-remark ++ parrot + perl-mode + php-mode + rjsx-mode + side-hustle ++ spell-fu + swift-mode + tab-bar-echo-area + tide ++ undo-hl ++ vdiff + vertico-indexed + vertico-mouse -+ vertico-quick * Notes on individual packages :properties: @@ -3324,40 +4504,6 @@ supported by the themes. This section covers information that may be of interest to users of individual packages. -** Note on avy hints -:properties: -:custom_id: h:2fdce705-6de7-44e6-ab7f-18f59af99e01 -:end: - -Hints can appear everywhere, in wildly varying contexts, hence, their -appearance, by necessity, is a compromise. However, there are various -options for making them stand out. First is dimming the surroundings: - -#+begin_src emacs-lisp -(setq avy-background t) -#+end_src - -Dimming works well when you find it difficult to spot hints, any hint. -Second is limiting the number of faces used by hints: - -#+begin_src emacs-lisp -(setq avy-lead-faces - '(avy-lead-face - avy-lead-face-1 - avy-lead-face-1 - avy-lead-face-1 - avy-lead-face-1)) -#+end_src - -Limiting the number of faces works well with longer hints when you find -it difficult to identify individual hints, especially with hints -touching each other. The first character of the hint will have an -intense color, the remaining ones the same neutral color. - -Third is preferring commands that produce fewer candidates. Fewer hints -is less noise: ~avy-goto-char-timer~ is an excellent alternative to -~avy-goto-char~. - ** Note on calendar.el weekday and weekend colors :properties: :custom_id: h:b2db46fb-32f4-44fd-8e11-d2b261cf51ae @@ -3387,6 +4533,72 @@ weekends uniformly. For changes to take effect, the Calendar buffer needs to be generated anew. +** Note on git-gutter in Doom Emacs +:PROPERTIES: +:CUSTOM_ID: h:a195e37c-e58c-4148-b254-8ba1ed8a731a +:END: + +The =git-gutter= and =git-gutter-fr= packages default to drawing bitmaps +for the indicators they display (e.g. bitmap of a plus sign for added +lines). In Doom Emacs, these bitmaps are replaced with contiguous lines +which may look nicer, but require a change to the foreground of the +relevant faces to yield the desired color combinations. + +Since this is Doom-specific, we urge users to apply changes in their +local setup. Below is some sample code, based on what we cover at +length elsewhere in this manual: + +[[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]. + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + ;; Replace green with blue if you use `modus-themes-deuteranopia'. + `(git-gutter-fr:added ((,class :foreground ,green-fringe-bg))) + `(git-gutter-fr:deleted ((,class :foreground ,red-fringe-bg))) + `(git-gutter-fr:modified ((,class :foreground ,yellow-fringe-bg)))))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +If the above does not work, try this instead: + +#+begin_src emacs-lisp +(after! modus-themes + (modus-themes-with-colors + (custom-set-faces + ;; Replace green with blue if you use `modus-themes-deuteranopia'. + `(git-gutter-fr:added ((,class :foreground ,green-fringe-bg))) + `(git-gutter-fr:deleted ((,class :foreground ,red-fringe-bg))) + `(git-gutter-fr:modified ((,class :foreground ,yellow-fringe-bg)))))) +#+end_src + +Replace ~green-fringe-bg~ with ~blue-fringe-bg~ if you want to optimize +for red-green color deficiency. + +[[#h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe][Option for red-green color deficiency or deuteranopia]]. + +** Note on php-mode multiline comments +:PROPERTIES: +:CUSTOM_ID: h:d0a3157b-9c04-46e8-8742-5fb2a7ae8798 +:END: + +Depending on your build of Emacs and/or the environment it runs in, +multiline comments in PHP with the =php-mode= package use the +~font-lock-doc-face~ instead of ~font-lock-comment-face~. + +This seems to make all comments use the appropriate face: + +#+begin_src emacs-lisp +(defun my-multine-comments () + (setq-local c-doc-face-name 'font-lock-comment-face)) + +(add-hook 'php-mode-hook #'my-multine-comments) +#+end_src + ** Note on underlines in compilation buffers :properties: :custom_id: h:420f5a33-c7a9-4112-9b04-eaf2cbad96bd @@ -3396,14 +4608,15 @@ Various buffers that produce compilation results or run tests on code apply an underline to the file names they reference or to relevant messages. Users may consider this unnecessary or excessive. -To outright disable the effect, use this: +To outright disable the effect, use this (buffers need to be generated +anew): #+begin_src emacs-lisp (setq compilation-message-face nil) #+end_src If some element of differentiation is still desired, a good option is to -render the affected text using the ~italic~ face: +render the affected text with the ~italic~ face: #+begin_src emacs-lisp (setq compilation-message-face 'italic) @@ -3467,33 +4680,35 @@ package: it draws too much attention to unfocused windows. :custom_id: h:2a602816-bc1b-45bf-9675-4cbbd7bf6cab :end: -While designing the style for ~display-fill-column-indicator-mode~, we -stayed close to the mode's defaults: to apply a subtle foreground color -to the ~fill-column-indicator~ face, which blends well with the rest of -theme and is consistent with the role of that mode. This is to not -upset the expectations of users. +The ~display-fill-column-indicator-mode~ uses a typographic character to +draw its line. This has the downside of creating a dashed line. The +dashes are further apart depending on how tall the font's glyph height +is and what integer the ~line-spacing~ is set to. -Nevertheless, ~display-fill-column-indicator-mode~ has some known -limitations pertaining to its choice of using typographic characters to -draw its indicator. What should be a continuous vertical line might -appear as a series of dashes in certain contexts or under specific -conditions: a non-default value for ~line-spacing~, scaled and/or -variable-pitch headings have been observed to cause this effect. - -Given that we cannot control such factors, it may be better for affected -users to deviate from the default style of the ~fill-column-indicator~ -face. Instead of setting a foreground color, one could use a background -and have the foreground be indistinguishable from it. For example: +At the theme level we eliminate this effect by making the character one +pixel tall: the line is contiguous. Users who prefer the dashed line +are advised to change the ~fill-column-indicator~ face, as explained +elsewhere in this document. For example: #+begin_src emacs-lisp (modus-themes-with-colors (custom-set-faces - `(fill-column-indicator ((,class :background ,bg-inactive - :foreground ,bg-inactive))))) + `(fill-column-indicator ((,class :foreground ,bg-active))))) #+end_src [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. +To make the line thicker, set the height to be equal to the base font +size instead of the one pixel we use. This is done by specifying a rate +instead of an absolute number, as in =:height 1.0= versus =:height 1=. +For example: + +#+begin_src emacs-lisp +(modus-themes-with-colors + (custom-set-faces + `(fill-column-indicator ((,class :height 1.0 :background ,bg-inactive :foreground ,bg-inactive))))) +#+end_src + ** Note on highlight-parentheses.el :PROPERTIES: :CUSTOM_ID: h:24bab397-dcb2-421d-aa6e-ec5bd622b913 @@ -3684,7 +4899,7 @@ implements an alternative to the typical coloration of code. Instead of highlighting the syntactic constructs, it applies color to different levels of depth in the code structure. -As {{{file(prism.el)}}} offers a broad range of customisations, we cannot +As {{{file(prism.el)}}} offers a broad range of customizations, we cannot style it directly at the theme level: that would run contrary to the spirit of the package. Instead, we may offer preset color schemes. Those should offer a starting point for users to adapt to their needs. @@ -3775,11 +4990,11 @@ examples with the 4, 8, 16 colors): :custom_id: h:4da1d515-3e05-47ef-9e45-8251fc7e986a :end: -The ~god-mode~ library does not provide faces that could be configured -by the Modus themes. Users who would like to get some visual feedback -on the status of {{{kbd(M-x god-mode)}}} are instead encouraged by upstream -to set up their own configurations, such as by changing the ~mode-line~ -face ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]). This is an adaptation of the approach +The ~god-mode~ library does not provide faces that could be configured by +the Modus themes. Users who would like to get some visual feedback on +the status of {{{kbd(M-x god-mode)}}} are instead encouraged by upstream to +set up their own configurations, such as by changing the ~mode-line~ face +([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]). This is an adaptation of the approach followed in the upstream README: #+begin_src emacs-lisp @@ -3872,22 +5087,68 @@ Emacs' HTML rendering library ({{{file(shr.el)}}}) may need explicit configuration to respect the theme's colors instead of whatever specifications the webpage provides. -Consult {{{kbd(C-h v shr-use-colors)}}}. +Consult the doc string of ~shr-use-colors~. -** Note on EWW and Elfeed fonts +** Note on SHR fonts :properties: :custom_id: h:e6c5451f-6763-4be7-8fdb-b4706a422a4c :end: +#+cindex: Fonts in EWW, Elfeed, Ement, and SHR -EWW and Elfeed rely on the Simple HTML Renderer to display their -content. The {{{file(shr.el)}}} library contains the variable ~shr-use-fonts~ -that controls whether the text in the buffer is set to a ~variable-pitch~ -typeface (proportionately spaced) or if just retains whatever the -default font family is. Its default value is non-nil, which means that -~variable-pitch~ is applied. +By default, packages that build on top of the Simple HTML Remember (=shr=) +use proportionately spaced fonts. This is controlled by the user option +~shr-use-fonts~, which is set to non-nil by default. To use the standard +font instead, set that variable to nil. [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. +Packages affected by this are: + ++ elfeed ++ ement ++ eww + +This is a non-exhaustive list. + +** Note on Ement colors and fonts +:properties: +:custom_id: h:8e636056-356c-4ca7-bc78-ebe61031f585 +:end: + +The =ement.el= library by Adam Porter (also known as "alphapapa") defaults +to a method of colorizing usernames in a rainbow style. This is +controlled by the user option ~ement-room-prism~ and can be disabled with: + +#+begin_src emacs-lisp +(setq ement-room-prism nil) +#+end_src + +The contrast ratio of these colors is governed by another user option: +~ement-room-prism-minimum-contrast~. By default, it is set to 6 which is +slightly below our nominal target. Try this instead: + +#+begin_src emacs-lisp +(setq ement-room-prism-minimum-contrast 7) +#+end_src + +With regard to fonts, Ement depends on =shr= ([[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note on SHR fonts]]). + +Since we are here, here is an excerpt from Ement's source code: + +#+begin_src emacs-lisp +(defcustom ement-room-prism-minimum-contrast 6 + "Attempt to enforce this minimum contrast ratio for user faces. +This should be a reasonable number from, e.g. 0-7 or so." + ;; Prot would almost approve of this default. :) I would go all the way + ;; to 7, but 6 already significantly dilutes the colors in some cases. + :type 'number) +#+end_src + +Yes, I do approve of that default. Even a 4.5 (the WCAG AA rating) +would be a good baseline for many themes and/or user configurations. +Our target is the highest of the sort, though we do not demand that +everyone conforms with it. + ** Note on Helm grep :properties: :custom_id: h:d28879a2-8e4b-4525-986e-14c0f873d229 @@ -3988,11 +5249,25 @@ you've customized any faces. "-draw" "text %X,%Y '%c'")))) #+end_src +** Note on the Notmuch logo +:properties: +:custom_id: h:636af312-54a5-4918-84a6-0698e85a3c6d +:end: + +By default, the "hello" buffer of Notmuch includes a header with the +programs' logo and a couple of buttons. The logo has the effect of +enlarging the height of the line, which negatively impacts the shape of +those buttons. Disabling the logo fixes the problem: + +#+begin_src emacs-lisp +(setq notmuch-show-logo nil) +#+end_src + * Frequently Asked Questions :properties: :custom_id: h:b3384767-30d3-4484-ba7f-081729f03a47 :end: -#+cindex: Frequently Asked Questions (FAQ) +#+cindex: Frequently Asked Questions In this section we provide answers related to some aspects of the Modus themes' design and application. @@ -4111,8 +5386,8 @@ and hints of green give us suitable shades of purple. Due to the need of maintaining some difference in hueness between adjacent colors, it is not possible to make red, green, and yellow the -primary colors, because blue could not be used to control their -luminance and, thus the relevant space would shrink considerably. +main colors, because blue cannot be used to control their luminance and, +thus the relevant space will shrink considerably. [[#h:5ce7ae2e-9348-4e55-b4cf-9302345b1826][Is the contrast ratio about adjacent colors?]] @@ -4199,6 +5474,139 @@ The color combinations may have been optimized for accessibility, though the remaining contributing factors in each case need to be considered in full. +** Are these color schemes? +:properties: +:custom_id: h:a956dbd3-8fd2-4f5d-8b01-5f881268cf2b +:end: +#+cindex: Themes, not color schemes + +No, the Modus themes are not color schemes. + +A color scheme is a collection of colors. A good color scheme is a +combination of colors with an inner logic or abstract structure. + +A theme is a set of patterns that are applied across different contexts. +A good theme is one that does so with consistency, though not +uniformity. + +In practical terms, a color scheme is what one uses when, for example, +they edit the first sixteen escape sequences of a terminal emulator to +the hues of their preference. The terminal offers the option to choose, +say, the exact value of what counts as "red", but does not provide the +means to control where that is mapped to and whether it should also have +other qualities such as a bold weight for the underlying text or an +added background color. In contradistinction, Emacs uses constructs +known as "faces" which allow the user/developer to specify where a given +color will be used and whether it should be accompanied by other +typographic or stylistic attributes. + +By configuring the multitude of faces on offer we thus control both +which colors are applied and how they appear in their context. When a +package wants to render each instance of "foo" with the "bar" face, it +is not requesting a specific color, which makes things considerably more +flexible as we can treat "bar" in its own right without necessarily +having to use some color value that we hardcoded somewhere. + +Which brings us to the distinction between consistency and uniformity +where our goal is always the former: we want things to look similar +across all interfaces, but we must never force a visual identity where +that runs contrary to the functionality of the given interface. For +instance, all links are underlined by default yet there are cases such +as when viewing listings of emails in Gnus (and Mu4e, Notmuch) where (i) +it is already understood that one must follow the indicator or headline +to view its contents and (ii) underlining everything would make the +interface virtually unusable. + +[[#h:5808be52-361a-4d18-88fd-90129d206f9b][Option for links]]. + +Again, one must exercise judgment in order to avoid discrimination, +where "discrimination" refers to: + ++ The treatment of substantially different magnitudes as if they were of + the same class. ++ Or the treatment of the same class of magnitudes as if they were of a + different class. + +(To treat similar things differently; to treat dissimilar things alike.) + +If, in other words, one was to enforce uniformity without accounting for +the particular requirements of each case---the contextual demands for +usability beyond matters of color---they would be making a +not-so-obvious error of treating different cases as if they were the +same. + +The Modus themes prioritize "thematic consistency" over abstract harmony +or regularity among their applicable colors. In concrete terms, we do +not claim that, say, our yellows are the best complements for our blues +because we generally avoid using complementary colors side-by-side, so +it is wrong to optimize for a decontextualised blue+yellow combination. +Not to imply that our colors do not work well together because they do, +just to clarify that consistency of context is what themes must strive +for, and that requires widening the scope of the design beyond the +particularities of a color scheme. + +Long story short: color schemes and themes have different requirements. +Please do not conflate the two. + +** Port the Modus themes to other platforms? +:properties: +:custom_id: h:7156b949-917d-488e-9a72-59f70d80729c +:end: +#+cindex: Porting the themes to other editors + +There is no plan to port the themes to other platforms or text editors. +I (Protesilaos) only use GNU Emacs and thus cannot maintain code that +targets software I am either not familiar with or am not using on a +daily basis. + +While it is possible to produce a simulacrum based on a given template, +doing so would run contrary to how this project is maintained where +details matter greatly. + +Each program has its own requirements so it won't always be +possible---or indeed desirable---to have 1:1 correspondence between what +applies to Emacs and what should be done elsewhere. No port should ever +strive to be a faithful copy of the Emacs implementation, as no other +program is an Emacs equivalent, but instead try to follow the spirit of +the design. For example, some of the customization options accept a +list as their value, or an alist, which may not be possible to reproduce +on other platforms. + +[[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization options]]. + +In other words, if something must be done differently on a certain +editor then that is acceptable so long as (i) the accessibility +standards are not compromised and (ii) the overall character of the +themes remains consistent. + +The former criterion should be crystal clear as it pertains to the +scientific foundations of the themes: high legibility and taking care of +the needs of users with red-green color deficiency (deuteranopia) by +avoiding red+green color coding paradigms and/or by providing red+blue +variants. + +The latter criterion is the "je ne sais quoi" of the artistic aspect of +the themes, which is partially fleshed out in this manual. + +[[#h:b3384767-30d3-4484-ba7f-081729f03a47][Frequently Asked Questions]]. + +With regard to the artistic aspect (where "art" qua skill may amount to +an imprecise science), there is no hard-and-fast rule in effect as it +requires one to exercise discretion and make decisions based on +context-dependent information or constraints. As is true with most +things in life, when in doubt, do not cling on to the letter of the law +but try to understand its spirit. + +For a trivial example: the curly underline that Emacs draws for spelling +errors is thinner than, e.g., what a graphical web browser has, so if I +was to design for an editor than has a thicker curly underline I would +make the applicable colors less intense to counterbalance the +typographic intensity of the added thickness. + +With those granted, if anyone is willing to develop a port of the +themes, they are welcome to contact me and I will do my best to help +them in their efforts. + * Contributing :properties: :custom_id: h:9c3cd842-14b7-44d7-84b2-a5c8bc3fc3b1 @@ -4215,11 +5623,11 @@ in which you can contribute to their ongoing development. 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. +The source code of the themes is [[https://git.sr.ht/~protesilaos/modus-themes][available on SourceHut]]. Or check the +[[https://gitlab.com/protesilaos/modus-themes/][GitLab mirror (former main source)]] and the [[https://github.com/protesilaos/modus-themes/][GitHub mirror]]. An HTML version of this manual is provided as an extension of the -[[https://protesilaos.com/modus-themes/][author's personal website]] (does not rely on any non-free code). +[[https://protesilaos.com/emacs/modus-themes/][author's personal website]] (does not rely on any non-free code). ** Issues you can help with :properties: @@ -4227,7 +5635,10 @@ An HTML version of this manual is provided as an extension of the :end: #+cindex: Contributing -A few tasks you can help with: +#+findex: modus-themes-report-bug +A few tasks you can help with by sending an email to the general +[[https://lists.sr.ht/~protesilaos/modus-themes][modus-themes public mailing list]] (or use the command +~modus-themes-report-bug~). + Suggest refinements to packages that are covered. + Report packages not covered thus far. @@ -4235,7 +5646,8 @@ A few tasks you can help with: + Help expand the documentation of covered-but-not-styled packages. + Suggest refinements to the color palette. + Help expand this document or any other piece of documentation. -+ Merge requests for code refinements. ++ Send patches for code refinements (if you need, ask me for help with + Git---we all start out as beginners). [[#h:111773e2-f26f-4b68-8c4f-9794ca6b9633][Patches require copyright assignment to the FSF]]. @@ -4243,6 +5655,10 @@ It is preferable that your feedback includes some screenshots, GIFs, or short videos, as well as further instructions to reproduce a given setup. Though this is not a requirement. +#+findex: modus-themes-version +Also consider mentioning the version of the themes you are using, such +as by invoking the command ~modus-themes-version~. + Whatever you do, bear in mind the overarching objective of the Modus themes: to keep a contrast ratio that is greater or equal to 7:1 between background and foreground colors. If a compromise is ever necessary @@ -4274,7 +5690,7 @@ will send you the assignment form for your past and future changes. Please use your full legal name (in ASCII characters) as the subject line of the message. ----------------------------------------------------------------------- + REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES [What is the name of the program or package you're contributing to?] @@ -4322,47 +5738,58 @@ The Modus themes are a collective effort. Every bit of work matters. + Author/maintainer :: Protesilaos Stavrou. -+ Contributions to code or documentation :: Anders Johansson, Basil - L.{{{space()}}} Contovounesios, Carlo Zancanaro, Eli Zaretskii, Fritz Grabo, - 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. ++ Contributions to code or documentation :: Alex Griffin, Anders + Johansson, Basil L.{{{space()}}} Contovounesios, Björn Lindström, + Carlo Zancanaro, Christian Tietze, Daniel Mendler, Eli Zaretskii, + Fritz Grabo, Illia Ostapyshyn, Kévin Le Gouguec, Kostadin Ninev, + Madhavan Krishnan, Manuel Giraud, Markus Beppler, Matthew Stevenson, + Mauro Aranda, Nicolas De Jaeghere, Philip Kaludercic, Pierre + Téchoueyres, Rudolf Adamkovič, Stephen Gildea, Shreyas Ragavan, Stefan + Kangas, Utkarsh Singh, Vincent Murphy, Xinglu Chen, Yuanchen Xie. + 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), - Stefan Monnier (GNU Elpa), André Alexandre Gomes, Dimakakos Dimos, - Morgan Smith, Nicolas Goaziou (Guix), Dhavan Vaidya (Debian). + Adrian Manea, Alex Griffin, Alex Koen, Alex Peitsinis, Alexey Shmalko, + Alok Singh, Anders Johansson, André Alexandre Gomes, Andrew Tropin, + Antonio Hernández Blas, Arif Rezai, Augusto Stoffel, Basil + L.{{{space()}}} Contovounesios, Burgess Chang, Christian Tietze, + Christopher Dimech, Christopher League, 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, Gonçalo Marrafa, + Guilherme Semente, Gustavo Barros, Hörmetjan Yiltiz, Ilja Kocken, Iris + Garcia, Ivan Popovych, Jeremy Friesen, Jerry Zhang, Johannes Grødem, + John Haman, Jorge Morais, Joshua O'Connor, Julio C. Villasante, Kenta + Usami, Kevin Fleming, Kévin Le Gouguec, Kostadin Ninev, Len Trigg, + Lennart C. Karssen, Magne Hov, Manuel Uberti, Mark Bestley, Mark + Burton, Markus Beppler, Mauro Aranda, Maxime Tréca, Michael + Goldenberg, Morgan Smith, Morgan Willcock, Murilo Pereira, Nicky van + Foreest, Nicolas De Jaeghere, Paul Poloskov, Pengji Zhang, Pete + Kazmier, Peter Wu, Philip Kaludercic, Pierre Téchoueyres, Przemysław + Kryger, Robert Hepple, Roman Rudakov, Ryan Phillips, Rytis Paškauskas, + Rudolf Adamkovič, Sam Kleinman, Samuel Culpepper, Saša Janiška, + Shreyas Ragavan, Simon Pugnet, Tassilo Horn, Thibaut Verron, Thomas + Heartman, Togan Muftuoglu, Tony Zorman, Trey Merkley, Tomasz + Hołubowicz, Toon Claes, Uri Sharf, Utkarsh Singh, Vincent Foley. As + well as users: Ben, CsBigDataHub1, Emacs Contrib, Eugene, Fourchaux, + Fredrik, Moesasji, Nick, TheBlob42, Trey, bepolymathe, bit9tream, + derek-upham, doolio, fleimgruber, gitrj95, iSeeU, jixiuf, okamsn, + pRot0ta1p. + ++ Packaging :: Basil L.{{{space()}}} Contovounesios, Eli Zaretskii, + Glenn Morris, Mauro Aranda, Richard Stallman, Stefan Kangas (core + Emacs), Stefan Monnier (GNU Elpa), André Alexandre Gomes, Andrew + Tropin, Dimakakos Dimos, Morgan Smith, Nicolas Goaziou (Guix), Dhavan + Vaidya (Debian). + Inspiration for certain features :: Bozhidar Batsov (zenburn-theme), Fabrice Niessen (leuven-theme). -Special thanks, in no particular order, to Manuel Uberti, Gustavo -Barros, and Omar Antolín Camarena for their long time contributions and -insightful commentary. +Special thanks (from A-Z) to Gustavo Barros, Manuel Uberti, Nicolas De +Jaeghere, and Omar Antolín Camarena for their long time contributions +and insightful commentary on key aspects of the themes' design and/or +aspects of their functionality. -* Meta +* Other notes about the project :properties: :custom_id: h:13752581-4378-478c-af17-165b6e76bc1b :end: @@ -4385,12 +5812,18 @@ of this sort): + [[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: - -+ Manual :: <https://protesilaos.com/modus-themes> -+ Change Log :: <https://protesilaos.com/modus-themes-changelog> -+ Screenshots :: <https://protesilaos.com/modus-themes-pictures> ++ [[https://protesilaos.com/codelog/2022-01-02-review-modus-themes-org-habit-colours/][Modus themes: review of the org-habit graph colours]] (2022-01-02) ++ [[https://protesilaos.com/codelog/2022-01-03-modus-themes-port-faq/][Re: VSCode or Vim ports of the Emacs modus-themes?]] (2022-01-03) ++ [[https://protesilaos.com/codelog/2022-04-20-modus-themes-case-study-avy/][Modus themes: case study on Avy faces and colour combinations]] (2022-04-20) ++ [[https://protesilaos.com/codelog/2022-04-21-modus-themes-colour-theory/][Emacs: colour theory and techniques used in the Modus themes]] (2022-04-21) + +And here are the canonical sources of this project: + ++ Manual :: <https://protesilaos.com/emacs/modus-themes> ++ Change Log :: <https://protesilaos.com/emacs/modus-themes-changelog> ++ Screenshots :: <https://protesilaos.com/emacs/modus-themes-pictures> ++ Git repository :: https://git.sr.ht/~protesilaos/modus-themes ++ Mailing list :: https://lists.sr.ht/~protesilaos/modus-themes * GNU Free Documentation License :properties: diff --git a/doc/misc/octave-mode.texi b/doc/misc/octave-mode.texi index 58fb8a49b68..31d64c3d840 100644 --- a/doc/misc/octave-mode.texi +++ b/doc/misc/octave-mode.texi @@ -240,7 +240,7 @@ entering Octave commands at the prompt. The buffer is in Inferior Octave mode, which is derived from the standard Comint mode, a major mode for interacting with an inferior interpreter. See the documentation for @code{comint-mode} for more details, and use -@kbd{C-h b} to find out about available special keybindings. +@kbd{C-h b} to find out about available special key bindings. You can also communicate with an inferior Octave process from within files with Octave code (i.e., buffers in Octave mode), using the diff --git a/doc/misc/org.org b/doc/misc/org.org index 9f69c684318..7971c417a52 100644 --- a/doc/misc/org.org +++ b/doc/misc/org.org @@ -3352,7 +3352,7 @@ current buffer: ~org-link-email-description-format~. By default, it refers to the addressee and the subject. -- /Web browsers: W3, W3M and EWW/ :: +- /Web browsers: W3M and EWW/ :: Here the link is the current URL, with the page title as the description. diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi index 87807b5bdab..80c130fb8e9 100644 --- a/doc/misc/pcl-cvs.texi +++ b/doc/misc/pcl-cvs.texi @@ -524,8 +524,8 @@ you can use in PCL-CVS@. They are grouped together by type. Most commands in PCL-CVS require that you have a @file{*cvs*} buffer. The commands that you use to get one are listed below. For each, a @samp{cvs} process will be run, the output will be parsed by -PCL-CVS, and the result will be printed in the @file{*cvs*} buffer (see -@ref{Buffer contents}, for a description of the buffer's contents). +PCL-CVS, and the result will be printed in the @file{*cvs*} buffer +(@pxref{Buffer contents}, for a description of the buffer's contents). @table @kbd @item M-x cvs-update diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi index da214958d5c..8c798d6c33b 100644 --- a/doc/misc/rcirc.texi +++ b/doc/misc/rcirc.texi @@ -154,8 +154,11 @@ deego: fsbot rules! @cindex nick completion @cindex completion of nicks +@vindex rcirc-cycle-completion-flag @kindex TAB Since this is so common, you can use @key{TAB} to do nick completion. +By default rcirc will use the default completion system, but you can +enable @code{rcirc-cycle-completion-flag} to cycle nicks in place. @node Getting started with rcirc @section Getting started with rcirc @@ -609,12 +612,6 @@ Use this symbol if you need to identify yourself in the Bitlbee channel as follows: @code{identify secret}. The necessary arguments are the nickname you want to use this for, and the password to use. -@item sasl -@cindex sasl authentication -Use this symbol if you want to use @acronym{SASL} authentication. The -necessary arguments are the nickname you want to use this for, and the -password to use. - @cindex gateway to other IM services @cindex instant messaging, other services @cindex Jabber @@ -633,6 +630,19 @@ the other instant messaging services, and Bitlbee will log you in. All @code{rcirc} needs to know, is the login to your Bitlbee account. Don't confuse the Bitlbee account with all the other accounts. +@item sasl +@cindex sasl authentication +Use this symbol if you want to use @acronym{SASL} authentication. The +necessary arguments are the nickname you want to use this for, and the +password to use. + +@item certfp +@cindex certfp authentication +Use this symbol if you want to use CertFP authentication. The +necessary arguments are the path to the key and to the client +certificate associated with the account. The CertFP authentication +requires a @acronym{TLS} connection. + @end table @end table @@ -926,6 +936,11 @@ how to include the date in the time stamp: (setq rcirc-time-format "%Y-%m-%d %H:%M ") @end example +@findex rcirc-when +If you don't wish to use verbose time formatting all the time, you can +use the @code{rcirc-when} command to display a complete timestamp for +the message at point. + @node Defining a new command @section Defining a new command @cindex defining commands diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi index a980c39616a..9d1fe545d47 100644 --- a/doc/misc/remember.texi +++ b/doc/misc/remember.texi @@ -313,7 +313,7 @@ Save (if it is modified) and bury the current buffer. @node Keystrokes @chapter Keystroke Reference -@file{remember.el} defines the following keybindings by default: +@file{remember.el} defines the following key bindings by default: @table @kbd diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index 70ccdf4a612..3141ab7c692 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -145,7 +145,7 @@ this means moving to the parent of the current tag. @item C-c , @key{SPC} Display a list of possible completions for the symbol at point (@code{semantic-complete-analyze-inline}). This also activates a -special set of keybindings for choosing a completion: @key{RET} +special set of key bindings for choosing a completion: @key{RET} accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible completions, @key{TAB} completes as far as possible and then cycles, and @kbd{C-g} or any other key aborts the completion. @@ -655,7 +655,7 @@ usual summary if the text at point has one of these faces. Semantic Idle Completions mode is a minor mode for performing @dfn{code completions} during idle time. The completions are -displayed inline, with keybindings that allow you to cycle through +displayed inline, with key bindings that allow you to cycle through different alternatives. Semantic Idle Completions mode performs completion based on the @@ -681,7 +681,7 @@ besselj [1 of 6 matches] @end example @noindent -While the completion is being displayed, the following keybindings +While the completion is being displayed, the following key bindings take effect: @table @kbd @@ -785,7 +785,7 @@ Most of the other commands documented in this section call This command is bound to @kbd{C-c , @key{SPC}} when Semantic mode is enabled (@pxref{Semantic mode user commands}). It displays a list of possible completions for the symbol at point, and activates a special -set of keybindings for choosing a completion. +set of key bindings for choosing a completion. You can type @key{RET} to accept the current completion, @kbd{M-n} and @kbd{M-p} to cycle through the possible completions, @key{TAB} to @@ -1122,7 +1122,7 @@ that @code{grep} is much slower than the others. The commands to display symbol references are @kbd{C-c , g} (@code{semantic-symref-symbol} and @kbd{C-c , G} -(@code{semantic-symref}). These keybindings are available whenever +(@code{semantic-symref}). These key bindings are available whenever Semantic mode is enabled (@pxref{Semantic mode user commands}). @deffn Command semantic-symref-symbol sym diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi index 0acb7bf3f15..6d0415cdbbb 100644 --- a/doc/misc/ses.texi +++ b/doc/misc/ses.texi @@ -220,7 +220,14 @@ You move around with the regular Emacs movement commands. @table @kbd @item j -Moves point to cell, specified by identifier (@code{ses-jump}). +Moves point to cell, specified by identifier (@code{ses-jump}). Unless +the cell is a renamed cell, the identifier is case-insensitive. A +prefix argument @math{n} move to cell with coordinates @math{(n\div R, +n \% C)} for a spreadsheet of @math{R} rows and @math{C} columns, and +A1 being of coordinates @math{(0,0)}. The way the identifier or the +command prefix argument are interpreted can be customized through +variables @code{ses-jump-cell-name-function} and +@code{ses-jump-prefix-function}. @end table Point is always at the left edge of a cell, or at the empty endline. @@ -726,10 +733,6 @@ yank. This doesn't make any difference? @section Customizing @acronym{SES} @cindex customizing @vindex enable-local-eval -@vindex ses-mode-hook -@vindex safe-functions -@vindex enable-local-eval - By default, a newly-created spreadsheet has 1 row and 1 column. The column width is 7 and the default printer is @samp{"%.7g"}. Each of these @@ -740,9 +743,34 @@ cell. You can customize @code{ses-after-entry-functions} to move left or up or down. For diagonal movement, select two functions from the list. +@vindex ses-jump-cell-name-function +@code{ses-jump-cell-name-function} is a customizable variable by +default set to the @code{upcase} function. This function is called +when you pass a cell name to the @command{ses-jump} command (@kbd{j}), +it changes the entered cell name to that where to jump. The default +setting @code{upcase} allows you to enter the cell name in low +case. Another use of @code{ses-jump-cell-name-function} could be some +internationalisation to convert non latin characters into latin +equivalents to name the cell. Instead of a cell name, the function may +return cell coordinates in the form of a cons, for instance @code{(0 +. 0)} for cell @code{A1}, @code{(1 . 0)} for cell @code{A2}, etc. + +@vindex ses-jump-prefix-function +@code{ses-jump-prefix-function} is a customisable variable by default +set to the @code{ses-jump-prefix} function. This function is called +when you give a prefix argument to the @command{ses-jump} command +(@kbd{j}). It returns a cell name or cell coordinates corresponding to +the prefix argument. Cell coordinates are in the form of a cons, for +instance @code{(1 . 0)} for cell @code{A2}. The default setting +@code{ses-jump-prefix} will number cells left to right and then top +down, so assuming a 4x3 spreadsheet prefix argument 0 jumps to cell +A1, prefix argument 2 jumps to C1, prefix argument 3 jumps to A2, etc. + +@vindex ses-mode-hook @code{ses-mode-hook} is a normal mode hook (list of functions to execute when starting @acronym{SES} mode for a buffer). +@vindex safe-functions The variable @code{safe-functions} is a list of possibly-unsafe functions to be treated as safe when analyzing formulas and printers. @xref{Virus protection}. Before customizing @code{safe-functions}, diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index 8368f198a34..13b709bfc8b 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -1218,4 +1218,3 @@ Two good values are @code{nil} and @code{statictag}. @bye @c LocalWords: speedbar's xref slowbar kbd subsubsection -@c LocalWords: keybindings diff --git a/doc/misc/srecode.texi b/doc/misc/srecode.texi index 9b1578ec0e0..a0cbf7e33fb 100644 --- a/doc/misc/srecode.texi +++ b/doc/misc/srecode.texi @@ -293,14 +293,14 @@ If the variable @code{srecode-takeover-INS-key} is set, then the key The most important key is bound to @code{srecode-insert} which is @kbd{C-c / /}, or @kbd{@key{INSERT} @key{INSERT}}. @ref{Quick Start}. -Major keybindings are: +Major key bindings are: @table @kbd @item C-c / / Insert a template whose name is typed into the minibuffer. @item C-c / <lower case letter> Reserved for direct binding of simple templates to keys using a -keybinding command in the template file. +key binding command in the template file. @item C-c / <upper case letter> Reserved for template applications (Such as comment or get/set inserter.) @item C-c / E @@ -1070,9 +1070,9 @@ Here is an example of wrapping a semantic tag in a compound value: "Wrap up a collection of semantic tag information. This class will be used to derive dictionary values.") -(defmethod srecode-compound-toString((cp srecode-semantic-tag) - function - dictionary) +(cl-defmethod srecode-compound-toString ((cp srecode-semantic-tag) + function + dictionary) "Convert the compound dictionary value CP to a string. If FUNCTION is non-nil, then FUNCTION is somehow applied to an aspect of the compound value." diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index 4e83986b8dd..67602b90537 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{2021-04-25.21} +\def\texinfoversion{2022-04-09.08} % -% Copyright 1985--1986, 1988, 1990--2022 Free Software Foundation, Inc. +% Copyright 1985, 1986, 1988, 1990-2022 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 @@ -3171,16 +3171,8 @@ end % Default is `distinct'. \kbdinputstyle distinct -% @kbd is like @code, except that if the argument is just one @key command, -% then @kbd has no effect. -\def\kbd#1{{\def\look{#1}\expandafter\kbdsub\look??\par}} - -\def\xkey{\key} -\def\kbdsub#1#2#3\par{% - \def\one{#1}\def\three{#3}\def\threex{??}% - \ifx\one\xkey\ifx\threex\three \key{#2}% - \else{\tclose{\kbdfont\setcodequotes\look}}\fi - \else{\tclose{\kbdfont\setcodequotes\look}}\fi +\def\kbd#1{% + \tclose{\kbdfont\setcodequotes#1}% } % definition of @key that produces a lozenge. Doesn't adjust to text size. @@ -3193,14 +3185,9 @@ end % \kern-0.4pt\hrule}% % \kern-.06em\raise0.4pt\hbox{\angleright}}}} -% definition of @key with no lozenge. If the current font is already -% monospace, don't change it; that way, we respect @kbdinputstyle. But -% if it isn't monospace, then use \tt. +% definition of @key with no lozenge. % -\def\key#1{{\setregularquotes - \nohyphenation - \ifmonospace\else\tt\fi - #1}\null} +\def\key#1{{\setregularquotes \nohyphenation \tt #1}\null} % @clicksequence{File @click{} Open ...} \def\clicksequence#1{\begingroup #1\endgroup} @@ -3614,6 +3601,9 @@ $$% \def\quotedblbase{{\ecfont \char"12}} \def\quotesinglbase{{\ecfont \char"0D}} % +\def\L{{\ecfont \char"8A}} % L with stroke +\def\l{{\ecfont \char"AA}} % l with stroke +% % This positioning is not perfect (see the ogonek LaTeX package), but % we have the precomposed glyphs for the most common cases. We put the % tests to use those glyphs in the single \ogonek macro so we have fewer @@ -4419,7 +4409,7 @@ $$% % Find the correct column width \hsize=\expandafter\csname col\the\colcount\endcsname % - \rightskip=0pt + \advance\rightskip by -1\rightskip % Zero leaving only any stretch \ifnum\colcount=1 \advance\hsize by\leftskip % Add indent of surrounding text \else @@ -5963,7 +5953,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % Chapters, sections, etc. % Let's start with @part. -\outer\parseargdef\part{\partzzz{#1}} +\parseargdef\part{\partzzz{#1}} \def\partzzz#1{% \chapoddpage \null @@ -7592,6 +7582,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % \def\printdefunline#1#2{% \begingroup + \plainfrenchspacing % call \deffnheader: #1#2 \endheader % common ending: @@ -7660,7 +7651,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % If SUBTOPIC is present, precede it with a space, and call \doind. % (At some time during the 20th century, this made a two-level entry in an % index such as the operation index. Nobody seemed to notice the change in -% behavior though.) +% behaviour though.) \def\dosubind#1#2#3{% \def\thirdarg{#3}% \ifx\thirdarg\empty @@ -8681,9 +8672,11 @@ might help (with 'rm \jobname.?? \jobname.??s')% } \def\wordTop{Top} -% Until the next @node or @bye command, divert output to a box that is not -% output. -\def\ignorenode{\setbox\dummybox\vbox\bgroup\def\node{\egroup\node}% +% Until the next @node, @part or @bye command, divert output to a box that +% is not output. +\def\ignorenode{\setbox\dummybox\vbox\bgroup +\def\part{\egroup\part}% +\def\node{\egroup\node}% \ignorenodebye } @@ -9392,25 +9385,27 @@ might help (with 'rm \jobname.?? \jobname.??s')% \catcode`\^^M = 5 % in case we're inside an example \normalturnoffactive % allow _ et al. in names \makevalueexpandable - % If the image is by itself, center it. \ifvmode \imagevmodetrue \else \ifx\centersub\centerV % for @center @image, we need a vbox so we can have our vertical space \imagevmodetrue - \vbox\bgroup % vbox has better behavior than vtop herev + \vbox\bgroup % vbox has better behavior than vtop here \fi\fi % \ifimagevmode - \nobreak\medskip + \medskip % Usually we'll have text after the image which will insert % \parskip glue, so insert it here too to equalize the space % above and below. - \nobreak\vskip\parskip - \nobreak + \vskip\parskip + % + % Place image in a \vtop for a top page margin that is (close to) correct, + % as \topskip glue is relative to the first baseline. + \vtop\bgroup\hrule height 0pt\vskip-\parskip \fi % - % Leave vertical mode so that indentation from an enclosing + % Enter horizontal mode so that indentation from an enclosing % environment such as @quotation is respected. % However, if we're at the top level, we don't want the % normal paragraph indentation. @@ -9439,6 +9434,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \fi % \ifimagevmode + \egroup \medskip % space after a standalone image \fi \ifx\centersub\centerV \egroup \fi @@ -10899,6 +10895,9 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{1EF8}{\~Y}% \DeclareUnicodeCharacter{1EF9}{\~y}% % + % Exotic spaces + \DeclareUnicodeCharacter{2007}{\hphantom{0}}% + % % Punctuation \DeclareUnicodeCharacter{2013}{--}% \DeclareUnicodeCharacter{2014}{---}% @@ -11244,23 +11243,6 @@ directory should work if nowhere else does.} \defbodyindent = .5cm }} -% Use @smallerbook to reset parameters for 6x9 trim size. -% (Just testing, parameters still in flux.) -\def\smallerbook{{\globaldefs = 1 - \parskip = 1.5pt plus 1pt - \textleading = 12pt - % - \internalpagesizes{7.4in}{4.8in}% - {-.2in}{-.4in}% - {0pt}{14pt}% - {9in}{6in}% - % - \lispnarrowing = 0.25in - \tolerance = 700 - \contentsrightmargin = 0pt - \defbodyindent = .4cm -}} - % Use @afourpaper to print on European A4 paper. \def\afourpaper{{\globaldefs = 1 \parskip = 3pt plus 2pt minus 1pt @@ -11599,11 +11581,9 @@ directory should work if nowhere else does.} @setregularquotes @c Local variables: -@c eval: (add-hook 'before-save-hook 'time-stamp) +@c eval: (add-hook 'before-save-hook 'time-stamp nil t) +@c time-stamp-pattern: "texinfoversion{%Y-%02m-%02d.%02H}" @c page-delimiter: "^\\\\message\\|emacs-page" -@c time-stamp-start: "def\\\\texinfoversion{" -@c time-stamp-format: "%:y-%02m-%02d.%02H" -@c time-stamp-end: "}" @c End: @c vim:sw=2: diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 06df3192968..cfbc96f4692 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -50,13 +50,10 @@ This file documents @w{@value{tramp} @value{trampver}}, a remote file editing package for Emacs. @value{tramp} stands for ``Transparent Remote (file) Access, Multiple -Protocol''. This package provides remote file editing, similar to -Ange FTP@. - -The difference is that Ange FTP uses FTP to transfer files between the -local and the remote host, whereas @value{tramp} uses a combination of -@command{rsh} and @command{rcp} or other work-alike programs, such as -@command{ssh}/@command{scp}. +Protocol''. This package provides an easy, convenient, and consistent +interface to editing remote files transparently, just as if they are +local files. This extends to editing, version control, @code{dired}, +and more. You can find the latest version of this document on the web at @uref{@value{trampurl}}. @@ -133,19 +130,21 @@ Configuring @value{tramp} for use * Multi-hops:: Connecting to a remote host using multiple hops. * Firewalls:: Passing firewalls. * Customizing Methods:: Using Non-Standard Methods. -* Customizing Completion:: Selecting config files for user/host name completion. +* Customizing Completion:: Selecting config files for user/host name @c +completion. * Password handling:: Reusing passwords for several connections. * Connection caching:: Reusing connection related information. * Predefined connection information:: Setting own connection related information. -* Remote programs:: How @value{tramp} finds and uses programs on the remote host. +* Remote programs:: How @value{tramp} finds and uses programs @c +on the remote host. * Remote shell setup:: Remote shell setup hints. +* Ssh setup:: Ssh setup hints. * FUSE setup:: @acronym{FUSE} setup hints. * Android shell setup:: Android shell setup hints. * Auto-save File Lock and Backup:: Auto-save, File Lock and Backup. * Keeping files encrypted:: Protect remote files by encryption. -* Windows setup hints:: Issues with Cygwin ssh. Using @value{tramp} @@ -155,6 +154,7 @@ Using @value{tramp} @end ifset * File name completion:: File name completion. * Ad-hoc multi-hops:: Declaring multiple hops in the file name. +* Home directories:: Expanding @file{~} to home directory. * Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. * Renaming remote files:: Renaming remote files. @@ -179,10 +179,10 @@ interface to remote files as if they are local files. @value{tramp}'s transparency extends to editing, version control, and @code{dired}. @value{tramp} can access remote hosts using any number of access -methods, such as @command{rsh}, @command{rlogin}, @command{telnet}, -and related programs. If these programs can successfully pass -@acronym{ASCII} characters, @value{tramp} can use them. -@value{tramp} does not require or mandate 8-bit clean connections. +methods, such as @command{ssh}, @command{scp}, @command{telnet}, and +related programs. If these programs can successfully pass +@acronym{ASCII} characters, @value{tramp} can use them. @value{tramp} +does not require or mandate 8-bit clean connections. @value{tramp}'s most common access method is through @command{ssh}, a more secure alternative to @command{ftp} and other older access @@ -230,10 +230,10 @@ first time connecting to that host, here's what happens: @itemize @item -@value{tramp} invokes @samp{telnet @var{host}} or @samp{rsh @var{host} --l @var{user}} and establishes an external process to connect to the -remote host. @value{tramp} communicates with the process through an -Emacs buffer, which also shows output from the remote host. +@value{tramp} invokes @samp{telnet @var{host}} or @samp{ssh -l +@var{user} @var{host}} and establishes an external process to connect +to the remote host. @value{tramp} communicates with the process +through an Emacs buffer, which also shows output from the remote host. @item The remote host may prompt for a login name (for @command{telnet}, for @@ -243,7 +243,7 @@ followed by a newline. @item The remote host may then prompt for a password or passphrase (for -@command{rsh} or for @command{telnet}). @value{tramp} displays the +@command{ssh} or for @command{telnet}). @value{tramp} displays the password prompt in the minibuffer. @value{tramp} then sends whatever is entered to the remote host, followed by a newline. @@ -309,7 +309,7 @@ I hope this has provided you with a basic overview of what happens behind the scenes when you open a file with @value{tramp}. -@c For the end user +@c For the end user. @node Obtaining @value{tramp} @chapter Obtaining @value{tramp} @cindex obtaining @value{tramp} @@ -523,7 +523,7 @@ performed on another host, it can be comnbined with a leading connects first to the other host with non-administrative credentials, and changes to administrative credentials on that host afterwards. In a simple case, the syntax looks like -@file{@value{prefix}ssh@value{postfixhop}user@@host|sudo@value{postfixhop}@value{postfix}/path/to/file}. +@file{@trampfn{ssh@value{postfixhop}user@@host|sudo,,/path/to/file}}. @xref{Ad-hoc multi-hops}. @@ -688,19 +688,21 @@ to non-@code{nil}, @xref{Directory Variables, , , emacs}. * Multi-hops:: Connecting to a remote host using multiple hops. * Firewalls:: Passing firewalls. * Customizing Methods:: Using Non-Standard Methods. -* Customizing Completion:: Selecting config files for user/host name completion. +* Customizing Completion:: Selecting config files for user/host name @c +completion. * Password handling:: Reusing passwords for several connections. * Connection caching:: Reusing connection related information. * Predefined connection information:: Setting own connection related information. -* Remote programs:: How @value{tramp} finds and uses programs on the remote host. +* Remote programs:: How @value{tramp} finds and uses programs @c +on the remote host. * Remote shell setup:: Remote shell setup hints. +* Ssh setup:: Ssh setup hints. * FUSE setup:: @acronym{FUSE} setup hints. * Android shell setup:: Android shell setup hints. * Auto-save File Lock and Backup:: Auto-save, File Lock and Backup. * Keeping files encrypted:: Protect remote files by encryption. -* Windows setup hints:: Issues with Cygwin ssh. @end menu @@ -1239,7 +1241,8 @@ be populated in your @command{Online Accounts} application outside Emacs. Since Google Drive uses cryptic blob file names internally, @value{tramp} works with the @code{display-name} of the files. This could produce unexpected behavior in case two files in the same -directory have the same @code{display-name}, such a situation must be avoided. +directory have the same @code{display-name}, such a situation must be +avoided. @item @option{mtp} @cindex method @option{mtp} @@ -1453,7 +1456,7 @@ External methods might be more efficient for large files, but most @value{tramp} users edit small files more often than large files. Enable compression, @code{tramp-inline-compress-start-size}, for a -performance boost for large files. +performance boost for large files with inline methods. Since @command{ssh} has become the most common method of remote host access and it has the most reasonable security protocols, use @@ -1479,6 +1482,10 @@ For editing large files, @option{scp} is faster than @option{ssh}. @option{pscp} is faster than @option{plink}. But this speed improvement is not always true. +When copying large files between two different remote hosts via +@option{scp}, set @code{tramp-use-scp-direct-remote-copying} to +non-@code{nil}. + @node Default User @section Selecting a default user @@ -1659,7 +1666,7 @@ local one, first connect via @command{ssh}, and then apply (add-to-list 'tramp-default-proxies-alist '(nil "\\`root\\'" "@trampfn{ssh,%h,}")) (add-to-list 'tramp-default-proxies-alist - '((regexp-quote (system-name)) nil nil)) + `(,(regexp-quote (system-name)) nil nil)) @end group @end lisp @end defopt @@ -1694,8 +1701,8 @@ Sometimes, it is not possible to reach a remote host directly. A firewall might be in the way, which could be passed via a proxy server. -Both ssh and PuTTY support such proxy settings, using an HTTP tunnel -via the @command{CONNECT} command (conforming to RFC 2616, 2817 +Both OpenSSH and PuTTY support such proxy settings, using an HTTP +tunnel via the @command{CONNECT} command (conforming to RFC 2616, 2817 specifications). Proxy servers using HTTP 1.1 or later protocol support this command. @@ -1804,12 +1811,23 @@ Access of a hadoop/hdfs file system. A file is accessed via the user that you want to use, and @samp{node} is the name of the hadoop server. +@item tramp-nspawn +@cindex method @option{nspawn} +@cindex @option{nspawn} method +Access to environments provided by systemd-nspawn. A file is accessed +via @file{@trampfn{nspawn,user@@container,/path/to/file}}, where +@samp{user} is the (optional) user that you want to use, and +@samp{container} is the container to connect to. systemd-nspawn and +its container utilities often require super user access to run, use +multi-hop file names with @option{doas} or @option{sudo} to raise your +privileges. + @item vagrant-tramp @cindex method @option{vagrant} @cindex @option{vagrant} method Convenience method to access vagrant boxes. It is often used in multi-hop file names like -@file{@value{prefix}vagrant@value{postfixhop}box|sudo@value{postfixhop}box@value{postfix}/path/to/file}, +@file{@trampfn{vagrant@value{postfixhop}box|sudo,box,/path/to/file}}, where @samp{box} is the name of the vagrant box. @end table @@ -1865,29 +1883,25 @@ Example: The following predefined functions parsing configuration files exist: -@table @asis +@ftable @asis @item @code{tramp-parse-rhosts} -@findex tramp-parse-rhosts This function parses files which are syntactical equivalent to @file{~/.rhosts}. It returns both host names and user names, if specified. @item @code{tramp-parse-shosts} -@findex tramp-parse-shosts This function parses files which are syntactical equivalent to @file{~/.ssh/known_hosts}. Since there are no user names specified in such files, it can return host names only. @item @code{tramp-parse-sconfig} -@findex tramp-parse-sconfig This function returns the host nicknames defined by @option{Host} entries in @file{~/.ssh/config} style files. @item @code{tramp-parse-shostkeys} -@findex tramp-parse-shostkeys SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and @file{~/ssh2/hostkeys/*}. Hosts are coded in file names @@ -1895,7 +1909,6 @@ SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and are always @code{nil}. @item @code{tramp-parse-sknownhosts} -@findex tramp-parse-sknownhosts Another SSH2 style parsing of directories like @file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This @@ -1903,26 +1916,22 @@ case, hosts names are coded in file names @file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}. @item @code{tramp-parse-hosts} -@findex tramp-parse-hosts A function dedicated to @file{/etc/hosts} for host names. @item @code{tramp-parse-passwd} -@findex tramp-parse-passwd A function which parses @file{/etc/passwd} for user names. @item @code{tramp-parse-etc-group} -@findex tramp-parse-etc-group A function which parses @file{/etc/group} for group names. @item @code{tramp-parse-netrc} -@findex tramp-parse-netrc A function which parses @file{~/.netrc} and @file{~/.authinfo}-style files. -@end table +@end ftable To keep a custom file with custom data in a custom structure, a custom function has to be provided. This function must meet the following @@ -1982,6 +1991,20 @@ file name syntax, must be appended to the machine and login items: machine melancholia#4711 port davs login daniel%BIZARRE password geheim @end example +For the methods @option{doas}, @option{sudo} and @option{sudoedit} the +password of the user requesting the connection is needed, and not the +password of the target user. If these connections happen on the local +host, an entry with the local user and local host is used: + +@example +machine @var{HOST} port sudo login @var{USER} password secret +@end example + +@var{USER} and @var{HOST} are the strings returned by +@code{(user-login-name)} and @code{(system-name)}. If one of these +methods is connected via a multi hop (@pxref{Multi-hops}), the +credentials of the previous hop are used. + @vindex auth-source-save-behavior If no proper entry exists, the password is read interactively. After successful login (verification of the password), @@ -2147,6 +2170,14 @@ reestablished. A value of @code{nil} disables this feature. Most of the methods do not set this property except the @option{sudo} and @option{doas} methods, which use predefined values. +@item @t{"~"}@* +@t{"~user"} + +This is the home directory on the remote host. Setting this +connection property helps especially for methods which cannot expand +to a remote home directory, like @option{adb}, @option{rclone} and +@option{sshfs}. @ref{Home directories} for an example. + @item @t{"tmpdir"} The temporary directory on the remote host. If not specified, the @@ -2243,8 +2274,7 @@ preserves the path value, which can be used to update shell supports the login argument @samp{-l}. @end defopt -Starting with @w{Emacs 26}, @code{tramp-remote-path} can be set per -host via connection-local +@code{tramp-remote-path} can also be set per host via connection-local @ifinfo variables, @xref{Connection Variables, , , emacs}. @end ifinfo @@ -2612,6 +2642,246 @@ where @samp{192.168.0.1} is the remote host IP address @end table +@node Ssh setup +@section Ssh setup hints + +The most common @value{tramp} connection family is based on either +@command{ssh} or @command{scp} of OpenSSH, or @command{plink} or +@command{pscp} of PuTTY on MS Windows. In the following, some +configuration recommendations are given. + + +@subsection Using ssh config include for host name completion + +@vindex Include@r{, ssh option} +@findex tramp-set-completion-function +@findex tramp-get-completion-function +OpenSSH configuration files can use an @option{Include} option for +further configuration files. Default @value{tramp} host name +completion ignores this option. However, you can configure this +yourself. + +Given, your @file{~/.ssh/config} file contains the following option: + +@example +Include ~/.ssh/conf.d/* +@end example + +The following code snippet in your @file{.emacs} uses all files in +that directory for host name completion: + +@lisp +@group +(tramp-set-completion-function + "ssh" (append (tramp-get-completion-function "ssh") + (mapcar (lambda (file) `(tramp-parse-sconfig ,file)) + (directory-files + "~/.ssh/conf.d/" + 'full directory-files-no-dot-files-regexp)))) +@end group +@end lisp + +This code snippet does it for the @option{ssh} method. If you replace +@t{"ssh"} by @t{"scp"}, it does it also for that method (or any other +method you like). + + +@subsection Detection of session hangouts + +@vindex ServerAliveInterval@r{, ssh option} +@vindex ServerAliveCountMax@r{, ssh option} +@command{ssh} sessions on the local host hang when the network is +down. @value{tramp} cannot safely detect such hangs. OpenSSH can be +configured to kill such hangs with the following settings in +@file{~/.ssh/config}: + +@example +@group +Host * + ServerAliveInterval 5 + ServerAliveCountMax 2 +@end group +@end example + +The corresponding PuTTY configuration is in the @option{Connection} +entry, @option{Seconds between keepalives} option. Set this to 5. +There is no counter which could be set. + + +@subsection Using ssh connection sharing + +@vindex ControlPath@r{, ssh option} +@vindex ControlPersist@r{, ssh option} +@value{tramp} uses the @option{ControlMaster=auto} OpenSSH option by +default, if possible. However, it overwrites @option{ControlPath} +settings when initiating @command{ssh} sessions. @value{tramp} does +this to fend off a stall if a master session opened outside the Emacs +session is no longer open. That is why @value{tramp} prompts for the +password again even if there is an @command{ssh} already open. + +@vindex tramp-ssh-controlmaster-options +Some OpenSSH versions support a @option{ControlPersist} option, which +allows you to set the @option{ControlPath} provided the variable +@code{tramp-ssh-controlmaster-options} is customized as follows: + +@lisp +@group +(customize-set-variable + 'tramp-ssh-controlmaster-options + (concat + "-o ControlPath=/tmp/ssh-ControlPath-%%r@@%%h:%%p " + "-o ControlMaster=auto -o ControlPersist=yes")) +@end group +@end lisp + +Note how @samp{%r}, @samp{%h} and @samp{%p} must be encoded as +@samp{%%r}, @samp{%%h} and @samp{%%p}. + +@vindex tramp-use-ssh-controlmaster-options +If the @file{~/.ssh/config} file is configured appropriately for the +above behavior, then any changes to @command{ssh} can be suppressed +with this @code{nil} setting: + +@lisp +(customize-set-variable 'tramp-use-ssh-controlmaster-options nil) +@end lisp + +@vindex ProxyCommand@r{, ssh option} +@vindex ProxyJump@r{, ssh option} +This should also be set to @code{nil} if you use the +@option{ProxyCommand} or @option{ProxyJump} options in your +@command{ssh} configuration. + +In order to use the @option{ControlMaster} option, @value{tramp} must +check whether the @command{ssh} client supports this option. This is +only possible on the local host, for the first hop. @value{tramp} +does not use this option on proxy hosts, therefore. + +If you want to use this option also for the other hops, you must +configure @file{~/.ssh/config} on the proxy host: + +@example +@group +Host * + ControlMaster auto + ControlPath tramp.%C + ControlPersist no +@end group +@end example + +Check the @samp{ssh_config(5)} man page whether these options are +supported on your proxy host. + +On MS Windows, @code{tramp-use-ssh-controlmaster-options} is set to +@code{nil} by default, because the MS Windows and MSYS2 +implementations of @command{OpenSSH} do not support this option properly. + +In PuTTY, you can achieve connection sharing in the @option{Connection/SSH} +entry, enabling the @option{Share SSH connections if possible} option. + + +@subsection Configure direct copying between two remote servers + +@vindex tramp-use-scp-direct-remote-copying +@value{tramp} uses a temporary local copy when copying two files +between different remote hosts via external methods. This behavior is +due to authentication problems @value{tramp} cannot handle +sufficiently. However, for @option{scp} connections this can be +changed. When a file shall be copied between two different remote +hosts @samp{source} and @samp{target}, and + +@itemize @minus +@item +Variable @code{tramp-use-scp-direct-remote-copying} is non-@code{nil}, + +@item +Remote host @samp{source} doesn't use the @option{RemoteCommand} +option in @file{~/.ssh/config}, + +@item +Remote host @samp{target} shows the same host key when seen from the +local host and from host @samp{source}, and + +@item +@command{scp} running on host @samp{source} can authenticate to host +@samp{target} without requiring a password, +@end itemize + +@noindent +@value{tramp} applies direct remote copying between hosts +@samp{source} and @samp{target} like + +@example +scp -p -T -R -q -r source:/path/to/file target:/path/to/another/file +@end example + +This protects also your local temporary directory from overrun when +copying large files. + +If these conditions do not apply, and +@code{tramp-use-scp-direct-remote-copying} is non-@code{nil}, the +option @samp{-3} is used instead of @samp{-R}. + +@c FIXME +When @value{tramp} uses direct remote copying, password caches are not +consulted. + + +@subsection Issues with Cygwin ssh +@cindex cygwin, issues + +This section is incomplete. Please share your solutions. + +@cindex method @option{sshx} with cygwin +@cindex @option{sshx} method with cygwin + +Cygwin's @command{ssh} works only with a Cygwin version of Emacs. To +check for compatibility: type @kbd{M-x eshell @key{RET}}, and start +@kbd{ssh test.host @key{RET}}. Incompatibilities trigger this +message: + +@example +Pseudo-terminal will not be allocated because stdin is not a terminal. +@end example + +Some older versions of Cygwin's @command{ssh} work with the +@option{sshx} access method. Consult Cygwin's FAQ at +@uref{https://cygwin.com/faq/} for details. + +@cindex cygwin and @command{fakecygpty} +@cindex @command{fakecygpty} and cygwin + +On @uref{https://www.emacswiki.org/emacs/SshWithNTEmacs, the Emacs +Wiki} it is explained how to use the helper program +@command{fakecygpty} to fix this problem. + +@cindex method @option{scpx} with cygwin +@cindex @option{scpx} method with cygwin + +When using the @option{scpx} access method, Emacs may call +@command{scp} with MS Windows file naming, such as @file{c:/foo}. But +the version of @command{scp} that is installed with Cygwin does not +know about MS Windows file naming, which causes it to incorrectly look +for a host named @samp{c}. + +A workaround: write a wrapper script for @option{scp} to convert +Windows file names to Cygwin file names. + +@cindex cygwin and @command{ssh-agent} +@cindex @env{SSH_AUTH_SOCK} and emacs on ms windows +@vindex SSH_AUTH_SOCK@r{, environment variable} + +When using the @command{ssh-agent} on MS Windows for password-less +interaction, @option{ssh} methods depend on the environment variable +@env{SSH_AUTH_SOCK}. But this variable is not set when Emacs is +started from a Desktop shortcut and authentication fails. + +One workaround is to use an MS Windows based SSH Agent, such as +@command{Pageant}. It is part of the PuTTY Suite of tools. + +The fallback is to start Emacs from a shell. + + @node FUSE setup @section @acronym{FUSE} setup hints @@ -2671,6 +2941,7 @@ Additionally, it declares also the arguments for running remote processes, using the @command{ssh} command. These don't need to be changed. + @node Android shell setup @section Android shell setup hints @cindex android shell setup for ssh @@ -2834,10 +3105,10 @@ Example: The backup file name of @file{@trampfn{su,root@@localhost,/etc/secretfile}} would be @ifset unified -@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}} +@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}. @end ifset @ifset separate -@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}} +@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}}. @end ifset @vindex auto-save-file-name-transforms @@ -2855,6 +3126,14 @@ auto-saved files to the same directory as the original file. Alternatively, set the user option @code{tramp-auto-save-directory} to direct all auto saves to that location. +@c Since Emacs 29. +@vindex remote-file-name-inhibit-auto-save-visited +An alternative to @code{auto-save-mode} is +@code{auto-save-visited-mode}. In this mode, auto-saving is identical +to explicit saving. If you want to disable this behavior for remote +files, set user option +@code{remote-file-name-inhibit-auto-save-visited} to non-@code{nil}. + @vindex lock-file-name-transforms And still more issues to handle. Since @w{Emacs 28}, file locks use a similar user option as auto-save files, called @@ -2991,62 +3270,6 @@ subdirectories will remain encrypted. @end deffn -@node Windows setup hints -@section Issues with Cygwin ssh -@cindex cygwin, issues - -This section is incomplete. Please share your solutions. - -@cindex method @option{sshx} with cygwin -@cindex @option{sshx} method with cygwin - -Cygwin's @command{ssh} works only with a Cygwin version of Emacs. To -check for compatibility: type @kbd{M-x eshell @key{RET}}, and start -@kbd{ssh test.host @key{RET}}. Incompatibilities trigger this -message: - -@example -Pseudo-terminal will not be allocated because stdin is not a terminal. -@end example - -Some older versions of Cygwin's @command{ssh} work with the -@option{sshx} access method. Consult Cygwin's FAQ at -@uref{https://cygwin.com/faq/} for details. - -@cindex cygwin and @command{fakecygpty} -@cindex @command{fakecygpty} and cygwin - -On @uref{https://www.emacswiki.org/emacs/SshWithNTEmacs, the Emacs -Wiki} it is explained how to use the helper program -@command{fakecygpty} to fix this problem. - -@cindex method @option{scpx} with cygwin -@cindex @option{scpx} method with cygwin - -When using the @option{scpx} access method, Emacs may call -@command{scp} with MS Windows file naming, such as @file{c:/foo}. But -the version of @command{scp} that is installed with Cygwin does not -know about MS Windows file naming, which causes it to incorrectly look -for a host named @samp{c}. - -A workaround: write a wrapper script for @option{scp} to convert -Windows file names to Cygwin file names. - -@cindex cygwin and @command{ssh-agent} -@cindex @env{SSH_AUTH_SOCK} and emacs on ms windows -@vindex SSH_AUTH_SOCK@r{, environment variable} - -When using the @command{ssh-agent} on MS Windows for password-less -interaction, @option{ssh} methods depend on the environment variable -@env{SSH_AUTH_SOCK}. But this variable is not set when Emacs is -started from a Desktop shortcut and authentication fails. - -One workaround is to use an MS Windows based SSH Agent, such as -Pageant. It is part of the Putty Suite of tools. - -The fallback is to start Emacs from a shell. - - @node Usage @chapter Using @value{tramp} @cindex using @value{tramp} @@ -3075,6 +3298,7 @@ is a feature of Emacs that may cause missed prompts when using @end ifset * File name completion:: File name completion. * Ad-hoc multi-hops:: Declaring multiple hops in the file name. +* Home directories:: Expanding @file{~} to home directory. * Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. * Renaming remote files:: Renaming remote files. @@ -3090,6 +3314,7 @@ is a feature of Emacs that may cause missed prompts when using @file{@trampfn{method,host,/path/to/file}} opens file @var{/path/to/file} on the remote host @var{host}, using the method @var{method}. +@c We cannot use @trampfn{} in @item. @table @file @item @value{prefix}ssh@value{postfixhop}melancholia@value{postfix}.emacs For the file @file{.emacs} located in the home directory, on the host @@ -3121,12 +3346,9 @@ brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}. @end ifset By default, @value{tramp} will use the current local user name as the -remote user name for log in to the remote host. Specifying a different -name using the proper syntax will override this default behavior: - -@example -@trampfn{method,user@@host,path/to/file} -@end example +remote user name for log in to the remote host. Specifying a +different name using the proper syntax will override this default +behavior: @file{@trampfn{method,user@@host,path/to/file}}. @file{@trampfn{ssh,daniel@@melancholia,.emacs}} is for file @file{.emacs} in @code{daniel}'s home directory on the host, @@ -3322,8 +3544,9 @@ remote host name and file name. For example, hopping over a single proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}: @example -@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh,you,remotehost,/path} @key{RET}} -@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path @key{RET}} +@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh,you@@remotehost,/path} @key{RET}} +@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|@c +ssh@value{postfixhop}you@@remotehost@value{postfix}/path @key{RET}} @end example Each involved method must be an inline method (@pxref{Inline methods}). @@ -3351,12 +3574,72 @@ Ad-hoc proxies can take patterns @code{%h} or @code{%u} like in @code{tramp-default-proxies-alist}. The following file name expands to user @samp{root} on host @samp{remotehost}, starting with an @option{ssh} session on host @samp{remotehost}: -@samp{@value{prefix}ssh@value{postfixhop}%h|su@value{postfixhop}remotehost@value{postfix}}. +@samp{@trampfn{ssh@value{postfixhop}%h|su,remotehost,}}. -On the other hand, if a trailing hop does not specify a host name, -the host name of the previous hop is reused. Therefore, the following +On the other hand, if a trailing hop does not specify a host name, the +host name of the previous hop is reused. Therefore, the following file name is equivalent to the previous example: -@samp{@value{prefix}ssh@value{postfixhop}remotehost|su@value{postfixhop}@value{postfix}}. +@samp{@trampfn{ssh@value{postfixhop}remotehost|su,,}}. + + +@node Home directories +@section Expanding @file{~} to home directory + +Home directories on remote hosts can be typed as tilde @file{~}. If +possible, they are expanded to the remote user's home directory on the +remote host. Example: + +@example +@group +@trampfn{ssh,user@@host,~} +@result{} @trampfn{ssh,user@@host,/home/user} +@end group +@end example + +This works in general for @option{ssh}-like methods, and for +@option{sudoedit}. These methods allow also the home directory +expansion for another user, like + +@example +@group +@trampfn{sudoedit,,~otheruser} +@result{} @trampfn{sudoedit,root@@localhost,/home/otheruser} +@end group +@end example + +For other methods, a home directory can be expanded only if supported. +This happens for example for the @option{sftp} method. Methods, which +require a share directory in the remote file name (@option{afp}, +@option{smb}), use the value of this share directory as home +directory: + +@example +@group +@trampfn{smb,user@@host,~} +@result{} @trampfn{smb,user@@host,/share} +@end group +@end example + +Since Tramp cannot know in advance which share directory is intended +to use, this expansion can be applied only when a share directory has +been used already. + +The methods @option{adb}, @option{rclone} and @option{sshfs} do not +support home directory expansion at all. However, @value{tramp} keeps +the home directory in the cache. Therefore, those methods could be +configured to expand a home directory via a connection property, +@xref{Predefined connection information}. Example: + +@lisp +@group +(add-to-list 'tramp-connection-properties + (list (regexp-quote "@trampfn{sshfs,user@@randomhost.your.domain,}") + "~user" "/home/user")) +@end group +@end lisp + +When your remote file name does not contain a @samp{user} part, the +connection property @t{"~"} must be used instead. @node Remote processes @@ -3394,9 +3677,9 @@ returns the exit code for it. When the user option indication that the process has been interrupted, and returns a corresponding string. -This remote process handling does not apply to @acronym{GVFS} (see -@ref{GVFS-based methods}) because the remote file system is mounted on -the local host and @value{tramp} accesses it by changing the +This remote process handling does not apply to @acronym{GVFS} +(@pxref{GVFS-based methods}) because the remote file system is mounted +on the local host and @value{tramp} accesses it by changing the @code{default-directory}. @value{tramp} starts a remote process when a command is executed in a @@ -3416,7 +3699,7 @@ might also add their name to this environment variable, like For @value{tramp} to find the command on the remote, it must be accessible through the default search path as setup by @value{tramp} upon first connection. Alternatively, use an absolute path or extend -@code{tramp-remote-path} (see @ref{Remote programs}): +@code{tramp-remote-path} (@pxref{Remote programs}): @lisp @group @@ -3538,9 +3821,8 @@ ensures the correct name of the remote shell program. When @code{explicit-shell-file-name} is equal to @code{nil}, calling @code{shell} interactively will prompt for a shell name. -Starting with @w{Emacs 26}, you could use connection-local variables -for setting different values of @code{explicit-shell-file-name} for -different remote hosts. +You could use connection-local variables for setting different values +of @code{explicit-shell-file-name} for different remote hosts. @ifinfo @xref{Connection Variables, , , emacs}. @end ifinfo @@ -3774,6 +4056,127 @@ using the @code{:connection-type} keyword. If this keyword is not used, the value of @code{process-connection-type} is applied instead. +@subsection Process properties of asynchronous remote processes +@cindex Asynchronous remote processes + +When available, @value{tramp} adds process properties to process +objects of asynchronous properties. However, it is not guaranteed +that all these properties are set. + +@itemize +@item @code{remote-tty} + +This is the name of the terminal a @var{process} uses on the remote +host, i.e., it reads and writes on. + +@item @code{remote-pid} + +The process id of the command executed on the remote host. This is +used when sending signals remotely. + +@item @code{remote-command} + +The remote command which has been invoked via @code{make-process} or +@code{start-file-process}, a list of strings (program and its +arguments). This does not show the additional shell sugar +@value{tramp} makes around the commands, in order to see this you must +inspect @value{tramp} @ref{Traces and Profiles, traces}. +@end itemize + +@findex list-system-processes +@findex process-attributes +The functions @code{list-system-processes} and +@code{process-attributes} return information about system processes on +the respective remote host. In order to retrieve this information, +they use the command @command{ps}, driven by the following constants: + +@defvr Constant tramp-process-attributes-ps-args +This is a list of arguments (strings) @command{ps} is called with. +The default value is appropriate for GNU/Linux remote hosts. +@end defvr + +@defvr Constant tramp-process-attributes-ps-format +This is a list of cons cells @code{(@var{key} . @var{type})} for +interpretation of the @command{ps} output. @var{key} is a key used in +the @code{process-attributes} output plus the key @code{pid}, and +@var{type} is the respective value returned by @command{ps}. It can +be + + +@multitable {@bullet{} @code{numberp}} {--- a string of @var{number} width, could contain spaces} +@item @bullet{} @code{numberp} @tab --- a number +@item @bullet{} @code{stringp} @tab --- a string without spaces +@item @bullet{} @var{number} +@tab --- a string of @var{number} width, could contain spaces +@item @bullet{} @code{nil} @tab --- a string until end of line +@end multitable + +The default value is appropriate for GNU/Linux remote hosts. +@end defvr + +If, for example, @code{tramp-process-attributes-ps-args} is declared +as @code{("-eww" "-o" "pid,euid,euser,egid,egroup,comm:40,state")}, +the output of the respective @command{ps} command would look like + +@smallexample +@group + PID EUID EUSER EGID EGROUP COMMAND S + 1 0 root 0 root systemd S + 1610 0 root 0 root NFSv4 callback S + @dots{} +@end group +@end smallexample + +The corresponding @code{tramp-process-attributes-ps-format} has the value + +@smallexample +@group +@code{((pid . numberp) (euid . numberp) (user . stringp) + (egid . numberp) (group . stringp) (comm . 40) (state . stringp))} +@end group +@end smallexample + +@vindex tramp-adb-connection-local-default-ps-profile +@vindex tramp-adb-connection-local-default-ps-variables +@vindex tramp-connection-local-bsd-ps-profile +@vindex tramp-connection-local-bsd-ps-variables +@vindex tramp-connection-local-busybox-ps-profile +@vindex tramp-connection-local-busybox-ps-variables +@vindex tramp-connection-local-darwin-ps-profile +@vindex tramp-connection-local-darwin-ps-variables +The default values for @code{tramp-process-attributes-ps-args} and +@code{tramp-process-attributes-ps-format} can be overwritten by +connection-local variables. +@ifinfo +@xref{Connection Variables, , , emacs}. +@end ifinfo +This is already done by @value{tramp} for the @option{adb} method, see +@code{tramp-adb-connection-local-default-ps-profile} and +@code{tramp-adb-connection-local-default-ps-variables}. + +There are three further predefined sets of connection-local variables +for remote BSD systems, for remote macOS systems, and for a remote +@command{ps} command implemented with @command{busybox}. These are +called @code{tramp-connection-local-*-ps-profile} and +@code{tramp-connection-local-*-ps-variables}. Use them like + +@lisp +@group +(connection-local-set-profiles + '(:application tramp :machine "mybsdhost") + 'tramp-connection-local-bsd-ps-profile) +@end group +@end lisp + +@cindex proced +@vindex proced-show-remote-processes +If you want to see a listing of remote system processes when calling +@code{proced}, set user option @code{proced-show-remote-processes} to +non-@code{nil}, or invoke that command with a negative argument like +@kbd{C-u - M-x proced @key{RET}} when your buffer has a remote +@code{default-directory}. + + @anchor{Improving performance of asynchronous remote processes} @subsection Improving performance of asynchronous remote processes @cindex Asynchronous remote processes @@ -3811,8 +4214,8 @@ Furthermore, this approach has the following limitations: @itemize @item -It works only for connection methods defined in @file{tramp-sh.el} and -@file{tramp-adb.el}. +It works only for connection methods defined in @file{tramp-adb.el}, +@file{tramp-sh.el} and @file{tramp-sshfs.el}. @item It does not support interactive user authentication. With @@ -3978,7 +4381,9 @@ would trigger renaming of buffer file names on @samp{badhost} to @samp{goodhost}, including changing the directory name. @lisp -("@trampfn{ssh,.+\\\\.company\\\\.org,}" . "@value{prefix}ssh@value{postfixhop}multi.hop|ssh@value{postfixhop}%h@value{postfix}") +("@trampfn{ssh,.+\\\\.company\\\\.org,}" @c +. "@value{prefix}ssh@value{postfixhop}multi.hop|@c +ssh@value{postfixhop}%h@value{postfix}") @end lisp routes all connections to a host in @samp{company.org} via @@ -4068,6 +4473,11 @@ CPIO archives @cindex @file{cpio} file archive suffix @cindex file archive suffix @file{cpio} +@item @samp{.crate} --- +Cargo (Rust) packages +@cindex @file{crate} file archive suffix +@cindex file archive suffix @file{crate} + @item @samp{.deb} --- Debian packages @cindex @file{deb} file archive suffix @@ -4078,6 +4488,11 @@ HP-UX SD depots @cindex @file{depot} file archive suffix @cindex file archive suffix @file{depot} +@item @samp{.epub} --- +Electronic publications +@cindex @file{epub} file archive suffix +@cindex file archive suffix @file{epub} + @item @samp{.exe} --- Self extracting Microsoft Windows EXE files @cindex @file{exe} file archive suffix @@ -4235,7 +4650,8 @@ It is even possible to access file archives in file archives, as (progn (url-handler-mode 1) (find-file - "https://ftp.debian.org/debian/pool/main/c/coreutils/coreutils_8.28-1_amd64.deb/control.tar.gz/control")) + "https://ftp.debian.org/debian/pool/main/c/coreutils/\ +coreutils_8.28-1_amd64.deb/control.tar.gz/control")) @end group @end lisp @@ -4368,8 +4784,8 @@ Where is the latest @value{tramp}? @item Which systems does it work on? -The package works successfully on @w{Emacs 25}, @w{Emacs 26}, @w{Emacs -27}, and @w{Emacs 28}. +The package works successfully on @w{Emacs 26}, @w{Emacs 27}, @w{Emacs +28}, and @w{Emacs 29}. While Unix and Unix-like systems are the primary remote targets, @value{tramp} has equal success connecting to other platforms, such as @@ -4556,97 +4972,6 @@ In order to disable those optimizations, set user option @item -@value{tramp} does not recognize if a @command{ssh} session hangs - -@vindex ServerAliveInterval@r{, ssh option} -@command{ssh} sessions on the local host hang when the network is -down. @value{tramp} cannot safely detect such hangs. The network -configuration for @command{ssh} can be configured to kill such hangs -with the following command in the @file{~/.ssh/config}: - -@example -@group -Host * - ServerAliveInterval 5 -@end group -@end example - - -@item -@value{tramp} does not use default @command{ssh} @option{ControlPath} - -@vindex ControlPath@r{, ssh option} -@vindex ControlPersist@r{, ssh option} -@value{tramp} overwrites @option{ControlPath} settings when initiating -@command{ssh} sessions. @value{tramp} does this to fend off a stall -if a master session opened outside the Emacs session is no longer -open. That is why @value{tramp} prompts for the password again even -if there is an @command{ssh} already open. - -@vindex tramp-ssh-controlmaster-options -Some @command{ssh} versions support a @option{ControlPersist} option, -which allows you to set the @option{ControlPath} provided the variable -@code{tramp-ssh-controlmaster-options} is customized as follows: - -@lisp -@group -(customize-set-variable - 'tramp-ssh-controlmaster-options - (concat - "-o ControlPath=/tmp/ssh-ControlPath-%%r@@%%h:%%p " - "-o ControlMaster=auto -o ControlPersist=yes")) -@end group -@end lisp - -Note how @samp{%r}, @samp{%h} and @samp{%p} must be encoded as -@samp{%%r}, @samp{%%h} and @samp{%%p}. - -@vindex tramp-use-ssh-controlmaster-options -If the @file{~/.ssh/config} file is configured appropriately for the -above behavior, then any changes to @command{ssh} can be suppressed -with this @code{nil} setting: - -@lisp -(customize-set-variable 'tramp-use-ssh-controlmaster-options nil) -@end lisp - -@vindex ProxyCommand@r{, ssh option} -@vindex ProxyJump@r{, ssh option} -This should also be set to @code{nil} if you use the -@option{ProxyCommand} or @option{ProxyJump} options in your -@command{ssh} configuration. - -On MS Windows, @code{tramp-use-ssh-controlmaster-options} is set to -@code{nil} by default, because the MS Windows and MSYS2 -implementations of @command{OpenSSH} do not support this option properly. - - -@item -On multi-hop connections, @value{tramp} does not use @command{ssh} -@option{ControlMaster} - -In order to use the @option{ControlMaster} option, @value{tramp} must -check whether the @command{ssh} client supports this option. This is -only possible on the local host, for the first hop. @value{tramp} -does not use this option on proxy hosts. - -If you want to use this option also for the other hops, you must -configure @file{~/.ssh/config} on the proxy host: - -@example -@group -Host * - ControlMaster auto - ControlPath tramp.%C - ControlPersist no -@end group -@end example - -Check the @samp{ssh_config(5)} man page whether these options are -supported on your proxy host. - - -@item Does @value{tramp} support @acronym{SSH} security keys? Yes. @command{OpenSSH} has added support for @acronym{FIDO} hardware @@ -4839,6 +5164,26 @@ be restored by moving them manually from @item +How to identify temporary files produced by @value{tramp}? + +@vindex tramp-temp-name-prefix +Temporary files are kept in your @code{temporary-file-directory} +directory, which is often @file{/tmp/}. By default, they have the +file name prefix @t{"tramp."}. If you want to change this prefix, for +example because you want to identify temporary files produced by +@code{file-local-copy} in your package, you can bind the variable +@code{tramp-temp-name-prefix} temporarily: + +@example +@group +(let ((tramp-temp-name-prefix "my-prefix.")) + (file-local-copy "@trampfn{ssh,,.emacs}")) +@result{} "/tmp/my-prefix.HDfgDZ" +@end group +@end example + + +@item How to shorten long file names when typing in @value{tramp}? Adapt several of these approaches to reduce typing. If the full name @@ -5086,7 +5431,8 @@ Why saved multi-hop file names do not work in a new Emacs session? When saving ad-hoc multi-hop @value{tramp} file names (@pxref{Ad-hoc multi-hops}) via bookmarks, recent files, filecache, bbdb, or another package, use the full ad-hoc file name including all hops, like -@file{@trampfn{ssh,bird@@bastion|ssh@value{postfixhop}news.my.domain,/opt/news/etc}}. +@file{@trampfn{ssh,bird@@bastion|ssh@value{postfixhop}@c +news.my.domain,/opt/news/etc}}. Alternatively, when saving abbreviated multi-hop file names @file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, the user @@ -5239,6 +5585,28 @@ time being you can suppress this error by the following code in your @item +I get an error @samp{Remote file error: Not a valid Tramp file name +function `tramp-FOO-file-name-p'} + +@value{tramp} has changed the signature of an internal function. +External packages implementing an own @value{tramp} backend must +follow this change. Please report this problem to the author of that +package. + +For the running session, @value{tramp} disables the external package, +and you can continue to work. If you don't want to see this error +while activating @value{tramp}, you can suppress it by the same code +as above in your @file{~/.emacs}: + +@lisp +@group +(setq debug-ignored-errors + (cons 'remote-file-error debug-ignored-errors)) +@end group +@end lisp + + +@item How to disable other packages from calling @value{tramp}? There are packages that call @value{tramp} without the user ever @@ -5256,6 +5624,7 @@ Disable @value{tramp} file name completion: (customize-set-variable 'ido-enable-tramp-completion nil) @end lisp +@c Obsolete since Emacs 29.1. @item @file{rlogin.el} @@ -5314,10 +5683,19 @@ local host's root directory as @file{/ssh:example.com:}. To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp @key{RET}}. Unloading @value{tramp} resets Ange FTP plugins also. @end itemize + + +@item +What is the difference between Ange FTP and @value{tramp}? + +The difference is that Ange FTP uses @command{ftp} to transfer files +between the local and the remote host, whereas @value{tramp} uses a +combination of @command{ssh} and @command{scp} or other work-alike +programs. @end itemize -@c For the developer +@c For the developer. @node Files directories and localnames @chapter How file names, directories and localnames are mangled and managed @@ -5373,7 +5751,7 @@ bind it to non-@code{nil} value. Keeping a local cache of remote file attributes in sync with the remote host is a time-consuming operation. Flushing and re-querying these attributes can tax @value{tramp} to a grinding halt on busy -remote servers. +remote hosts. To get around these types of slow-downs in @value{tramp}'s responsiveness, set the @code{process-file-side-effects} to @code{nil} @@ -5528,6 +5906,8 @@ function call traces are written to the buffer @file{*trace-output*}. @c @c * Say something about the .login and .profile files of the remote @c shells. +@c @c * Explain how tramp.el works in principle: open a shell on a remote @c host and then send commands to it. +@c @c * Consistent small or capitalized words especially in menus. diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index 8352fed1b70..9e1be52cd38 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -8,10 +8,10 @@ @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.3.28.2 +@set trampver 2.6.0-pre @set trampurl https://www.gnu.org/software/tramp/ @set tramp-bug-report-address tramp-devel@@gnu.org -@set emacsver 25.1 +@set emacsver 26.1 @c Other flags from configuration. @set instprefix /usr/local diff --git a/doc/misc/vhdl-mode.texi b/doc/misc/vhdl-mode.texi index 75e8747412a..7d451c71bd4 100644 --- a/doc/misc/vhdl-mode.texi +++ b/doc/misc/vhdl-mode.texi @@ -243,7 +243,7 @@ components. Also notice that the first component, @vindex vhdl-offsets-alist @vindex offsets-alist @r{(vhdl-)} Indentation for the current line is calculated using the syntactic -component list derived in step 1 above (see @ref{Syntactic +component list derived in step 1 above (@pxref{Syntactic Analysis}). Each component contributes to the final total indentation of the line in two ways. @@ -668,7 +668,7 @@ not handled by the mode directly. @cindex custom indentation functions One of the most common ways to customize VHDL Mode is by writing @dfn{custom indentation functions} and associating them with specific -syntactic symbols (see @ref{Syntactic Symbols}). VHDL Mode itself +syntactic symbols (@pxref{Syntactic Symbols}). VHDL Mode itself uses custom indentation functions to provide more sophisticated indentation, for example when lining up selected signal assignments: @example @@ -732,7 +732,7 @@ operator on the first line of the statement. Here is the lisp code @end example @noindent Custom indent functions take a single argument, which is a syntactic -component cons cell (see @ref{Syntactic Analysis}). The +component cons cell (@pxref{Syntactic Analysis}). The function returns an integer offset value that will be added to the running total indentation for the line. Note that what actually gets returned is the difference between the column that the signal assignment @@ -928,7 +928,7 @@ If you want to customize indentation, here you go: (setq tab-width 8 ;; this will make sure spaces are used instead of tabs indent-tabs-mode nil) - ;; keybindings for VHDL are put in vhdl-mode-map + ;; key bindings for VHDL are put in vhdl-mode-map (define-key vhdl-mode-map "\C-m" 'newline-and-indent) ) diff --git a/doc/misc/vtable.texi b/doc/misc/vtable.texi new file mode 100644 index 00000000000..296dc520a1b --- /dev/null +++ b/doc/misc/vtable.texi @@ -0,0 +1,577 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ../../info/vtable.info +@settitle Variable Pitch Tables +@include docstyle.texi +@c Merge all indexes into a single Index node. +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp +@c %**end of header + +@copying +This file documents the GNU vtable.el package. + +Copyright @copyright{} 2022 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' +@end quotation +@end copying + +@dircategory Emacs misc features +@direntry +* vtable: (vtable). Variable Pitch Tables. +@end direntry + +@finalout + +@titlepage +@title Variable Pitch Tables +@subtitle Columnar Display of Data. + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top vtable + +@insertcopying +@end ifnottex + +@menu +* Introduction:: Introduction and examples. +* Concepts:: vtable concepts. +* Making A Table:: The main interface function. +* Commands:: vtable commands. +* Interface Functions:: Interface functions. + +Appendices +* GNU Free Documentation License:: The license for this documentation. + +Indices +* Index:: +@end menu + +@node Introduction +@chapter Introduction and Tutorial + +Most modes that display tabular data in Emacs use +@code{tabulated-list-mode}, but it has some limitations: It assumes +that the text it's displaying is monospaced, which makes it difficult +to mix fonts and images in a single list. The @dfn{vtable} (``variable +pitch tables'') package tackles this instead. + +@code{tabulated-list-mode} is a major mode, and assumes that it +controls the entire buffer. A vtable doesn't assume that---you can have +a vtable in the middle of other data, or have several vtables in the +same buffer. + +Here's just about the simplest vtable that can be created: + +@lisp +(make-vtable + :objects '(("Foo" 1034) + ("Gazonk" 45))) +@end lisp + +By default, vtable uses the @code{vtable} face (which inherits from +the @code{variable-pitch} face), and right-aligns columns that have +only numerical data (and left-aligns the rest). + +You'd normally want to name the columns: + +@lisp +(make-vtable + :columns '("Name" "ID") + :objects '(("Foo" 1034) + ("Gazonk" 45))) +@end lisp + +Clicking on the column names will sort the table based on the data in +each column (which, in this example, corresponds to an element in a +list). + +By default, the data is displayed ``as is'', that is, the way +@samp{(format "%s" ...)} would display it, but you can override that. + +@lisp +(make-vtable + :columns '("Name" "ID") + :objects '(("Foo" 1034) + ("Gazonk" 45)) + :formatter (lambda (value column &rest _) + (if (= column 1) + (file-size-human-readable value) + value))) +@end lisp + +In this case, that @samp{1034} will be displayed as @samp{1k}---but +will still sort after @samp{45}, because sorting is done on the actual +data, and not the displayed data. + +Alternatively, instead of having a general formatter for the table, +you can put the formatter in the column definition: + +@lisp +(make-vtable + :columns '("Name" + (:name "ID" :formatter file-size-human-readable)) + :objects '(("Foo" 1034) + ("Gazonk" 45))) +@end lisp + +The data doesn't have to be simple lists---you can give any type of +object to vtable, but then you also have to write a function that +returns the data for each column. For instance, here's a very simple +version of @kbd{M-x list-buffers}: + +@lisp +(make-vtable + :columns '("Name" "Size" "File") + :objects (buffer-list) + :actions '("k" kill-buffer + "RET" display-buffer) + :getter (lambda (object column vtable) + (pcase (vtable-column vtable column) + ("Name" (buffer-name object)) + ("Size" (buffer-size object)) + ("File" (or (buffer-file-name object) ""))))) +@end lisp + +@var{objects} in this case is a list of buffers. To get the data to +be displayed, vtable calls the @dfn{getter} function, which is called +for each column of every object, and which should return the data that +will eventually be displayed. + +Also note the @dfn{actions}: These are simple commands that will be +called with the object under point. So hitting @kbd{@key{RET}} on a line +will result in @code{display-buffer} being called with a buffer object +as the parameter. (You can also supply a keymap to be used, but then +you have to write commands that call @code{vtable-current-object} to +get at the object.) + +Note that the actions aren't called with the data displayed in the +buffer---they're called with the original objects. + +Finally, here's an example that uses just about all the features: + +@lisp +(make-vtable + :columns `(( :name "Thumb" :width "500px" + :displayer + ,(lambda (value max-width table) + (propertize "*" 'display + (create-image value nil nil + :max-width max-width)))) + (:name "Size" :width 10 + :formatter file-size-human-readable) + (:name "Time" :width 10 :primary ascend) + "Name") + :objects-function (lambda () + (directory-files "/tmp/" t "\\.jpg\\'")) + :actions '("RET" find-file) + :getter (lambda (object column table) + (pcase (vtable-column table column) + ("Name" (file-name-nondirectory object)) + ("Thumb" object) + ("Size" (file-attribute-size (file-attributes object))) + ("Time" (format-time-string + "%F" (file-attribute-modification-time + (file-attributes object)))))) + :separator-width 5 + :keymap (define-keymap + "q" #'kill-buffer)) +@end lisp + +This vtable implements a simple image browser that displays image +thumbnails (that change sizes dynamically depending on the width of +the column), human-readable file sizes, date and file name. The +separator width is 5 typical characters wide. Hitting @kbd{@key{RET}} on a +line will open the image in a new window, and hitting @kbd{q} will +kill a buffer. + +@node Concepts +@chapter Concepts + +@cindex vtable +A vtable lists data about a number of @dfn{objects}. Each object can +be a list or a vector, but it can also be anything else. + +@cindex getter of a vtable +To get the @dfn{value} for a particular column, the @dfn{getter} +function is called on the object. If no getter function is defined, +the default is to try to index the object as a sequence. In any case, +we end up with a value that is then used for sorting. + +@cindex formatter of a vtable +This value is then @dfn{formatted} via a @dfn{formatter} function, +which is called with the @dfn{value} as the argument. The formatter +commonly makes the value more reader friendly. + +@cindex displayer of a vtable +Finally, the formatted value is passed to the @dfn{displayer} +function, which is responsible for putting the table face on the +formatted value, and also ensuring that it's not wider than the column +width. The displayer will commonly truncate too-long strings and +scale image sizes. + +All these three transforms, the getter, the formatter and the display +functions, can be defined on a per-column basis, and also on a +per-table basis. (The per-column transform takes precedence over the +per-table transform.) + +User commands that are defined on a table does not work on the +displayed data. Instead they are called with the original object as +the argument. + +@node Making A Table +@chapter Making A Table + +@findex make-vtable +The interface function for making (and optionally inserting a table +into a buffer) is @code{make-vtable}. It returns a table object. + +The keyword parameters are described below. + +There are many callback interface functions possible in +@code{make-vtable}, and many of them take a @var{object} argument (an +object from the @code{:objects} list), a column index argument (an +integer starting at zero), and a table argument (the object returned +by @code{make-vtable}). + +@table @code +@item :objects +This is a list of objects to be displayed. It should either be a list +of strings (which will then be displayed as a single-column table), or +a list where each element is a sequence containing a mixture of +strings, numbers, and other objects that can be displayed ``simply''. + +In the latter case, if @code{:columns} is non-@code{nil} and there's +more elements in the sequence than there is in @code{:columns}, only +the @code{:columns} first elements are displayed. + +@item :objects-function +It's often convenient to generate the objects dynamically (for +instance, to make reversion work automatically). In that case, this +should be a function (which will be called with no arguments), and +should return a value as accepted as an @code{:objects} list. + +@item :columns +This is a list where each element is either a string (the column +name), a plist of keyword/values (to make a @code{vtable-column} +object), or a full @code{vtable-column} object. A +@code{vtable-column} object has the following slots: + +@table @code +@item name +The name of the column. + +@item width +The width of the column. This is either a number (the width of that +many @samp{x} characters in the table's face), or a string on the form +@samp{Xe@var{x}}, where @var{x} is a number of @samp{x} characters, or a +string on the form @samp{Xp@var{x}} (denoting a number of pixels), or a +string on the form @samp{X%} (a percentage of the window's width). + +@item min-width +This uses the same format as @code{width}, but specifies the minimum +width (and overrides @code{width} if @code{width} is smaller than this. + +@item max-width +This uses the same format as @code{width}, but specifies the maximum +width (and overrides @code{width} if @code{width} is larger than this. +@code{min-width}/@code{max-width} can be useful if @code{width} is +given as a percentage of the window width, and you want to ensure that +the column doesn't grow pointlessly large or unreadably narrow. + +@item primary +Whether this is the primary column---this will be used for initial +sorting. This should be either @code{ascend} or @code{descend} to say +in which order the table should be sorted. + +@item getter +If present, this function will be called to return the column value. + +@defun column-getter object table +It's called with two parameters: the object and the table. +@end defun + +@item formatter +If present, this function will be called to format the value. + +@defun column-formatter value +It's called with one parameter: the column value. +@end defun + +@item displayer +If present, this function will be called to prepare the formatted +value for display. This function should return a string with the +table face applied, and also limit the width of the string to the +display width. + +@defun column-displayer fvalue max-width table +@var{fvalue} is the formatted value; @var{max-width} is the maximum +width (in pixels), and @var{table} is the table. +@end defun + +@item align +Should be either @code{right} or @code{left}. +@end table + +@item :getter +If given, this is a function that should return the values to use in +the table, and will be called once for each element in the table +(unless overridden by a column getter function). + +@defun getter object index table +For a simple object (like a sequence), this function will typically +just return the element corresponding to the column index (zero-based), but the +function can do any computation it wants. If it's more convenient to +write the function based on column names rather than the column index, +the @code{vtable-column} function can be used to map from index to name. +@end defun + +@item :formatter +If present, this is a function that should format the value, and it +will be called on all values in the table (unless overridden by a +column formatter). + +@defun formatter value index table +This function is called with three parameters: the value (as returned +by the getter); the column index, and the table. It can return any +value. + +This can be used to (for instance) format numbers in a human-readable +form. +@end defun + +@item :displayer +Before displaying an element, it's passed to the displaying function +(if any). + +@defun displayer fvalue index max-width table +This is called with four arguments: the formatted value of the element +(as returned by the formatter function); the column index; the display +width (in pixels); and the table. + +This function should return a string with the table face applied, and +truncated to the display width. + +This can be used to (for instance) change the size of images that are +displayed in the table. +@end defun + +@item :use-header-line +If non-@code{nil} (which is the default), display the column names on +the header line. This is the most common use +case, but if there's other text in the buffer before the table, or +there are several tables in the same buffer, then this should be +@code{nil}. + +@item :face +The face to be used. This defaults to @code{vtable}. This face +doesn't override the faces in the data, or the faces supplied by the +getter and formatter functions. + +@item :row-colors +If present, this should be a list of color names to be used as the +background color on the rows. If there are fewer colors here than +there are rows, the rows will be repeated. The most common use +case here is to have alternating background colors on the rows, so +this would usually be a list of two colors. This can also be a list +of faces to be used. + +@item :column-colors +If present, this should be a list of color names to be used as the +background color on the columns. If there are fewer colors here than +there are columns, the colors will be repeated. The most common use +case here is to have alternating background colors on the columns, so +this would usually be a list of two colors. This can also be a list +of faces to be used. If both @code{:row-colors} and +@code{:column-colors} is present, the colors will be ``blended'' to +produce the final colors in the table. + +@item :actions +This uses the same syntax as @code{define-keymap}, but doesn't refer +to commands directly. Instead each key is bound to a command that +picks out the current object, and then calls the function specified +with that as the argument. + +@item :keymap +This is a keymap used on the table. The commands here are called as +usual, and if they're supposed to work on the object displayed on the +current line, they can use the @code{vtable-current-object} function +(@pxref{Interface Functions}) to determine what that object is. + +@item :separator-width +The width of the blank space between columns. + +@item :divider-width +@itemx :divider +You can have a divider inserted between the columns. This can either +be specified by using @code{:divider}, which should be a string to be +displayed between the columns, or @code{:divider-width}, which +specifies the width of the space to be used as the divider. + +@item :sort-by +This should be a list of tuples, and specifies how the table is to be +sorted. Each tuple should consist of an integer (the column index) +and either @code{ascend} or @code{descend}. + +The table is first sorted by the first element in this list, and then +the next, until the end is reached. + +@item :ellipsis +By default, when shortening displayed values, an ellipsis will be +shown. If this is @code{nil}, no ellipsis is shown. (The text to use +as the ellipsis is determined by the @code{truncate-string-ellipsis} +function.) + +@findex vtable-insert +@item :insert +By default, @code{make-vtable} will insert the table at point. If this +is @code{nil}, nothing is inserted, but the vtable object is returned, +and you can insert it later with the @code{vtable-insert} function. +@end table + +@code{make-table} returns a @code{vtable} object. You can access the +slots in that object by using accessor functions that have names based +on the keywords described above. For instance, to access the face, +use @code{vtable-face}. + +@node Commands +@chapter Commands +@cindex vtable commands + +When point is placed on a vtable, the following keys are bound: + +@table @kbd +@findex vtable-sort-by-current-column +@item S +Sort the table by the current column +(@code{vtable-sort-by-current-column}). Note that the table is sorted +according to the data returned by the getter function (@pxref{Making A +Table}), not by how it's +displayed in the buffer. Columns that have only numerical data is +sorted as numbers, the rest are sorted as strings. + +@findex vtable-narrow-current-column +@item @{ +Make the current column narrower +(@code{vtable-narrow-current-column}). + +@findex vtable-widen-current-column +@item @} +Make the current column wider +(@code{vtable-widen-current-column}). + +@findex vtable-previous-column +@item M-<left> +Move to the previous column (@code{vtable-previous-column}). + +@findex vtable-next-column +@item M-<right> +Move to the next column (@code{vtable-next-column}). + +@findex vtable-revert-command +@item g +Regenerate the table (@code{vtable-revert-command}). This command +mostly makes sense if the table has a @code{:objects-function} that +can fetch new data. +@end table + +@node Interface Functions +@chapter Interface Functions + +If you need to write a mode based on vtable, you will have to interact +with the table in +various ways---for instance, you'll need to write commands that +updates an object +and then displays the result. This chapter describes functions for +such interaction. + +@defun vtable-current-table +This function returns the table under point. +@end defun + +@defun vtable-current-object +This function returns the object on the current line. (Note that this +is the original object, not the characters displayed in the +buffer.) +@end defun + +@defun vtable-current-column +This function returns the column index of the column under point. +@end defun + +@defun vtable-goto-table table +Move point to the start of @var{table} and return the position. If +@var{table} can't be found in the current buffer, don't move point and +return @code{nil}. +@end defun + +@defun vtable-goto-object object +Move point to the start of the line where @var{object} is displayed in +the current table and return the position. If @var{object} can't be found, +don't move point and return @code{nil}. +@end defun + +@defun vtable-goto-column index +Move point to the start of the @var{index}th column. (The first +column is numbered zero.) +@end defun + +@defun vtable-beginning-of-table +Move to the beginning of the current table. +@end defun + +@defun vtable-end-of-table +Move to the end of the current table. +@end defun + +@defun vtable-remove-object table object +Remove @var{object} from @var{table}. This also updates the displayed +table. +@end defun + +@defun vtable-insert-object table object &optional after-object +Insert @var{object} into @var{table}. If @var{after-object}, insert +the object after this object; otherwise append to @var{table}. This +also updates the displayed table. +@end defun + +@defun vtable-update-object table object old-object +Change @var{old-object} into @var{object} in @var{table}. This also +updates the displayed table. + +This has the same effect as calling @code{vtable-remove-object} and +then @code{vtable-insert-object}, but is more efficient. +@end defun + +@defun vtable-column table index +Return the column name of the @var{index}th column in @var{table}. +@end defun + +@node GNU Free Documentation License +@chapter GNU Free Documentation License +@include doclicense.texi + +@node Index +@unnumbered Index +@printindex cp + +@bye |