[fpc-pascal] Questions on Documentation

David Emerson dle3ab at angelbase.com
Tue Oct 11 18:21:43 CEST 2005


Thanks, Tomas! This list is terrific. Whenever I need a function, I'm usually aching for something like this to help me find what I want. While searching is great, sometimes I don't know what word to search for, and I can spend 40 minutes doing various searches through the documentation, without a clue of which unit I should be using. Then I get frustrated and post to the list, and more often than not, I just didn't know the correct search term, and if I'd had a way of knowing which units to narrow my search down to, I probably could have found what I wanted. It's just invaluable to have such a summarization-- I think I'm going to print this out. I'd really like to see more of this helpful summarization in the documentation. If it were more prevalent, I think we would get fewer very basic questions posted to the list, and people could use the documentation more effectively to find the information they need.

~David.



 -------- Original Message --------
> From: "Tomas Hajny" <XHajT03 at mbox.vol.cz>
> Sent: Tuesday, October 11, 2005 6:02 AM
> To: "FPC-Pascal users discussions" <fpc-pascal at lists.freepascal.org>
> Subject: Re: [fpc-pascal] Questions on Documentation
> 
> 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
> 







More information about the fpc-pascal mailing list