Hi All:

I am new to this list, but not new to pascal programming. I have been writing pascal code since Turbo pascal Version 3.0.

I have installed Free Pascal Ver. 2.0.0, running it on a Linux WorkStation, and am writing CGI apps which run on a Linux server. I love FPC! It keeps me honest, and my code "safe", and easy to follow years later.

I miss the old DOS IDE of Borland-of-Old; FP is somewhat OK, and Lazarus is way too much for system programming. But that's no real problem, VI does me just fine!

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.

I was reviewing some code I wrote, and discovered that some functions I had written were now part of an FPC Unit (more elegantly coded I might add).... Is there such a cross-reference document somewhere? If not, can one be generated using 'fpcdoc'?

Are there any printed manuals? Has someone written a good book which would be a good reference? Not knowing any OOP (nor having a desire to) would purchasing a book on Delphi help me in my FPC documentation quest? Any sugestions on which one?

Best Regards
Bob

Bob Richards wrote

I miss the old DOS IDE of Borland-of-Old; FP is somewhat OK, and Lazarus is way too much for system programming. But that's no real problem, VI does me just fine!

Why don't you try FP? It's included in the FPC distribution IIRC. But i'd rather program in VI any day ;-).

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, you could just print the PDF's. OOP is not required to program in FPC, but it sure helps. The FPC implementation of Delphi classes are very similar to... ehhhm, Delphi, so you could benefit from learning it.

Best Regards Bob

They are per unit, and then alphabetically. This is organized as logical as it comes.

A unit with a lot of procedures contains topics which group the procedures by category.

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.

They are listed like that, but on a unit-per-unit basis. You are supposed to know which units you want to use. It makes no sense to use e.g. SysUtils and Dos.

I was reviewing some code I wrote, and discovered that some functions I had written were now part of an FPC Unit (more elegantly coded I might add).... Is there such a cross-reference document somewhere? If not, can one be generated using 'fpcdoc'?

No.

Are there any printed manuals? Has someone written a good book which would be a good reference? Not knowing any OOP (nor having a desire to) would purchasing a book on Delphi help me in my FPC documentation quest? Any sugestions on which one?

A book on Delphi will only help you for the OOP part.

Michael.

I miss the old DOS IDE of Borland-of-Old; FP is somewhat OK, and Lazarus is way too much for system programming. But that's no real problem, VI does me just fine!

Try Joe editor, it looks like TP (3.0) editor and has the same short keys.

jk

Elio Cuevas Gómez wrote

El Lun 10 Oct 2005 19:19, Bob Richards escribió:

.
.

.
.

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

I think you would be far more productive if some kind of search function would be implemented.

Michael.

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.

Michael Van Canneyt napsal(a):

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

Tomas Hajny wrote

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.

Will do when I get a moment! This sort of reference is what I think is needed.

Thank you very much Tomas! This goes a long way to alleviate the frustration. It gives be a hint as to where to go looking for something needed.

If anyone else here finds Tomas' summary useful, I have done a quick and dirty html conversion for easy inclusion into the fpctoc file. Here: http://www.tamara-b.org/users/bob/AddToDoc.html

Bob

Also a problem i often face is to know where is what documentation. I often have to open all three documents to figure out which one i need. This isn't a major problem just a minor annoyance, but still...

A list member wrote me a private email and enclosed a very useful Korn Shell script which he posted here on the list in the past; it produced this: http://www.tamara-b.org/users/bob/rtl_pf_index.html Document.

With this, as well as Tomas' file added to the docs, I am now cooking! Thanks!!

Bob

Thomas,

What do you think about adding this unit list to the wiki? Maybe it could be added to the "Run-Time Library" article, witch is quite short currently. If you agree I can include it on the wiki, so it can help others looking for this kind of information.

thanks,

Date sent: Wed, 12 Oct 2005 15:02:48 -0300
From: Felipe Monteiro de Carvalho
To: ,
FPC-Pascal users discussions
Subject: Re: [fpc-pascal] Questions on Documentation Copies to: Send reply to: FPC-Pascal users discussions

Felipe

What do you think about adding this unit list to the wiki? Maybe it could be added to the "Run-Time Library" article, witch is quite short currently. If you agree I can include it on the wiki, so it can help others looking for this kind of information.

Actually, if I haven't been so lazy, I'd put it in wiki directly. ;-) Fixed now. One of the advantages is that people can provide description for individual platform specific units this way (have I already mentioned my laziness? ;-) - anyway, at least sometimes it's better if people know what they are describing ;-) and I certainly don't know all the units for all platforms, so the risk of incorrect information would be rather high).

Tomas