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

[Michael Van Canneyt]

On Sat, 3 Dec 2011, Graeme Geldenhuys wrote:

> On 3 December 2011 16:03,   wrote:
>> First, it keeps the actual documentation XML more "clean" in the sense that
>> it contains only documentation, and not 'organizational instructions'.
>
> The documentation is useless unless you have the associated *.pas
> unit. As you even mentioned earlier. fpdoc doesn't include
> documentation if it can't find the associated identifiers, units etc.
>
> So no matter how you think about it, the XML documentation is closely
> tied to the source code it documents. After all, it is API
> documentation we are talking about.

Agreed. But see below. I think we are talking about different things.

>
>> 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.
>
> API documentation writers are technical people, probably a programmer.
> They *will* have to look at the source code, no know how to document
> each API.

All correct, but the documentation writers are not the people who create 
the final documentation (as in "html files", or whatever format).

It is the packagers who must produce the output, and it is the latter 
who, in my opinion, benefit from the use of a project file: 
they must 'organize' their work: from disparate XML files create 
a single, coherent documentation, from files located in different 
locations, obtained from different writers. This is the organization 
I was talking about. Not the organization of actually writing the 
documentation.

The former (the documenters) will normally work in Lazdoc or whatever 
tool that supplements the IDE, and the IDE knows where all relevant 
source files are.

Michael.