[fpc-devel] FPDoc projects future

[michael.vancanneyt at wisa.be]

On Wed, 30 Nov 2011, Hans-Peter Diettrich wrote:

> In my review of the fpdoc project option some questions popped up. The most 
> important question: should fpdoc be usable for creating online help only, or 
> should it also allow users to create offline documentation on their local 
> machine? When a user can create documentation files for local use, the 
> configuration and directory structure of the current machine deserve some 
> considerations.
>
>
> Currently the commandlines are created by scripts, with predefined compiler 
> options, at least for the RTL units. How portable are these options, with 
> regards to different platforms? In detail the -Fi options?

They are not platform specific.

>
> What's the purpose of --ostarget and --cputarget? These options are 
> documented as "for the scanner", presumably for conditional compilation. Are 
> these options valid (or required), so that the input files are processed in 
> the same way and with the same include directories, regardless of the machine 
> running fpdoc? In this case all related fpdoc options have to be saved in the 
> fpdoc project files.

These options simply add some defines in the scanner. They have no other
effect.

>
>
> The --import options specify both the locations of the content files, of 
> related packages, as well as the link target locations (prefixes). This 
> requires a fixed directory structure, or else the content files can not be 
> found, and HTML links may be broken. Such a fixed directory structure can be 
> assumed only for the RTL and FCL documentation. The LCL documentation instead 
> will reside in an unrelated directory branch, so that all references to the 
> FPC documentation depend on the directory structure of the user machines.

Explain why you think this requires a fixed directory structure ?

> This doesn't look very practicable to me - how would fpdoc or any script find 
> the location of the FPC documentation, on every single machine? Or will the 
> user be responsible for providing the locations of all dependent packages 
> documentation? Lazarus already requires to configure the paths to all 
> documentation source directories, for use by the FPDoc Editor.

Obviously, the user is responsible for providing the locations.

You are of course free to set up a system to register such locations;
I do not consider it the job of fpdoc. You can create a shell around fpdoc
that handles all this.

> Should we introduce a single (HTML) documentation directory, on every target 
> machine, where *all* package documentations can reside side-by-side, with 
> fixed relative references? Or should HTML documentation be deprecated, in 
> favor of more position-independent CHM files? (dunno whether this would 
> really help).

These are not fpdoc questions; These are questions on how you organize your
work.

It seems to me you are reading too much in fpdoc. fpdoc takes some input
files and produces output. No more, no less.

All the questions you ask have more to do with 
'how do I organize my work with fpdoc' 
rather than with 
'how should fpdoc function'.

Michael.