`org-refile' doc string

`org-refile' doc string

[Štěpán Němec]

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?

Many thanks,

  Štěpán

Re: `org-refile' doc string

[Nick Dokos]

Š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

Re: `org-refile' doc string

[Štěpán Němec]

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

Re: `org-refile' doc string

[Nick Dokos]

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

> Nick Dokos <nicholas.dokos@hp.com> writes:
> 
> > ...
> > 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
> 

OK - here's a patch - mostly Štěpán's wording.

Thanks,
Nick

diff --git a/lisp/org.el b/lisp/org.el
index 9920504..748c140 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -9556,9 +9556,9 @@ Depending on `org-reverse-note-order', the new subitem will either be the
 first or the last subitem.
 
 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.
+However, the region must fulfill the requirement that all the included
+headings are on the same level as the first one or below (i.e. it must
+be a subtree or a sequence of subtrees.)
 
 With prefix arg GOTO, the command will only visit the target location,
 not actually move anything.

[PATCH] Clean up docstring for org-refile

[Bernt Hansen]

---
This commit is available at git://git.norang.ca/org-mode.git for-carsten

 lisp/org.el |    5 ++---
 1 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 0f69296..1eac6dc 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -9584,9 +9584,8 @@ Depending on `org-reverse-note-order', the new subitem will either be the
 first or the last subitem.
 
 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.
+However, the region must fulfill the requirement that the first heading
+is the top-level of the moved text - at most siblings below it are allowed.
 
 With prefix arg GOTO, the command will only visit the target location,
 not actually move anything.
-- 
1.7.1