missing from the manual

missing from the manual

[Peter Mao]

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

Dear maintainers,

The following commands are missing from the manual!

org-forward-element
org-backward-element

These two should be mentioned in the manual in section 2.3 "Motion"

I just found them via the *HELP* page for org mode (by accident).  I
thought nothing like them existed in org mode, so I had my own (less well
crafted) commands.

Peter

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

Re: missing from the manual

[Marcin Borkowski]

On 2022-12-24, at 03:43, Peter Mao <peter.mao@gmail.com> wrote:

> Dear maintainers,
>
> The following commands are missing from the manual!
>
> org-forward-element
> org-backward-element
>
> These two should be mentioned in the manual in section 2.3 "Motion"

How are they different from `org-forward-heading-same-level` and
`org-backward-heading-same-level'?  (Not irony etc., I'm genuinely
curious.)

Best,

-- 
Marcin Borkowski
http://mbork.pl

Re: missing from the manual

[Ihor Radchenko]

Marcin Borkowski <mbork@mbork.pl> writes:

>> org-forward-element
>> org-backward-element
>>
>> These two should be mentioned in the manual in section 2.3 "Motion"
>
> How are they different from `org-forward-heading-same-level` and
> `org-backward-heading-same-level'?  (Not irony etc., I'm genuinely
> curious.)

They work on paragraphs, lists, blocks, etc.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: missing from the manual

[Peter Mao]

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

Also, it moves you to an outer level if you are at an end.

For my own use, because I want the command to treat the first item in a
list the same way as the others (when moving forward), I tweaked
org-forward-element from
(let* ((elem (org-element-at-point))

to:
(let* ((elem (progn
                        (when (equal (car (org-element-at-point))
'plain-list)
                          (forward-char))
                        (org-element-at-point)))

The "backward" version behaves exactly as I would like it to.

Peter

On Sun, Dec 25, 2022 at 12:19 AM Ihor Radchenko <yantar92@posteo.net> wrote:

> Marcin Borkowski <mbork@mbork.pl> writes:
>
> >> org-forward-element
> >> org-backward-element
> >>
> >> These two should be mentioned in the manual in section 2.3 "Motion"
> >
> > How are they different from `org-forward-heading-same-level` and
> > `org-backward-heading-same-level'?  (Not irony etc., I'm genuinely
> > curious.)
>
> They work on paragraphs, lists, blocks, etc.
>
> --
> Ihor Radchenko // yantar92,
> Org mode contributor,
> Learn more about Org mode at <https://orgmode.org/>.
> Support Org development at <https://liberapay.com/org-mode>,
> or support my work at <https://liberapay.com/yantar92>
>

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

Re: missing from the manual - move commands

[Max Nikulin]

On 24/12/2022 09:43, Peter Mao wrote:
> The following commands are missing from the manual!
> 
> org-forward-element
> org-backward-element

I think, the manual was written with assumption that Emacs users are 
familiar with C-up, M-{, C-down, M-} keystrokes.

> These two should be mentioned in the manual in section 2.3 "Motion"

A as person for whom Emacs is almost solely a note taking application 
(thanks to Org), I do not mind. Perhaps the relevant section from Emacs 
should be mentioned as well.

Someone should take the challenge to extend the info "(org) Motion" 
section in a way informative for novices and not boring for experienced 
Emacs users and to emphasize difference of (maybe familiar) shortcuts 
from the fundamental mode.

Re: missing from the manual - move commands

[Peter Mao]

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

On Mon, Dec 26, 2022 at 7:03 AM Max Nikulin <manikulin@gmail.com> wrote:

> On 24/12/2022 09:43, Peter Mao wrote:
> > The following commands are missing from the manual!
> >
> > org-forward-element
> > org-backward-element
>
> I think, the manual was written with assumption that Emacs users are
> familiar with C-up, M-{, C-down, M-} keystrokes.
>
Not everyone uses all of the motion commands.  I've been using emacs since
v18, and forward-paragraph and backward-paragraph have never been part of
my repertoire.

In addition, M-right and M-left, which I have used a lot outside of org,
for decades, behave differently in org, so the existence of motion commands
that are common in emacs (outside of org) do not guarantee an equivalent
inside of org.  BTW, I think M-f and M-b are better anyways, but decades of
muscle memory die hard.

Peter

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

[TODO] Document org-forward-element and org-backward-element in the manual (was: missing from the manual)

[Ihor Radchenko]

Peter Mao <peter.mao@gmail.com> writes:

> Dear maintainers,
>
> The following commands are missing from the manual!
>
> org-forward-element
> org-backward-element
>
> These two should be mentioned in the manual in section 2.3 "Motion"

I think we all agreed that it will be a welcome addition.
This also sounds like something others can easily contribute by editing
doc/org-manual.org. Patches welcome!

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>