On 12/6/2021 4:55 AM, Eli Zaretskii wrote:
> I think the most natural place is where we describe how to construct
> menus.

Thanks.

>> We can detect whether an item is a separator pretty easily without this
>> change. However, context menu functions use specific separators to
>> determine where exactly it should put new menu items. For example,
>> `elisp-context-menu' adds menu items after `middle-separator':
>>
>>       (define-key-after menu [elisp-separator] menu-bar-separator
>>         'middle-separator)
>>
>> (Later in the function, it adds the actual menu items after the
>> newly-added `elisp-separator'.)
> 
> If this is a private convention of elisp-mode, we don't have to codify
> it.

It's not just for `elisp-mode'; any mode (or other third-party code) may 
want to insert context menu items in a certain spot. `middle-separator' 
follows the naming convention I recommend, but a hypothetical mode might 
want to insert a new item just after the separator for the Undo section. 
However, that's currently named `separator-undo' on master, so it can be 
confusing to remember the difference in naming between these two cases:

   (define-key-after menu [my-separator] menu-bar-separator
     'middle-separator)

   (define-key-after menu [my-separator] menu-bar-separator
     'separator-undo)

> So maybe instead of conventions we should have recommendations, with
> explanation why following that could be useful in some situation.
> Then let Lisp programmers decide what they want.

Ok, I've tried to provide a brief explanation of the recommendation and 
the reasoning for it without *over*-explaining it. I also added a small 
explanation about how to use `menu-bar-separator', since I didn't see 
documentation on that in the manual, and it helped segue into an 
explanation about the naming recommendation.