Prefix arguments, checklists, and lists

Prefix arguments, checklists, and lists

[Robert Horn]

The keystroke bindings for lists need some examination and repair.  In 7.9.3 the situation is:

| Keystrokes          | First Item                        | Any other item            |
|---------------------+-----------------------------------+---------------------------|
| C-c C-c             | Toggle completion this item       | Toggle this item          |
| C-u C-c C-c         | Toggle checkbox on/off whole list | Toggle checkbox this item |
| C-u C-u C-c C-c     | Set in-progess whole list         | Set in-progress this item |
| M-- C-c C-c         | Toggle completion whole list      | Toggle this item          |
| M-- C-u C-c C-c     | Toggle completion whole list      | Toggle this item          |
| M-- C-u C-u C-c C-c | Toggle completion whole list      | Toggle this item          |


Is this what is really intended?  The present behavior has the odd result that there is no sequence to toggle presence of checkbox for the first item, and there is no sequence to set in-progress for the first item.  The first item must be manually edited.  (Or maybe there's another sequence that I haven't found.)

I think this is a bug.  But the intended behavior is unclear, and the proper fix is unclear. 

I personally find that I want to apply a change to individual items far more often than I want to change the whole list.  So I would pick the prefixes C-u and C-u C-u for the single item behavior in all cases, and add a different prefix to mean "apply to whole list".  Perhaps a numeric prefix of "-1"?  That's not unreasonably hard to type.  Then toggling checkbox presence for the whole list would be M-- C-u C-c C-c, and toggling the whole list for in-progress would be M-- C-u C-u C-c C-c.  The user mental model becomes "M-- means apply to whole list", which means tracking down any other relevant commands and fixing them too. The current implementation is close to this.


R Horn
rjhorn@alum.mit.edu

Re: Prefix arguments, checklists, and lists

[Nicolas Goaziou]

Hello,

Robert Horn <rjhorn@alum.mit.edu> writes:

