[Lazarus] FPDocManager now handles selectable FCL packages

[Hans-Peter Diettrich]

Only few FCL units are documented right now. This is not a special 
limitation for Lazarus applications, which do not normally use FCL 
units. But when e.g. the PParser unit is used in a project (like 
FPDocManager), a few notes on the essenial parts of selected units are 
appreciated. That's why the (now removed) docs/xml/fcl directory had 
been added for such inofficial descriptions. For now we assume that such 
a directory exists, and has been added to the FCL options in FPDocManager.

The FPDoc Editor can be used in the IDE, to add descriptions even to FCL 
units. But when somebody wants to supply such descriptions for addition 
to the official docs, some problems become noticeable.

Most FPDoc tools fail to work on units which deserve special compiler 
options, when the user cannot supply the required options. I.e. you may 
not be able to add descriptions in the FPDoc Editor, or MakeSkel or 
LazDE creates only an empty or invalid skeleton. In these (rare) cases 
you are most probably lost :-(

This was the reason for the addition of *selectable* FCL packages, for 
which the FPDocManager now can create documentation skeletons, and 
allows to update, syntax check, and to create the final documentation 
for the contained units.

Before you start documenting new FCL units, you should check the 
according package in the FCL packages list, and then try to Refresh the 
FCL docs. This may fail, e.g. for fcl-process, due to beformentioned 
missing compiler options. Then you'll have to uncheck that package 
again, and stop working on it for now[1].

Otherwise you'll get the skeletons for all units, pertaining to that 
package, *and* which had not been documented before by e.g. using the 
FPDoc Editor. As soon as a description file is found, the Refresh 
feature only will create *update* files, which have to be merged 
manually into the existing file. Or, even worse, MakeSkel may extinguish 
your previous work (untested). An automatic merge is on my ToDo list, 
but don't hold your breath. So you better create skeletons *before* 
adding any documentation to yet undocumented units.

Please note that your added descriptions do *not* become part of the 
entire FCL package, i.e. they are not listed in the FCL units pane. 
Nonetheless they are checked or added to the final docs by the 
FPDocManager, when no specific unit is selected.


The remainder is for keen users, which want to work around 
beforementioned problems.

[1] The FPDocManager creates both an INI file and an FPDoc project for 
all registered packages. In the case of the FCL package it also creates 
an additional fcl_prj_ext.xml project file, which contains all the added 
source and description files. This file is re-created for every 
operation on the FCL package, based on an scan of the FCL source and 
description directories. This way the input files are supplied for all 
added description files, no need to add them explicitly.

The project files can be edited manually and supplied to FPDoc or 
MakeSkel. This way a user can e.g. try to figure out the compiler 
options, required to process specific units properly.

So much for now.

DoDi