Path: utzoo!utgpu!news-server.csri.toronto.edu!rpi!batcomputer!cornell!uw-beaver!zephyr.ens.tek.com!vice!bobb From: bobb@vice.ICO.TEK.COM (Bob Beauchaine) Newsgroups: comp.lang.pascal Subject: Re: Borland flaming Message-ID: <7254@vice.ICO.TEK.COM> Date: 9 Apr 91 18:31:35 GMT References: Reply-To: bobb@vice.ICO.TEK.COM (Bob Beauchaine) Organization: Tektronix, Inc., Beaverton, OR. Lines: 131 In article cschmidt@lynx.northeastern.edu writes: > >I will give you a reason for free: Borland documentation is awful. > I generally avoid flame wars, but since you chose to speak for all professional developers, I must contest your assertion. >To prove this assertion would require a much longer critique than you >would care to read. How exactly does one go about proving an opinion? I personally think that Borland's products have the absolute best documentation I've ever seen. They go into more detail and cover more topics that anyone else. Just the other day, I installed some desktop publishing software. After installing several fonts, the computer locked up when I tried to use the fonts. Turns out I had to run one more utility before I could use this program, but the documentation relegates this fact to the fineprint and removes the documentation of the utility some 200 pages from it's implementation. For a real laugh, try to read Microsoft's Quick Pasal documentation sometime, especially if you've programmed in Pascal for more that 6 months and want some real information. >o The Turbo C++ manuals describe several methods to tell the > compiler whether to regard the input program as "C++ code" or as > "C code", but I have not found an explanation in any of the four > Turbo C++ manuals of how the results might differ. How is it > possible that Borland could describe a compiler switch without > explaining its effect? > If you read a little more closely, you would have noticed that the differences are only the syntax the compiler allows in a source module. The final run time code is not altered if you don't use any of the C++ extensions. > I could speculate that the difference might have something to do > with "type-safe linkage", but that term is not mentioned in any of > the Turbo C++ manuals, as far as I have determined. (However, > Borland manuals are poorly organized, so it is hard to find > things. I am certain that "type-safe linkage" does not appear in > any form in any of the indexes.) Probably because it's not the issue. >o The following excerpt from the Turbo Assembler User's Guide (page > 529 in my edition) is Borland's explanation of what is commonly > known as "scope", in regard to field names within structure > defintions: > > [Borlands humor attempt deleted] > The reader's task is more difficult when useful information is > hidden within nonsense like this, and there's lots of nonsense > like this in Borland manuals. I don't go to technical manuals to > find amusement or entertainment. It is tedious to wade through > nonsense like this to find the information I need. I specifically remember reading this excerpt from the TASM manual, and getting a good chuckle. Of course, you neglect to mention the following paragraph, which (from memory) states "But seriously...". The point of the paragraph was not lost because of a little pun. I, for one, appreciate a documentation group that understands it's product enough to be able to make a few jokes about it in the process. Don't take your profession too seriously; lighten' up! > Perhaps if the Borland documentation people spent less time > writing long tutorials and weaving nonsense into their prose, they > could devote more time to their primary mission, which is to > produce accurate, concise, and complete technical documentation. > I think they do a better job than any other professional software house I've ever had the pleasure of doing business with. Granted, that's not an all encompassing statement, but you asked... >o In Turbo Pascal 5.0, unsigned integers are not allowed as labels > in case statements, even when the case statement selector > expression is an unsigned integer. The workaround I employed was > to use equivalent negative values as case statement labels for > values greater than 32767. > > In Turbo Pascal 5.5, unsigned integers ARE allowed in case > statement labels, and negative integers are NOT allowed when the > case statement selector expression is unsigned. This means the > workaround I employed was no longer valid. My old code would not > even compile. > So you don't want bug fixes included in updates? I agree, I have never seen a bug fix update in Borland's documentation, but perhaps you would have been notified if you had told Borland Technical support of the bug in the first place. > There was no mention of any of this in the Borland documentation. > Borland must document these things if they expect to be taken > seriously by professional programmers. One programmer I know said > that "Turbo Pascal is a joke". He does not appreciate Turbo > Pascal's many strengths, and he probably never will unless the > Borland manuals develop a more serious style. > Sounds like he needs a laxative. Does he program exclusively in C by any chance? :-). >The most effective thing Borland could do to improve their image among >professional programmers would be to improve their documentation, >since their compilers are already pretty good. At the very least, >Borland should provide complete revision details with product >upgrades. If they want respect from professional programmers, they >should show respect for us by providing smart documentation written >for grownups. > Gee, my Turbo Pascal 5.0 update devotes pages 199-225 entirely to differences between Turbo Pascal 3.0,4.0, and 5.0. Maybe the guys missed a few bugs, but don't say they don't document the progress of the language. /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ Bob Beauchaine bobb@vice.ICO.TEK.COM C: The language that combines the power of assembly language with the flexibility of assembly language.