Date: Mon, 14 Jan 2002 11:30:02 -0800 (PST) From: swear@blarg.net (Gary W. Swearingen) To: freebsd-doc@freebsd.org Subject: Re: docs/33852: split(1) man page implies that input file is removed. Message-ID: <200201141930.g0EJU2g98909@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 <ru@FreeBSD.org>
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 <ru@FreeBSD.org> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200201141930.g0EJU2g98909>