Skip to content

Commit

Permalink
docs: Don't use unicode quotes in texi export
Browse files Browse the repository at this point in the history
  • Loading branch information
tarsius committed Aug 29, 2023
1 parent 8cf1238 commit d4ccbe9
Show file tree
Hide file tree
Showing 2 changed files with 47 additions and 46 deletions.
1 change: 1 addition & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
92 changes: 46 additions & 46 deletions docs/transient.texi
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -153,20 +153,20 @@ 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
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

Expand Down Expand Up @@ -217,15 +217,15 @@ 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.
@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
Expand All @@ -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
Expand Down Expand Up @@ -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).

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:

Expand All @@ -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}.

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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}),
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -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}.
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit d4ccbe9

Please sign in to comment.