[fpc-devel] MakeSkel and FPDoc projects

[Michael Van Canneyt]

On Sat, 17 Dec 2011, Hans-Peter Diettrich wrote:

> michael.vancanneyt at wisa.be schrieb:
>> 
>> 
>> On Sat, 17 Dec 2011, Hans-Peter Diettrich wrote:
>> 
>>> Michael Van Canneyt schrieb:
>>> 
>>>> 
>>>> Feel free to create this program. If I may give some advice: the tasks 
>>>> you outline belong in a "Documentation writers IDE".
>>> 
>>> To some degree, maybe. But checking for updates should be doable by a 
>>> script, without a need to open an IDE - for every single package!
>> 
>> I have done so for years, with the existing tools, using the Makefiles. No 
>> changes were necessary.
>
> Can you explain that a bit more? I'm not a professional commandline user, 
> perhaps I'm doing something stupid?

I just do a "make updatexml" or "make updatefclxml" or "make updatertlxml"

The makefile contains all commands necessary to create a unitname.new.xml 
for all units that have changed modifiers. It tries to remove "empty" ones.

> BTW I mean tracking changes in the source code, which require to update the 
> documentation files accordingly (makeskel --update ...). I don't see how a 
> Makefile is involved in this task? This is different from the following:
>
>>> Currently changes to the RTL and FCL (MakeFiles) require a dry-run of 
>>> make, analysis of the resulting commandline, and a manual merge with the 
>>> existing project. According to the Unix philosophy another tool is 
>>> required, that automates the project file update, and one more for 
>>> updating the project file when description files are added...
>> 
>> According to Unix philosophy, the person doing so is aware of what he is 
>> doing,
>> and makes the necessary changes (if there are such changes) to the project 
>> file himself.
>> 
>> I do not believe the tools can make the correct decisions, except in the
>> most trivial circumstances.
>
> The tool should update the file lists *only* (input, descr), and leave 
> everything else in the project file unmodified. This has not been a big 
> problem with textual INI files, but the XML project files can contain further 
> information (element attributes...), that is interleaved with the filename 
> entries.

It's not a technical issue. It's an issue that the tool does not know 
whether something requires changing or not.

The makefile can create the .new.xml files, but a human (me) needs to 
examine them and decide if something needs to be merged to the original 
files or not. This decision cannot be automated.

Michael.