> The keystroke bindings for lists need some examination and repair.  In 7.9.3 the situation is:
>
> | Keystrokes          | First Item                        | Any other item            |
> |---------------------+-----------------------------------+---------------------------|
> | C-c C-c             | Toggle completion this item       | Toggle this item          |
> | C-u C-c C-c         | Toggle checkbox on/off whole list | Toggle checkbox this item |
> | C-u C-u C-c C-c     | Set in-progess whole list         | Set in-progress this item |
> | M-- C-c C-c         | Toggle completion whole list      | Toggle this item          |
> | M-- C-u C-c C-c     | Toggle completion whole list      | Toggle this item          |
> | M-- C-u C-u C-c C-c | Toggle completion whole list      | Toggle this item          |
>
>
> Is this what is really intended? The present behavior has the odd
> result that there is no sequence to toggle presence of checkbox for
> the first item, and there is no sequence to set in-progress for the
> first item. The first item must be manually edited. (Or maybe there's
> another sequence that I haven't found.)
>
> I think this is a bug. But the intended behavior is unclear, and the
> proper fix is unclear.

I plan to rewrite C-c C-c using Elements, so the behaviour will slightly
change.

It will be better to discuss about checkboxes when this change is done.


Regards,

-- 
Nicolas Goaziou

Re: Prefix arguments, checklists, and lists

[Robert Horn]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> I plan to rewrite C-c C-c using Elements, so the behaviour will slightly
> change.
>
> It will be better to discuss about checkboxes when this change is done.
>

I've got no problem waiting, but it would be a good idea to figure out a
consistent non-contradictory key-binding in advance, so you can switch
to that when you make the other changes.

R Horn
rjhorn@alum.mit.edu

Re: Prefix arguments, checklists, and lists

[Nicolas Goaziou]

Hello,

Robert Horn <rjhorn@alum.mit.edu> writes:

> I've got no problem waiting, but it would be a good idea to figure out a
> consistent non-contradictory key-binding in advance, so you can switch
> to that when you make the other changes.

I made the change to the internals. Actually, there is no contradictory
key-bindings.

As a rule of thumb, C-c C-c on a list will operate on every top level
items and C-c C-c on a item will operate on the item. You are considered
to be on a list when calling C-c C-c from affiliated keywords or from
the very beginning of the first line in the first item. Note that
element-wise navigation (like M-{ and M-}) behaves the same.

As a convenient exception, since calling C-c C-c without argument on
a whole list does nothing, it will operate on the first item instead.

What do you find inconsistent?


Regards,

-- 
Nicolas Goaziou

Re: Prefix arguments, checklists, and lists

[Robert Horn]

Nicolas Goaziou writes:

> Hello,
>
> Robert Horn <rjhorn@alum.mit.edu> writes:
>
> As a rule of thumb, C-c C-c on a list will operate on every top level
> items and C-c C-c on a item will operate on the item. You are considered
> to be on a list when calling C-c C-c from affiliated keywords or from
> the very beginning of the first line in the first item. Note that
> element-wise navigation (like M-{ and M-}) behaves the same.
>

This is different than your initial response, and still needs to be
documented.  My major concern (and the bug that Bastien fixed) was that
it was applying the whole list logic whenever the point was on the first
*item* of the list.  Restricting it to being different when on the first
*character of the first item* is different, and at least allows the
commands to be used on the first line.

I still think it's poor user interface design.  The impact when you go
through the documentation for each command and add "... except when on
the first character of the first item of the list, in which case the
behavior is ...." may make this clear.  The user has to add that into
their thought processes when using lists.  This constant side nag of
"where am I on this line? which item am I on?" is an indication of a
user interface problem.

The other times that emacs and org-mode care about where you are on the
line are situations where you are directly editing and changing the
contents of the line.  It feels natural to pay attention to the location
on the line when editing the text.  And, even then, the change is
restricted to that location on the line.  It is only when using a
prefixed commands that the changes affect other locations.

That's why I prefer using a different prefix to mean "whole list".  That
leaves all of the list related commands that affect the current item to
be C-u prefixed.  If you have a different prefix that means "whole
list", you eliminate the "where is the point?" mental effort.  It adds
the ability to have that different prefix enable "whole list" when on
any item in any location in the list.

R Horn
rjhorn@alum.mit.edu

Re: Prefix arguments, checklists, and lists

[Nicolas Goaziou]

Hello,

Robert Horn <rjhorn@alum.mit.edu> writes:

> Nicolas Goaziou writes:
>>
>> As a rule of thumb, C-c C-c on a list will operate on every top level
>> items and C-c C-c on a item will operate on the item. You are considered
>> to be on a list when calling C-c C-c from affiliated keywords or from
>> the very beginning of the first line in the first item. Note that
>> element-wise navigation (like M-{ and M-}) behaves the same.
>>
>
> This is different than your initial response, and still needs to be
> documented.

Certainly. Help is welcome, too.

> I still think it's poor user interface design.  The impact when you go
> through the documentation for each command and add "... except when on
> the first character of the first item of the list, in which case the
> behavior is ...." may make this clear.

There's no point in adding it for each command. The list and item
boundaries just need to be defined once. Then, each command that behaves
differently on a list and on an item will have a documentation along the
lines of: "When at a list, do this. When at an item, do that."

> The user has to add that into their thought processes when using
> lists. This constant side nag of "where am I on this line? which item
> am I on?" is an indication of a user interface problem.
>
> The other times that emacs and org-mode care about where you are on the
> line are situations where you are directly editing and changing the
> contents of the line.  It feels natural to pay attention to the location
> on the line when editing the text.  And, even then, the change is
> restricted to that location on the line.  It is only when using a
> prefixed commands that the changes affect other locations.

I think you are wrong. Org is all about context.

Think about speed commands: you have to be on the first character of
a headline to trigger them. Think about "M-RET": it will add a headline
before the current one if the point is at its very beginning. Think
about "C-c C-c". You hardly control it with prefixes: it acts according
to the location of point in the buffer.

I don't know if it's a user interface problem. I do like it, though. You
just have to _look_ for context, while you have to _think_ about the
right prefix to use. I must be faster at looking than at thinking,
I guess.

Anyway, to put it clearly, the syntax introduced in this situation
didn't come out of nowhere. It followed the same logic as the rest of
Org, really.

> That's why I prefer using a different prefix to mean "whole list".  That
> leaves all of the list related commands that affect the current item to
> be C-u prefixed.  If you have a different prefix that means "whole
> list", you eliminate the "where is the point?" mental effort.  It adds
> the ability to have that different prefix enable "whole list" when on
> any item in any location in the list.

To really understand where it comes from, you have to forget about lists
for a while. You even have to forget about C-c C-c. Let's talk about
`org-forward-element' ("M-}") instead.

In the following example `org-forward-element' on the first paragraph
will move point on the second paragraph. All good and logical.

--8<---------------cut here---------------start------------->8---
This is the first paragraph

This is the second paragraph
--8<---------------cut here---------------end--------------->8---

If we add attributes to the first paragraph, as in the next example,
`org-forward-element' on the first paragraph (even on its attribute)
will unsurprisingly move point on the other one.

--8<---------------cut here---------------start------------->8---
#+NAME: para1
This is the first paragraph

This is the second paragraph
--8<---------------cut here---------------end--------------->8---

Now, we replace the first paragraph with a two-row table. If we stay
consistent, `org-forward-element' on the attribute line of the table
should move point on the paragraph, and so it does.

--8<---------------cut here---------------start------------->8---
#+NAME: table1
| a | b |
| c | d |

This is the second paragraph
--8<---------------cut here---------------end--------------->8---

But what if we remove that attribute line? Assuming point is on the
table's first row, should `org-forward-element' move it onto the next
paragraph or the second row?

--8<---------------cut here---------------start------------->8---
| a | b |
| c | d |

This is the second paragraph
--8<---------------cut here---------------end--------------->8---

We can move to the next row and add a prefix to "M-{", in order to skip
the whole table, much like what you suggest for lists. But what about
the table with the attribute line? There, an un-prefixed command will
still skip a table, or it won't be compliant with the example before it.

So what we really get is a prefixed command that behaves differently
according to context. In my book, it means we lose on both sides.

Now, let's look again at the same example, with point on the paragraph
this time.

--8<---------------cut here---------------start------------->8---
| a | b |
| c | d |

This is the second paragraph
--8<---------------cut here---------------end--------------->8---

Even in a poor user interface design (!), it is not unreasonable to
imagine that `org-forward-element' and `org-backward-element' have
opposite effects. So, basically, `org-backward-element' +
`org-forward-element'[1] should keep point on the same element.

`org-backward-element' moves point to the first character in the table.
Since `org-forward-element' has to bring it back to the paragraph, this
is no rocket science to say it should skip the whole table. Question
answered. We don't have to add a prefix either, and we get the rest of
the line to operate on the row. It is also consistent if there is
a prefix line.

We can generalize a bit: a command called on the very first character of
an element is expected to operate at the container level, not at the
contents level.

What about lists? Just replace "table" with "list" and "row" with
"item". This is a global design, and lists are but a part of it.

Also you can dislike this interface. At least, you know there are
reasons for it.


Regards,

[1] If point is at the beginning of an element. Otherwise, the first
call to `org-backward-element' will move it there.

-- 
Nicolas Goaziou

Re: Prefix arguments, checklists, and lists

[Bastien]

Hi Robert and Nicolas,

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> What about lists? Just replace "table" with "list" and "row" with
> "item". This is a global design, and lists are but a part of it.

Agreed.  And Org commands are so much about context that users could
benefit from a "command helper": a library that would display what
function C-c C-c will call depending on the context.

My understanding is that Robert's concern is more about
discoverability than global design inconsistency.  So perhaps 
such a library would lower his concern.

2 cts,

-- 
 Bastien