[fpc-devel] FPDoc projects future

[Hans-Peter Diettrich]

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?

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.


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.

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.

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

DoDi