From rfg@tristatelogic.com  Mon Mar  4 19:52:44 2013
Return-Path: <rfg@tristatelogic.com>
Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115])
	by hub.freebsd.org (Postfix) with ESMTP id CA90D508
	for <FreeBSD-gnats-submit@freebsd.org>; Mon,  4 Mar 2013 19:52:44 +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 9C00210A3
	for <FreeBSD-gnats-submit@freebsd.org>; Mon,  4 Mar 2013 19:52:44 +0000 (UTC)
Received: by segfault.tristatelogic.com (Postfix, from userid 1237)
	id EB06E3B858; Mon,  4 Mar 2013 11:52:33 -0800 (PST)
Message-Id: <20130304195233.EB06E3B858@segfault.tristatelogic.com>
Date: Mon,  4 Mar 2013 11:52:33 -0800 (PST)
From: Ronald F.Guilmette <rfg@tristatelogic.com>
Reply-To: Ronald F.Guilmette <rfg@tristatelogic.com>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: restore(8) man page is misleading/confusing
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         176648
>Category:       docs
>Synopsis:       restore(8) man page is misleading/confusing
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:
>Keywords:
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Mar 04 20:00:01 UTC 2013
>Closed-Date:
>Last-Modified:
>Originator:     Ronald F. Guilmette
>Release:        FreeBSD 9.1-RELEASE amd64
>Organization:
entr0py
>Environment:

System: FreeBSD 9.1-RELEASE amd64

>Description:

The following text appears in the restore(8) man page:

    The -r flag ... can be detrimental to one's health if
    not used carefully (not to mention the disk).  An example:

             newfs /dev/da0s1a
             mount /dev/da0s1a /mnt
             cd /mnt

             restore rf /dev/sa0

The above passage is confusing because first it is giving an omnious
warning about bad effects that can derive from misusing the -r option,
and then, immediately following that, it gives an example of _correct_
usage of the -r option.

It has been suggested that the material begining with "An example:" should
be placed into its own separate paragraph, and I agree with that suggestion.
Furthermore, I think that it would be best to make the meaning entirely
clear by changing "An example:" to "Here is an example of how to
_correctly_ use the -r option:"

>How-To-Repeat:

man 8 restore

>Fix:

See above.
>Release-Note:
>Audit-Trail:
>Unformatted:
