Improving input-methods docs

Improving input-methods docs

[Rustom Mody]

Stefan Monnier wrote  (on gnu.emacs.help list):
> Rusi Mody wrote:
> > I see (info "(elisp)input methods")
> > that in emacs including 25, docs are still at
> >
> > | How to define input methods is not yet documented in this manual,
> > | but here we describe how to use them.
> >
> > Is there something I can do (within my capacity!) to move this forward?

> Start to document what you know?  Or try to document what you think
> should be there, and if you don't know what to write because you don't
> know how it works, then ask on emacs-devel.

Ok
First a basic question:
When I do describe-input-method
I see a lot of stuff 'described'
However unlike describe-function|variable etc that links to the relevant stuff
here there is no such.

Is there any way to get to the input method (source) from an activated
input-method?

Strangely even describe-key shows (say) self-insert-command for "\" in
tex-input-method
which seems strange if not plain wrong.
[Yeah I ran grep on the elisp sources and found a quail and an international
and ... Just asking if there is easier way to not get lost]

Re: Improving input-methods docs

[Chris Feng]

> Stefan Monnier wrote  (on gnu.emacs.help list):
>> Rusi Mody wrote:
>> > I see (info "(elisp)input methods")
>> > that in emacs including 25, docs are still at
>> >
>> > | How to define input methods is not yet documented in this manual,
>> > | but here we describe how to use them.
>> >
>> > Is there something I can do (within my capacity!) to move this forward?
>
>> Start to document what you know?  Or try to document what you think
>> should be there, and if you don't know what to write because you don't
>> know how it works, then ask on emacs-devel.

AFAIK to define a new input method it only requires one to register it
to `input-method-alist' and feed `input-method-function' a customized
function.  But it seems most input methods in Emacs are defined as
Quail packages, so an intro to `quail-define-package' (and perhaps
other parts of Quail) may also be helpful.

> Ok
> First a basic question:
> When I do describe-input-method
> I see a lot of stuff 'described'
> However unlike describe-function|variable etc that links to the relevant stuff
> here there is no such.
>
> Is there any way to get to the input method (source) from an activated
> input-method?

You can find most input methods in 'lisp/leim/leim-list.el' as they're
registered there.  For example, there's a form for the 'TeX' input
method indicating that it's actually a Quail package named
'quail/latin-ltx', so its source is in 'lisp/leim/quail/latin-ltx.el'.

> Strangely even describe-key shows (say) self-insert-command for "\" in
> tex-input-method
> which seems strange if not plain wrong.

IIUC input methods do not create new key bindings but translate
characters, so `describe-key' doesn't make much sense here.

Re: Improving input-methods docs

[Rustom Mody]

Thanks Chris

On Fri, Oct 2, 2015 at 10:53 AM, Chris Feng <chris.w.feng@gmail.com> wrote:
>> Stefan Monnier wrote  (on gnu.emacs.help list):
>>> Rusi Mody wrote:
>>> > I see (info "(elisp)input methods")
>>> > that in emacs including 25, docs are still at
>>> >
>>> > | How to define input methods is not yet documented in this manual,
>>> > | but here we describe how to use them.
>>> >
>>> > Is there something I can do (within my capacity!) to move this forward?
>>
>>> Start to document what you know?  Or try to document what you think
>>> should be there, and if you don't know what to write because you don't
>>> know how it works, then ask on emacs-devel.
>
> AFAIK to define a new input method it only requires one to register it
> to `input-method-alist' and feed `input-method-function' a customized
> function.  But it seems most input methods in Emacs are defined as
> Quail packages, so an intro to `quail-define-package' (and perhaps
> other parts of Quail) may also be helpful.

What's quail?
Why is it there? [or] What's its relation to (define)-input-method?
Sorry if I seem obtuse but I gather there is a close relation but I
cant make out what...

Re: Improving input-methods docs

[Chris Feng]

> What's quail?
> Why is it there? [or] What's its relation to (define)-input-method?
> Sorry if I seem obtuse but I gather there is a close relation but I
> cant make out what...

Quail is an implementation of Emacs input method
(`quail-input-method') without concrete rules on how to do the
translation (they are provided by Quail packages instead).  You can
think of it as an input method framework, I think.

Re: Improving input-methods docs

[Rustom Mody]

[-- Attachment #1: Type: text/plain, Size: 1420 bytes --]

Just resending since the mail to (earlier address of) Kenichi Handa bounced



On Fri, Oct 2, 2015 at 11:01 AM, Rustom Mody <rustompmody@gmail.com> wrote:

> Thanks Chris
>
> On Fri, Oct 2, 2015 at 10:53 AM, Chris Feng <chris.w.feng@gmail.com>
> wrote:
> >> Stefan Monnier wrote  (on gnu.emacs.help list):
> >>> Rusi Mody wrote:
> >>> > I see (info "(elisp)input methods")
> >>> > that in emacs including 25, docs are still at
> >>> >
> >>> > | How to define input methods is not yet documented in this manual,
> >>> > | but here we describe how to use them.
> >>> >
> >>> > Is there something I can do (within my capacity!) to move this
> forward?
> >>
> >>> Start to document what you know?  Or try to document what you think
> >>> should be there, and if you don't know what to write because you don't
> >>> know how it works, then ask on emacs-devel.
> >
> > AFAIK to define a new input method it only requires one to register it
> > to `input-method-alist' and feed `input-method-function' a customized
> > function.  But it seems most input methods in Emacs are defined as
> > Quail packages, so an intro to `quail-define-package' (and perhaps
> > other parts of Quail) may also be helpful.
>
> What's quail?
> Why is it there? [or] What's its relation to (define)-input-method?
> Sorry if I seem obtuse but I gather there is a close relation but I
> cant make out what...
>

Also the relation of mule and quail??

[-- Attachment #2: Type: text/html, Size: 2250 bytes --]

Re: Improving input-methods docs

[Eli Zaretskii]

> From: Rustom Mody <rustompmody@gmail.com>
> Date: Fri, 2 Oct 2015 12:20:07 +0530
> Cc: handa@gnu.org, Kenichi Handa <handa@m17n.org>,
> 	emacs-devel <emacs-devel@gnu.org>
> 
> Also the relation of mule and quail??

Almost none.  Quail deals with input of non-ASCII characters that your
keyboard doesn't support.  By contrast, MULE deals with non-ASCII
characters sent encoded by your keyboard.  IOW, they complement each
other.

Re: Improving input-methods docs

[Eli Zaretskii]

> From: Rustom Mody <rustompmody@gmail.com>
> Date: Fri, 2 Oct 2015 08:23:48 +0530
> 
> When I do describe-input-method
> I see a lot of stuff 'described'
> However unlike describe-function|variable etc that links to the relevant stuff
> here there is no such.
> 
> Is there any way to get to the input method (source) from an activated
> input-method?

How about starting with a change that would include in the description
the place where the input method is defined?  I think this would be a
valuable documentation feature.  Currently, you need to grep the
relevant sources for the name of the input method.

> Strangely even describe-key shows (say) self-insert-command for "\" in
> tex-input-method
> which seems strange if not plain wrong.

It's not wrong: Emacs doesn't know better.  But maybe there should be
some addition that is related to the currently active input method.