root@ozdaltx.UUCP (root) (06/14/86)
"The only STUPID question is the one that is never asked.." - Anon. It is sad but true that the manuals provided with this system are often very poorly written and/or include so much techinical jorgan that the intent of the section gets lost in the translation... (Are you listening MicroSoft and/or Tandy ????). As an example; the function 'expr'. Nowhere in the manual is stated that expr has a 'index', 'length', or 'match' capibility, NOR does it state that it is limited to positive, non-floating point numbers. They, as a rule, seriously lack clear, concise examples on the use of the "tool"... What good is a tool is you don't know how to use it?!? BTW the way I found out about the above was one day I decided to do: strings /bin/expr | more and saw the entries and played with them until I got them to work. Another example is 'sort'. The information IS there, ok, BUT if you read the paragraphs enought times, finially from within all of the verbosity finially emerges the fact that the entire line is "0" and that a partialy line can be represented as "0.xx".. or what-ever. What ever happened to the K I S S rule? (Keep It Simple Stupid!). I strongly suspect that many of the manual pages/sections were written by PhD. canidates intent on impressing their peers with their command of gobbledegook! I've been working with this system for close to 5 years now, and STILL find myself learning something new about it almost every day... The truth of the matter is, I have obtained most of my useful information from "civilian" publications rather than the supplied manuals! Speaking of verbosity....'nuf said. Flames are OK... I LOVE mail! Scotty ...ihnp4!cuae2!ltuxa!we53!sw013b!dj3b1!killer!ozdaltx!root DISCLAIMER: "This system is mine, so there!"
keppel@pavepaws.berkeley.edu (David Keppel) (06/15/86)
In article <112@ozdaltx.UUCP> root@ozdaltx.UUCP (root) writes: >"The only STUPID question is the one that is never asked.." - Anon. > >It is sad but true that the manuals provided with this system are often >very poorly written and/or include so much techinical jorgan that >the intent of the section gets lost in the translation... (Are >you listening MicroSoft and/or Tandy ????). >[ description of 'expr' not taking negative arguments ] I'm told by some of the locals that when Sun bought their 4BSD license they went through the manuals and _TOOK_OUT_ a whole bunch of the "BUGS" section entries, because they didn't want to look bad! @$%*#%! (Then, of course, a whole bunch of other companies probably followed the lead) ;-D avid K eppel ..!ucbvax!pavepaws!keppel "Learning by Osmosis: Gospel in, Gospel out"
guy@sun.UUCP (06/16/86)
> "The only STUPID question is the one that is never asked.." - Anon. Questions which can be answered just by looking up the answer in a reference book are stupid *if* it doesn't take more knowledge to find the answer than to answer the question. Some questions *do* fall under that heading, and the person who is asked the question is perfectly within their rights to tell somebody to RTFM. > It is sad but true that the manuals provided with this system are often > very poorly written... Yes, and often incomplete, and often sometimes just *wrong*. If somebody gets caught by one of those, there's nothing wrong with them asking. (Recently, somebody asked why a call to the 4.2BSD "gethostbyaddr" routine wasn't working. It wasn't working because he was passing a printable representation of the address to the routine, rather than a binary representation; however, it isn't stated in the "gethostent" manual page that the binary representation is required, it's just implied.) However, there are some questions, asked on the net among other places, which indicate that the asker didn't even *try* to look the answer up. I don't have an opinion on whether the "/bin/sh" and "/bin/csh" are of this form. In at least one case, you could have argued that the documentation isn't good enough. The fact that a shell script can open multiple files and keep them open throughout the script, in order to read from or write to them, is somewhat obscurely buried in the description of the "exec" command. > As an example; the function 'expr'. Nowhere in the manual is > stated that expr has a 'index', 'length', or 'match' capibility, > NOR does it state that it is limited to positive, non-floating > point numbers. Watch it. The "index", "length", and "match" functions, along with the "substr" function, were deleted in System V. The trouble is that, since they are reserved words, they cause problems if strings "index", "substr", "length", or "match" appear in an "expr" expression; they are treated as reserved words, not as strings. "match", by the way, performs the exact same operation as the ":" operator, just with a diferent syntax, so even without "match" it has a "match" capability. I have no idea why they were undocumented, but by and large we should be grateful that they were, otherwise it would have been difficult as all hell to back them out. It would be nice if those capabilities could be provided, but it would have to be done in such a way as not to cause certain character strings to be unusable as data. -- Guy Harris {ihnp4, decvax, seismo, decwrl, ...}!sun!guy guy@sun.com (or guy@sun.arpa)
shannon@sun.uucp (Bill Shannon) (06/17/86)
> I'm told by some of the locals that when Sun bought their 4BSD license > they went through the manuals and _TOOK_OUT_ a whole bunch of the > "BUGS" section entries, because they didn't want to look bad! @$%*#%! > > (Then, of course, a whole bunch of other companies probably followed the lead) > > ;-D avid K eppel ..!ucbvax!pavepaws!keppel > "Learning by Osmosis: Gospel in, Gospel out" Not true. I've heard the same rumor about DEC and Ultrix. Many companies also change the name of the BUGS section to something that doesn't give such a bad impression. You have to admit that much of what is in the BUGS section in most UNIX manuals is not really bugs but rather random facts abut the program that it would be useful for the user to know about. At Sun we've tried to clean up the documentation so that things that are not bugs are not labelled as bugs. After all, if they are bugs, why don't we just fix them? Most of them are instead limitations or restrictions of the current implementation. Bill Shannon
avolio@decuac.UUCP (06/18/86)
In article <4198@sun.uucp>, shannon@sun.uucp (Bill Shannon) writes: > Not true. I've heard the same rumor about DEC and Ultrix. Many companies > also change the name of the BUGS section... Yeah. We call that section "RESTRICTIONS." Neat, huh? -- Fred @ DEC Ultrix Applications Center INET: avolio@decuac.DEC.COM * Fight the Fight * UUCP: {decvax,seismo,cbosgd}!decuac!avolio * Rescue the Unborn *
jso@edison.UUCP (John Owens) (06/23/86)
In article <4198@sun.uucp>, shannon@sun.UUCP writes: > You have to admit that much of what is in the BUGS section in most UNIX > manuals is not really bugs but rather random facts abut the program that > it would be useful for the user to know about. Yep. I like Microsoft's adaptation: they call them "Comments". -John Owens jso@edison.UUCP
gdw@sslvax.UUCP (Grenville Whelan) (07/02/86)
In article <808@edison.UUCP> jso@edison.UUCP writes: >In article <4198@sun.uucp>, shannon@sun.UUCP writes: >> You have to admit that much of what is in the BUGS section in most UNIX >> manuals is not really bugs but rather random facts abut the program that >> it would be useful for the user to know about. > >Yep. I like Microsoft's adaptation: they call them "Comments". > > -John Owens > jso@edison.UUCP If you have seen the BUGS report for catman(8), you'd know just how useful bug reports are !! -- gdw@uk.co.ssl-macc gdw@sslvax.UUCP