From owner-freebsd-doc Mon Jan 14 11:30:22 2002 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21]) by hub.freebsd.org (Postfix) with ESMTP id 1ECFD37B417 for ; Mon, 14 Jan 2002 11:30:03 -0800 (PST) Received: (from gnats@localhost) by freefall.freebsd.org (8.11.6/8.11.6) id g0EJU2g98909; Mon, 14 Jan 2002 11:30:02 -0800 (PST) (envelope-from gnats) Date: Mon, 14 Jan 2002 11:30:02 -0800 (PST) Message-Id: <200201141930.g0EJU2g98909@freefall.freebsd.org> To: freebsd-doc@freebsd.org Cc: From: swear@blarg.net (Gary W. Swearingen) Subject: Re: docs/33852: split(1) man page implies that input file is removed. Reply-To: swear@blarg.net (Gary W. Swearingen) Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org The following reply was made to PR docs/33852; it has been noted by GNATS. From: swear@blarg.net (Gary W. Swearingen) To: Ruslan Ermilov Cc: bug-followup@FreeBSD.org Subject: Re: docs/33852: split(1) man page implies that input file is removed. Date: 14 Jan 2002 11:29:54 -0800 Ruslan Ermilov writes: > I don't like changing "file" to "filename", because "file" is a > standard value that's output if you don't give .Ar any arguments. Bad conventions are better (in this case) than none. :-) > +and breaks it up into files of 1000 lines each > +(if no options are specified), leaving the > +.Ar file > +unchanged. That should be either "leaving the file _file_ unchanged" or "leaving _file_ unchanged" because "the _file_" refers to a filename or option argument which nobody will be concerned might change. > -.Bl -tag -width Ds > -.It Fl b > +.Bl -tag -width indent > +.It Fl b Ar byte_count Ns Op Cm k Ns | Ns Cm m I think it's better to leave option arguments out of the option description labels and leave them in the synopsis (at least for small man pages where the synopsis is easily viewed). It should result in fewer man page bugs. When an option has several forms of arguments or is otherwise complex, it is probably best buried in the description and still not in the description label. But I've noticed it both ways. >> +No padding is added, so the last new file is normally smaller than the >> +others and proper catenation of the output files creates a copy of the >> +unsplit original. I'm glad you caught my -p (non-fixed-size chunks) oversight, but I wonder if you would replace my sentence above with: +No padding is added, so the proper catenation of the output files +creates a copy of the unsplit original. It could be at the end of the DESCRIPTION first paragraph, or as a new last paragraph of the DESCRIPTION. (I thought it best to omit shell interaction by mentioning "cat prefix* >copy-of-original".) Users shouldn't have to experiment to determine that padding is not performed, especially since the first paragraph of the DESCRIPTION will imply that it does pad out to 1000 lines (by default). > -"usage: split [-b byte_count] [-l line_count] [-p pattern] [file [prefix]]\n"); > +"usage: split [-b byte_count | -l line_count | -p pattern] [file [prefix]]\n"); You might want to break that into two shorter lines. I wasn't 100% sure how to do it. What's the FreeBSD standard limit? To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message