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.
_______________________________________________
fpc-devel maillist - fpc-devel@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-devel
