[fpc-pascal] standard unit description -- builtin funcs & procs

[Tomas Hajny]

On Fri, May 7, 2010 11:55, spir ☣ wrote:
> On Fri, 7 May 2010 11:09:42 +0200 (CEST)
> "Tomas Hajny" <XHajT03 at hajny.biz> wrote:
>
>> > http://www.freepascal.org/docs-html/user/userch9.html
>>  .
>>  .
>>
>> BTW, you may also want to have a look at
>> http://wiki.freepascal.org/Unit_categorization - it's incomplete (some
>> newer units are missing there), but it still may help you a bit (and you
>> or anyone else are welcome to extend it with further findings).
>> Obviously,
>> it's just for the first orientation especially for newcomers not having
>> TP
>> and/or Delphi background; the details are provided within the reference
>> guide.
>>
>> Tomas
>
> Thank you very much, Thomas. This page seems to be what I missed.

I'm glad that you find it useful. :-)


> Actually, the issue is for me there seems to be (from an outside/newcomer
> pov) no organisation principle for libs (?), units, funcs, types that come
> with fpc. For instance, there are collections in various units, and those
> are not predictable for me (why the f*** is TFPList in "classes"? It one
> and a half hour to find it using a systematic review, after someone
> mentionned it) (and why not even listed in the overview of "classes"?
> while TList is there
> http://www.freepascal.org/docs-html/rtl/classes/index.html) (and why is
> "classes" in "rtl", by the way?).

I understand your point. A lot of that is directly or indirectly related
to the background of FPC written from the beginning specifically for
compatibility with TP/BP at first and later extended to compatibility with
Delphi. Over time (or even from the very beginning), Delphi has thrown
away a lot (most ;-) ) of compatibility with TP/BP (although it was a
direct successor of TP/BP and came from the same company), whereas FPC
kept compatibility to both. This results in duplicities / overlaps -
that's why you find collections in both objects (TP/BP compatibility) and
classes (Delphi compatibility, different OOP model).

Also, this is why TFPList is in classes - if TList is in classes due to
compatibility with Delphi, it's logical to have TFPList there too.

Unit classes is part of RTL for mostly the same reason - it's in RTL in
Delphi too and it contains some rather basic elements used in many
different contexts by probably most programmers using the Delphi OOP
model. See description at the bottom of
http://www.freepascal.org/docs-html/rtl/.


> I'll update/expand the page as I get to know better what it points to. A
> short introduction to the content, structure and use of fpc units' ref
> pages would also be helpful, what do you think?

"FPC units' ref pages" are just one of the formats in which FPC
documentation is provided (in addition to e.g. PDFs and CHMs) and which
are all generated from sources maintained in our SVN repository. If you
mean that the introductory part of this documentation (as available e.g.
on http://www.freepascal.org/docs-html/rtl/) should be extended with some
more information in order for a newcomer to understand the structure of
the documentation, I'd suggest creating a feature request ticket in our
bugs tracker with the appropriate category (docs) and adding a suggestion
or even directly proposed changes to the text. The Wiki page I created
some time ago is meant just as an additional resource with all advantages
and disadvantages related to the fact that it is maintained separately
(one of the advantages is the fact that everyone can extend it with
additional information he considers important and missing there).

Tomas