On Fri, 2 Dec 2011, Hans-Peter Diettrich wrote:
Michael Van Canneyt schrieb:
This means that we can document platform-specific items in additional
files, which are automatically merged with the other descriptions. The
description file specifications can be extended by a platform attribute,
so that problems arising from multiple (platform specific) descriptions
can be eliminated. E.g.:
<description file="sysutils.xml"/>
<description file="linux-sysutils.xml" platform="linux,unix"/>
<description file="win-sysutils.xml" platform=windows/>
I don't see the point of this. Why not simply add them to the description
file sysutils.xml ?
You're right. So what's the use of --ostarget and --cpuversion, WRT common
documentation?
They are for the parser, not for the description files.
I have no plans to support directory or wildcard search in fpdoc. That is a
can of worms I will not open;
I just implemented wildcards, and it seems to work nicely :-)
I do not doubt it is possible, I am just concerned about everything
that may go wrong in the future. I prefer a different way.
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.
There may remain things, which better should (and can!) reside in separate
tools. Currently I feel no need for such additional tools, where the purpose
would justify such efforts.
I have no problem including such tools in the FPC distribution, whereas
wildcard search in fpdoc itself is sure to be rejected.
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.
The last is in fact probably the easiest solution for the RTL/FCL docs.
We can distribute a template project on which simple macro substitution
is performed prior to feeding it to fpdoc. Thanks to your patch for
creating a project file from given command-line options,
I now actually have such a file.
I split the tool so the class that does the actual work can be integrated in
e.g. a GUI tool for quick manipulation of project files.
I expect and hope the tool will solve most - if not all - of the problems you
experienced as well.
Michael.
_______________________________________________
fpc-devel maillist - fpc-devel@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-devel
