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

[Michael Van Canneyt]

On Sun, 4 Dec 2011, Hans-Peter Diettrich wrote:

> Michael Van Canneyt schrieb:
>
>> I did several things:
>> 
>> 1. Enable various log levels in parser and scanner. It uses an event 
>> handler.
>>   (writing to terminal is not possible)
>> 
>> 2. Route all this logging through the TPasContainer.
>>    I tried to remove all direct writes from all backends and other places 
>> in fpdoc,
>>    so now it should work in a GUI app as well.
>> 
>> 3. Create a TFPDocCreater component. It contains the CreateDocumentation 
>> logic,
>>    verbose and dry-run logic, and some more.
>>    You should be able to re-use this component as-is, see unit mkfpdoc.pp
>> 
>> 4. Implemented the --verbose and --dry-run options.
>
> Great :-)
>
> Waiting for a commit of these extensions, and for a description of your 
> mkfpdocproj tool...

Everything was already committed in rev. 19755.

>
>
>> These 2 options are not stored in the project file, they must be given on 
>> the command-line.
>> I do not believe they belong in the project file.
>
> ACK. See my other mail about the options stored in project files.
>
>
>> Todo: implement a --descr-dir command-line option for fpdoc application. 
>> That will scan a directory and add all XML files it finds in that dir to 
>> the project.
>> I can see why you want such thing, but I think such logic belongs in the 
>> command-line tool itself, not in the project description itself.
>
> My solution doesn't deserve an change to the project files, the expansion of 
> --descr="dir/*" can be done in TFPDocEngine.AddDocFile, for all kinds of 
> invocations. A search also could be started when the --descr argument does 
> not specify an ".xml" extension, whereupon the argument can be treated as a 
> documentation directory.

I prefer an explicit command, and impleented it like that, there are now 2 options
--descr-dir and --input-dir. This is also in rev. 19755.

Incidentally
   --descr=@filename
will append all lines in @filename as description files, the same is true for --input.
This was already there since many years.

> I still miss a "required package" option (variation of --import?), describing 
> the packages whose content files are required to build a dependent package 
> documentation. Since the location of these packages can differ on every 
> machine, the user should be alerted when he missed to specify the locations 
> of required content files. An error message "content file not found" exists 
> already, but it will not be shown when fpdoc has no idea of the required 
> content files.

IMHO The project file should simply contain the appropriate import lines ?

> Such an option IMO becomes very important, when e.g. the LCL documentation 
> shall be created from a project file. Required packages can be handled in an 
> according tool, but even such a tool needs informations about required 
> packages.

There is no such thing as a 'Required' package. fpdoc should still be able to 
build the docs in the absence of this package. It will simply not be able to 
build some cross-references. So at most a warning is in order.

I think that the warnings about missing links in target ID should be plenty 
to alert the user; Of necessity they will start with #packagename, and will 
probably drown the one additional warning.

>
> Another issue are the relative directories, as used in all current scripts 
> and project files. E.g. build_lcl_docs invokes fpdoc from the HTML directory, 
> so that the project file will contain references relative to that directory - 
> which does not normally exist before the first invocation of build_lcl_docs! 
> Moving the created project file into an safe place will invalidate all 
> contained file references :-(
> Should this bad situation be cured in build_lcl_docs, or can we provide other 
> assistance?

This must be cured in build_lcl_docs.

fpdoc builds documentation from available files. 
Where these files are depends on the environment and should be determined 
by the person who created the environment.

Michael.