[fpc-pascal] Questions on Documentation

[Elio Cuevas Gómez]

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 at lists.freepascal.org
> http://lists.freepascal.org/mailman/listinfo/fpc-pascal