From k-horik@yk.rim.or.jp  Sun Jan 24 02:01:13 1999
Received: from mail.yk.rim.or.jp (mail.yk.rim.or.jp [202.247.130.37])
          by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id CAA08515
          for <FreeBSD-gnats-submit@freebsd.org>; Sun, 24 Jan 1999 02:01:10 -0800 (PST)
          (envelope-from k-horik@yk.rim.or.jp)
Received: from localhost (ppp429.yk.rim.or.jp [202.247.165.129])
	by mail.yk.rim.or.jp (8.8.5/3.6W-RIMNET-98-06-09) with ESMTP id TAA10709
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 24 Jan 1999 19:00:57 +0900 (JST)
Message-Id: <19990124190013W.k-horik@yk.rim.or.jp>
Date: Sun, 24 Jan 1999 19:00:13 +0900
From: horikawa@jp.freebsd.org
Sender: Kazuo Horikawa <k-horik@yk.rim.or.jp>
Reply-To: horikawa@jp.freebsd.org
To: FreeBSD-gnats-submit@freebsd.org
Subject: tar(1) SYNOPSIS refinement
X-Send-Pr-Version: 3.2

>Number:         9658
>Category:       docs
>Synopsis:       tar(1) SYNOPSIS refinement
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Jan 24 02:10:00 PST 1999
>Closed-Date:    Tue May 4 11:16:12 PDT 1999
>Last-Modified:  Tue May  4 11:16:36 PDT 1999
>Originator:     Kazuo Horikawa
>Release:        FreeBSD 2.2.7-RELEASE i386
>Organization:
jpman project, Japan FreeBSD Users Group
>Environment:

	src/gnu/usr.bin/tar/tar.1 revision 1.18 (HEAD and RELENG_3)

>Description:

	tar.1's SYNOPSIS says:
	SYNOPSIS
	     tar [[-]bundled-options] [gnu-style-flags] [tarfile] [blocksize]
	         [exclude-file] [filenames] [-C directory-name]
	while I think that tar.1's SYNOPSIS should be:
	SYNOPSIS
	     tar [[-]bundled-options args] [gnu-style-flags] [filenames | -C
	         directory-name] ...

	The reasons why I think as above are described below.
	o About [tarfile], [blocksize], and [exclude-file]:
	  - The order of tarfile, blocksize, exclude-file depends
	    on the order of bubdled-options.
	    Ex. $ tar xfb tarfile blocksize
	        $ tar xbf blocksize tarfile
	  - gnu-style-flags should not exist between bundled-options
	    and arguments (tarfile, blocksize, exclude-file, and
	    etc.).
	    Ex.
	    $ {128} ls
	    files           tarfile
	    $ tar cf --blocking-facotr=64 tarfile files
	    $ ls
	    --blocking-facotr=64    files                   tarfile

	  So, I think that [tarfile], [blocksize], and [exclude-file]
	  should be expressed as `args' and should follow
	  bundled-options.

	o About [filenames] and [-C directory-name]:
	  -C option is applied for following filenames and can be
	  speficied multiple.
	  Ex.
	  $ ls /tmp/a /tmp/b
	  /tmp/a:
	  a1      a2

	  /tmp/b:
	  b1      b2
	  $ tar cvf tarfile -C /tmp/a a1 a2 -C /tmp/b b1 b2
	  a1
	  a2
	  b1
	  b2

	  So, I think that `[filenames | -C directory-name] ...' is
	  better than `[filenames] [-C directory-name]'.

>How-To-Repeat:

	$ man 1 tar

>Fix:

	Apply following patch for src/gnu/usr.bin/tar/tar.1 revision
	1.18 (HEAD and RELENG_3).
	
--- tar.1.bak	Sun Jan 24 18:07:24 1999
+++ tar.1	Sun Jan 24 18:09:41 1999
@@ -15,13 +15,11 @@
 tape archiver; manipulate "tar" archive files
 .Sh SYNOPSIS
 .Nm tar
-.Op [-] Ns Ar bundled-options
+.Op [-] Ns Ar bundled-options Ar args
 .Op Ar gnu-style-flags
-.Op Ar tarfile
-.Op Ar blocksize
-.Op Ar exclude-file
-.Op Ar filenames
-.Op Fl C Ar directory-name
+.Oo
+.Ar filenames | Fl C Ar directory-name
+.Oc ...
 .Sh DESCRIPTION
 .Nm Tar
 is short for 

>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->closed 
State-Changed-By: ghelmer 
State-Changed-When: Tue May 4 11:16:12 PDT 1999 
State-Changed-Why:  
Patch committed (tar.1 revs 1.20, 1.18.2.1) 
>Unformatted:
