FreePascal/Lazarus documentation

[Lauriet]

I miss the old programming so much.

I remember when I was a kid, Borland Pascal 7 had all it needed. With one Turbo Pascal programming book in Romanian, and with the ginormous help file BP had, everyone was there. Nothing was missing. You want graphics - you look at Graph unit. You want file operations - you look at Dos unit. And so on.

I'm just gonna skip the BPW. I wasn't ready at the time to understand hwnds and device contexts and message loops and all of that.

After the transition to .Net - which I missed at that time - we got into magical coding. So instead of the beautiful coding we had, it all turned into a form of wizardry where you dig in for hours thru the classes and methods to write a few lines, like finding the right spell in a grimoire. That's when I kinda lost connection to regular coding before moving into Metatrader/MQL4 for some years.

Is there any full documentation for Lazarus, just as BP7 had ?

I mean how the hell would I know that it has an UINT32 and an UINT64 since I knew these are C things ? Our world knew only Longint and the deceased Comp.

I was just trying yesterday to test CopyFile in FreePascal and it even fails with compilation errorc : illegal expression at 1329 in lazfileutils.pas cause it can't do Param+:=Params[p] -> although it's the same 3.2.2 and I tried with {$mode objfpc} as well.

I moved the test to Lazarus where it compiled, I don't understand why and I don't need to. But why do I need to google everything ?

Is there really no full reference for the units and the classes ? How can i possibly know that it can copy a file and even make the directory structure in the meanwhile if there is no manual about it ? Marco Cantu wrote a 500-page book about Delphi 11 Alexandria without even touching stuff that's in units!

Is there really no full documentation, top to bottom, including the units and various useful packages like RichMemo for instance, something that can be navigated fully offline ?

Likewise, I still have the manuals for TP4, 5, 7 and you could learn the complete package while in the "loo"
OOPS came along, promising that it would simplify everything. But as you point out you, now you've got so many objects that its quicker to write it yourself than to wade through truck loads of docs if they are available. (is there an object that I can use ? What are the properties/methods, what is it inherited from etc)
GUI came along with a million more objects/classes to learn and now there is bloated code, just to make things look pretty.
N Wirth. probably saw the light and chose to invent languages even simpler (eg Oberon)

[MarkMLl]

Emphasising the distinction between FPC and Lazarus and focusing on the former, IMO the reference manual etc. is excellent.

What is not at all excellent is the indexing of the RTL and FCL documentation, which makes "how do I do this?" questions difficult to resolve.

I attempted to tackle this a few months ago by way of a permuted index, but it was not favourably received so I abandoned it.

https://forum.lazarus.freepascal.org/index.php/topic,69941.msg544398.html#msg544398

MarkMLl

[PascalDragon]

I was just trying yesterday to test CopyFile in FreePascal and it even fails with compilation errorc : illegal expression at 1329 in lazfileutils.pas cause it can't do Param+:=Params[p] -> although it's the same 3.2.2 and I tried with {$mode objfpc} as well.

C-style operators require $COperators On which might not be enabled depending on your setup.

Is there really no full reference for the units and the classes ? How can i possibly know that it can copy a file and even make the directory structure in the meanwhile if there is no manual about it ? Marco Cantu wrote a 500-page book about Delphi 11 Alexandria without even touching stuff that's in units!

Is there really no full documentation, top to bottom, including the units and various useful packages like RichMemo for instance, something that can be navigated fully offline ?

No, there is no complete documentation, because it would need someone to write it. And as both FPC and Lazarus are hobby projects you can't force people to do so.

For starters, TRichMemo is a third-party component. So Lazarus will not provide docs for it - that project would have to provide it. And even if they do, you can't integrate that CHM into the IDE help system. HTML yes... CHM no.

But LHelp uses CHM? 🤔

[dsiders]

For starters, TRichMemo is a third-party component. So Lazarus will not provide docs for it - that project would have to provide it. And even if they do, you can't integrate that CHM into the IDE help system. HTML yes... CHM no.

But LHelp uses CHM? 🤔

Yes it can display CHM, but it requires custom code in the help system to integrate the CHM with the source code that it documents. There is an ExternalHelp package... but it's not the same level of intregation as the built-ins (RTL, FCL, LCL, LazUtils).

[MarkMLl]

No, there is no complete documentation, because it would need someone to write it.

And doing so would be extremely difficult for something like the LCL, because of the difficulty of indexing "How do I make /this/ look like /that/?" questions.

MarkMLl

[marcov]

I attempted to tackle this a few months ago by way of a permuted index, but it was not favourably received so I abandoned it.

https://forum.lazarus.freepascal.org/index.php/topic,69941.msg544398.html#msg544398

I did look favorable on the principle of having over arching lists of certain topics (like string routines). While developing the CHM support I hoped to use alinks for that, but it was not up to snuff.

Back then I was thinking about having tags in the function descriptions of topics, and stuffing that info into the .XCT files or into a file in the root of the CHM.  Then you would be able to blend those files of all registered fpdoc helpfile packages to such tables.

And we are a Pascal project. Even if Perl hypothetical would be better to write it in, it wouldn't be better for the project to maintain it. Scripts like yours however could be used to mass tag such topics, and e.g. before every release check if tags need updating. But even then I'd rather have something in a language that appeals to as many people within the project as possible.

p.s. originally the FPC latex docs were converted to html using a Perl script. It broke every 0.00001 version upgrade of Perl. I vowed never to touch Perl again.

[MarkMLl]

It wasn't you so much Marco as the incoherent gripe from somebody else which made me realise just how fed up I was with things.

I believe I did emphasise that what I'd done was a "proof of concept" which could obviously be rewritten once the workflow was understood: any "retrospective" like this is bound to be iterative.

Apart from that it's unfortunate that the .chm files of 2.4 and earlier aren't available so that the full timeline could be documented. When I first looked at this (I'd guess in the 2.6 era) I was working from the PDF files, but that was very much a hack since I was having to deduce page structure purely from header markup etc... which was highly undesirable.

I believe that I started looking at document generation (I can't remember whether I was trying to generate .chm files, but at least in retrospect that would have been the obvious approach) but hit major cross-version compatibility issues. That was unfortunately curtailed due to "real life" issues, and even if they were any use I doubt the files are retrievable.

I'll run off a permuted index of 3.4 if it's eventually released. However I suggest that the main problem right now is the "this needs main to work" mantra regularly chanted by the somebody else alluded to above: I suggest that having to refer people to unreleased code and/or documentation is in nobody's interest.

MarkMLl

p.s. My business logic has used Perl for 25 years without compatibility issues, I /have/ however seen problems with other people's code where they were trying to be clever using internal facilities. That's more than I can say for either FPC (the FileExists() debacle, portability between Debian 11 and 12, and so on) or Lazarus (redesign of the tabbed pages API etc.). I'm not trying to find fault, "just sayin'" as they say.