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

[Hans-Peter Diettrich]

Michael Van Canneyt schrieb:

>> This means that we can document platform-specific items in additional 
>> files, which are automatically merged with the other descriptions. The 
>> description file specifications can be extended by a platform 
>> attribute, so that problems arising from multiple (platform specific) 
>> descriptions can be eliminated. E.g.:
>>        <description file="sysutils.xml"/>
>>        <description file="linux-sysutils.xml" platform="linux,unix"/>
>>        <description file="win-sysutils.xml" platform=windows/>
> 
> I don't see the point of this. Why not simply add them to the 
> description file sysutils.xml ?

You're right. So what's the use of --ostarget and --cpuversion, WRT 
common documentation?


> <element> tags for which no source file identifier exists are discarded 
> anyway.
> 
> If anything needs to be done at all, I see more use in adding a 
> 'platform' tag to the element tags themselves; That would give the 
> documentation generator useful information which it can use. In fact, 
> the 'platform' directive should in the first place be in the sources 
> themselves, where it will be picked up by the scanner/parser - as per 
> the remark of Marco.

Right.

>> It may make sense to place the platform specific files into dedicated 
>> subdirectories. When fpdoc is extended with description directories, 
>> from which all XML files are collected automatically, it will be 
>> sufficient to provide the platform-specific directories to fpdoc, so 
>> that most explicit --descr items can be removed or replaced by:
>>        <description file="*.xml"/>
>>        <description file="windows/*.xml"/>
>> or
>>        <description directory="windows"/>
> 
> I have no plans to support directory or wildcard search in fpdoc. That 
> is a can of worms I will not open;

I just implemented wildcards, and it seems to work nicely :-)

> One objection is for instance that your proposal will cause all XML 
> files to be loaded both when FCL and RTL documentation are created.

Already included: all XML files are discarded, when they don't 
contribute to the current package :-)

> In general: "Keep it simple" is a good design strategy.
> 
> All these 'automatisms' should be delegated to separate tools. This 
> keeps things simple, much more maintainable.

Well, I found it the simplest approach to add certain features to fpdoc 
itself, as long as nothing else is broken.


> Your strategy seems to be to put everything and the kitchen sink in fpdoc.
> You would be far better off making separate tools that implement these 
> automatisms. You can write a e.g. tool that creates or updates a project 
> file based on a directory scan.

There may remain things, which better should (and can!) reside in 
separate tools. Currently I feel no need for such additional tools, 
where the purpose would justify such efforts.

> I have no problem including such tools in the FPC distribution, whereas 
> wildcard search in fpdoc itself is sure to be rejected.

I already expected such a reaction ;-)

As long as the the fpdoc classes cannot be used and extended outside 
fpdoc, I see no way around inofficial patches, for private use. The 
number of fpdoc users is very limited, most users will be comfortable 
with the  final documenatation, so that there exists no urgent need to 
improve the distributed fpdoc itself. Fortunately my work on fpdoc 
itself is almost finished, so that I can return to the Lazarus 
documentation now.

DoDi