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

[Michael Van Canneyt]

On Fri, 2 Dec 2011, Hans-Peter Diettrich wrote:

> Michael Van Canneyt schrieb:
>
>> If there are any platform-specific identifiers, the docs have always 
>> contained the linux-specific ones.
>
> I'm just about to create a Windows version of the RTL docs. In contrast to 
> the assumption, that one XML file could hold descriptions of multiple 
> modules, I tested the opposite way: having multiple XML files for one unit. 
> And it seems to work :-)

Nice to hear that.

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

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

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

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

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.

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.
I have no problem including such tools in the FPC distribution, whereas 
wildcard search in fpdoc itself is sure to be rejected.

Michael.