[fpc-pascal] Questions on Documentation

[Tomas Hajny]

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