From: Po Lu Date: Tue, 29 Aug 2023 01:29:20 +0000 (+0800) Subject: Avoid Unicode quotes within transient.texi X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=fb4be1d5ae97694cdfc7fd7570bac7cd3bb8f895;p=emacs.git Avoid Unicode quotes within transient.texi * doc/misc/transient.texi (Top, Introduction) (Aborting and Resuming Transients, Common Suffix Commands) (Enabling and Disabling Suffixes, Modifying Existing Transients) (Defining Transients, Binding Suffix and Infix Commands) (Suffix Specifications, Defining Suffix and Infix Commands) (Transient State, Group Classes, Suffix Value Methods) (Prefix Slots, Comparison With Other Packages, FAQ): Replace Unicode quote characters with grave quotes. --- diff --git a/doc/misc/transient.texi b/doc/misc/transient.texi index 6cf861ed243..e06f7759d1b 100644 --- a/doc/misc/transient.texi +++ b/doc/misc/transient.texi @@ -47,9 +47,9 @@ General Public License for more details. Taking inspiration from prefix keys and prefix arguments, Transient implements a similar abstraction involving a prefix command, infix arguments and suffix commands. We could call this abstraction a -“transient command”, but because it always involves at least two +``transient command'', but because it always involves at least two commands (a prefix and a suffix) we prefer to call it just a -“transient”. +``transient''. When the user calls a transient prefix command, a transient (temporary) keymap is activated, which binds the transient's infix @@ -153,9 +153,9 @@ Related Abstractions and Packages Taking inspiration from prefix keys and prefix arguments, Transient implements a similar abstraction involving a prefix command, infix arguments and suffix commands. We could call this abstraction a -“transient command”, but because it always involves at least two +``transient command'', but because it always involves at least two commands (a prefix and a suffix) we prefer to call it just a -“transient”. +``transient''. @cindex transient prefix command @quotation @@ -163,10 +163,10 @@ Transient keymaps are a feature provided by Emacs. Transients as implemented by this package involve the use of transient keymaps. Emacs provides a feature that it calls @dfn{prefix commands}. When we -talk about “prefix commands” in this manual, then we mean our own kind -of “prefix commands”, unless specified otherwise. To avoid ambiguity +talk about ``prefix commands'' in this manual, then we mean our own kind +of ``prefix commands'', unless specified otherwise. To avoid ambiguity we sometimes use the terms @dfn{transient prefix command} for our kind and -“regular prefix command” for Emacs' kind. +``regular prefix command'' for Emacs' kind. @end quotation @@ -217,7 +217,7 @@ looks a bit like this: @quotation This is a simplified version of @code{magit-tag}. Info manuals do not -support images or colored text, so the above “screenshot” lacks some +support images or colored text, so the above ``screenshot'' lacks some information; in practice you would be able to tell whether the arguments @code{--force} and @code{--annotate} are enabled or not based on their color. @@ -225,7 +225,7 @@ color. @end quotation @cindex command dispatchers -Transient can be used to implement simple “command dispatchers”. The +Transient can be used to implement simple ``command dispatchers''. The main benefit then is that the user can see all the available commands in a popup buffer. That is useful by itself because it frees the user from having to remember all the keys that are valid after a certain @@ -251,9 +251,9 @@ from Lisp. Invoking a transient suffix command with arguments is similar to invoking a command in a shell with command-line completion and history enabled. One benefit of the Transient interface is that it remembers -history not only on a global level (“this command was invoked using +history not only on a global level (``this command was invoked using these arguments, and previously it was invoked using those other -arguments”), but also remembers the values of individual arguments +arguments''), but also remembers the values of individual arguments independently. See @xref{Using History}. After a transient prefix command is invoked, @kbd{C-h @var{KEY}} can be used to @@ -382,7 +382,7 @@ suspended transients, if any. Like @code{transient-quit-all}, this command quits an incomplete key sequence, if any, and all transients. Additionally, it saves the stack of transients so that it can easily be resumed (which is -particularly useful if you quickly need to do “something else” and +particularly useful if you quickly need to do ``something else'' and the stack is deeper than a single transient, and/or you have already changed the values of some infix arguments). @@ -409,7 +409,7 @@ as well as some other commands that are all bound to @kbd{C-x @var{KEY}}. After @kbd{C-x} is pressed, a section featuring all these common commands is temporarily shown in the popup buffer. After invoking one of them, the section disappears again. Note, however, that one of these -commands is described as “Show common permanently”; invoke that if you +commands is described as ``Show common permanently''; invoke that if you want the common commands to always be shown for all transients. @table @asis @@ -589,7 +589,7 @@ displayed at any level. The levels of individual transients and/or their individual suffixes can be changed interactively, by invoking the transient and then -pressing @kbd{C-x l} to enter the “edit” mode, see below. +pressing @kbd{C-x l} to enter the ``edit'' mode, see below. The default level for both transients and their suffixes is 4. The @code{transient-default-level} option only controls the default for @@ -939,8 +939,8 @@ The following functions share a few arguments: @item @var{SUFFIX} is a transient infix or suffix specification in the same form as expected by @code{transient-define-prefix}. Note that an infix is a -special kind of suffix. Depending on context “suffixes” means -“suffixes (including infixes)” or “non-infix suffixes”. Here it +special kind of suffix. Depending on context ``suffixes'' means +``suffixes (including infixes)'' or ``non-infix suffixes''. Here it means the former. @xref{Suffix Specifications}. @var{SUFFIX} may also be a group in the same form as expected by @@ -1066,7 +1066,7 @@ however, call that function only when some condition is satisfied. All transients have a (possibly @code{nil}) value, which is exported when suffix commands are called, so that they can consume that value. For some transients it might be necessary to have a sort of -secondary value, called a “scope”. Such a scope would usually be +secondary value, called a ``scope''. Such a scope would usually be set in the command's @code{interactive} form and has to be passed to the setup function: @@ -1088,8 +1088,8 @@ described below. Users and third-party packages can add additional bindings using functions such as @code{transient-insert-suffix} (@pxref{Modifying -Existing Transients}). These functions take a “suffix -specification” as one of their arguments, which has the same form as +Existing Transients}). These functions take a ``suffix +specification'' as one of their arguments, which has the same form as the specifications used in @code{transient-define-prefix}. @menu @@ -1224,8 +1224,8 @@ The same form is also used when later binding additional commands using functions such as @code{transient-insert-suffix}, see @ref{Modifying Existing Transients}. Note that an infix is a special kind of suffix. Depending on context -“suffixes” means “suffixes (including infixes)” or “non-infix -suffixes”. Here it means the former. +``suffixes'' means ``suffixes (including infixes)'' or ``non-infix +suffixes''. Here it means the former. Suffix specifications have this form: @@ -1319,8 +1319,8 @@ argument supported by the constructor of that class. See @ref{Suffix Slots}. @cindex defining infix commands Note that an infix is a special kind of suffix. Depending on context -“suffixes” means “suffixes (including infixes)” or “non-infix -suffixes”. +``suffixes'' means ``suffixes (including infixes)'' or ``non-infix +suffixes''. @defmac transient-define-suffix name arglist [docstring] [keyword value]@dots{} body@dots{} This macro defines @var{NAME} as a transient suffix command. @@ -1453,7 +1453,7 @@ returned value is a symbol, the transient prefix command. @cindex transient state -Invoking a transient prefix command “activates” the respective +Invoking a transient prefix command ``activates'' the respective transient, i.e., it puts a transient keymap into effect, which binds the transient's infix and suffix commands. @@ -1465,20 +1465,20 @@ Invoking an infix command does not affect the transient state; the transient remains active. @item -Invoking a (non-infix) suffix command “deactivates” the transient +Invoking a (non-infix) suffix command ``deactivates'' the transient state by removing the transient keymap and performing some additional cleanup. @item Invoking a command that is bound in a keymap other than the transient keymap is disallowed and trying to do so results in a -warning. This does not “deactivate” the transient. +warning. This does not ``deactivate'' the transient. @end itemize But these are just the defaults. Whether a certain command -deactivates or “exits” the transient is configurable. There is more -than one way in which a command can be “transient” or “non-transient”; -the exact behavior is implemented by calling a so-called “pre-command” +deactivates or ``exits'' the transient is configurable. There is more +than one way in which a command can be ``transient'' or ``non-transient''; +the exact behavior is implemented by calling a so-called ``pre-command'' function. Whether non-suffix commands are allowed to be called is configurable per transient. @@ -1506,17 +1506,17 @@ essentially equivalent to it being @code{nil}. @item A suffix command can be a prefix command itself, i.e., a -“sub-prefix”. While a sub-prefix is active we nearly always want -@kbd{C-g} to take the user back to the “super-prefix”. However in rare +``sub-prefix''. While a sub-prefix is active we nearly always want +@kbd{C-g} to take the user back to the ``super-prefix''. However in rare cases this may not be desirable, and that makes the following complication necessary: For @code{transient-suffix} objects the @code{transient} slot is unbound. We can ignore that for the most part because, as stated above, @code{nil} and the -slot being unbound are equivalent, and mean “do exit”. That isn't +slot being unbound are equivalent, and mean ``do exit''. That isn't actually true for suffixes that are sub-prefixes though. For such -suffixes unbound means “do exit but allow going back”, which is the -default, while @code{nil} means “do exit permanently”, which requires that +suffixes unbound means ``do exit but allow going back'', which is the +default, while @code{nil} means ``do exit permanently'', which requires that slot to be explicitly set to that value. @item @@ -1531,7 +1531,7 @@ called by @code{transient--pre-command}, a function on @code{pre-command-hook} a the value that they return determines whether the transient is exited. To do so the value of one of the constants @code{transient--exit} or @code{transient--stay} is used (that way we don't have to remember if @code{t} means -“exit” or “stay”). +``exit'' or ``stay''). Additionally, these functions may change the value of @code{this-command} (which explains why they have to be called using @code{pre-command-hook}), @@ -1607,7 +1607,7 @@ i.e., for sub-prefixes. Suspend the active transient, saving the transient stack. This is used by the command @code{transient-suspend} and optionally also by -“external events” such as @code{handle-switch-frame}. Such bindings should +``external events'' such as @code{handle-switch-frame}. Such bindings should be added to @code{transient-predicate-map}. @end defun @@ -1733,7 +1733,7 @@ The abstract @code{transient-child} class is the base class of both @code{transient-group} (and therefore all groups) as well as of @code{transient-suffix} (and therefore all suffix and infix commands). -This class exists because the elements (or “children”) of certain +This class exists because the elements (or ``children'') of certain groups can be other groups instead of suffix and infix commands. @item @@ -1743,7 +1743,7 @@ group classes. @item The @code{transient-column} class is the simplest group. -This is the default “flat” group. If the class is not specified +This is the default ``flat'' group. If the class is not specified explicitly and the first element is not a vector (i.e., not a group), then this class is used. @@ -1759,7 +1759,7 @@ Direct elements have to be groups whose elements have to be commands or strings. Each subgroup represents a column. This class takes care of inserting the subgroups' elements. -This is the default “nested” group. If the class is not specified +This is the default ``nested'' group. If the class is not specified explicitly and the first element is a vector (i.e., a group), then this class is used. @@ -1937,7 +1937,7 @@ function is how the value of a transient is determined so that the invoked suffix command can use it. Currently most values are strings, but that is not set in stone. -@code{nil} is not a value, it means “no value”. +@code{nil} is not a value, it means ``no value''. Usually only infixes have a value, but see the method for @code{transient-suffix}. @@ -2027,7 +2027,7 @@ multiple sub-lists. @item @code{scope} For some transients it might be necessary to have a sort of -secondary value, called a “scope”. See @code{transient-define-prefix}. +secondary value, called a ``scope''. See @code{transient-define-prefix}. @end itemize @anchor{Internal Prefix Slots} @@ -2503,9 +2503,9 @@ Both packages use transient keymaps to make a set of commands temporarily available and show the available commands in a popup buffer. -A Hydra “body” is equivalent to a Transient “prefix” and a Hydra -“head” is equivalent to a Transient “suffix”. Hydra has no equivalent -of a Transient “infix”. +A Hydra ``body'' is equivalent to a Transient ``prefix'' and a Hydra +``head'' is equivalent to a Transient ``suffix''. Hydra has no equivalent +of a Transient ``infix''. Both hydras and transients can be used as simple command dispatchers. Used like this they are similar to regular prefix commands and prefix @@ -2614,14 +2614,14 @@ bindings. The bindings that do use a prefix do so to avoid wasting too many non-prefix bindings, keeping them available for use in individual transients. The bindings that do not use a prefix and that are @strong{not} grayed out are very important bindings that are @strong{always} -available, even when invoking the “common command key prefix” or @strong{any +available, even when invoking the ``common command key prefix'' or @strong{any other} transient-specific prefix. The non-prefix keys that @strong{are} grayed out however, are not available when any incomplete prefix key sequence -is active. They do not use the “common command key prefix” because it +is active. They do not use the ``common command key prefix'' because it is likely that users want to invoke them several times in a row and e.g., @kbd{M-p M-p M-p} is much more convenient than @kbd{C-x M-p C-x M-p C-x M-p}. -You may also have noticed that the “Set” command is bound to @kbd{C-x s}, +You may also have noticed that the ``Set'' command is bound to @kbd{C-x s}, while Magit-Popup used to bind @kbd{C-c C-c} instead. I have seen several users praise the latter binding (sic), so I did not change it willy-nilly. The reason that I changed it is that using different