[fpc-pascal] Questions on Documentation

[Tomas Hajny]

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):

1) procedural programming, short strings, cross-platform:

- System - basic type definition, execution control, parameter processing,
string handling, type conversions, mathematic operations, memory
management, basic routines for console and disk I/O, constants and
variables describing the particular platform and/or current environment
(available in TP/BP and Delphi)

- Strings - operations with PChar strings (available in TP/BP)

- Matrix - vector and matrix routines (FPC specific)

- UComplex - operations with complex numbers (FPC specific)

- GetOpts - routines for more advanced access to program parameters

- Keyboard - low-level access to keyboard (FPC specific)

- Mouse - mouse support (FPC specific)

- Video - routines for low-level access to screen (FPC specific)

- Printer - very basic access to printer (available in TP/BP)

- Sockets - basic support for TCP/IP socket communication (FPC specific)

- CMem - replacement memory manager based on C run-time library to allow
easier integration with some code written in C (FPC specific)

- CTypes - definition of C language types for easier integration with
routines written in C (FPC specific)

- InitC - some functions required for linking of some libraries written in C

- MacPas - special unit supporting constructs formerly available in some
Pascal compilers for Mac OS platform (ThinkPascal, Metrowerks etc.);
available for all platforms with FPC to support -Mmacpas/$MODE MACPAS (FPC
specific)

- HeapTrc - debugging support unit for tracing of incorrect memory
allocation (more or less FPC specific, at least not available with TP/BP
and probably Delphi either)

- LineInfo - debugging support unit to allow displaying of location (line)
in source files in case of an error based on debug information linked to
executable file (FPC specific)

- Crt - more advanced console (keyboard and screen) routines (TP/BP
compatibility unit plus some FPC specific functions)

- Dos - more advanced disk I/O, execution flow (including running of other
programs), date and time handling and access to environment variables,
plus some compatibility routines only available/making sense for DOS
platform (TP/BP compatibility unit plus some FPC specific functions; some
of the functions were provided in WinDos unit in older Delphi versions)

- Graph - simple graphics support (TP/BP compatibility unit)


2) procedural programming, ansistrings, cross-platform:

- SysUtils - more advanced disk I/O, execution control (including
exception handling and running of other programs), access to environment
variables, string routines (support of ansistrings and widestrings),
conversion routines (strings, numbers, date/time), internationalization
support (Delphi compatibility plus some FPC specific functions)

- StrUtils - various more advanced string routines (Delphi compatibility)

- DateUtils - data/time handling routines (Delphi compatibility)

- ConvUtils - conversion between different units of measurement (Delphi
compatibility)

- SysConst - resource texts for SysUtils (Delphi compatibility?)

- RTLConst - resource texts for other RTL libraries (especially unit Classes)

- DynLibs - on-demand (run time) loading of dynamic libraries

- Math - more complex mathematic and statistic routines; no ansistrings
really used here directly, although it loads unit SysUtils and thus
installs its exception handler (Delphi compatibility with FPC specific
additions)

- FreeBIDI - helper routines for bidirectional text output (FPC specific)

- Utf8BIDI - helper routines for conversion of UTF-8 encoded text
supporting bidirectional output (FPC specific)

- ObjPas - basic support for -Mobjfpc and -Mdelphi including some type
redefinitions and resource string support; unit used automatically for
those modes, no need to add it manually (FPC specific, although the
provided routines are compatible to routines available System unit with
Delphi)


3) TP/BP style OOP, shortstrings, cross-platform:

- Objects - base of the object hierarchy, disk I/O and memory operations
for OOP programs - streams, resources, lists and collections (TP/BP
compatibility)

- FV (Free Vision) units - complete framework for writing TP/BP-style OOP
programs with text-mode windowing user interface (TP/BP compatibility -
more or less compatible to Turbo Vision)


4) Delphi style OOP, ansistrings, cross-platform:

- Classes - base of the class hierarchy, disk I/O, execution control and
memory operations for OOP programs - streams, resources, lists,
collections, threads, components, actions, interfaces, data modules etc.
(Delphi compatibility)

- VarUtils - variant support routines (Delphi compatibility?)

- FCL units - non-visual classes for OOP programming (partly similar to
Delphi VCL, but only non-visual parts are provided here)


5) procedural programming, shortstrings (although ansistrings may be
used/supported in some cases too), platform-specific:

This list is fairly extensive, so I'll stick to information about
availability for individual platforms and ask you to have a look at the
description of individual units for more information about them. In
general, these units or FPC specific except for the Windows, WinCrt and
WinSock units available with Delphi, and unit LibC available with Kylix.

- Ports - x86 platforms to support port access construct provided with TP/BP

- CPU and MMX - x86 platforms for support of some low-level CPU-specific
functions

- UnixType, BaseUnix, Unix, UnixUtil, SysCall, GPM, IPC - Unix platforms
(Linux, *BSD including Mac OS X, Solaris, NetwLibC, plus possibly BeOS and
QNX again in the future)

- x86 - Unix platforms running on x86

- LibC - mostly Unix platforms, although it could be probably used with
other platforms too (Cygwin for Win32, Innotek GNU C/C++ for OS/2, etc.)

- Linux, OldLinux - as the name implies, specific to Linux (the latter is
provided for compatibility with FPC 1.0.x and not supposed to be used in
new programs any more)

- Windows, WinMouse, WinEvent, WinSysUt, WinCrt (plus package WinUnits
provided outside of RTL in "Packages" - MS Windows platforms (Win32,
Win64, WinCE)

- WinSock - MS Windows, OS/2 and Netware

- Go32, Emu387, DpmiExcp, DxeType, DxeLoad - GO32v2

- MacOS, MacUtils - classic Mac OS

- Exec, Timer, DosLib, Utility, Hardware, InputEvent, Graphics, Layers,
Intuition, Clipboard, ASL, AHI and Get9 - MorphOS

- Netware, NWCalls, NWNit, NWPre, NWProt, NWServ, NWSNUt - Netware

- OS2Def, DosCalls, KbdCalls, MonCalls, MouCalls, VioCalls, PMWin, PMGpi,
PMStdDlg, PMBitmap, PMBidi, PMHelp, PMSpl, PMShl, PMWP, PMWSock, PMDev
(plus package OS2Units provided outside of RTL in "Packages") - OS/2


I'm sure I forgot some units in this list. ;-)

Tomas