Re: `org-refile' doc string

[Nick Dokos <nicholas.dokos@hp.com>]

Štěpán Němec <stepnem@gmail.com> wrote:

> 
> In the documentation of `org-refile' we read:
> 
>   If there is an active region, all entries in that region will be moved.
>   However, the region must fulfil the requirement that the first heading
>   is the first one sets the top-level of the moved text - at most siblings
>   below it are allowed.
> 
> 
> I completely fail at parsing the second sentence. Could please someone
> who knows what it's trying to say fix it?
> 

What's the problem? It's crystal clear! :-)

But seriously, I think what's it's trying to say is that you can't just
select an arbitrary region of the org file and refile it: it has to
satisfy some constraints. For example, if you start at a level 2 headline,
the region cannot then include a level 1 headline further down; it can only
include level 2 and lower headlines.

The error message from the function when you try something illegal is
much clearer than the long explanation above:

  "The region is not a (sequence of) subtree(s)"

Maybe the doc string should say:

  ... However, the region must satisfy some constraints: it has to be
  a subtree (or a sequence of subtrees).

Would that be clear enough?

Nick