[fpc-devel] MakeSkel and FPDoc projects

[Michael Van Canneyt]

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

> Michael Van Canneyt schrieb:
>
> ACK. There is no *need* to use MakeSkel with a project, but using this option 
> offers many advantages.
>
> 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".

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.

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)

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.

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.

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

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.

Michael.