[fpc-devel] MakeSkel and FPDoc projects

[Hans-Peter Diettrich]

Michael Van Canneyt schrieb:

>> When we look at new packages, some general tasks come into mind:
>>
> 
> [snip]
> 
>> I'd prefer that all beforementioned tasks can be accomplished by a 
>> single program, by only giving it an project file, task, and 
>> task-specific options.
> 
> 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!

> fpdoc and makeskel are command-line tools, not IDEs.
> 
> IMHO you should concentrate on enhancing lazde or lazdoc, so they call 
> fpdoc and makeskel with whatever options you see fit.

For that purpose such an IDE *also* must be extended with projects, 
what's much more complicated than making use of the projects in the 
commandline tools. I already tried to adopt LazDE to my needs, for use 
with kind of projects, but gave up after several weeks of fruitless 
tries. Tweaking the commandline tools is much easier, each one boils 
down to essentially a single worker procedure, which is easy to 
parametrize :-)

> Just like Lazarus is a front-end for the compiler, with its own options, 
> config files and whatnot. But in the end, it calls the compiler, and 
> lets the compiler do what it does best: compile pascal code. The IDE 
> itself manages 'projects' and packages and whatnot: it helps you 
> organize your work.
> (the lazarus IDE does a lot more, of course)

The documentation related features could become Lazarus plug-ins, of 
course, similar to or as an extension of the FPDoc Editor window. But 
this already existing support makes it *harder* to add further 
functionality - it's quite easy to crash the IDE when editing the 
documentation file for an open unit :-(


> You seem to have the typical windows-users approach: all in one program.
> I am more an advocate of the Unix approach: many small programs that 
> cooperate together. fpdoc and makeskel are the result of the latter 
> approach. I will not cooperate on efforts to make them into
> one-tool-for-all-tasks programs.

Right, I don't like the Unix approach, but almost only for one reason: 
building the commandlines for using these tools is a mess, hardly doable 
without obscure scripts in whatever additional langugage. I had much 
less problems with a *library* of tool components, configurable and 
callable from Pascal code.

That's why I tried to separate the commandline interface from the worker 
code of FPDoc and MakeSkel, what turned out doable by a simple patch. 
Now I have all options to integrate the essential functionality of these 
tools into other programs, be GUI or CLI :-)


> I will cooperate on additional options which enhance the operation of 
> the tools within the frame of their purpose, as I have done recently. I 
> think that makeskel can be enhanced to use a project file to create an 
> update for a single unit file, to spare you the effort of typing all 
> options again, but that's about it.

This would be very kind, of course :-)

Can you also add this option to FPDoc, so that it will allow to do a 
test build for an single unit file?


>> Think about an project file first, what does it contain? Then think 
>> about which of the stored options may deserve an override, or which 
>> require overrides in specific use cases. Also keep in mind that 
>> project files may be distributed, and that the target environments may 
>> deserve certain modifications. When I use "make all", to create the 
>> full RTL/FCL documentation on Windows, the resulting commandline does 
>> not always reflect the intentions of the documentation writers (on 
>> Linux). It IMO is a bad idea to store the OS and CPU targets and the 
>> output format in an project file.
> 
> 1. No-one says that you must store all these options.
>    While the fpdoc project file *can* contain all options, it does not mean
>    that it *must* contain all options.

Consider what happens when FPDoc, MakeSkel or MkFpdocProj *update* a 
project - a new file will be created, that contains whatever the 
programs have extracted from the input project, and whatever else they 
find worth to store in the output project. When they do not update the 
projects themselves, how can the user be informed of possible changes, 
so that he can update the project file himself?

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


> 2. If command-line options override the defaults in the file (as they do),
>    you just need to specify the correct options on the command-line in 
> case the
>    project file contains the wrong ones.

This means in practice that almost all settings have to be given on the 
commandline (except the file lists), or to inspect every single project 
for the contained settings, in order to find out what must not 
necessarily be overridden.


>>>> This means that you disallow for e.g. scripts which provide built-in 
>>>> defaults, that *should* be overridden by values stored in the 
>>>> project :-(
>>>
>>> Of course I disallow this. The working method is the opposite. The 
>>> project provides defaults, to be overridden on the command line.
>>
>> This is how you have learned or expect it to work.
> 
> ? My person has nothing to do with it.

So how can you give advice to project file users? ;-)


> This is the result of many years of experience of many programmers in 
> many open source projects: a config file for defaults, command-line 
> options to override the defaults. It's simply standard operating 
> procedure, which has proven its usefulness over the years.
> But yes, it is a typical Unix approach.

Right, Unix leaves it almost to the user, to find the config files and 
the line(s) to modify when something has to be changed. This differs 
from the Windows Registry only in the storage format (text/binary). But 
(Unix) commandline tools have another source of settings, the 
environment variables. This often means that such a tool cannot be 
started (as a process), before its environment is set up as required. On 
Windows it's almost required to configure an desktop shortcut, to e.g. 
run Lazarus. For updating FPC or Lazarus, and for testing and building 
the documentation, I had to write a couple of batch files, which allow 
me to establish the right environment in a console, before I can start 
the tool itself. That's one more reason why I don't like commandline 
tools, and prefer to configure their worker procedure in a more 
transparent environment (my own main program).

BTW the Unix approach may work fine, when only one version of a tool 
(like FPC and Lazarus) is in use. Then the setup must be done only once, 
and when this step has been mastered (differently for every Linux 
version), the average user can forget about all the related config files 
and settings. But when I have to use Lazarus with different settings, 
for building applications (last release or trunk, with or without 
patches for a dockable IDE), and for different FPC versions (e.g. trunk 
for building the documentation tools), life can become very complicated :-(

Okay, whined enough, returning to work now ;-)

DoDi