diff options
Diffstat (limited to 'doc/misc')
33 files changed, 1352 insertions, 547 deletions
diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index fab4edcc32b..6c1e9cbc910 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -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 diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index e4254faabb9..b28ae247ea9 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -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") diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 9da18cd9201..8b36d1afd7a 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:: diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 9bace48df4f..a6fe29e1026 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -1245,6 +1245,12 @@ blocks for other macros like @code{cl-incf}, and @code{cl-pushnew}. The @code{cl-letf} and @code{cl-letf*} macros are used in the processing of symbol macros; @pxref{Macro Bindings}. +@defmac with-memoization @var{place} @var{code}@dots{} +This macro provides a simple way to do memoization. @var{code} is +evaluated and then stashed in @var{place}. If @var{place}'s value is +non-@code{nil}, return that value instead of evaluating @var{code}. +@end defmac + @node Variable Bindings @section Variable Bindings @@ -5028,7 +5034,7 @@ The above @code{incf} example could be written using @ignore (defmacro concatf (place &rest args) (gv-letplace (getter setter) place - (macroexp-let2 nil v (mapconcat 'identity args "") + (macroexp-let2 nil v (mapconcat 'identity args) (funcall setter `(concat ,getter ,v))))) @end ignore @end defmac diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index 518b30fea89..af8e2153dd8 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. diff --git a/doc/misc/efaq-w32.texi b/doc/misc/efaq-w32.texi index 20dcb07ed76..8dcdb121abe 100644 --- a/doc/misc/efaq-w32.texi +++ b/doc/misc/efaq-w32.texi @@ -687,9 +687,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 @@ -697,7 +697,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 c1fd002bcb5..ed8a919ac7e 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -151,7 +151,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 @@ -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}). 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..b9297738ea2 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. diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index aeae6aef8c7..0d01efb0355 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" @@ -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,21 @@ 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, 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 +524,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 +808,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 +1124,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 +1199,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 4f1d8c15da3..83d324c7e1b 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -271,8 +271,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 +304,137 @@ 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 stack. Each line is +numbered. + +@item +With @kbd{cd =foo}, Eshell searches the directory stack 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. If @code{eshell-plain-echo-behavior} is +non-@code{nil}, @command{echo} will try to behave more like a plain +shell's @command{echo}. + +@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 +446,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 +493,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,6 +648,50 @@ 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 Built-in variables diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index 248bd63e87f..6d1ba3962f3 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 @@ -312,7 +313,9 @@ can set the maximal image proportion in relation to the window they are displayed in. E.g., 0.7 means an image is allowed to take up 70% of the width and height. If Emacs supports image scaling (ImageMagick support required) then larger images are scaled down. You can block -specific images completely by customizing @code{shr-blocked-images}. +specific images completely by customizing @code{shr-blocked-images}, +or, if you want to only allow some specific images, customize +@code{shr-allowed-images}. @vindex shr-inhibit-images You can control image display by customizing @@ -380,6 +383,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..0db02608dd2 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 @@ -1145,7 +1145,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.texi b/doc/misc/gnus.texi index 479e7d94824..61870311ed8 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 @@ -12237,6 +12245,7 @@ possible but those listed are probably sufficient for most people. @item gnus-treat-capitalize-sentences (t, integer) @item gnus-treat-overstrike (t, integer) @item gnus-treat-strip-cr (t, integer) +@item gnus-treat-emojize-symbols (t, integer) @item gnus-treat-strip-headers-in-body (t, integer) @item gnus-treat-strip-leading-blank-lines (t, first, integer) @item gnus-treat-strip-multiple-blank-lines (t, integer) @@ -13468,7 +13477,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. @@ -15438,10 +15447,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 @@ -18043,7 +18048,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))) @@ -28881,7 +28886,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/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 2c49cbdd72b..35bc8853fd3 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.0.0 +#+macro: release-date 2021-12-24 +#+macro: development-version 2.1.0-dev #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ #+macro: space @@texinfo:@: @@ #+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ @@ -82,9 +82,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 +108,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 +121,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 @@ -268,7 +281,7 @@ could look like: (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,15 +292,16 @@ 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: @@ -309,6 +323,25 @@ 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 +(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 +358,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. @@ -352,7 +385,7 @@ 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: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 +405,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 +414,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-markup t + 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 +427,13 @@ 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', and a natural number for extra padding + modus-themes-mode-line '(4 accented borderless) ;; Options for `modus-themes-syntax' are either nil (the default), ;; or a list of properties that may include any of those symbols: @@ -434,32 +470,22 @@ this manual. ;; `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 +496,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 +512,43 @@ currently active Modus theme. Enable this behaviour 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. +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. -With a non-nil value (~t~), use variants of blue instead of green. This -is meant to empower users with red-green color deficiency. +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. -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. - -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 +558,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 +588,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 +616,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,36 +672,41 @@ 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 + +Brief: Toggle the use of monospaced fonts for spacing-sensitive +constructs (affects font families). -Symbol: ~modus-themes-no-mixed-fonts~ +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 behaviour, 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 @@ -667,7 +715,9 @@ are ~org-variable-pitch~ and ~mixed-pitch~. :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: @@ -738,7 +788,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 +847,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 +859,44 @@ effect, color, and border visibility: - ~moody~ + ~accented~ + ~borderless~ -+ ~padded~ ++ A natural number > 1 for extra padding 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. -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) @@ -874,8 +931,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 +946,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: @@ -906,7 +969,9 @@ Centaur tabs package. :end: #+vindex: modus-themes-completions -Symbol: ~modus-themes-completions~ +Brief: Set the overall style of completion framework interfaces. + +Symbol: ~modus-themes-completions~ (=choice= type) Possible values: @@ -921,7 +986,7 @@ 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. +covers Helm and Ivy. A value of ~nil~ (the default) will simply respect the metaphors of each completion framework. @@ -951,7 +1016,10 @@ 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: @@ -980,7 +1048,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 +1074,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 +1085,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 +1103,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 +1131,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 +1143,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 +1197,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 +1220,30 @@ 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 intense markup in Org and others +:properties: +:alt_title: Intense markup +:description: Toggle intense style for markup in Org and others +:custom_id: h:9d9a4e64-99ac-4018-8f66-3051b9c43fd7 +:end: +#+vindex: modus-themes-intense-markup + +Brief: Toggle intense style for inline code and related markup. + +Symbol: ~modus-themes-intense-markup~ (=boolean= type) + +Possible value: + +1. ~nil~ (default) +2. ~t~ + +The default style for certain markup types like inline code and verbatim +constructs in Org and related major modes is a subtle foreground color +combined with a subtle background. + +With a non-nil value (~t~), these constructs will use a more prominent +background and foreground color combination instead. + ** Option for parenthesis matching :properties: :alt_title: Matching parentheses @@ -1145,7 +1252,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 +1302,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 +1345,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 +1370,22 @@ 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]]. ** Option for org-mode block styles :properties: @@ -1284,7 +1395,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: @@ -1325,7 +1438,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 +1449,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 +1464,31 @@ 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. +- 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 to 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). +- The symbol of a weight attribute adjusts the font of the heading + accordingly, such as ~light~, ~semibold~, etc. Valid symbols are defined + in the internal variable ~modus-themes--heading-weights~. The absence + of a weight means that bold will be used by virtue of inheriting the + ~bold~ face. -In case both ~scale-title~ and ~no-scale~ are in the list, the latter takes -precedence. +[[#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 @@ -1376,12 +1503,12 @@ the following properties: 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). For example: @@ -1394,28 +1521,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: - -- ~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. +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: + +- ~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 +1594,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 habit graph uses a + three-color style like the aforementioned ~traffic-light~ variant, + except that shades of blue are applied instead of green. This is + suitable for users with red-green color deficiency (deuteranopia). + +[[#h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe][Option for red-green color deficiency or deuteranopia]]. For example: @@ -1475,17 +1612,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 +1635,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 +1648,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 +1659,22 @@ 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 By default (a ~nil~ value for this variable), all headings have a bold typographic weight and use a desaturated text color. @@ -1531,20 +1686,34 @@ 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 ~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 ~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 internal variable ~modus-themes--heading-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 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. 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) #+end_src The order in which the properties are set is not significant. @@ -1553,9 +1722,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 +1739,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 +1748,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 +1756,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 +1778,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 @@ -2460,17 +2515,16 @@ inspiration from the ~modus-themes-toggle~ we already provide: :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 +2545,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 +2565,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 +2607,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 +2635,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,6 +2668,8 @@ themes). (add-hook 'modus-themes-after-load-theme-hook #'my-modes-themes-bold-italic-faces) #+end_src +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + ** Custom Org user faces :properties: :custom_id: h:89f0678d-c5c3-4a57-a526-668b2bb2d7ad @@ -2897,6 +2962,101 @@ 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~. +** 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 + ** A theme-agnostic hook for theme loading :properties: :custom_id: h:86f6906b-f090-46cc-9816-1fe8aeb38776 @@ -2946,6 +3106,61 @@ 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. + * Face coverage :properties: :custom_id: h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19 @@ -2969,14 +3184,12 @@ 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 + annotate + ansi-color + anzu + apropos -+ apt-sources-list + artbollocks-mode + auctex and TeX + auto-dim-other-buffers @@ -2989,7 +3202,6 @@ 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 + centaur-tabs @@ -3007,7 +3219,6 @@ have lots of extensions, so the "full support" may not be 100% true… + corfu + counsel* + counsel-css -+ counsel-org-capture-string + cov + cperl-mode + css-mode @@ -3019,7 +3230,6 @@ have lots of extensions, so the "full support" may not be 100% true… + dashboard (emacs-dashboard) + deadgrep + debbugs -+ define-word + deft + dictionary + diff-hl @@ -3032,15 +3242,12 @@ 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 + eglot @@ -3076,7 +3283,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 +3294,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 +3304,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 +3327,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) @@ -3152,7 +3350,6 @@ have lots of extensions, so the "full support" may not be 100% true… + markup-faces (~adoc-mode~) + mentor + messages -+ minibuffer-line + minimap + mmm-mode + mode-line @@ -3160,14 +3357,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 +3382,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 @@ -3206,7 +3398,6 @@ have lots of extensions, so the "full support" may not be 100% true… + quick-peek + racket-mode + rainbow-blocks -+ rainbow-identifiers + rainbow-delimiters + rcirc + recursion-indicator @@ -3215,7 +3406,6 @@ have lots of extensions, so the "full support" may not be 100% true… + ripgrep + rmail + ruler-mode -+ sallet + selectrum + selectrum-prescient + semantic @@ -3233,13 +3423,10 @@ have lots of extensions, so the "full support" may not be 100% true… + solaire + spaceline + speedbar -+ spell-fu -+ spray + stripes + suggest + switch-window + swiper -+ swoop + sx + symbol-overlay + syslog-mode @@ -3261,12 +3448,11 @@ 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 + wcheck-mode + web-mode @@ -3298,23 +3484,38 @@ 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 ++ easy-kill + edit-indirect + evil-owl ++ flyspell-correct + fortran-mode ++ git-walktree + goggles ++ highlight-defined ++ highlight-escape-sequences (~hes-mode~) + i3wm-config-mode ++ minibuffer-line ++ no-emoji ++ parrot + perl-mode + php-mode + rjsx-mode + side-hustle ++ spell-fu + swift-mode + tab-bar-echo-area + tide ++ vdiff + vertico-indexed + vertico-mouse -+ vertico-quick * Notes on individual packages :properties: @@ -3775,11 +3976,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 @@ -3992,7 +4193,7 @@ you've customized any faces. :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. @@ -4219,7 +4420,7 @@ The source code of the themes is [[https://gitlab.com/protesilaos/modus-themes/] being. A [[https://github.com/protesilaos/modus-themes/][mirror on Github]] is also on offer. 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: @@ -4323,7 +4524,8 @@ 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, + 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, Markus Beppler, Matthew Stevenson, Mauro Aranda, Nicolas De Jaeghere, Philip Kaludercic, Rudolf Adamkovič, Stephen Gildea, Shreyas Ragavan, Stefan @@ -4336,19 +4538,20 @@ The Modus themes are a collective effort. Every bit of work matters. 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. + Agbobada, Gianluca Recchia, Guilherme Semente, Gustavo Barros, + Hörmetjan Yiltiz, Ilja Kocken, Iris Garcia, Jeremy Friesen, Jerry + Zhang, Johannes Grødem, 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), @@ -4358,9 +4561,10 @@ The Modus themes are a collective effort. Every bit of work matters. + 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 :properties: @@ -4388,9 +4592,9 @@ of this sort): 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> ++ Manual :: <https://protesilaos.com/emacs/modus-themes> ++ Change Log :: <https://protesilaos.com/emacs/modus-themes-changelog> ++ Screenshots :: <https://protesilaos.com/emacs/modus-themes-pictures> * 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/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..f13ecc7d28d 100644 --- a/doc/misc/rcirc.texi +++ b/doc/misc/rcirc.texi @@ -609,12 +609,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 +627,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 client certificate key and +password. The CertFP authentication requires a @acronym{TLS} +connection. + @end table @end table 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/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 0d86b25dc41..2e21a211aad 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,7 +3,7 @@ % 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{2021-11-01.16} % % Copyright 1985--1986, 1988, 1990--2022 Free Software Foundation, Inc. % @@ -3614,6 +3614,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 @@ -7592,6 +7595,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % \def\printdefunline#1#2{% \begingroup + \plainfrenchspacing % call \deffnheader: #1#2 \endheader % common ending: @@ -9402,7 +9406,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \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. @@ -11599,11 +11603,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 ae7031e7988..3c159558600 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -2238,8 +2238,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 @@ -3389,9 +3388,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 @@ -3411,7 +3410,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 @@ -3533,9 +3532,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 @@ -4061,6 +4059,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 @@ -4347,8 +4350,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 @@ -5225,6 +5228,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 diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index ac44c27b0d6..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.2.28.1 +@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) ) |