Re: `org-refile' doc string

["Štěpán Němec" <stepnem@gmail.com>]

Nick Dokos <nicholas.dokos@hp.com> writes:

> Š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?

Clear enough for me to understand at least, thanks!
An alternative and more verbose wording could be something like:

  However, the region must fulfil the requirement that all the included
  headings are on the same level as the first one or below (i.e.
  a subtree or sequence of subtrees).

Best,

  Štěpán