On Sun, 4 Dec 2011, Hans-Peter Diettrich wrote:
Michael Van Canneyt schrieb:
I did several things:
1. Enable various log levels in parser and scanner. It uses an event
handler.
(writing to terminal is not possible)
2. Route all this logging through the TPasContainer.
I tried to remove all direct writes from all backends and other places
in fpdoc,
so now it should work in a GUI app as well.
3. Create a TFPDocCreater component. It contains the CreateDocumentation
logic,
verbose and dry-run logic, and some more.
You should be able to re-use this component as-is, see unit mkfpdoc.pp
4. Implemented the --verbose and --dry-run options.
Great :-)
Waiting for a commit of these extensions, and for a description of your
mkfpdocproj tool...
Everything was already committed in rev. 19755.
These 2 options are not stored in the project file, they must be given on
the command-line.
I do not believe they belong in the project file.
ACK. See my other mail about the options stored in project files.
Todo: implement a --descr-dir command-line option for fpdoc application.
That will scan a directory and add all XML files it finds in that dir to
the project.
I can see why you want such thing, but I think such logic belongs in the
command-line tool itself, not in the project description itself.
My solution doesn't deserve an change to the project files, the expansion of
--descr="dir/*" can be done in TFPDocEngine.AddDocFile, for all kinds of
invocations. A search also could be started when the --descr argument does
not specify an ".xml" extension, whereupon the argument can be treated as a
documentation directory.
I prefer an explicit command, and impleented it like that, there are now 2
options
--descr-dir and --input-dir. This is also in rev. 19755.
Incidentally
--descr=@filename
will append all lines in @filename as description files, the same is true for
--input.
This was already there since many years.
I still miss a "required package" option (variation of --import?), describing
the packages whose content files are required to build a dependent package
documentation. Since the location of these packages can differ on every
machine, the user should be alerted when he missed to specify the locations
of required content files. An error message "content file not found" exists
already, but it will not be shown when fpdoc has no idea of the required
content files.
IMHO The project file should simply contain the appropriate import lines ?
Such an option IMO becomes very important, when e.g. the LCL documentation
shall be created from a project file. Required packages can be handled in an
according tool, but even such a tool needs informations about required
packages.
There is no such thing as a 'Required' package. fpdoc should still be able to
build the docs in the absence of this package. It will simply not be able to
build some cross-references. So at most a warning is in order.
I think that the warnings about missing links in target ID should be plenty
to alert the user; Of necessity they will start with #packagename, and will
probably drown the one additional warning.
Another issue are the relative directories, as used in all current scripts
and project files. E.g. build_lcl_docs invokes fpdoc from the HTML directory,
so that the project file will contain references relative to that directory -
which does not normally exist before the first invocation of build_lcl_docs!
Moving the created project file into an safe place will invalidate all
contained file references :-(
Should this bad situation be cured in build_lcl_docs, or can we provide other
assistance?
This must be cured in build_lcl_docs.
fpdoc builds documentation from available files.
Where these files are depends on the environment and should be determined
by the person who created the environment.
Michael.
_______________________________________________
fpc-devel maillist - [email protected]
http://lists.freepascal.org/mailman/listinfo/fpc-devel
