gda@creare.uucp (Gray Abbott) (10/16/85)
I vote for net.doc . The first item I would like to see is a Guide
to Unix Documentation. The most frustrating thing about looking for
something in the Unix Programmers Guide is you usually have to know
its *name* in order to find it. The second most frustrating thing is
that there are no *examples* which make usage clear (how about an
Examples Manual?). The third worst thing is that not all of the
pointers (SEE ALSO) that should be there *are* there.
And how about some more clever program than "man" to help
find things ??
Gray Abbott
Creare Inc.
Hanover, NH
{...dartvax!creare!gda}fair@ucbarpa.BERKELEY.EDU (Erik E. &) (10/17/85)
In article <381@creare.uucp> gda@creare.uucp (Gray Abbott) writes: > > I vote for net.doc . The first item I would like to see is a Guide > to Unix Documentation. The most frustrating thing about looking for > something in the Unix Programmers Guide is you usually have to know > its *name* in order to find it. The second most frustrating thing is > that there are no *examples* which make usage clear (how about an > Examples Manual?). The third worst thing is that not all of the > pointers (SEE ALSO) that should be there *are* there. I await with breathless anticipation your proposal for finding competant technical writers who are willing to give away for free the fruits of their labors. What people haven't gotten through their heads yet is that creating a newsgroup only creates a forum for discussion. IT DOES NOT GUARANTEE DISCUSSION! Even if there is discussion, there is no guarantee that it will be `worthwhile' for any arbitrary definition of `worthwhile'. I cite net.bizzare as perfect example of this. welcome to the real world, Erik E. Fair ucbvax!fair fair@ucbarpa.BERKELEY.EDU
dave@lsuc.UUCP (David Sherman) (10/18/85)
People are suggesting that we have a net.doc for every
UNIX neophyte to be able to use to ask questions to the net.
Please, NO NO NO NO NO!
We already have the right newsgroup for this - net.unix.
It's a matter of using it PROPERLY.
Most questions you have can be answered by someone relatively
close to you, and should not be sent around the world or even
the continent. Netnews is a scarce resource, and if people
start asking all kinds of questions which someone on their
site can answer, we'll be swamped.
What I do when I have a simple question is one of the following,
in progression:
- ask a local person who's likely to know the answer
- post to net.unix or net.unix-wizards WITH DISTRIBUTION
LIMITED TO MY CITY. If you're on a large machine,
you may be able to limit this further, to your machine,
or perhaps to your organization.
- if the above two fail, and the question therefore appears
to be non-trivial, I'll consider posting to the net.
Dave Sherman
The Law Society of Upper Canada
Toronto
--
{ ihnp4!utzoo pesnta utcs hcr decvax!utcsri } !lsuc!daveearlw@pesnta.UUCP (20) (10/19/85)
In article <381@creare.uucp> gda@creare.uucp (Gray Abbott) writes: > > ... > The second most frustrating thing is > that there are no *examples* which make usage clear (how about an > Examples Manual?). > ... This is what Unix documentation needs desperately. Just a one page example for each section 2 and 3 function would be a great help for most people.
peter@graffiti.UUCP (Peter da Silva) (10/20/85)
> > I vote for net.doc . The first item I would like to see is a Guide > to Unix Documentation... > ... frustration about not being able to find things in the manual... The Berkeley manual has a keyword-in-context index that is *extremely* useful. The new AT&T manuals not only don't have that but they aren't even organised into the right sections any more... I remember a Berkeley program called "apropos" that looked up stuff in the KWIK index. Does it still exist?
nonh@utzoo.UUCP (Chris Robertson) (10/20/85)
This is another vote for mod.doc, especially for examples of usage. I even have a first article to contribute -- a little C program showing how to use the most common time routines, plus a short commentary on them. Some have said we don't need mod.doc because we have net.unix, but I perceive net.unix as for informal Q&A -- mod.doc contributions should be more formally presented, checked out, and (with any luck) more complete than the rambling discussions of net.unix. If no one else desperately wants to do it, I will moderate the group if it's formed. My Unix expertise is that of competent user with C and system admin experience (plus I am a vi and shell wizard, she confided modestly), and I am a pretty decent technical writer. How about a wizard volunteer to check kernal etc. stuff I am shaky on? --chris
sra@oddjob.UUCP (Scott R. Anderson) (10/23/85)
In article <327@graffiti.UUCP> peter@graffiti.UUCP (Peter da Silva) writes: > >The Berkeley manual has a keyword-in-context index that is *extremely* useful. >The new AT&T manuals not only don't have that but they aren't even organised >into the right sections any more... I remember a Berkeley program called >"apropos" that looked up stuff in the KWIK index. Does it still exist? It still exists in the standard Berkeley distribution; it has been removed from the Sun release, as it is a synonym for "man -k". The "whatis" command uses the same data base, but only keys on the command name; it is essentially a quick "man". I agree with Peter that "man -k" is extremely useful; much more useful than a VMS-style "help" command, which depends on a command name's ability to convey the gist of the command's function (which, of course, would not work with UNIX command names, and often does not with VMS command names). It also requires a user to sift through a large number of names (~100) to find what they want. What would be more useful, I think, is something like the "how" command posted by Bob Ware about a year ago, where commands are functionally and hierarchically organized and selected. It can be used when you know what you want to do, but not "how" to do it. Scott Anderson ihnp4!oddjob!kaos!sra
peter@yetti.UUCP (Runge) (10/26/85)
> I agree with Peter that "man -k" is extremely useful; much more useful than > a VMS-style "help" command, which depends on a command name's ability to > convey the gist of the command's function (which, of course, would not work > with UNIX command names, and often does not with VMS command names). There's a lot of unintentional humor in this comparison. The percentage of meaningful VMS commands relative to the total set is far higher than for UNIX (the only meaningful Unix command I can remember off-hand is yes :-)), and man -k is notorious for its inability to find anything appropriate. VMS Help has a lot of faults (particularly if you just slap what Digital provides on your system without doing some common-sense deletions and additions to cover the local environment) but at least on VMS, I can work effectively without a bookshelf full of manuals; my employer won't buy me a set, but the point is: I couldn't justify it anyway -- the stuff I need is almost all online. On VMS, self-instruction through the HELP facility is a meaningful and feasible activity. On Unix, the thought of trying to learn how to do things by reading man files seems ludicrous (at least for ordinary mortals). For one thing, on our 780, asking for a man file to be retrieved and formatted is something you do before leaving your office for a coffee or a washroom break. When you get back, it will probably be waiting for you - not the one you actually needed, mind you; it wasn't "refer" that had the %codes, it was "addbib"! But surely, you could use another cup of coffee? -- Peter H. Roosen-Runge, Department of Computer Science, York University Toronto M3J 1P3 , Ontario, Canada _____________________________________________________________________________ "Eccles, is the ship sinking?" "Only below the sea." "We must try to save the ship -- help me get it into the lifeboat." _____________________________________________________________________________
tp@ndm20 (10/28/85)
Actually, there are 2 groups that, taken together, cover all the
proposed uses of net.doc. For questions about unix, use net.unix.
If you have some documentation that would be valuable to somebody,
post it to net.sources. net.sources IS the appropriate place to post
documentation. If the volume becomes large, then net.sources.doc
will be created, as per the normal net procedures. There is at
present no demonstrated need. Prove me wrong (PLEASE!) by
generating some volume in net.sources. Discussions about what should
be posted should be in net.unix or net.unix-wizards (for kernel type
things). If a sufficient volume ensues, then we can talk about
net.sources.doc, and discussion can be moved there (though net.unix
would probably STILL be the best place for such discussion).
Getting groups created under those circumstances is quite easy.
Doing as you are trying, with no demonstrated volume, is impossible.
You might as well quit asking because it just doesn't happen that
way, no matter what the perceived usefulness of the group. This is
because most groups created without demonstrated need (cf.
mod.general) turn into empty forums. Everybody is waiting to read
the wonderful articles that should be posted there, and nobody is
writing them. Groups need to be created when there are people who
want to post something, not when people want to read something.
Terry Poot
Nathan D. Maier Consulting Engineers
(214)739-4741
Usenet: ...!{allegra|ihnp4}!convex!smu!ndm20!tp
CSNET: ndm20!tp@smu
ARPA: ndm20!tp%smu@csnet-relay.ARPAsra@oddjob.UUCP (Scott R. Anderson) (10/29/85)
In article <267@yetti.UUCP> peter@yetti.UUCP (Runge) writes: >> I agree with Peter that "man -k" is extremely useful; much more useful than >> a VMS-style "help" command, which depends on a command name's ability to >> convey the gist of the command's function (which, of course, would not work >> with UNIX command names, and often does not with VMS command names). > >There's a lot of unintentional humor in this comparison. The percentage of >meaningful VMS commands relative to the total set is far higher than for >UNIX (the only meaningful Unix command I can remember off-hand is yes :-)), I do not deny that VMS command names are generally more meaningful than UNIX command names, but that doesn't make help easier to use than man -k. They are both keyword-oriented, but with help you have a user trying to sift through a screen-full of keywords (some of which ARE meaningless in their generality -- set and analyze come to mind) to possibly find the one you are thinking of. With man -k, the program does the sifting for you, and through a much larger data base, the command descriptions. The latter are going to have a better set of meaningful keywords (assuming they are well-written) since they are not limited to being one keyword per command. >and man -k is notorious for its inability to find anything appropriate. How often does your brain flash "Nothing appropriate" when you are using VMS help? (:-) >For one thing, on our 780, asking for a man file to be >retrieved and formatted is something you do before leaving your office for >a coffee or a washroom break. Get your system manager to set up the 'cat' version of the manuals. They take up about 3 MB of disk space, but are much faster than the unformatted versions. Scott Anderson ihnp4!oddjob!kaos!sra
levy@ttrdc.UUCP (Daniel R. Levy) (10/30/85)
In article <532@ttrdc.UUCP>, levy@ttrdc.UUCP (that's me) writes: > >Yeah? How about raw terminal interfaces, for an example. On Unix, do a >"man 4 tty" (BSD) or "man 7 tty" (USG) [yeah I know it's in the admin >section but at least it's there]. Now, attempt to get similar online info I owe the net a correction. That section for USG is termio, not tty, in the administrator's manual. (I am looking now at a Sys5 manual. I was posting on such a machine too so shame on me for not looking at those "easily ac- cessible" :-) online man pages!) Still my main point stands. -- ------------------------------- Disclaimer: The views contained herein are | dan levy | yvel nad | my own and are not at all those of my em- | an engihacker @ | ployer or the administrator of any computer | at&t computer systems division | upon which I may hack. | skokie, illinois | -------------------------------- Path: ..!ihnp4!ttrdc!levy
peter@graffiti.UUCP (Peter da Silva) (10/31/85)
> additions to cover the local environment) but at least on VMS, I can work > effectively without a bookshelf full of manuals; my employer won't buy > me a set, but the point is: I couldn't justify it anyway -- the stuff I need > is almost all online. On VMS, self-instruction through the HELP facility is I can also work without a bookshelf full of manuals. I only need 2: the UNIX Programmer's Manual and the Users Guide. When I was working on RSX I needed all 6.5 volumes all the time, and VMS doesn't seem to be any better. > mortals). For one thing, on our 780, asking for a man file to be > retrieved and formatted is something you do before leaving your office for > a coffee or a washroom break. When you get back, it will probably be waiting So format all the man files ahead of time & archive off the unformatted version like everyone else does. Then man becomes a variant of cat/more. > _____________________________________________________________________________ > "Eccles, is the ship sinking?" "Only below the sea." > "We must try to save the ship -- help me get it into the lifeboat." > _____________________________________________________________________________ You rotten swines, you deaded me! (exits left. waits for applause. not a sausage) -- Name: Peter da Silva Graphic: `-_-' UUCP: ...!shell!{graffiti,baylor}!peter IAEF: ...!kitty!baylor!peter
iwm@icdoc.UUCP (Ian Moor) (11/16/85)
In article <854@lsuc.UUCP> dave@lsuc.UUCP (David Sherman) writes: >People are suggesting that we have a net.doc for every >UNIX neophyte to be able to use to ask questions to the net. >Most questions you have can be answered by someone relatively >close to you, and should not be sent around the world or even >the continent. Netnews is a scarce resource, and if people >What I do when I have a simple question is one of the following, >in progression: > - ask a local person who's likely to know the answer I have shared offices at different times with two people in this position and I began to wonder how they got any work done, there was a stream of people all day long: "when I type send foo!baa it says event not found ..." I have got to know VMS more than most people round here and I am able to tell people with questions to type HELP or point to the manuals which have examples of each command. I find unix has two problems working out what command to use, and how to do anthing not explained explicitly in the man page. net.docs could have as a starter the notes written for students starting to use unix. -- Ian W Moor UUCP: seismo!mcvax!ukc!icdoc!iwm ARPA: iwm%icdoc@ucl Department of Computing Whereat a great and far-off voice was heard, saying, Imperial College. Poop-poop-poopy, and it was even so; and the days 180 Queensgate of Poopy Panda were long in the land. London SW7 Uk.
pdg@ihdev.UUCP (P. D. Guthrie) (11/18/85)
In article <264@ivax.icdoc.UUCP> iwm@icdoc.UUCP (Ian Moor) writes: >In article <854@lsuc.UUCP> dave@lsuc.UUCP (David Sherman) writes: >>People are suggesting that we have a net.doc for every >>UNIX neophyte to be able to use to ask questions to the net. >>Most questions you have can be answered by someone relatively >>close to you, and should not be sent around the world or even >>the continent. Netnews is a scarce resource, and if people >>What I do when I have a simple question is one of the following, >>in progression: >> - ask a local person who's likely to know the answer > Quite right!! >net.docs could have as a starter the notes written for students starting >to use unix. > Yes. I believe the whole idea behind net.docs is NOT to compete with net.unix, or your local guru, but to provide a distinct place for DOCUMENTATION to be posted, much as in the way that sources are posted to net.sources. I think that every site, especially universities, have collected over the years documentation on every aspect of computing, from "How to install new device drivers on UNIX" to "How to boot your IBM PC". Now, if we had a place to post these, then in immitation of net.sources, those people that see a use for these papers could save them. I actually think that mod.docs would be a better idea though, just to keep the amount of illiterate trash down (no flames about my spelling or grammar - this is a posting *not* a published paper). I remember seeing a volunteer to be moderator, so if he would step forward again, and if net.powers-that-be will not create mod.docs, why not have a mailing list, so those poor objecting whiners need not be subjected to having to hit the 'n' key when the create newsgroup message comes around. Paul Guthrie ihnp4!ihdev!pdg
chris@globetek.UUCP (Chris Robertson) (11/20/85)
In article <404@ihdev.UUCP> pdg@ihdev.UUCP (55224-P. D. Guthrie) writes: > ...I remember seeing a volunteer to be moderator [of mod.docs], so if he > would step forward again, and if net.powers-that-be will not create mod.docs, > why not have a mailing list... I once again volunteer my services as moderator for mod.docs, or as co-ordinator for a mailing list. All in favour of a mailing list, send me mail, and send me docs! Christine Robertson {linus, ihnp4, decvax}!utzoo!globetek!chris
ron@brl-sem.ARPA (Ron Natalie <ron>) (11/27/85)
> I once again volunteer my services as moderator for mod.docs, or as > co-ordinator for a mailing list. All in favour of a mailing list, send > me mail, and send me docs! > Sorry for the delay, I do have the votes that were called for. The support was near unanimous for a moderate mod.docs group. I intend to set up the group as described, but I have been hampered by some problems with the serial lines on BRL-SEM. This group will be created next week. -Ron