aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPo Lu2023-08-29 09:29:20 +0800
committerPo Lu2023-08-29 09:29:20 +0800
commitfb4be1d5ae97694cdfc7fd7570bac7cd3bb8f895 (patch)
tree7a8b54f732f2143f04a193af40946d6c1ad21ec4
parenta2817be9f184087fbd7f235ad7792907330589ea (diff)
downloademacs-fb4be1d5ae97694cdfc7fd7570bac7cd3bb8f895.tar.gz
emacs-fb4be1d5ae97694cdfc7fd7570bac7cd3bb8f895.zip
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.
-rw-r--r--doc/misc/transient.texi94
1 files changed, 47 insertions, 47 deletions
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.
47Taking inspiration from prefix keys and prefix arguments, Transient 47Taking inspiration from prefix keys and prefix arguments, Transient
48implements a similar abstraction involving a prefix command, infix 48implements a similar abstraction involving a prefix command, infix
49arguments and suffix commands. We could call this abstraction a 49arguments and suffix commands. We could call this abstraction a
50transient command, but because it always involves at least two 50``transient command'', but because it always involves at least two
51commands (a prefix and a suffix) we prefer to call it just a 51commands (a prefix and a suffix) we prefer to call it just a
52transient. 52``transient''.
53 53
54When the user calls a transient prefix command, a transient 54When the user calls a transient prefix command, a transient
55(temporary) keymap is activated, which binds the transient's infix 55(temporary) keymap is activated, which binds the transient's infix
@@ -153,9 +153,9 @@ Related Abstractions and Packages
153Taking inspiration from prefix keys and prefix arguments, Transient 153Taking inspiration from prefix keys and prefix arguments, Transient
154implements a similar abstraction involving a prefix command, infix 154implements a similar abstraction involving a prefix command, infix
155arguments and suffix commands. We could call this abstraction a 155arguments and suffix commands. We could call this abstraction a
156transient command, but because it always involves at least two 156``transient command'', but because it always involves at least two
157commands (a prefix and a suffix) we prefer to call it just a 157commands (a prefix and a suffix) we prefer to call it just a
158transient. 158``transient''.
159 159
160@cindex transient prefix command 160@cindex transient prefix command
161@quotation 161@quotation
@@ -163,10 +163,10 @@ Transient keymaps are a feature provided by Emacs. Transients as
163implemented by this package involve the use of transient keymaps. 163implemented by this package involve the use of transient keymaps.
164 164
165Emacs provides a feature that it calls @dfn{prefix commands}. When we 165Emacs provides a feature that it calls @dfn{prefix commands}. When we
166talk about prefix commands in this manual, then we mean our own kind 166talk about ``prefix commands'' in this manual, then we mean our own kind
167of prefix commands, unless specified otherwise. To avoid ambiguity 167of ``prefix commands'', unless specified otherwise. To avoid ambiguity
168we sometimes use the terms @dfn{transient prefix command} for our kind and 168we sometimes use the terms @dfn{transient prefix command} for our kind and
169regular prefix command for Emacs' kind. 169``regular prefix command'' for Emacs' kind.
170 170
171@end quotation 171@end quotation
172 172
@@ -217,7 +217,7 @@ looks a bit like this:
217 217
218@quotation 218@quotation
219This is a simplified version of @code{magit-tag}. Info manuals do not 219This is a simplified version of @code{magit-tag}. Info manuals do not
220support images or colored text, so the above screenshot lacks some 220support images or colored text, so the above ``screenshot'' lacks some
221information; in practice you would be able to tell whether the 221information; in practice you would be able to tell whether the
222arguments @code{--force} and @code{--annotate} are enabled or not based on their 222arguments @code{--force} and @code{--annotate} are enabled or not based on their
223color. 223color.
@@ -225,7 +225,7 @@ color.
225@end quotation 225@end quotation
226 226
227@cindex command dispatchers 227@cindex command dispatchers
228Transient can be used to implement simple command dispatchers. The 228Transient can be used to implement simple ``command dispatchers''. The
229main benefit then is that the user can see all the available commands 229main benefit then is that the user can see all the available commands
230in a popup buffer. That is useful by itself because it frees the user 230in a popup buffer. That is useful by itself because it frees the user
231from having to remember all the keys that are valid after a certain 231from having to remember all the keys that are valid after a certain
@@ -251,9 +251,9 @@ from Lisp.
251Invoking a transient suffix command with arguments is similar to 251Invoking a transient suffix command with arguments is similar to
252invoking a command in a shell with command-line completion and history 252invoking a command in a shell with command-line completion and history
253enabled. One benefit of the Transient interface is that it remembers 253enabled. One benefit of the Transient interface is that it remembers
254history not only on a global level (this command was invoked using 254history not only on a global level (``this command was invoked using
255these arguments, and previously it was invoked using those other 255these arguments, and previously it was invoked using those other
256arguments), but also remembers the values of individual arguments 256arguments''), but also remembers the values of individual arguments
257independently. See @xref{Using History}. 257independently. See @xref{Using History}.
258 258
259After a transient prefix command is invoked, @kbd{C-h @var{KEY}} can be used to 259After a transient prefix command is invoked, @kbd{C-h @var{KEY}} can be used to
@@ -382,7 +382,7 @@ suspended transients, if any.
382Like @code{transient-quit-all}, this command quits an incomplete key 382Like @code{transient-quit-all}, this command quits an incomplete key
383sequence, if any, and all transients. Additionally, it saves the 383sequence, if any, and all transients. Additionally, it saves the
384stack of transients so that it can easily be resumed (which is 384stack of transients so that it can easily be resumed (which is
385particularly useful if you quickly need to do something else and 385particularly useful if you quickly need to do ``something else'' and
386the stack is deeper than a single transient, and/or you have already 386the stack is deeper than a single transient, and/or you have already
387changed the values of some infix arguments). 387changed the values of some infix arguments).
388 388
@@ -409,7 +409,7 @@ as well as some other commands that are all bound to @kbd{C-x @var{KEY}}. After
409@kbd{C-x} is pressed, a section featuring all these common commands is 409@kbd{C-x} is pressed, a section featuring all these common commands is
410temporarily shown in the popup buffer. After invoking one of them, 410temporarily shown in the popup buffer. After invoking one of them,
411the section disappears again. Note, however, that one of these 411the section disappears again. Note, however, that one of these
412commands is described as Show common permanently; invoke that if you 412commands is described as ``Show common permanently''; invoke that if you
413want the common commands to always be shown for all transients. 413want the common commands to always be shown for all transients.
414 414
415@table @asis 415@table @asis
@@ -589,7 +589,7 @@ displayed at any level.
589 589
590The levels of individual transients and/or their individual suffixes 590The levels of individual transients and/or their individual suffixes
591can be changed interactively, by invoking the transient and then 591can be changed interactively, by invoking the transient and then
592pressing @kbd{C-x l} to enter the edit mode, see below. 592pressing @kbd{C-x l} to enter the ``edit'' mode, see below.
593 593
594The default level for both transients and their suffixes is 4. The 594The default level for both transients and their suffixes is 4. The
595@code{transient-default-level} option only controls the default for 595@code{transient-default-level} option only controls the default for
@@ -939,8 +939,8 @@ The following functions share a few arguments:
939@item 939@item
940@var{SUFFIX} is a transient infix or suffix specification in the same form 940@var{SUFFIX} is a transient infix or suffix specification in the same form
941as expected by @code{transient-define-prefix}. Note that an infix is a 941as expected by @code{transient-define-prefix}. Note that an infix is a
942special kind of suffix. Depending on context suffixes means 942special kind of suffix. Depending on context ``suffixes'' means
943suffixes (including infixes) or non-infix suffixes. Here it 943``suffixes (including infixes)'' or ``non-infix suffixes''. Here it
944means the former. @xref{Suffix Specifications}. 944means the former. @xref{Suffix Specifications}.
945 945
946@var{SUFFIX} may also be a group in the same form as expected by 946@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.
1066All transients have a (possibly @code{nil}) value, which is exported when 1066All transients have a (possibly @code{nil}) value, which is exported when
1067suffix commands are called, so that they can consume that value. 1067suffix commands are called, so that they can consume that value.
1068For some transients it might be necessary to have a sort of 1068For some transients it might be necessary to have a sort of
1069secondary value, called a scope. Such a scope would usually be 1069secondary value, called a ``scope''. Such a scope would usually be
1070set in the command's @code{interactive} form and has to be passed to the 1070set in the command's @code{interactive} form and has to be passed to the
1071setup function: 1071setup function:
1072 1072
@@ -1088,8 +1088,8 @@ described below.
1088 1088
1089Users and third-party packages can add additional bindings using 1089Users and third-party packages can add additional bindings using
1090functions such as @code{transient-insert-suffix} (@pxref{Modifying 1090functions such as @code{transient-insert-suffix} (@pxref{Modifying
1091Existing Transients}). These functions take a suffix 1091Existing Transients}). These functions take a ``suffix
1092specification as one of their arguments, which has the same form as 1092specification'' as one of their arguments, which has the same form as
1093the specifications used in @code{transient-define-prefix}. 1093the specifications used in @code{transient-define-prefix}.
1094 1094
1095@menu 1095@menu
@@ -1224,8 +1224,8 @@ The same form is also used when later binding additional commands
1224using functions such as @code{transient-insert-suffix}, see @ref{Modifying Existing Transients}. 1224using functions such as @code{transient-insert-suffix}, see @ref{Modifying Existing Transients}.
1225 1225
1226Note that an infix is a special kind of suffix. Depending on context 1226Note that an infix is a special kind of suffix. Depending on context
1227suffixes means suffixes (including infixes) or non-infix 1227``suffixes'' means ``suffixes (including infixes)'' or ``non-infix
1228suffixes. Here it means the former. 1228suffixes''. Here it means the former.
1229 1229
1230Suffix specifications have this form: 1230Suffix specifications have this form:
1231 1231
@@ -1319,8 +1319,8 @@ argument supported by the constructor of that class. See @ref{Suffix Slots}.
1319@cindex defining infix commands 1319@cindex defining infix commands
1320 1320
1321Note that an infix is a special kind of suffix. Depending on context 1321Note that an infix is a special kind of suffix. Depending on context
1322suffixes means suffixes (including infixes) or non-infix 1322``suffixes'' means ``suffixes (including infixes)'' or ``non-infix
1323suffixes. 1323suffixes''.
1324 1324
1325@defmac transient-define-suffix name arglist [docstring] [keyword value]@dots{} body@dots{} 1325@defmac transient-define-suffix name arglist [docstring] [keyword value]@dots{} body@dots{}
1326This macro defines @var{NAME} as a transient suffix command. 1326This macro defines @var{NAME} as a transient suffix command.
@@ -1453,7 +1453,7 @@ returned value is a symbol, the transient prefix command.
1453 1453
1454@cindex transient state 1454@cindex transient state
1455 1455
1456Invoking a transient prefix command activates the respective 1456Invoking a transient prefix command ``activates'' the respective
1457transient, i.e., it puts a transient keymap into effect, which binds 1457transient, i.e., it puts a transient keymap into effect, which binds
1458the transient's infix and suffix commands. 1458the transient's infix and suffix commands.
1459 1459
@@ -1465,20 +1465,20 @@ Invoking an infix command does not affect the transient state; the
1465transient remains active. 1465transient remains active.
1466 1466
1467@item 1467@item
1468Invoking a (non-infix) suffix command deactivates the transient 1468Invoking a (non-infix) suffix command ``deactivates'' the transient
1469state by removing the transient keymap and performing some 1469state by removing the transient keymap and performing some
1470additional cleanup. 1470additional cleanup.
1471 1471
1472@item 1472@item
1473Invoking a command that is bound in a keymap other than the 1473Invoking a command that is bound in a keymap other than the
1474transient keymap is disallowed and trying to do so results in a 1474transient keymap is disallowed and trying to do so results in a
1475warning. This does not deactivate the transient. 1475warning. This does not ``deactivate'' the transient.
1476@end itemize 1476@end itemize
1477 1477
1478But these are just the defaults. Whether a certain command 1478But these are just the defaults. Whether a certain command
1479deactivates or exits the transient is configurable. There is more 1479deactivates or ``exits'' the transient is configurable. There is more
1480than one way in which a command can be transient or non-transient; 1480than one way in which a command can be ``transient'' or ``non-transient'';
1481the exact behavior is implemented by calling a so-called pre-command 1481the exact behavior is implemented by calling a so-called ``pre-command''
1482function. Whether non-suffix commands are allowed to be called is 1482function. Whether non-suffix commands are allowed to be called is
1483configurable per transient. 1483configurable per transient.
1484 1484
@@ -1506,17 +1506,17 @@ essentially equivalent to it being @code{nil}.
1506 1506
1507@item 1507@item
1508A suffix command can be a prefix command itself, i.e., a 1508A suffix command can be a prefix command itself, i.e., a
1509sub-prefix. While a sub-prefix is active we nearly always want 1509``sub-prefix''. While a sub-prefix is active we nearly always want
1510@kbd{C-g} to take the user back to the super-prefix. However in rare 1510@kbd{C-g} to take the user back to the ``super-prefix''. However in rare
1511cases this may not be desirable, and that makes the following 1511cases this may not be desirable, and that makes the following
1512complication necessary: 1512complication necessary:
1513 1513
1514For @code{transient-suffix} objects the @code{transient} slot is unbound. We can 1514For @code{transient-suffix} objects the @code{transient} slot is unbound. We can
1515ignore that for the most part because, as stated above, @code{nil} and the 1515ignore that for the most part because, as stated above, @code{nil} and the
1516slot being unbound are equivalent, and mean do exit. That isn't 1516slot being unbound are equivalent, and mean ``do exit''. That isn't
1517actually true for suffixes that are sub-prefixes though. For such 1517actually true for suffixes that are sub-prefixes though. For such
1518suffixes unbound means do exit but allow going back, which is the 1518suffixes unbound means ``do exit but allow going back'', which is the
1519default, while @code{nil} means do exit permanently, which requires that 1519default, while @code{nil} means ``do exit permanently'', which requires that
1520slot to be explicitly set to that value. 1520slot to be explicitly set to that value.
1521 1521
1522@item 1522@item
@@ -1531,7 +1531,7 @@ called by @code{transient--pre-command}, a function on @code{pre-command-hook} a
1531the value that they return determines whether the transient is exited. 1531the value that they return determines whether the transient is exited.
1532To do so the value of one of the constants @code{transient--exit} or 1532To do so the value of one of the constants @code{transient--exit} or
1533@code{transient--stay} is used (that way we don't have to remember if @code{t} means 1533@code{transient--stay} is used (that way we don't have to remember if @code{t} means
1534exit or stay). 1534``exit'' or ``stay'').
1535 1535
1536Additionally, these functions may change the value of @code{this-command} 1536Additionally, these functions may change the value of @code{this-command}
1537(which explains why they have to be called using @code{pre-command-hook}), 1537(which explains why they have to be called using @code{pre-command-hook}),
@@ -1607,7 +1607,7 @@ i.e., for sub-prefixes.
1607Suspend the active transient, saving the transient stack. 1607Suspend the active transient, saving the transient stack.
1608 1608
1609This is used by the command @code{transient-suspend} and optionally also by 1609This is used by the command @code{transient-suspend} and optionally also by
1610external events such as @code{handle-switch-frame}. Such bindings should 1610``external events'' such as @code{handle-switch-frame}. Such bindings should
1611be added to @code{transient-predicate-map}. 1611be added to @code{transient-predicate-map}.
1612@end defun 1612@end defun
1613 1613
@@ -1733,7 +1733,7 @@ The abstract @code{transient-child} class is the base class of both
1733@code{transient-group} (and therefore all groups) as well as of 1733@code{transient-group} (and therefore all groups) as well as of
1734@code{transient-suffix} (and therefore all suffix and infix commands). 1734@code{transient-suffix} (and therefore all suffix and infix commands).
1735 1735
1736This class exists because the elements (or children) of certain 1736This class exists because the elements (or ``children'') of certain
1737groups can be other groups instead of suffix and infix commands. 1737groups can be other groups instead of suffix and infix commands.
1738 1738
1739@item 1739@item
@@ -1743,7 +1743,7 @@ group classes.
1743@item 1743@item
1744The @code{transient-column} class is the simplest group. 1744The @code{transient-column} class is the simplest group.
1745 1745
1746This is the default flat group. If the class is not specified 1746This is the default ``flat'' group. If the class is not specified
1747explicitly and the first element is not a vector (i.e., not a group), 1747explicitly and the first element is not a vector (i.e., not a group),
1748then this class is used. 1748then this class is used.
1749 1749
@@ -1759,7 +1759,7 @@ Direct elements have to be groups whose elements have to be commands
1759or strings. Each subgroup represents a column. This class takes 1759or strings. Each subgroup represents a column. This class takes
1760care of inserting the subgroups' elements. 1760care of inserting the subgroups' elements.
1761 1761
1762This is the default nested group. If the class is not specified 1762This is the default ``nested'' group. If the class is not specified
1763explicitly and the first element is a vector (i.e., a group), then 1763explicitly and the first element is a vector (i.e., a group), then
1764this class is used. 1764this class is used.
1765 1765
@@ -1937,7 +1937,7 @@ function is how the value of a transient is determined so that the
1937invoked suffix command can use it. 1937invoked suffix command can use it.
1938 1938
1939Currently most values are strings, but that is not set in stone. 1939Currently most values are strings, but that is not set in stone.
1940@code{nil} is not a value, it means no value. 1940@code{nil} is not a value, it means ``no value''.
1941 1941
1942Usually only infixes have a value, but see the method for 1942Usually only infixes have a value, but see the method for
1943@code{transient-suffix}. 1943@code{transient-suffix}.
@@ -2027,7 +2027,7 @@ multiple sub-lists.
2027 2027
2028@item 2028@item
2029@code{scope} For some transients it might be necessary to have a sort of 2029@code{scope} For some transients it might be necessary to have a sort of
2030secondary value, called a scope. See @code{transient-define-prefix}. 2030secondary value, called a ``scope''. See @code{transient-define-prefix}.
2031@end itemize 2031@end itemize
2032 2032
2033@anchor{Internal Prefix Slots} 2033@anchor{Internal Prefix Slots}
@@ -2503,9 +2503,9 @@ Both packages use transient keymaps to make a set of commands
2503temporarily available and show the available commands in a popup 2503temporarily available and show the available commands in a popup
2504buffer. 2504buffer.
2505 2505
2506A Hydra body is equivalent to a Transient prefix and a Hydra 2506A Hydra ``body'' is equivalent to a Transient ``prefix'' and a Hydra
2507head is equivalent to a Transient suffix. Hydra has no equivalent 2507``head'' is equivalent to a Transient ``suffix''. Hydra has no equivalent
2508of a Transient infix. 2508of a Transient ``infix''.
2509 2509
2510Both hydras and transients can be used as simple command dispatchers. 2510Both hydras and transients can be used as simple command dispatchers.
2511Used like this they are similar to regular prefix commands and prefix 2511Used 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
2614too many non-prefix bindings, keeping them available for use in 2614too many non-prefix bindings, keeping them available for use in
2615individual transients. The bindings that do not use a prefix and that 2615individual transients. The bindings that do not use a prefix and that
2616are @strong{not} grayed out are very important bindings that are @strong{always} 2616are @strong{not} grayed out are very important bindings that are @strong{always}
2617available, even when invoking the common command key prefix or @strong{any 2617available, even when invoking the ``common command key prefix'' or @strong{any
2618other} transient-specific prefix. The non-prefix keys that @strong{are} grayed 2618other} transient-specific prefix. The non-prefix keys that @strong{are} grayed
2619out however, are not available when any incomplete prefix key sequence 2619out however, are not available when any incomplete prefix key sequence
2620is active. They do not use the common command key prefix because it 2620is active. They do not use the ``common command key prefix'' because it
2621is likely that users want to invoke them several times in a row and 2621is likely that users want to invoke them several times in a row and
2622e.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}. 2622e.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}.
2623 2623
2624You may also have noticed that the Set command is bound to @kbd{C-x s}, 2624You may also have noticed that the ``Set'' command is bound to @kbd{C-x s},
2625while Magit-Popup used to bind @kbd{C-c C-c} instead. I have seen several 2625while Magit-Popup used to bind @kbd{C-c C-c} instead. I have seen several
2626users praise the latter binding (sic), so I did not change it 2626users praise the latter binding (sic), so I did not change it
2627willy-nilly. The reason that I changed it is that using different 2627willy-nilly. The reason that I changed it is that using different