From owner-freebsd-questions@FreeBSD.ORG  Mon Mar  4 19:53:32 2013
Return-Path: <owner-freebsd-questions@FreeBSD.ORG>
Delivered-To: freebsd-questions@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org
 [IPv6:2001:1900:2254:206a::19:1])
 by hub.freebsd.org (Postfix) with ESMTP id 42F3D518
 for <freebsd-questions@freebsd.org>; Mon,  4 Mar 2013 19:53:32 +0000 (UTC)
 (envelope-from rfg@tristatelogic.com)
Received: from outgoing.tristatelogic.com (segfault.tristatelogic.com
 [69.62.255.118]) by mx1.freebsd.org (Postfix) with ESMTP id 22AC910AB
 for <freebsd-questions@freebsd.org>; Mon,  4 Mar 2013 19:53:32 +0000 (UTC)
Received: from segfault-nmh-helo.tristatelogic.com (localhost [127.0.0.1])
 by segfault.tristatelogic.com (Postfix) with ESMTP id E54873B8B9
 for <freebsd-questions@freebsd.org>; Mon,  4 Mar 2013 11:53:31 -0800 (PST)
From: "Ronald F. Guilmette" <rfg@tristatelogic.com>
To: freebsd-questions@freebsd.org
Subject: Re: Confused by restore(8) man page example
In-Reply-To: <63618304-837E-4B76-8157-D99C744AC72F@wolfhut.org>
Date: Mon, 04 Mar 2013 11:53:31 -0800
Message-ID: <8876.1362426811@server1.tristatelogic.com>
X-BeenThere: freebsd-questions@freebsd.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: User questions <freebsd-questions.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/options/freebsd-questions>, 
 <mailto:freebsd-questions-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-questions>
List-Post: <mailto:freebsd-questions@freebsd.org>
List-Help: <mailto:freebsd-questions-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-questions>, 
 <mailto:freebsd-questions-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Mon, 04 Mar 2013 19:53:32 -0000


In message <63618304-837E-4B76-8157-D99C744AC72F@wolfhut.org>, 
Ben Cottrell <tamino@wolfhut.org> wrote:

>I guess the same text in the man page could be read several
>different ways! The way I read it (which may or may not be
>correct) is that the example given is an example of how to
>use it *correctly*. It sounds to me like it's warning against
>deviating too far from the steps given in the example.
>
>I can see as how the text might allow other interpretations,
>though!

Thanks for the response Ben.

As others have pointed out, it would probably be less confusing
if the material starting with "An example:" were in a different
paragraph.  As the text stands now, first we have a sentence that
gives a frightening warning about possible mangling of a disk/partition
if restore -r is not used correctly, and then immediately following
that is "An example:" with an example of _correct_ usage.

I hope and trust that folks can understand my earlier befuddlement.

Anyway, I have just now filed a PR suggesting a new paragraph at the
appropriate point in the man page.

Thanks to all who responded.


Regards,
rfg