[fpc-pascal] Questions on Documentation

[Michael Van Canneyt]

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.

Michael.