Questions on Documentation

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

Questions on Documentation

Bob Richards-2
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

--
PGP Encrypted E-Mail Preferred
Public Key at: http://www.tamara-b.org/~bob/pubkey.asc
.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

Bugzilla from elio@mixtk.com
El Lun 10 Oct 2005 19:19, Bob Richards escribió:
>
> 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 ;-).

>
> 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...

>
> 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?
>

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
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

Michael Van Canneyt
In reply to this post by Bob Richards-2


On Mon, 10 Oct 2005, Bob Richards wrote:

> 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.

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.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

Jilani Khaldi
In reply to this post by Bob Richards-2

>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

--
// Jilani KHALDI
http://jkhaldi.oltrelinux.com



_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

Tomas Hajny
In reply to this post by Bugzilla from elio@mixtk.com
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

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

michael.vancanneyt


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.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

David Emerson
In reply to this post by Bob Richards-2
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" <[hidden email]>
> Sent: Tuesday, October 11, 2005 6:02 AM
> To: "FPC-Pascal users discussions" <[hidden email]>
> 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
>




_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

Tomas Hajny
In reply to this post by michael.vancanneyt
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

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

Bob Richards-2
In reply to this post by Tomas Hajny
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.

>
> My (simplified) categorization to get you started (before we manage to get
> it to our documentation):
>
> 1) procedural programming, short strings, cross-platform: ...
>

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



--
PGP Encrypted E-Mail Preferred
Public Key at: http://www.tamara-b.org/~bob/pubkey.asc
.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

Bugzilla from elio@mixtk.com
In reply to this post by Tomas Hajny
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...

El Mar 11 Oct 2005 11:31, Tomas Hajny escribió:

> 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
>
> _______________________________________________
> fpc-pascal maillist  -  [hidden email]
> http://lists.freepascal.org/mailman/listinfo/fpc-pascal
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

Bob Richards-2
In reply to this post by Tomas Hajny
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


--
PGP Encrypted E-Mail Prefered
Public Key at: http://www.tamara-b.org/~bob/pubkey.asc
.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

Felipe Monteiro de Carvalho
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,

--
Felipe Monteiro de Carvalho
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Documentation

Tomas Hajny
Date sent:       Wed, 12 Oct 2005 15:02:48 -0300
From:           Felipe Monteiro de Carvalho <[hidden email]>
To:             [hidden email],
        FPC-Pascal users discussions <[hidden email]>
Subject:         Re: [fpc-pascal] Questions on Documentation
Copies to:       Send reply to:   FPC-Pascal users discussions <[hidden email]>
        <mailto:[hidden email]?subject=unsubscribe>
        <mailto:[hidden email]?subject=subscribe>


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
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal