Also a problem i often face is to know where is what documentation. I often have to open all three documents to figure out which one i need. This isn't a major problem just a minor annoyance, but still...
El Mar 11 Oct 2005 11:31, Tomas Hajny escribió: > Michael Van Canneyt napsal(a): > > On Tue, 11 Oct 2005, Tomas Hajny wrote: > >> Elio Cuevas Gómez wrote: > >>> El Lun 10 Oct 2005 19:19, Bob Richards escribió: > >> > >> . > >> . > >> > >>>> The biggest problem I have run into is the function/procedure > >>>> documentation. While very complete, and clearly written, it is > >>>> organized > >>>> in > >>>> a way making it difficult to find things. Similar functions and > >>>> procedures > >>>> are scattered among various Units, making things difficult to locate. > >>>> What > >>>> I need is a reference document, listing procedures and functions by > >>>> category (or at the very least alphabetically as in the Turbo Pascal > >>>> 5.0 > >>>> Reference guide). All disk-file routines for instance, listed, in one > >>>> place. > >>> > >>> Well, the functions are organized by unit. The IO functions are in the > >>> system > >>> unit i think. Misc functions are in the SysUtils unit, etc... > >> > >> . > >> . > >> > >> Well, to be honest, I don't think this is a complete answer. It's > >> certainly true that you can achieve similar effects by using different > >> functions stored in different units. From this point of view, some kind > >> of > >> categorization of supplied units would probably help, in fact - as it is > >> now, it's a list of units without providing any hint what to search > >> where. > >> I don't think that it makes sense to try to list e.g. "all disk I/O > >> functions", because different things would be mixed together and it > >> probably wouldn't help either. > >> > >> Such categorization should probably include different programming models > >> (procedural, TP/BP style OOP, Delphi style OOP), whether ansistrings are > >> used or not (default with -Mdelphi/$MODE DELPHI or $H+), cross-platform > >> and platform specific units (with information about their > >> availability/useability for different targets), basic information about > >> type of functionality to be found there (similar to the "Overview" > >> chapter > >> in individual unit descriptions, which is unfortunately little bit > >> uncomplete regarding information about categories mentioned above and > >> even > >> missing altogether for many units) and availability of this unit in > >> other > >> Pascal compilers (at least TP/BP, Delphi and FPC specific). Something > >> like > >> this should probably appear at the beginning of the unit reference. From > >> this point of view, I'd suggest to fill your comment as a "Wishlist" > >> type > >> bug record for area "Documentation" in our bug repository, so it doesn't > >> get forgotten. > >> > >> My (simplified) categorization to get you started (before we manage to > >> get > >> it to our documentation): > > > > I think you would be far more productive if some kind of search function > > would be implemented. > > Search function is available at least for the PDF version. However, > searching only helps if you already know the right function name (and just > miss information the unit implementing it), or if you manage to guess the > words which would appear in the description (not too generic to avoid 100s > of results, but generic enough to find all different functions for > different contexts but more or less the same functionality). > > The situation of the original poster (and anybody coming new to FPC > without having recent TP/BP and Delphi background and thus knowing by > heart what functionality should be found in this or that unit) is IMHO > different - he really needs some kind of overview to understand which > units "fit together" (i.e. that it doesn't make much sense to mix > functions from SysUtils and Dos in one program, etc.) and where to find > the individual building blocks for his program. I sincerely believe that > adding this kind of simple overview (and adding/extending the current unit > overviews where appropriate) would help to some people - especially > newcomers who either learn Pascal with FPC, or know Pascal as programming > language, but not our (TP/BP/Delphi) units. But let's see what's his > opinion on this (i.e. whether my response helped him at least little bit, > or not at all). > > Tomas > > _______________________________________________ > fpc-pascal maillist - fpc-pascal@lists.freepascal.org > http://lists.freepascal.org/mailman/listinfo/fpc-pascal _______________________________________________ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
