Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!sun-barr!newstop!jethro!male!texsun!convex!rosenkra
From: rosenkra@convex.com (William Rosencranz)
Newsgroups: comp.sys.atari.st
Subject: Re: standard practices
Message-ID: <1991Mar22.100329.25351@convex.com>
Date: 22 Mar 91 10:03:29 GMT
References: <324@uqcspe.cs.uq.oz.au> <1991Mar21.065817.1799@convex.com> <352@uqcspe.cs.uq.oz.au>
Sender: news@convex.com (news access account)
Organization: Convex Computer Corporation, Richardson, Tx.
Lines: 75
Nntp-Posting-Host: convex1.convex.com


In article <352@uqcspe.cs.uq.oz.au> warwick@cs.uq.oz.au writes:
>	Huh?  Are we using ST's or University computers here?  Or are we
>writing portable code or WHAT?

i was generalizing. if POSIX (which by *definition* means PORTABLE) were
to adopt these, then even poor slobs like me with low speed access to big
boxes running POSIX OSs (at work, in my case) benefit from not always
having to man around for simple memory lapses...

>	Clearly, you are NOW talking about a SMALL amount of informative text
>or the -help option - this is a GOOD idea!  But why not have a SYNOPSIS section
>in your manual...

i ALWAYS was talking about this. i mean 1 screen or less, just enuf to
get by.

>NAME
>     cc - C compiler
>
>SYNOPSIS
>     cc [ -a ] [ -align _block ] [ -Bbinding ] [ -c ] [ -C ]
>          [ -dalign ] [ -dryrun ] [ -Dname [=def ] ] [ -E ]
>          [ float_option ] [ -fsingle ] [ -g ] [ -go ] [ -help ]
                                                           ^^^^^ SEE!!!
>          [ -Ipathname ] [ -J ] [ -Ldirectory ] [ -M ]
[ more of the same deleted ]

ok, so what. i still don't know what "-c" means, just that it exists.
however:

	cc -help
	...
	-c  compile to .o only (no link)
	...

tells me EXACTLY what i want to know (and quickly, since with man, i still
need to page to find the propper switch for the functionality i want - i
know the latter, not the former).

this way i get BOTH sides of the equation: option = function.
i agree, that SYNOPSIS from man cc may jog my memory enuf to get the
right info. but u and i are experienced. others are not. this is one
or the reasons unix has a bad rap for being cryptic and difficult to
learn. once u do get into the philosophy, however, it is, of course,
very nice and productive. but that can take months or even years.
so consider "-help" an aid to novices (and us older folks with degrading
memories...). again, YOU don't have to EVER type "-help". so i still
don't see the problem here. there is never a problem when you have
a choice NOT to do something which you can. there are potential problems,
however, when you want to do something but can't.

>Also, and this is my main gripe, too many programs have a -help option,
>but no man entry:  the developer is just too lazy it seems.

i don't know of many besides my own with -help. and i use precious few
gem programs because i can usually type faster than mouse. and i hate
cleaning the damn thing all the time. but i agree 1000% about the
laziness of (some) developers. if you take the time to write something,
you should also make the extra effort to have people remember your name
with fondness :-). i'd rather have someone say "nice total package" rather
than "nice program, but i can't figure out how it works...documentation
basically sucks...". pardon my french. i think it is better that some
functionality is lost at the sake of documentation. i think it is better
to have whatever is working clearly explained than have a zillion extra
functions that, without documentation, can't be used anyway.

i think we are getting closer to agreement here...

-bill
rosenkra@convex.com (not .edu :-)

--
Bill Rosenkranz            |UUCP: {uunet,texsun}!convex!c1yankee!rosenkra
Convex Computer Corp.      |ARPA: rosenkra%c1yankee@convex.com