docs/176648: restore(8) man page is misleading/confusing

[Ronald F.Guilmette]

>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: