Major mode and implementation of expected editing facilities

Major mode and implementation of expected editing facilities

[Daniele Nicolodi]

Hello,

is there somewhere an annotated list of the standard editing facilities
that a major mode is expected to implement or that it may be useful to
implement?

I'll try to explain what I mean with an example. I'm writing a major
mode to edit a form of structured data. The information in the file is
logically grouped into sections. Thus I thought that setting
fill-paragraph-function to something that would correctly indent one
such section would make sense so that fill-paragraph (M-q) would do the
right thing. Is that something desirable? Where can I find a list of
other hooks that would make sense to implement?

If such list does not exist what would be a good starting point to
compile it?

Thank you.

Cheers,
Dan

Re: Major mode and implementation of expected editing facilities

[Eli Zaretskii]

> From: Daniele Nicolodi <daniele@grinta.net>
> Date: Mon, 27 May 2019 16:14:33 -0600
> 
> is there somewhere an annotated list of the standard editing facilities
> that a major mode is expected to implement or that it may be useful to
> implement?

Did you read the corresponding node of the ELisp manual?

Re: Major mode and implementation of expected editing facilities

[Daniele Nicolodi]

On 27/05/2019 20:43, Eli Zaretskii wrote:
>> From: Daniele Nicolodi <daniele@grinta.net>
>> Date: Mon, 27 May 2019 16:14:33 -0600
>>
>> is there somewhere an annotated list of the standard editing facilities
>> that a major mode is expected to implement or that it may be useful to
>> implement?
> 
> Did you read the corresponding node of the ELisp manual?

I don't understand to which ELisp manual node you are referring too, so
most likely I have missed it. Can you provide me a more precise pointer?

Thank you.

Cheers,
Dan

Re: Major mode and implementation of expected editing facilities

[Eli Zaretskii]

On May 28, 2019 5:47:31 AM GMT+03:00, Daniele Nicolodi <daniele@grinta.net> wrote:
> On 27/05/2019 20:43, Eli Zaretskii wrote:
> >> From: Daniele Nicolodi <daniele@grinta.net>
> >> Date: Mon, 27 May 2019 16:14:33 -0600
> >>
> >> is there somewhere an annotated list of the standard editing
> facilities
> >> that a major mode is expected to implement or that it may be useful
> to
> >> implement?
> > 
> > Did you read the corresponding node of the ELisp manual?
> 
> I don't understand to which ELisp manual node you are referring too,
> so
> most likely I have missed it. Can you provide me a more precise
> pointer?
> 
> Thank you.
> 
> Cheers,
> Dan

I meant the section whose name is "Major Modes" and its subsections, mainly the first one.

Re: Major mode and implementation of expected editing facilities

[Daniele Nicolodi]

On 27/05/2019 22:20, Eli Zaretskii wrote:
> On May 28, 2019 5:47:31 AM GMT+03:00, Daniele Nicolodi <daniele@grinta.net> wrote:
>> On 27/05/2019 20:43, Eli Zaretskii wrote:
>>>> From: Daniele Nicolodi <daniele@grinta.net>
>>>> Date: Mon, 27 May 2019 16:14:33 -0600
>>>>
>>>> is there somewhere an annotated list of the standard editing
>> facilities
>>>> that a major mode is expected to implement or that it may be useful
>> to
>>>> implement?
>>>
>>> Did you read the corresponding node of the ELisp manual?
>>
>> I don't understand to which ELisp manual node you are referring too,
>> so
>> most likely I have missed it. Can you provide me a more precise
>> pointer?
> 
> I meant the section whose name is "Major Modes" and its subsections, mainly the first one.

I did read that and I didn't find anything there relevant to my question
other than

  A major mode can also rebind the keys M-n, M-p and M-s. The bindings
  for M-n and M-p should normally be some kind of moving forward and
  backward, but this does not necessarily mean cursor motion.

  It is legitimate for a major mode to rebind a standard key sequence if
  it provides a command that does the same job in a way better suited to
  the text this mode is used for. For example, a major mode for editing
  a programming language might redefine C-M-a to move to the beginning
  of a function in a way that works better for that language.

in "Major Mode Conventions", which describes exactly what I want to do,
but does not give any pointer which key sequences it makes sense and it
is most common to rebind. For example I don't fins mention of M-q
(fill-paragraph) which was in my original example.

Am I overlooking something?

Cheers,
Dan

Re: Major mode and implementation of expected editing facilities

[Eli Zaretskii]

> From: Daniele Nicolodi <daniele@grinta.net>
> Date: Mon, 27 May 2019 22:40:15 -0600
> 
>   A major mode can also rebind the keys M-n, M-p and M-s. The bindings
>   for M-n and M-p should normally be some kind of moving forward and
>   backward, but this does not necessarily mean cursor motion.
> 
>   It is legitimate for a major mode to rebind a standard key sequence if
>   it provides a command that does the same job in a way better suited to
>   the text this mode is used for. For example, a major mode for editing
>   a programming language might redefine C-M-a to move to the beginning
>   of a function in a way that works better for that language.
> 
> in "Major Mode Conventions", which describes exactly what I want to do,
> but does not give any pointer which key sequences it makes sense and it
> is most common to rebind. For example I don't fins mention of M-q
> (fill-paragraph) which was in my original example.
> 
> Am I overlooking something?

Given the above text, I'm not sure I understand what are you looking
for.  Clearly, what specific keys a major mode can reasonably rebind
depends on the mode and what it does, right?  IOW, it's your decision,
as someone who knows what the mode does, and which of its commands
could be usefully regarded as "generalizations" or "customizations" of
those in the related modes.

Re: Major mode and implementation of expected editing facilities

[John Yates]

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

On Tue, May 28, 2019 at 10:55 AM Eli Zaretskii <eliz@gnu.org> wrote:
>
> Given the above text, I'm not sure I understand what are you looking
> for.  Clearly, what specific keys a major mode can reasonably rebind
> depends on the mode and what it does, right?  IOW, it's your decision,
> as someone who knows what the mode does, and which of its commands
> could be usefully regarded as "generalizations" or "customizations" of
> those in the related modes.

What Daniele seeks makes eminent sense to me.

Designing a new mode is not easy, especially if one wants it to feel as
much like a natural extension of mainline emacs as possible.  One has
to develop the basic concept of the mode, decompose that envisioned
functionality into exposed operations consonant with the emacs mindset,
choose key bindings that will feel natural and inherit faces in a natural
manner.  (I am sure that there is more.  Those are simply the things that
come to mind as I compose this note.)

Those of us who have used emacs for years (decades?) and, further, used
many of its packages have distilled such wisdom.  Should we therefore
take the stance that we can offer no help towards such wisdom?  That there
is no substitute for paying one's dues and doing time in the emacs world?

If we are anxious to have new contributors who actually want to do a
craftsman-like job writing a new mode then we should do what we can to
help them along.  That we have not yet started writing down some of this
wisdom is no excuse not to start.  I am confident that beginning a chapter
on building a new mode would trigger much interesting discussion.

/john

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

Re: Major mode and implementation of expected editing facilities

[Daniele Nicolodi]

On 28-05-2019 13:37, John Yates wrote:
> On Tue, May 28, 2019 at 10:55 AM Eli Zaretskii <eliz@gnu.org
> <mailto:eliz@gnu.org>> wrote:
>>
>> Given the above text, I'm not sure I understand what are you looking
>> for.  Clearly, what specific keys a major mode can reasonably rebind
>> depends on the mode and what it does, right?  IOW, it's your decision,
>> as someone who knows what the mode does, and which of its commands
>> could be usefully regarded as "generalizations" or "customizations" of
>> those in the related modes.
> 
> What Daniele seeks makes eminent sense to me.
> 
> Designing a new mode is not easy, especially if one wants it to feel as
> much like a natural extension of mainline emacs as possible.  One has
> to develop the basic concept of the mode, decompose that envisioned
> functionality into exposed operations consonant with the emacs mindset,
> choose key bindings that will feel natural and inherit faces in a natural
> manner.  (I am sure that there is more.  Those are simply the things that
> come to mind as I compose this note.)
> 
> Those of us who have used emacs for years (decades?) and, further, used
> many of its packages have distilled such wisdom.  Should we therefore
> take the stance that we can offer no help towards such wisdom?  That there
> is no substitute for paying one's dues and doing time in the emacs world?
> 
> If we are anxious to have new contributors who actually want to do a
> craftsman-like job writing a new mode then we should do what we can to
> help them along.  That we have not yet started writing down some of this
> wisdom is no excuse not to start.  I am confident that beginning a chapter
> on building a new mode would trigger much interesting discussion.

