From mboxrd@z Thu Jan  1 00:00:00 1970
From: =?utf-8?B?xaB0xJtww6FuIE7Em21lYw==?= <stepnem@gmail.com>
Subject: Re: `org-refile' doc string
Date: Wed, 28 Apr 2010 22:32:31 +0200
Message-ID: <87och3gvxc.fsf@gmail.com>
References: <87sk6fh1ny.fsf@gmail.com> <10381.1272481004@alphaville.usa.hp.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Return-path: <emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org>
Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43)
	id 1O7DvM-0004XS-AS
	for emacs-orgmode@gnu.org; Wed, 28 Apr 2010 16:32:00 -0400
Received: from [140.186.70.92] (port=45054 helo=eggs.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.43) id 1O7DvJ-0004TC-7z
	for emacs-orgmode@gnu.org; Wed, 28 Apr 2010 16:31:58 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69)
	(envelope-from <stepnem@gmail.com>) id 1O7DvH-0001uf-4z
	for emacs-orgmode@gnu.org; Wed, 28 Apr 2010 16:31:56 -0400
Received: from fg-out-1718.google.com ([72.14.220.156]:9242)
	by eggs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <stepnem@gmail.com>) id 1O7DvG-0001uT-SA
	for emacs-orgmode@gnu.org; Wed, 28 Apr 2010 16:31:55 -0400
Received: by fg-out-1718.google.com with SMTP id e21so2280035fga.12
	for <emacs-orgmode@gnu.org>; Wed, 28 Apr 2010 13:31:54 -0700 (PDT)
In-Reply-To: <10381.1272481004@alphaville.usa.hp.com> (Nick Dokos's message of
	"Wed, 28 Apr 2010 14:56:44 -0400")
List-Id: "General discussions about Org-mode." <emacs-orgmode.gnu.org>
List-Unsubscribe: <http://lists.gnu.org/mailman/listinfo/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/pipermail/emacs-orgmode>
List-Post: <mailto:emacs-orgmode@gnu.org>
List-Help: <mailto:emacs-orgmode-request@gnu.org?subject=help>
List-Subscribe: <http://lists.gnu.org/mailman/listinfo/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=subscribe>
Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org
Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org
To: nicholas.dokos@hp.com
Cc: emacs-orgmode@gnu.org

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

> =C5=A0t=C4=9Bp=C3=A1n N=C4=9Bmec <stepnem@gmail.com> wrote:
>
>>=20
>> In the documentation of `org-refile' we read:
>>=20
>>   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 siblin=
gs
>>   below it are allowed.
>>=20
>>=20
>> I completely fail at parsing the second sentence. Could please someone
>> who knows what it's trying to say fix it?
>>=20
>
> 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 on=
ly
> 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,

  =C5=A0t=C4=9Bp=C3=A1n