Re: quail-define-package and guidance string

[Eli Zaretskii]

> From: Rahguzar <rahguzar@zohomail.eu>
> Date: Tue, 10 Oct 2023 18:34:41 +0200
> 
> I want to write and contribute to Emacs a couple of input methods for
> Urdu. Looking around the already defined ones, it seems like
> `quail-define-package` is the standard way to define these. One of the
> input method uses phonetic transliteration. However Urdu has a bigger
> alphabet than English and standard transliteration is quite lossy, so
> there is a need to pick one of the translations and assign them to a key
> and the others to a different key combination. As a result I want to
> show such confusables in the echo area. It seems like it should be able
> to use GUIDANCE arg of `quail-define-package` but setting it to an alist
> has no effect for me. Specifically let say I have this code,
> 
> (quail-define-package
>  "urdu-phonetic" "Urdu" "اردو صوتی"
>  `((?a . "a → ا , A → آ , ax → أ , u → ع"))
>  "Intuitive transliteration keyboard layout for Urdu."
>  nil t t t t nil nil nil nil nil t)
> 
> (quail-define-rules
>  ("a" ?ا)
>  ("u" ?ع)
>  ("i" ?ئ)
>  ("A" ?آ)
>  ("ax" ?أ))
> 
> Evaluating it defines the `urdu-phonetic` input method and I activate
> and use it to input the characters above. However if I type 'a' the echo
> area shows 'a[x]' i.e. the default behavior if the GUIDANCE arg was 't'
> and the alist I passed to it is just ignored. Am I missing something in
> the doc string? And is what I am trying to do possible?

Try

 (quail-define-package
  "urdu-phonetic" "Urdu" "اردو صوتی"
  '((?a . "a → ا , A → آ , ax → أ , u → ع"))
  "Intuitive transliteration keyboard layout for Urdu."
  nil t t t t nil nil nil nil nil t)

> Another related question: I don't understand the meaning of string or
> vector type as the second entry of an argument of quail-define-rules.

The doc string says:

  TRANSLATION is a character, a string, a vector, a Quail map, or a function.
  If it is a character, it is the sole translation of KEY.
  If it is a string, each character is a candidate for the translation.
  If it is a vector, each element (string or character) is a candidate
    for the translation.

This means that if TRANSLATION is a string of more than one character,
each one of these characters is a candidate for translation.  Emacs
will display in the echo-area the possible candidates and assign
one-character keys to select one of these candidates.  Same if
TRANSLATION is a vector of more than one character, as in [?a ?b ?c].