Thanks John!

I'm happy to see that what I'm asking for makes sense for someone.

Cheers,
Dan

Re: Major mode and implementation of expected editing facilities

[Eli Zaretskii]

> From: John Yates <john@yates-sheets.org>
> Date: Tue, 28 May 2019 15:37:47 -0400
> Cc: Daniele Nicolodi <daniele@grinta.net>, Emacs developers <emacs-devel@gnu.org>
> 
> What Daniele seeks makes eminent sense to me.

I never said it made no sense to me.

> If we are anxious to have new contributors who actually want to do a
> craftsman-like job writing a new mode then we should do what we can to
> help them along.  That we have not yet started writing down some of this
> wisdom is no excuse not to start.  I am confident that beginning a chapter
> on building a new mode would trigger much interesting discussion.

If you or someone else want to suggest improvements for that chapter
of the manual, please do, and thanks in advance.

Re: Major mode and implementation of expected editing facilities

[Clément Pit-Claudel]

On 2019-05-28 22:33, Eli Zaretskii wrote:
> If you or someone else want to suggest improvements for that chapter
> of the manual, please do, and thanks in advance.

To get the ball rolling, I'll mention a few facilities that I like major modes to hook into.  Others can likely point out many omissions:

* Syntax tables: see Syntax Tables in the ELisp manual (this helps with font-locking and motion) and syntax-propertize-function

* Font-locking: see font-lock-defaults and font-lock-keywords, and often font-lock-extra-managed-props and font-lock-syntactic-face-function

* Completion: see completion-at-point-functions, or (in ELPA) company-mode

* Outline: See outline-level, outline-regexp, and outline-heading-end-regexp; or hs-special-modes-alist; or both; or (in ELPA) many other packages

* Jump to definition: See xref-backend-functions

* Project: See project-find-functions

* On-the-fly errors: See flymake-mode, or (in ELPA) flycheck-mode

* Filling: See fill-paragraph-function, adaptive-fill-regexp, adaptive-fill-first-line-regexp, and fill-paragraph-handle-comment

* Comments: See comment-start-skip, comment-use-syntax, and comment-multi-line

* Indentation: See indent-line-function, indent-tabs-mode, indent-region-function, and possibly electric-indent-inhibit and electric-indent-chars

* Prettification: See prettify-symbols-alist.

* Auto-insert: See auto-insert-alist

* Eldoc: See eldoc-documentation-function

* Current function: See which-func-functions and add-log-current-defun-function

* Toolbars and menus: See tool-bar-map, easy-menu-define, and imenu-create-index-function

* Compilation: compilation-error-regexp-alist

* Navigation: See forward-sexp-function, parse-sexp-lookup-properties, parse-sexp-ignore-comments, paragraph-start, beginning-of-defun-function, and end-of-defun-function

* Snippets: See skeleton.el, or (in ELPA) yasnippet.

* Key bindings: You don't usually need to define or override many of these, because most keys that are supposed to operate consistently across modes call standardized functions or hooks that your major mode can configure (instead of redefining the corresponding key).  This is the case for M-q or TAB, for example (and even, despite what the manual say, for C-M-a as well).  If you override or create keybindings, please please don't forget the 'delete-selection property, to ensure that the overridden key works well with delete-selection-mode.

Btw, a good place to find these things is existing mode functions; look for setq-local or (set (make-local-variable …) …) in define-derived-mode blocks.

Clément.

Re: Major mode and implementation of expected editing facilities

[Daniele Nicolodi]

On 28/05/2019 22:11, Clément Pit-Claudel wrote:
> On 2019-05-28 22:33, Eli Zaretskii wrote:
>> If you or someone else want to suggest improvements for that chapter
>> of the manual, please do, and thanks in advance.
> 
> To get the ball rolling, I'll mention a few facilities that I like
> major modes to hook into.  Others can likely point out many
> omissions:
[snip]

Thanks Clément!  This is what I was looking for.  I wish it could find
its way into documentation.

> Btw, a good place to find these things is existing mode functions;
> look for setq-local or (set (make-local-variable …) …) in
> define-derived-mode blocks.
This is how I found the hooks that my mode already implements, but it is
a bit tedious to have to go through the source code.

Cheers,
Dan

Re: Major mode and implementation of expected editing facilities

[Eli Zaretskii]

