emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* `org-refile' doc string
@ 2010-04-28 18:28 Štěpán Němec
  2010-04-28 18:56 ` Nick Dokos
  2010-04-28 21:45 ` [PATCH] Clean up docstring for org-refile Bernt Hansen
  0 siblings, 2 replies; 5+ messages in thread
From: Štěpán Němec @ 2010-04-28 18:28 UTC (permalink / raw)
  To: emacs-orgmode


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

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: `org-refile' doc string
  2010-04-28 18:28 `org-refile' doc string Štěpán Němec
@ 2010-04-28 18:56 ` Nick Dokos
  2010-04-28 20:32   ` Štěpán Němec
  2010-04-28 21:45 ` [PATCH] Clean up docstring for org-refile Bernt Hansen
  1 sibling, 1 reply; 5+ messages in thread
From: Nick Dokos @ 2010-04-28 18:56 UTC (permalink / raw)
  To: =?utf-8?B?xaB0xJtww6FuIE7Em21lYw==?=; +Cc: nicholas.dokos, emacs-orgmode

Š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

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: `org-refile' doc string
  2010-04-28 18:56 ` Nick Dokos
@ 2010-04-28 20:32   ` Štěpán Němec
  2010-04-28 21:04     ` Nick Dokos
  0 siblings, 1 reply; 5+ messages in thread
From: Štěpán Němec @ 2010-04-28 20:32 UTC (permalink / raw)
  To: nicholas.dokos; +Cc: emacs-orgmode

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

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: `org-refile' doc string
  2010-04-28 20:32   ` Štěpán Němec
@ 2010-04-28 21:04     ` Nick Dokos
  0 siblings, 0 replies; 5+ messages in thread
From: Nick Dokos @ 2010-04-28 21:04 UTC (permalink / raw)
  To: carsten.dominik, =?utf-8?B?xaB0xJtww6FuIE7Em21lYw==?=
  Cc: nicholas.dokos, emacs-orgmode

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

^ permalink raw reply related	[flat|nested] 5+ messages in thread

* [PATCH] Clean up docstring for org-refile
  2010-04-28 18:28 `org-refile' doc string Štěpán Němec
  2010-04-28 18:56 ` Nick Dokos
@ 2010-04-28 21:45 ` Bernt Hansen
  1 sibling, 0 replies; 5+ messages in thread
From: Bernt Hansen @ 2010-04-28 21:45 UTC (permalink / raw)
  To: emacs-orgmode; +Cc: 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

^ permalink raw reply related	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2010-04-28 21:45 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2010-04-28 18:28 `org-refile' doc string Štěpán Němec
2010-04-28 18:56 ` Nick Dokos
2010-04-28 20:32   ` Štěpán Němec
2010-04-28 21:04     ` Nick Dokos
2010-04-28 21:45 ` [PATCH] Clean up docstring for org-refile Bernt Hansen

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).