Re: [O] Bug: Several small documentation problems [8.3.6 (8.3.6-4-g4835be-elpaplus @ /home/jorge/.emacs.d/elpa/org-plus-contrib-20160926/)]

[Nicolas Goaziou]

Hello,

Jorge <address@hidden> writes:

> This is the first batch of documentation problems.  I will report the rest
> later, because preparing this first batch already took several hours.

Those are fixed, except the points below.

>   • When describing the behavior with C-u C-u, it wrongly substitutes
>     "grandparent" for "parent".

I think "grandparent" is correct. In the following document

  * H1
  ** H2
  Text<--point

"H2" is the parent headline of "Text" and as a consequence, "H1" is its
grandparent.

> • [info:org#Structure editing]
>   I looked at the code, and C-<RET> (org-insert-heading-respect-content) just
>   calls (org-insert-heading '(4) invisible-ok), so it has the same effect as
>   C-u M-<RET>.  The manual could mention that C-<RET> has the same effect as
>   C-u M-<RET>, to aid the user's learning process, as she would just need to
>   memorize this quick fact, instead of understanding both behaviors and
>   deducing they're equal).  Also the manual doesn't adequately explain the
>   effect of C-u M-<RET>.  And the description of C-<RET> is actually wrong:
>         Just like `M-<RET>', except when adding a new heading below the
>         current heading, the new heading is placed after the body instead
>         of before it.  This command works from anywhere in the entry.
>   /After the body/?  Doesn't it mean /after the entry/?  Besides, there are
>   additional differences: that M-<RET> may create a new plain list item, while
>   C-<RET> always creates a new heading, and that C-<RET> never splits the
>   heading.  Please rewrite the whole description.

You are right, M-RET and C-RET are confusing, and making C-u M-RET
a duplicate of C-RET is wasting some important keybinding. This was
discussed on this ML already (with Rasmus) but led nowhere so far.

In any case, it is more future-proof to not insist on the fact that
C-RET is C-u M-RET.

Thank you for this tedious, yet very important work.

Regards,

-- 
Nicolas Goaziou