On Sat, 3 Dec 2011, Hans-Peter Diettrich wrote:
Michael Van Canneyt schrieb:
One objection is for instance that your proposal will cause all XML files
to be loaded both when FCL and RTL documentation are created.
Already included: all XML files are discarded, when they don't contribute
to the current package :-)
Because of the loose coupling between XML files and source files, there is
no way to know if a XML file is contributing or not, unless you impose some
convention like 1 unit = 1 file with equal filenames, or parse the XML file
to detect the module it documents or start moving XML files to directories.
Reading the XML files for both RTL and FCL takes almost no time, compared to
the time spent in generating the documentation. Lazarus already maintains
package documentation in a dedicated directory, so that it's up to the
documentation maintainers what they put into these directories. You remember
my question about the suggested organization of documentation?
Yes, of course.
The question is whether the fpdoc engine should cater for specific setups.
There our answers differ.
I went ahead and improved the tool I announced earlier. The end goal is to
use this tool to create the project file from the Makefiles for the docs.
Currently it can:
- Add directories of source files, with file mask, parser options to be
added to the found files, and recursion.
- Add directories of description files, with file mask and recursion.
- Add a list of input files (with options).
- Add a list of description files.
- Remove a list of input files.
- Remove a list of description files.
- Set/Unset engine options.
- Perform macro substitutions on a fpdoc project file.
Nice :-)
What I'm still missing, is support for documentation writers:
- process a single unit from a project, to get XML syntax and other error
messages.
- more verbose output for spotting such errors.
You remember my -n and -v options?
Absolutely, and I'll gladly accept patches implementing those 2 things in fpdoc.
If you could separate those out from your other work, that would be much
appreciated. If not, send whatever you have, and I'll try to extract it myself.
A last word:
This new tool will solve also a problem which we've been struggling
with in fppkg. The tool will allow to create a "site documentation file":
I envision a site-docs.xml file in a location known to fppkg.
Installing a package using fppkg can now call the new tool and add the
new package documentation to the site-docs.xml file as part of the installation
process, and rebuild the docs.
Anyway, I'll wait for your patch with the -n and -v options.
Michael.
_______________________________________________
fpc-devel maillist - [email protected]
http://lists.freepascal.org/mailman/listinfo/fpc-devel
