Bug 34239

Summary: tunefs(8) man page doesn't describe arguments.
Product: Documentation Reporter: Gary W. Swearingen <swear>
Component: Manual PagesAssignee: freebsd-bugs (Nobody) <bugs>
Status: Open ---    
Severity: Affects Only Me CC: doc
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   
Attachments:
Description Flags
file.diff none

Description Gary W. Swearingen 2002-01-24 22:20:01 UTC
-- The tunefs(8) man page doesn't describe the optional arguments
"special" and "filesystem".

-- It doesn't say what the default is and from my experiment and look
at code /usr/src/sbin/tunefs/tunefs.c I think there is no default; at
least one argument must be used.

-- The two argument names are not as clear as they should be, since both
are intended to identify the filesystem to be tuned and "special" is not
even standard jargon when used alone.  (Change "usage" later.)

-- It uses both "filesystem" and "file system" in similar contexts.

-- It doesn't say that it reads from /etc/fstab if the filesytem is
specified by a mount point.

-- It uses "flags" for "options" in one place.  (A flag is the first
part of an option.)
================

Fix: Replace "special" with "device-file" and "filesystem" with
"mount-point".  Remove the option brackets.  Add descriptions.
Replace "file system" with "filesystem" throughout.

patch -d "unknown uncompressed man directory" < this-PR
How-To-Repeat: 
tunefs -p
================
Comment 1 Gary W. Swearingen 2002-01-25 00:00:05 UTC
Please slip this into the tunefs(8) man page file too:

.Sh FILES
.Bl -tag -width /etc/fstab -compact
.It Pa /etc/fstab
read to determine the device file for a specified mount point
.El
Comment 2 Tom Rhodes freebsd_committer 2002-05-06 18:54:13 UTC
State Changed
From-To: open->patched

Slightly modified version of your patch committed to -current, will MFC 
upon re@ approval.  Thanks!! 


Comment 3 Tom Rhodes freebsd_committer 2002-05-06 18:54:13 UTC
Responsible Changed
From-To: freebsd-doc->trhodes

Slightly modified version of your patch committed to -current, will MFC 
upon re@ approval.  Thanks!!
Comment 4 Tom Rhodes freebsd_committer 2002-05-13 17:18:26 UTC
State Changed
From-To: patched->closed

Committed to -stable!  Thanks!
Comment 5 Gary W. Swearingen 2003-02-10 00:29:31 UTC
PR 34239 should be re-opened.

The PR was closed last May with:
    Slightly modified version of your patch committed to -current, will
    MFC upon re@ approval.

In fact, the 2 most serious of the 6 identified problems and fixes were
ignored, along with 2 other ones.  The fact that the manpage doesn't
describe it's arguments (as opposed to its options) is a problem which
should be fixed.  The fact that the synopsis is wrong about the last
argument being optional is a problem which should be fixed.  The
problems of the lousy argument names and the misuse of "flags" are less
important and I'll not complain futher about those.
Comment 6 Gary W. Swearingen 2003-02-10 00:58:02 UTC
Rather than fixing the Synopsis from using "[special | filesystem]"
to "special | filesystem" or (better) "{special | filesystem}" and
describing both, it would be better to just use "filesystem" and
explain that with something like this (ala dump(8)):

 +.Pp
 +The file system to be tuned is specified by the argument
 +.Ar filesystem ,
 +as either its device-special file or its mount point
 +(if that is in a standard entry in
 +.Pa /etc/fstab ) .
Comment 7 Tom Rhodes freebsd_committer 2003-02-10 05:46:20 UTC
State Changed
From-To: closed->open

Reopen as a request by submitter.
Comment 8 Tom Rhodes freebsd_committer 2003-02-10 05:48:38 UTC
On 09 Feb 2003 16:29:31 -0800
swear@attbi.com (Gary W. Swearingen) wrote:

> PR 34239 should be re-opened.
> 

Hi Gary,

I've reopened the PR as per your request.  Unfortunatly I don't
know when I'll have some free time to look over it.  My free
time has dwindled a tad as I get deeper into the current semester.

--
Tom Rhodes
Comment 9 Eitan Adler freebsd_committer freebsd_triage 2017-12-31 07:59:25 UTC
For bugs matching the following criteria:

Status: In Progress Changed: (is less than) 2014-06-01

Reset to default assignee and clear in-progress tags.

Mail being skipped