unified heading completion and cycling

[anarcat]

right now, in markdown-mode, you can use three different commands/keybindings to operate on headings:

• C-c C-]: markdown-complete
• C-c C--: markdown-promote
• C-c C-+: markdown-demote

I find this a little confusing and cumbersome. In comparison, the ReST edit mode has this keybinding:

• C-=: rst-adjust

rst-adjust is "smart": it will behave like markdown-complete if the heading is not complete yet, then if it is, it will cycle through heading styles (i guess the equivalent of markdown-demote).

Another thing that rst-complete does that is missing from markdown-complete is the possibility of adding headings to arbitrary text. Right now, if I call markdown-complete on a line that has no markup at all, I get Nothing to complete at point. It would be nice to simply add a heading similar to the surrounding ones instead.

It would be great to have an equivalent of rst-adjust in markdown-mode. To have it bound ti C-= is a bonus that i could do myself of course, but before working on a patch I figured I would ask here first. I am otherwise generally finding markdown-mode to be superior to the ReST mode in most points, and I especially enjoy the discoverability it offers through the menu system.

Thanks for this great mode!

[jrblevin]

Thanks for suggesting this. I have the sense that the current cycling, promotion, demotion, and completion stuff is unnecessarily complex, so I like the overall idea. At the same time, but I'm also not sure if one keybinding (like rst-adjust) can handle everything? I see that rst-adjust uses a negative argument, but I also like having C-c C-- and C-c C-= being adjacent keys.

I'm open to suggestions that take into account all of the other things that markdown-promote/demote do. Cycling bold and italics is certainly no problem with one key. List items are more complicated: maybe we stop "demoting" at the point where the indentation would be such that it would become a code block (four spaces past the parent indentation) and restart at the top level?

Another thing is that some people don't want to "complete" the heading markup. There is a setting markdown-asymmetric-header that markdown-complete doesn't currently honor. If completion and cycling are combined, then that setting should be honored: atx header completion should be bypassed if that variable is non-nil.

I know that rst-mode adds the C-= binding, but that might be problematic. See the Emacs Key Binding Conventions and GH-164. That being said, some documentation suggesting that users can re-bind to C-= if desired would be great.

Keeping markdown-complete at C-c C-] for the time being is probably safest. If a unification is possible, maybe it can be moved to C-c C-= and made to accept a negative argument, like rst-adjust. Then C-c C-- could be an alias for C-- C-c C-=, for backwards compatibility.

This is getting long, but another possible difference is that markdown-promote promotes entire atx heading subtrees, not just the heading at the point (as I assume rst-adjust does?), while markdown-complete works on the heading at the point.

[jrblevin]

Maybe it would a good idea to first sketch out the current behavior and proposed new behavior in the various contexts (when the point is at text with no markup, heading, list item, bold/italic, etc.).

[anarcat]

At the same time, but I'm also not sure if one keybinding (like rst-adjust) can handle everything?

Sure looks like it when reviewing your comment here. :)

I see that rst-adjust uses a negative argument, but I also like having C-c C-- and C-c C-= being adjacent keys.

Sure, whatever is good for you - i can override this on my side. Discoverability is the key here.

I'm open to suggestions that take into account all of the other things that markdown-promote/demote do. Cycling bold and italics is certainly no problem with one key. List items are more complicated: maybe we stop "demoting" at the point where the indentation would be such that it would become a code block (four spaces past the parent indentation) and restart at the top level?

That makes sense, for sure.

Another thing is that some people don't want to "complete" the heading markup. There is a setting markdown-asymmetric-header that markdown-complete doesn't currently honor. If completion and cycling are combined, then that setting should be honored: atx header completion should be bypassed if that variable is non-nil.

That sounds like a bug that's orthogonal with this feature request, no? I mean you have that problem right now anyways...

I know that rst-mode adds the C-= binding, but that might be problematic. See the Emacs Key Binding Conventions and GH-164. That being said, some documentation suggesting that users can re-bind to C-= if desired would be great.

Yeah, okay. Note that the "Convention" doesn't mention anything about top-level keybindings, that seems to be something restricted to a comment in GH-164... But I've always wondered about that..

Keeping markdown-complete at C-c C-] for the time being is probably safest. If a unification is possible, maybe it can be moved to C-c C-= and made to accept a negative argument, like rst-adjust. Then C-c C-- could be an alias for C-- C-c C-=, for backwards compatibility.

Yah, that makes sense.

This is getting long, but another possible difference is that markdown-promote promotes entire atx heading subtrees, not just the heading at the point (as I assume rst-adjust does?), while markdown-complete works on the heading at the point.

rst-adjust works only on the heading at point, and i would prefer markdown-complete/promote to do the same.

Maybe it would a good idea to first sketch out the current behavior and proposed new behavior in the various contexts (when the point is at text with no markup, heading, list item, bold/italic, etc.).

Didn't you just do exactly that? :)

(BTW: what is the markup for keybindings here? can't find it in the GFM documentation. I also didn't know you could use GH-NNN for issues, that's neat!)