From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 103376,88ed72d98e6b3457 X-Google-Attributes: gid103376,public X-Google-ArrivalTime: 2003-11-02 08:41:45 PST Path: archiver1.google.com!news2.google.com!news.maxwell.syr.edu!eusc.inter.net!cs.tu-berlin.de!uni-duisburg.de!not-for-mail From: Georg Bauhaus Newsgroups: comp.lang.ada Subject: Re: Standard Library Interest? (The Big Player ACT) Date: Sun, 2 Nov 2003 16:41:44 +0000 (UTC) Organization: GMUGHDU Message-ID: References: <3F82F527.3020101@noplace.com> <3F9EFDC6.7050508@noplace.com> <254c16a.0310290635.1a8b09d2@posting.google.com> <3FA04E6E.2070000@noplace.com> <3FA322D8.2040003@noplace.com> NNTP-Posting-Host: l1-hrz.uni-duisburg.de X-Trace: a1-hrz.uni-duisburg.de 1067791304 21064 134.91.1.34 (2 Nov 2003 16:41:44 GMT) X-Complaints-To: usenet@news.uni-duisburg.de NNTP-Posting-Date: Sun, 2 Nov 2003 16:41:44 +0000 (UTC) User-Agent: tin/1.5.8-20010221 ("Blue Water") (UNIX) (HP-UX/B.11.00 (9000/800)) Xref: archiver1.google.com comp.lang.ada:1927 Date: 2003-11-02T16:41:44+00:00 List-Id: Marin David Condic wrote: : Whatever documentation is available for Charles, it isn't an integrated : part of the library. I think it is, but you cannot see it :-) Point is, you cannot make good use of the library if you haven't understood how it works. No hypertext can help here. No short "contextfree" subprogram description, no example introducing more context than you had asked for. Worse, you can waste even more time trying to find answers for basic usage questions, as Stephane has explained. But, you rarely *need* to dive into the detailed annotation hypertext once you have understood how the (container) library works. That is because it is organised in a predictable way, around a few principles, for a well specified purpose. (Not for a massive collection of everything.) Would it make sense to try to explain the underlying fundamentals in descriptions of what is built upon the fundamentals, so to speak? Or should the fundamentals be explained elsewhere? And OTOH you don't need so much more than to know the priciples, in practice. If you look at SGI's STL headers and those of other vendors derived from them, you won't be seeing a lot of comment. And I think many of these comments would be repetitive as well as useless. Another example: One could argue that SUN's Java libraries have extensive hypertext documentation, and that Eclipse pops up relevant doc parts next to a name denoting an item from the library. That's useful if the library isn't that well organised, and you have forgotten some specifics. But still, given typical usage of the hypertext, how do people learn that there are "container classes" with methods, and "static functions" to work with containers, in a "parallel" set of classes? If they ever learn this at all. Some similar situations: How do you learn how to write a GUI using GTKAda, or NextSTEP, or ...? Hypertext describing relevant subprograms seems useless to me without prior learning, e.g. from an n-days tutorial. After that, if you know what subprogram to use, a quick lookup table is most helpful, and hypertext will guide you to parameter details etc. But no earlier than after the tutorial, and only if the library is a mess whose organisation cannot be kept in anyone's head :-) (It appears that container libraries such as Charles or Booch's need not be messy, but can be made consistent in your comprehension.) : There may be any number of ways for the determined : user to find out what Charles does, but it isn't just standing right : there saying "Here I am - let me tell you more about it..." In view of the above this expectation is maybe mislead. Once you know the principles, you can almost guess what is in the interface to some container. I think this is much more productive and fun. :> (Does it help knowing that STL work began with Ada and Scheme? :) :> : Nope. If I loved the STL so much, I'd run off and use C++. Ada having : inspired the STL and Charles having copied the STL is pretty irrelevant. : Its Ada saying "Me too!!!" rather than "I'm head-and-shoulders above the : STL!" You would have to prove how it is possible to be head-and-shoulders above the *principles* of STL. C++ or Ada is not that relevant here, I think, except that Matthew Heaney writes that Charles is an Ada library, using Ada features, not C++. : If you want to gain users, you must make it as EASY and PAINLESS as : possible to get REALLY high quality stuff. Users are like water flowing : downhill - they seek the path of least resistance. In the case of standard container library, should Ada vendors follow strategies from the MS marketing labs, in that they try to impress programmers with linked descriptions that turn out to be no more useful than Stephane has explained? Does this documentation hay stack searching trigger good software engineering in case good software engineering implies good use of a container library in the learned ways it has been designed to be used? Hypertext is just a formal aspect of text structure. It does not by itself guarantee that the links are good. Imagine an admonition link next to every occurrence of an Iterator, type Iterator is ... private; -- and again bla blah, same as Iterators everywhere, bla bla -- bla bla blah bla bla, blabla blaha. -- BUT DON'T forget to read the introductory -->[Chapter on Iterators] when understanding the introductory chapter on Iterators makes all the bla bla comments nothing but a waste of time? In an IDE, what information should be one click away, for example if it comes to Ada reserved words? One answer to this question can be found on http://www.htdp.org which goes along with an IDE. Does this say something about the kind of text accompanying a library's "standard" identifiers when the identifiers are used as starting points of links to documentation? Georg