Re: [PATCH] Add mode for automatically unhiding emphasis markers in the current region

[Gustavo Barros]

Hi Nicolas,
Hi All,

On Sun, 05 Jul 2020 at 07:50, Nicolas Goaziou <mail@nicolasgoaziou.fr> 
wrote:

> The problem is not your implementation, really. It's just that I don't
> think it should be the _built-in_ way to solve emphasis 
> management. IOW,
> we shouldn't need to activate a minor mode to make that management
> tolerable in the first place.
>
> However, I agree that it makes senses as an extension, in the same 
> vein
> as `org-fragtog` for LaTeX fragments.

[...]

> But, really, I think an option like `org-hide-emphasis-markers' is
> a one-off toggle. Having to, in a way, switch regularly between two
> values is sub-optimal.

I don't think I have anything to add to the previous discussion on this 
matter, and I know you took it into consideration.  Also, I'm well aware 
that sometimes a user interested in a feature lacks a more general 
perspective a maintainer has.  So I take your position here stems from 
one such general design choices, and I understand and respect it.

> Here it is.
>
> The main command is `org-emphasis'. It emphasizes the minimal possible
> area around point, or region. If there's already an emphasis object of
> the desired type around point or region, it extends it forward 
> instead.
> With a prefix argument, it removes the emphasis.
>
> Interactively, the command asks for the type of emphasis to use, but
> I suggest to use dedicated commands instead. Thus, I added a 
> key-binding
> for each of the six emphasis types. For example, for bold, use
>
>       `M-o *'    or    `M-o M-*'
>
> There are equivalent commands for underline (`M-o _` or `M-o M-_'), 
> and
> so on.
>
> Note there, even though I polished it, there are probably some 
> glitches
> left, but it works well enough to give an idea. Tests are missing, 
> too.
>
> Please evaluate the following code to try it.

This is really, really nice.  Certainly a major improvement in the way 
`org-emphasize' works.  I specially like you've chosen to make it act on 
the element around point, that you added the possibility of increasing 
this scope with repetition, and that you made the functions commands we 
can bind.

If I may, I'd like to add comments and report tests, for your 
consideration, in the spirit of trying to help you polish the approach.

One low hanging fruit, which you probably have already considered, is to 
use a transient keymap to ease the repetition of the emphasis commands. 
So that we could type `M-o * * * *' to emphasize four words, instead of 
`M-o * M-o * M-o * M-o *'.  Even better if in this keymap we could call 
a command, bound e.g. to `-', to go back one step in case we have gone 
too far in the repetition.  This is interesting in itself, but specially 
so given a number of the markers are shift-keys, which means the first 
and the second part of the bindings use different modifiers, making the 
repetition quite "athletic" (I suppose we could use "M-O", but still).

A second thing is regarding the removal of the markers.  I think there 
is space to simplify this further and make it even more convenient.  As 
things are, we have six different bindings to remove an emphasis marker 
around point.  Of course, when adding emphasis, we have to specify which 
one we want, but when removing it, the markers are already there and we 
know what is the emphasis around point, and can go with a single 
command, e.g. `org-remove-emphasis', and a single binding, e.g. `M-o 
r/M-r', without the cognitive load of having to identify visually which 
is the marker, to call the correct command to remove it.  The only case 
not covered by this would be if we have nested emphasis of different 
types and want to remove the outer one.  I'd say this is rare enough to 
leave uncovered in exchange for the simplification of 6 to 1 commands 
for emphasis removal.  True, this seventh command could just be added, 
and leave the current six as they are, but I do have a suggestion for 
another use of the prefix, which see.  (Perhaps an argument similar to 
the one being made here for removal could be made for extending 
emphasis, but I'm not sure if with the same relevance).

Still regarding emphasis removal, I see two things one might want when 
"removing" emphasis: one is to remove the whole emphasis around point, 
the other is to remove part of an existing emphasized region, doing the 
analogous of what your six emphasis commands do, but removing emphasis 
one word at a time.  If this distinction is deemed useful and worth 
implementing, how about `org-remove-emphasis' with no prefix doing the 
first, and with prefix doing the second?

A third thing I think is worth considering is the direction of 
extension, given that `org-emphasize' also works by extending an 
existing emphasized region.  Two things here:  should one be able to 
control the direction the expansion occurs?  what should be the 
preferred (or only) expansion direction?  I'd say the first one would be 
really nice, and I'd suggest using the prefix to the six emphasis 
commands to achieve it ("prefix changes the default direction").  As to 
the second, I'd go for preferring a backwards expansion, rather than a 
forwards one.  My reasoning here is that one would be adding emphasis 
either while skimming/navigating through an existing document, in which 
case one has more freedom in point placement, or when one is typing, in 
which case moving point implies that we must get back to where we were 
before continuing typing.  So for this "while typing" situation a 
backward expansion would be much more useful, while for the case of 
"adding emphasis to existing text" the direction would be less 
important.  I take that's the reason `flyspell' has 
`flyspell-auto-correct-previous-word' while it does not have a "next" 
equivalent, and why `flyspell-correct' (the package) defaults to 
correcting the previous misspelling.

A fourth issue is point placement after the emphasis is added. 
`org-emphasis' takes a stance here and places point within the emphasis. 
I do agree with this option, but it is still true that sometimes, one 
might want or need otherwise.  This, of course, gets more interesting 
when `org-hide-emphasis-markers' is t.  And I actually think this issue 
is still more general.  One thing is to "add emphasis markers to 
existing text", another is "adding text around existing emphasis 
markers".  The first one is superbly dealt with by this implementation 
of `org-emphasize', the second one, as far as I can see, not equally so.

Finally, as I took it for a spin, I might as well report some cases 
which called my attention.  I know you said this isn't ready yet, but I 
hope it is still useful.  In the examples, '|' represents point, and '·' 
space.

1) When point is at the right-edge of a word, the emphasis command will 
either emphasize the following word, if there is one before eol, or 
error with "Nothing to emphasize in the region" even though there is no 
active region.  If there is only whitespace between point and eol the 
emphasis command will issue the same error and move point to eol. 
Illustrations:

Starting from:

#+begin_src org
foo|·bar
#+end_src

`M-o *' results in:

#+begin_src org
foo·*|bar*
#+end_src

(note point has moved)

Starting from:

#+begin_src org
foo·bar|
#+end_src

`M-o *' errors with "Nothing to emphasize in the region".

Starting from:

#+begin_src org
foo·bar|···
#+end_src

`M-o *' errors with "Nothing to emphasize in the region" and moves point 
to:

#+begin_src org
foo·bar···|
#+end_src

I suggest it would make sense, when at a word right boundary, to 
emphasize the immediately preceding word rather than the next one. 
Though this is probably somewhat a matter of preference, I'd argue it is 
more intuitive.  On the other hand, the last case, where the command 
issues an error, does not apply emphasis and moves point, is clearly 
unexpected behavior (it should at least not move point).

2) When point is within whitespace, with no "word" at point, it still 
emphasizes the next word, if there is one.  Illustration:

Starting from:

#+begin_src org
foo·|·bar
#+end_src

`M-o *' results in:

#+begin_src org
foo··*|bar*
#+end_src

(note point has moved)

I would expect to get instead:

#+begin_src org
foo·*|*·bar
#+end_src

Starting from an empty line (or a "whitespace only" line):

#+begin_src org
|
#+end_src

We get error "Cannot emphasize contents here". But why not?

#+begin_src org
*|*
#+end_src

And be able to insert some content "to be bold".

Indeed, if the right boundary logic above is used, and this within 
whitespace one is also used, then point never needs to move when 
applying emphasis "around point", which seems sensible to me.  (I 
haven't given proper thought on what to do with point/region when region 
is active though.)  Also, as far as I can tell, it would also never fall 
back to "Nothing to emphasize in the region", which indeed is somewhat 
strange when no region is active.  The general idea is, if no "minimal 
area around region or point" can be identified, place the markers around 
point, instead of returning error.


That said, I reiterate I really consider this revamping of 
`org-emphasize' a major improvement, and a very welcome one.  And I 
thank you very much for that.  My comments here are just offered for 
your consideration and use as you see fit, in the hope they might be 
useful.  And I'm looking forward to see this reach distribution.

Best,
Gustavo.