diff --git a/doc/racket-mode.texi b/doc/racket-mode.texi index ea402288..f69ebf58 100644 --- a/doc/racket-mode.texi +++ b/doc/racket-mode.texi @@ -1044,11 +1044,13 @@ To insert Unicode symbols generally, see @ref{racket-input-mode}. @kbd{M-x} @code{racket-insert-symbol} -A command alternative to the ``Racket'' input method. +Insert a symbol from @ref{racket-input-translations}. -Presents a @code{completing-read} UI to choose and insert from -@ref{racket-input-translations}. The symbols that would be inserted -are shown as annotations -- serves as a preview unlike what is +A command alternative to the ``Racket'' input method activated by +@ref{racket-input-mode}. + +Presents a @code{completing-read} UI, in which the symbols that would +be inserted are shown as annotations -- a preview unlike what is currently provided by the Emacs UI for input method. @node racket-fold-all-tests @@ -1412,18 +1414,15 @@ repeatedly. A minor mode to enable the ``Racket'' input method. -The Racket input method lets you easily use various Unicode -symbols that might be useful when writing Racket code. - -When the Racket input method is active, and @ref{racket-input-prefix} -is the default ``\'', you can for example type ``\All'' and it -is immediately replaced with ``∀''. +The Racket input method lets you type @ref{racket-input-prefix}, +followed by a key sequence from @ref{racket-input-translations}, +directly in a buffer, to insert a symbol. -See @ref{racket-input-translations} for the full list of translations, -which is also used by the @ref{racket-insert-symbol} command. +For example when @ref{racket-input-prefix} is the default ``\'', you +can type ``\All'' and it is immediately replaced with ``∀''. -To automatically enable the Racket input method for all new -buffers, put the following in your Emacs init file: +To enable @ref{racket-input-mode} (and the Racket input method) for +all new buffers, put the following in your Emacs init file: @lisp (dolist (hook '(racket-mode-hook @@ -1432,11 +1431,16 @@ buffers, put the following in your Emacs init file: (add-hook hook #'racket-input-mode)) @end lisp -You may use the standard Emacs key C-\ to toggle the current -input method. +Tip: You may use the standard Emacs key C-\ to toggle the +current input method. + +Tip: If you don’t like the highlighting of partially matching +tokens you can disable that using @code{input-method-highlight-flag}. -If you don’t like the highlighting of partially matching tokens you -can turn it off by setting @code{input-method-highlight-flag} to nil. +See the Emacs manual for other information about input methods. + +Tip: Another way to use @ref{racket-input-translations} is by using a +command: @ref{racket-insert-symbol}. This is a minor mode. If called interactively, toggle the @code{Racket-Input mode} mode. If the prefix argument is positive, @@ -3755,9 +3759,15 @@ Predefined choices include @ref{racket-shell}, @ref{racket-term}, @node racket-input-prefix @subsection racket-input-prefix -A prefix for the Racket input method. +A prefix used by the ``Racket'' input method. + +This string is prepended to the key sequence strings in +@ref{racket-input-translations}, when setting up the input method. -The prefix is applied to the @ref{racket-input-translations}. +Using some non-nil, non-blank prefix avoids conflicts between key +sequences and portions of normal words. For example ``oint'' +would insert ``∮'' while you're typing ``point'' -- but not +``\oint''. If you change this setting manually with @code{setq} (instead of using the customization buffer or @code{setopt}) you need to call @@ -3770,8 +3780,9 @@ A list of translations. Each element is (KEY-SEQUENCE-STRING TRANSLATION-STRING). -Used by the ``Racket'' input method as well as the -@ref{racket-insert-symbol} command. +Used by the ``Racket'' input method activated by +@ref{racket-input-mode}, as well as by the @ref{racket-insert-symbol} +command. If you change this setting manually with @code{setq} (instead of using the customization buffer or @code{setopt}) you need to call diff --git a/racket-input.el b/racket-input.el index 7b2dee28..1e86f8a3 100644 --- a/racket-input.el +++ b/racket-input.el @@ -16,9 +16,15 @@ :group 'racket) (defcustom racket-input-prefix "\\" - "A prefix for the Racket input method. + "A prefix used by the \"Racket\" input method. -The prefix is applied to the `racket-input-translations'. +This string is prepended to the key sequence strings in +`racket-input-translations', when setting up the input method. + +Using some non-nil, non-blank prefix avoids conflicts between key +sequences and portions of normal words. For example \"oint\" +would insert \"∮\" while you're typing \"point\" -- but not +\"\\oint\". If you change this setting manually with `setq' (instead of using the customization buffer or `setopt') you need to call @@ -62,7 +68,7 @@ the customization buffer or `setopt') you need to call ("prod" "∏") ("coprod" "∐") ("integrate" "∫") - ("Oint" "∮") + ("oint" "∮") ("vee" "∨") ("wedge" "∧") ("follows" "∘") @@ -208,8 +214,9 @@ the customization buffer or `setopt') you need to call Each element is (KEY-SEQUENCE-STRING TRANSLATION-STRING). -Used by the \"Racket\" input method as well as the -`racket-insert-symbol' command. +Used by the \"Racket\" input method activated by +`racket-input-mode', as well as by the `racket-insert-symbol' +command. If you change this setting manually with `setq' (instead of using the customization buffer or `setopt') you need to call @@ -260,18 +267,15 @@ variables." (define-minor-mode racket-input-mode "A minor mode to enable the \"Racket\" input method. -The Racket input method lets you easily use various Unicode -symbols that might be useful when writing Racket code. - -When the Racket input method is active, and `racket-input-prefix' -is the default \"\\\", you can for example type \"\\All\" and it -is immediately replaced with \"∀\". +The Racket input method lets you type `racket-input-prefix', +followed by a key sequence from `racket-input-translations', +directly in a buffer, to insert a symbol. -See `racket-input-translations' for the full list of translations, -which is also used by the `racket-insert-symbol' command. +For example when `racket-input-prefix' is the default \"\\\", you +can type \"\\All\" and it is immediately replaced with \"∀\". -To automatically enable the Racket input method for all new -buffers, put the following in your Emacs init file: +To enable `racket-input-mode' (and the Racket input method) for +all new buffers, put the following in your Emacs init file: #+BEGIN_SRC elisp (dolist (hook \\='(racket-mode-hook @@ -280,11 +284,16 @@ buffers, put the following in your Emacs init file: (add-hook hook #\\='racket-input-mode)) #+END_SRC -You may use the standard Emacs key C-\\ to toggle the current -input method. +Tip: You may use the standard Emacs key C-\\ to toggle the +current input method. + +Tip: If you don’t like the highlighting of partially matching +tokens you can disable that using `input-method-highlight-flag'. -If you don’t like the highlighting of partially matching tokens you -can turn it off by setting `input-method-highlight-flag' to nil." +See the Emacs manual for other information about input methods. + +Tip: Another way to use `racket-input-translations' is by using a +command: `racket-insert-symbol'." :lighter "" (if racket-input-mode (set-input-method "Racket") @@ -299,11 +308,13 @@ can turn it off by setting `input-method-highlight-flag' to nil." ;;; Command flavor, using completing-read with annotations (defun racket-insert-symbol () - "A command alternative to the \"Racket\" input method. + "Insert a symbol from `racket-input-translations'. + +A command alternative to the \"Racket\" input method activated by +`racket-input-mode'. -Presents a `completing-read' UI to choose and insert from -`racket-input-translations'. The symbols that would be inserted -are shown as annotations -- serves as a preview unlike what is +Presents a `completing-read' UI, in which the symbols that would +be inserted are shown as annotations -- a preview unlike what is currently provided by the Emacs UI for input method." (interactive) (let* ((translations racket-input-translations)