[fpc-devel] Errors with make rtl.chk on Windows

[michael.vancanneyt at wisa.be]

On Sat, 3 Dec 2011, Graeme Geldenhuys wrote:

> On 3 December 2011 01:59, Michael Van Canneyt  wrote:
>>> Already included: all XML files are discarded, when they don't contribute
>>> to the current package :-)
>>
>>
>> Because of the loose coupling between XML files and source files, there is
>> no way to know if a XML file is contributing or not, unless you impose some
>> convention like 1 unit = 1 file with equal filenames, or parse the XML file
>> to detect the module it documents or start moving XML files to directories.
>
>
> I've always wonder about the very verbose command line parameters used
> with fpdoc. Why couldn't the XML simply mention which unit(s) it
> documents. You could also include macros [eg: $(somemacro) ] which
> fpdoc could substitute when the xml file is processed. The macros
> could be defined in some fpdoc.ini file, or passed as command line
> option. I would opt for the ini file choice, but the command line
> param could be used to override the macro if needed.

Strictly speaking, the XML file does say which units it documents. 
See the <module name=xyz"> tag. One problem is that you know this 
only after you have parsed the XML when you should know before starting.

I think there are several other reasons why the project file approach is more
powerful.

First, it keeps the actual documentation XML more "clean" in the sense that 
it contains only documentation, and not 'organizational instructions'.

Just like a lazarus project file (.lpi) is different from the actual source file (lpr).
You'll remember that Delphi used to try and put all project info in the 
.dpr file, and I think we all know what a pain that was.

I think it would also require the documentation writer to foresee organizational 
issues and parametrize them in the XML, which I think is something the documentation 
writer should not have to care about. The person generating the documentation, on the
other hand, 'knows' the possible situations and can parametrize his project
file for this. (and indeed, can create many different project files)

Speed is also an option. If we start allowing macros, then as an end result
the macros must be processed in the whole XML file. The documentation XML 
is rather big; the project file is small.

In true unix philosophy, I think it is better to have many small and simple tools
cooperating well than one large tool which tries to do everything and fails
miserably. There you have, in a nutshell, the design philosophy of fpdoc :-)

Michael.