From d4ccbe956a8f7c9679ca4fd0e51b45a4339333ab Mon Sep 17 00:00:00 2001 From: Jonas Bernoulli Date: Wed, 30 Aug 2023 01:40:14 +0200 Subject: [PATCH] docs: Don't use unicode quotes in texi export Re https://lists.gnu.org/archive/html/emacs-devel/2023-08/msg01232.html. --- docs/Makefile | 1 + docs/transient.texi | 92 ++++++++++++++++++++++----------------------- 2 files changed, 47 insertions(+), 46 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index a70c87a4..97629a2b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -17,6 +17,7 @@ texi: @printf "Generating $(PKG).texi\n" @$(EMACS) $(ORG_ARGS) $(PKG).org $(ORG_EVAL) @printf "\n" >> $(PKG).texi + @sed -i -e 's/“/``/' -e "s/”/''/" $(PKG).texi @rm -f $(PKG).texi~ %.info: %.texi diff --git a/docs/transient.texi b/docs/transient.texi index cd12259e..637c5d1e 100644 --- a/docs/transient.texi +++ b/docs/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 @ref{Using History}. After a transient prefix command is invoked, @kbd{C-h @var{KEY}} can be used to @@ -370,7 +370,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). @@ -397,7 +397,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 @@ -577,7 +577,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 @@ -925,8 +925,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. See @ref{Suffix Specifications}. @var{SUFFIX} may also be a group in the same form as expected by @@ -1044,7 +1044,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: @@ -1064,7 +1064,7 @@ This defines the actual transient prefix command (see @ref{Defining Transients}) described below. Users and third-party packages can add additional bindings using -functions such as @code{transient-insert-suffix} (See @ref{Modifying Existing Transients}). These functions take a “suffix specification” as one of +functions such as @code{transient-insert-suffix} (See @ref{Modifying 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}. @@ -1197,8 +1197,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: @@ -1290,8 +1290,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]... body... This macro defines @var{NAME} as a transient suffix command. @@ -1424,7 +1424,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. @@ -1436,20 +1436,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. @@ -1477,17 +1477,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 @@ -1502,7 +1502,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}), @@ -1578,7 +1578,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 @@ -1704,7 +1704,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 @@ -1714,7 +1714,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. @@ -1730,7 +1730,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. @@ -1908,7 +1908,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}. @@ -1998,7 +1998,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} @@ -2469,9 +2469,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 @@ -2580,14 +2580,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