From mboxrd@z Thu Jan  1 00:00:00 1970
From: Nick Dokos <nicholas.dokos@hp.com>
Subject: Re: `org-refile' doc string
Date: Wed, 28 Apr 2010 14:56:44 -0400
Message-ID: <10381.1272481004@alphaville.usa.hp.com>
References: <87sk6fh1ny.fsf@gmail.com>
Reply-To: nicholas.dokos@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 1O7CUK-00078W-5o
	for emacs-orgmode@gnu.org; Wed, 28 Apr 2010 15:00:00 -0400
Received: from [140.186.70.92] (port=34798 helo=eggs.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.43) id 1O7CUE-00071r-Lm
	for emacs-orgmode@gnu.org; Wed, 28 Apr 2010 14:59:57 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69)
	(envelope-from <nicholas.dokos@hp.com>) id 1O7CRD-0008SZ-Vb
	for emacs-orgmode@gnu.org; Wed, 28 Apr 2010 14:56:49 -0400
Received: from g6t0187.atlanta.hp.com ([15.193.32.64]:2848)
	by eggs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <nicholas.dokos@hp.com>) id 1O7CRD-0008SE-Su
	for emacs-orgmode@gnu.org; Wed, 28 Apr 2010 14:56:47 -0400
In-Reply-To: Message from =?us-ascii?Q?=3D=3Futf-8=3FB=3FxaB0xJtww6FuIE7Em?=
	=?us-ascii?Q?21lYw=3D=3D=3F=3D?= <stepnem@gmail.com>
	of "Wed\, 28 Apr 2010 20\:28\:33 +0200." <87sk6fh1ny.fsf@gmail.com>
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: =?us-ascii?Q?=3D=3Futf-8=3FB=3FxaB0xJtww6FuIE7Em21lYw=3D=3D=3F=3D?= <stepnem@gmail.com>
Cc: nicholas.dokos@hp.com, emacs-orgmode@gnu.org

=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 siblings
>   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 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