> From: Clément Pit-Claudel <cpitclaudel@gmail.com>
> Date: Wed, 29 May 2019 00:11:38 -0400
> Cc: daniele@grinta.net, emacs-devel@gnu.org
> 
> To get the ball rolling, I'll mention a few facilities that I like major modes to hook into.  Others can likely point out many omissions:

Thanks.  Do you think this list can basically go in as-is, or more
details are needed for each item?

Re: Major mode and implementation of expected editing facilities

[Clément Pit-Claudel]

On 2019-05-29 10:34, Eli Zaretskii wrote:
>> From: Clément Pit-Claudel <cpitclaudel@gmail.com>
>> Date: Wed, 29 May 2019 00:11:38 -0400
>> Cc: daniele@grinta.net, emacs-devel@gnu.org
>>
>> To get the ball rolling, I'll mention a few facilities that I like major modes to hook into.  Others can likely point out many omissions:
> 
> Thanks.  Do you think this list can basically go in as-is, or more
> details are needed for each item?

My pleasure.  I think some more detail might be needed, and there's likely mistakes and omissions in the list, so I'd like to wait for a bit of feedback.  Then we can tidy up the list and include it, if we deem it useful.

Clément.

Re: Major mode and implementation of expected editing facilities

[Dmitry Gutov]

On 29.05.2019 7:11, Clément Pit-Claudel wrote:
> * Project: See project-find-functions

I'm not sure it's a major mode's job to define the project.

Or else we'll get multiple different notions of the current project in 
the same directory.

Re: Major mode and implementation of expected editing facilities

[Clément Pit-Claudel]

On 2019-05-29 11:08, Dmitry Gutov wrote:
> On 29.05.2019 7:11, Clément Pit-Claudel wrote:
>> * Project: See project-find-functions
> 
> I'm not sure it's a major mode's job to define the project.
> 
> Or else we'll get multiple different notions of the current project in the same directory.

Thanks, that's useful feedback :)

Re: Major mode and implementation of expected editing facilities

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I agree it would be useful to have a list to guide people who
develop new majer modes.  It could be an incomplete list of characters
that some majer modes rebind, with an incomplete list of modes that
rebind each one.

We could separate it into two sublists.

1. Characters that are rebound with a mode-specific way
of doing the same job.

2. Characters that are rebound to do a totally different job
because their standard job is useless or meaningless in that mode.

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Major mode and implementation of expected editing facilities

[Daniele Nicolodi]

On 28-05-2019 08:55, Eli Zaretskii wrote:
>> From: Daniele Nicolodi <daniele@grinta.net>
>> Date: Mon, 27 May 2019 22:40:15 -0600
>>
>>   A major mode can also rebind the keys M-n, M-p and M-s. The bindings
>>   for M-n and M-p should normally be some kind of moving forward and
>>   backward, but this does not necessarily mean cursor motion.
>>
>>   It is legitimate for a major mode to rebind a standard key sequence if
>>   it provides a command that does the same job in a way better suited to
>>   the text this mode is used for. For example, a major mode for editing
>>   a programming language might redefine C-M-a to move to the beginning
>>   of a function in a way that works better for that language.
>>
>> in "Major Mode Conventions", which describes exactly what I want to do,
>> but does not give any pointer which key sequences it makes sense and it
>> is most common to rebind. For example I don't fins mention of M-q
>> (fill-paragraph) which was in my original example.
>>
>> Am I overlooking something?
> 
> Given the above text, I'm not sure I understand what are you looking
> for.  Clearly, what specific keys a major mode can reasonably rebind
> depends on the mode and what it does, right?  IOW, it's your decision,
> as someone who knows what the mode does, and which of its commands
> could be usefully regarded as "generalizations" or "customizations" of
> those in the related modes.

The text above mention four example of keybindings that make sense to
rebind in a mode: M-n, M-p, M-s, C-M-a. I'm surer this is not an
exhaustive list and I am also sure there are cases in which rebinding
the keys is not the right thing to do as in the case of M-q.

From your answer I understand that consistency in the "user interface"
of major modes is not a desirable thing or that emacs hackers want to
reserve for themselves the right to complain that new modes will not
follow the emacs way. I understand that the elders like to have
something to be grumpy about, but it does not invite new contributions.

By the way, what is M-s supposed to do? It is not bind in the couple of
modes I looked at.

Cheers,
Dan

