From swear@blarg.net  Thu Jan 24 14:15:12 2002
Return-Path: <swear@blarg.net>
Received: from lists.blarg.net (lists.blarg.net [206.124.128.17])
	by hub.freebsd.org (Postfix) with ESMTP id F12F537BA33
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 Jan 2002 14:13:19 -0800 (PST)
Received: from thig.blarg.net (thig.blarg.net [206.124.128.18])
	by lists.blarg.net (Postfix) with ESMTP id ACC63BE02
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 Jan 2002 14:13:15 -0800 (PST)
Received: from localhost.localdomain ([206.124.139.115])
	by thig.blarg.net (8.9.3/8.9.3) with ESMTP id OAA27374
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 Jan 2002 14:13:14 -0800
Received: (from jojo@localhost)
	by localhost.localdomain (8.11.6/8.11.3) id g0OMGar02864;
	Thu, 24 Jan 2002 14:16:36 -0800 (PST)
	(envelope-from swear@blarg.net)
Message-Id: <q77kq78ke3.kq7@localhost.localdomain>
Date: 24 Jan 2002 14:16:36 -0800
From: "Gary W. Swearingen" <swear@blarg.net>
Reply-To: swear@blarg.net
To: FreeBSD-gnats-submit@freebsd.org
Subject: tunefs(8) man page doesn't describe arguments.
X-GNATS-Notify:

>Number:         34239
>Category:       docs
>Synopsis:       tunefs(8) man page doesn't describe arguments.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jan 24 14:20:01 PST 2002
>Closed-Date:    
>Last-Modified:  Sun Feb  9 21:50:05 PST 2003
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 4.5-PRERELEASE i386 (26 dec)
>Organization:
none
>Environment:
n/a
================
>Description:

-- 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.)
================
>How-To-Repeat:

tunefs -p
================
>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

--- /tmp/tunefs..orig.8	Thu Jan 24 13:10:07 2002
+++ /tmp/tunefs.8	Thu Jan 24 14:06:43 2002
@@ -37,7 +37,7 @@
 .Os
 .Sh NAME
 .Nm tunefs
-.Nd tune up an existing file system
+.Nd tune up an existing filesystem
 .Sh SYNOPSIS
 .Nm
 .Op Fl A
@@ -52,16 +52,22 @@
 .Op Fl p
 .Op Fl s Ar avgfpdir
 .Ek
-.Op Ar special | Ar filesystem
+.Ar device-file | mount-point
 .Sh DESCRIPTION
 .Nm Tunefs
-is designed to change the dynamic parameters of a file system
+is designed to change the dynamic parameters of a filesystem
 which affect the layout policies.
-The parameters which are to be changed are indicated by the flags
-given below:
+.Pp
+.Pp
+The filesystem to be tuned is specified by either its device-special file,
+.Ar device-file ,
+or its mount point,
+.Ar mount-point
+(if that is in a standard entry in /etc/fstab).
+The parameters which are to be changed are indicated by these options:
 .Bl -tag -width indent
 .It Fl A
-The file system has several backups of the super-block.  Specifying
+The filesystem has several backups of the super-block.  Specifying
 this option will cause all backups to be modified as well as the
 primary super-block.  This is potentially dangerous - use with caution.
 .It Fl a Ar maxcontig
@@ -92,7 +98,7 @@
 The effect of this limit is to cause big files to do long seeks
 more frequently than if they were allowed to allocate all the blocks
 in a cylinder group before seeking elsewhere.
-For file systems with exclusively large files,
+For filesystems with exclusively large files,
 this parameter should be set higher.
 .It Fl f Ar avgfilezsize
 Specify the expected average file size.
@@ -113,16 +119,16 @@
 Turn on/off soft updates.
 An unmounted filesystem is required.
 .It Fl o Ar space | time
-The file system can either try to minimize the time spent
+The filesystem can either try to minimize the time spent
 allocating blocks, or it can attempt to minimize the space
 fragmentation on the disk.
 Optimization for space has much
 higher overhead for file writes.
 The kernel normally changes the preference automatically as
-the percent fragmentation changes on the file system.
+the percent fragmentation changes on the filesystem.
 .It Fl p
 Show a summary of what the current tunable settings
-are on the selected file system.  More detailed information can be
+are on the selected filesystem.  More detailed information can be
 obtained in the
 .Xr dumpfs 8
 manual page.
@@ -133,7 +139,7 @@
 If
 .Nm
 .Fl n
-is run to enable/disable soft update on an unmounted file system
+is run to enable/disable soft update on an unmounted filesystem
 after booting single-user then
 .Nm
 will output the warning
@@ -167,16 +173,16 @@
 .%O "(reprinted in the BSD System Manager's Manual, SMM:5)"
 .Re
 .Sh BUGS
-This program should work on mounted and active file systems.
+This program should work on mounted and active filesystems.
 Because the super-block is not kept in the buffer cache,
 the changes will only take effect if the program
-is run on dismounted file systems.
-To change the root file system, the system must be rebooted
-after the file system is tuned.
+is run on dismounted filesystems.
+To change the root filesystem, the system must be rebooted
+after the filesystem is tuned.
 .\" Take this out and a Unix Demon will dog your steps from now until
 .\" the time_t's wrap around.
 .Pp
-You can tune a file system, but you can't tune a fish.
+You can tune a filesystem, but you can't tune a fish.
 .Sh HISTORY
 The
 .Nm
>Release-Note:
>Audit-Trail:

From: swear@blarg.net (Gary W. Swearingen)
To: swear@blarg.net
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/34239: tunefs(8) man page doesn't describe arguments.
Date: 24 Jan 2002 16:00:05 -0800

 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
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Mon May 6 10:54:13 PDT 2002 
State-Changed-Why:  
Slightly modified version of your patch committed to -current, will MFC 
upon re@ approval.  Thanks!! 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Mon May 6 10:54:13 PDT 2002 
Responsible-Changed-Why:  
Slightly modified version of your patch committed to -current, will MFC 
upon re@ approval.  Thanks!! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=34239 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Mon May 13 09:18:26 PDT 2002 
State-Changed-Why:  
Committed to -stable!  Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=34239 

From: swear@attbi.com (Gary W. Swearingen)
To: bug-followup@freebsd.org
Cc: Tom Rhodes <trhodes@freebsd.org>
Subject: Re: docs/34239: tunefs(8) man page doesn't describe arguments.
Date: 09 Feb 2003 16:29:31 -0800

 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.

From: swear@attbi.com (Gary W. Swearingen)
To: bug-followup@freebsd.org
Cc: Tom Rhodes <trhodes@freebsd.org>
Subject: Re: docs/34239: tunefs(8) man page doesn't describe arguments.
Date: 09 Feb 2003 16:58:02 -0800

 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 ) .
State-Changed-From-To: closed->open 
State-Changed-By: trhodes 
State-Changed-When: Sun Feb 9 21:46:20 PST 2003 
State-Changed-Why:  
Reopen as a request by submitter. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=34239 

From: Tom Rhodes <trhodes@FreeBSD.org>
To: swear@attbi.com (Gary W. Swearingen)
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/34239: tunefs(8) man page doesn't describe arguments.
Date: Mon, 10 Feb 2003 00:48:38 -0500

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