goldste@uthub.UUCP (Jack Goldstein) (11/01/85)
I would like to propose that some sort of standard be adopted
by posters to this newsgroup to introduce the program posted. I
am thinking of something resembling the standard man page entry on
UNIX, like the following:
SYNOPSIS
- A one to three line description of what the program does
INTENDED ENVIRONMENT
This paragraph would describe the environments that the
author intended the program to run on. For example: only
BSD 4.x, any UNIX system, any UNIX-like system, any system
with a C compiler, etc. Note that this is not a guarantee
that the program will work in the stated environments; it is
only an estimate of how portable the program is.
TESTED ENVIRONMENTS
A description of the environments on which the program
has actually been tested.
DESCRIPTION
A description of the program. Often, this could just
be copied from part of the manual page.
AUTHOR
Such a standard would make it easier for everyone to quickly
determine whether the source is relevant for them. Also, there
has been concern lately about the volume of news traffic. If
it becomes necessary, the description above could be posted alone
with the source mailed on request.
Although a description in the above format may require a few
minutes to write, the time is negligible compared to that required
to write most programs, and the benefit to others may be significant.
An introduction to the program, explaining what prompted the
user to write it, who will be interested, etc. should probably be
included in the description above. I'm not sure where.
I would like to hear other comments and ideas on this
proposal. Post them or mail to me, as you see fit. I'll
summarize to the net.
I'm sorry for posting this to this newsgroup. I don't know
where else to put it.
Jack Goldstein
{decvax,watmath!utzoo,linus!utzoo}!utcsri!uthub!goldste