Re: Major mode and implementation of expected editing facilities

[Noam Postavsky]

On Tue, 28 May 2019 at 15:52, Daniele Nicolodi <daniele@grinta.net> wrote:

> By the way, what is M-s supposed to do? It is not bind in the couple of
> modes I looked at.

I think it's a leftover that should be removed from that manual
section; from what I found in NEWS.23, M-s used to be bound in a few
modes but is now reserved for isearch and shouldn't be bound by major
modes (unless it's such a strange mode that using isearch in it
doesn't make sense, but that seems fairly unlikely).

** Shell (and other comint modes)
*** M-s is no longer bound to `comint-next-matching-input'.
[...]
** In Isearch mode, a special case of typing `C-w' at the beginning of
the minibuffer that toggles word search (i.e. using key sequences
`C-s RET C-w' or `C-s M-e C-w') is obsolete.  You can use the global key
`M-s w' to start word search, or type `M-s w' in Isearch mode to
toggle word search.  To start nonincremental word search you can now use
`M-s w RET' and `M-s w C-r RET' instead of `C-s RET C-w' and `C-r RET C-w'.
** In Info, `Info-search' is unbound from `M-s' to allow using `M-s w'
for word search as well as other search commands from the global prefix
key `M-s'.
** In Text mode, `center-line' and `center-paragraph' are rebound from
`M-s' and `M-S' to global keys `M-o M-s' and `M-o M-S' on the global
prefix map `M-o', which is intended for such formatting commands.

Re: Major mode and implementation of expected editing facilities

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@gmail.com>
> Date: Tue, 28 May 2019 16:20:36 -0400
> Cc: Eli Zaretskii <eliz@gnu.org>, Emacs developers <emacs-devel@gnu.org>
> 
> On Tue, 28 May 2019 at 15:52, Daniele Nicolodi <daniele@grinta.net> wrote:
> 
> > By the way, what is M-s supposed to do? It is not bind in the couple of
> > modes I looked at.
> 
> I think it's a leftover that should be removed from that manual
> section

I agree.

Re: Major mode and implementation of expected editing facilities

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Daniele Nicolodi <daniele@grinta.net>
> Date: Tue, 28 May 2019 13:52:35 -0600
> 
> The text above mention four example of keybindings that make sense to
> rebind in a mode: M-n, M-p, M-s, C-M-a. I'm surer this is not an
> exhaustive list and I am also sure there are cases in which rebinding
> the keys is not the right thing to do as in the case of M-q.

It is not an exhaustive list.  What I tried to explain is that an
exhaustive list is not really practical, because a lot depends on what
your mode does.

> >From your answer I understand that consistency in the "user interface"
> of major modes is not a desirable thing or that emacs hackers want to
> reserve for themselves the right to complain that new modes will not
> follow the emacs way. I understand that the elders like to have
> something to be grumpy about, but it does not invite new contributions.

I'm sorry that this was your understanding, because nothing is farther
from the truth.  All I wanted to say is that a lot depends on the mode
and on your best judgment.

Re: Major mode and implementation of expected editing facilities

[Clément Pit-Claudel]

On 2019-05-28 00:40, Daniele Nicolodi wrote:
> For example I don't fins mention of M-q (fill-paragraph) which was in my original example.

This is because major modes shouldn't rebind M-q; instead, they should set fill-paragraph-function.  I don't know of a good list of this a major-mode should redefine, so I sent one in a separate email.

Btw, this part of the manual looks wrong:

>   For example, a major mode for editing
>   a programming language might redefine C-M-a to move to the beginning
>   of a function in a way that works better for that language.

C-M-a invokes beginning-of-defun-function if available, so setting that variable is likely better than rebinding C-M-a.

Clément.

Re: Major mode and implementation of expected editing facilities

[Daniele Nicolodi]

On 28/05/2019 22:14, Clément Pit-Claudel wrote:
> On 2019-05-28 00:40, Daniele Nicolodi wrote:
>> For example I don't fins mention of M-q (fill-paragraph) which was
>> in my original example.>
> This is because major modes shouldn't rebind M-q; instead, they
> should set fill-paragraph-function.  I don't know of a good list of
> this a major-mode should redefine, so I sent one in a separate
> email.
That is what I meant. The existing documentation makes it look like the
right solution is to rebind keys, while in at least some cases that is
not the case.

Cheers,
Dan