Mattias Gaertner schrieb:
Problems arise with branches.
For example?
When I work in a local branch, and find something worth to document,
then this documentation is added to the branch and removed when
switching back to another branch.
The current fpdoc documentation is only for sources and is only valid
for the associated version. A help entry may be wrong for an older
version, or an identifier might be renamed or moved to another place.
Moved or renamed items will loose their associated documentation anyhow.
Not anyhow.
When you rename an identifier the corresponding fpdoc entry must be
renamed too. This could be done by the IDE. In fact I already started
it.
Fine :-)
Let's assume a single help directory associated with every package. Then
two search strategies for help files can be used:
1) find the package containing the file, then search the help directory
associtated with that package, or
2) find the help directory containing the file.
In the first case a list of packages has to be searched, then the
associated help directories. Packages or units not in that list can not
be found, e.g. when no package exists for the IDE project.
In other words: If a package has help it is found, if a package has
no help, nothing is found.
If no package is found, *or* the package was found but does not have help...
In the second case a list of help directories is required, that can be
maintained by the user or package system. A single machine-specific xml
directory may be sufficient, with subdirectories for all packages, so
that no existing help file can be missed in the search. A concrete unit
owner is not required, the help directory name can be used for that
purpose. E.g. the complete LCL help can be created from
<helpdir/xml>/lcl/*.xml.
How can help files for lcl version 1.0 and lcl version 2.0 be
distinguished?
When this matters, the user can create separate doc folders.
In fact a versioning system were nice for the documentation, where added
or updated help can be applied either to common help or to version
(branch...) specific help. Most entries apply to all versions, and it
even does no harm to add version 2.0 specific extensions to the common
lcl help - they will never be searched when working with 1.0 code.
Only the final documentation may have to know about versions, so that
the proper overviews can be created for the 1.0 and 2.0 version. IMO
such overviews *always* should be created from the source code of the
proper version (like makeskel does), not from manually maintained lists
in help or topic files. The related entries then can be collected from
the separate help files, where every item can be tagged with the version
that introduced (moved, renamed...) that source code item.
Since documentation is written only after the source code has been
created and committed, it doesn't make sense to have both in the same
versioning system. When help *on* r0815 source code is committed, the
help should become visible *starting* with r0815 as well, not only when
committed *as* r4711. Of course SVN doesn't allow to amend an older
commit, so that separate source and help repositories IMO are the only
viable solution.
How should help files for third party packages be distributed?
Usually these are distributed as part of the package. As you suggested
already, the user can add a symlink to that help after installation, or
the help can be placed into the user/machine specific help directory on
installation of the package.
I do not really understand this requirement, in
detail when Lazarus.lpi is not detected/accepted as the owning project :-(
I hope you understand now.
No, see above.
Dedicated help directories are somewhat self-organizing, no chance for
missing help files in a search. But lists of packages and their
contained files can be incomplete.
If the file is not listed in any package the IDE searches in the unit
and src paths of all packages.
Why use search paths for packages, when it's easier to specify search
paths for documentation? As already mentioned, a single LazDoc path may
be sufficient, when all docs are installed into subdirectories of that
directory. The package-specific location of the docs is required only at
the time of installation of the package, later on the help system will
know where to find all the installed docs.
Do you have an example where the IDE can not find a fpdoc file?
When the FPDoc Editor denies to create an item, and requires to add the
source file to a package...
As a concrete example, I couldn't add help on widgetset-specific units
like win32wscomctrls.pp. Why should help be available only for installed
packages, known to the IDE, when the IDE allows to *open* source files
without such a restriction?
When e.g. an index file is added to every source directory, that file
could contain all the information required to find the associated help
files. Such a file can be created automatically, or when not found the
parent directories can be searched. Then the help file for
$(LazDir)/lcl/interfaces/win32/someunit.pp could be found in
$(LazDoc)[/xml]/lcl/interfaces/win32/someunit.xml, with the only
required information that $(LazDir)/lcl/ is the root directory of
package lcl. For projects an existing .lpi file could be used as the
root-directory marker of the project, and similar conventions could
apply to package directories.
IMO a default directory could be used to store help on source files,
whose owner cannot be determined.
Please check before writing.
It exists since years.
Sorry, not in my time machine :-(
See Environment options / FPDoc editor / FPDoc files path.
These pathes do not specify unit owners, so I wonder in what situations
these directories are searched at all.
For example when a user does no want to use the Lazarus package system.
I'm really confused now :-(
First FPDoc Editor requires that the source file is part of a package.
Then you say that this is not (no more?) a requirement. So what's the
use of added pathes?
When a help directory can be specified whenever a non-packaged file is
documented, the help system (later) has no idea in which directory that
help file has been created, and consequently must search the entire help
path. Until here a single NonPackaged directory would be sufficient to
hold all such help files. When multiple such directories are allowed,
the help system still cannot know whether Unit1.xml should be loaded
from directory X or Y :-(
The fpdoc editor does not support to create new fpdoc files for such
units.
That's why we should allow to create help for unowned files first,
before we discuss how they can be found later again.
IMO finding help files is the most important thing. F1 must work out of
the box with minimal setup.
ACK. The FPDoc Editor should also work with minimal setup, since it
doesn't require to press F1 all the time, and does not require compiled
(HTML) help.
The current model is this: I download a
package from the net, open it in the IDE and can press F1 on an
identifier to get help. All details are up to the package maintainer.
Details are not (only) up to the package maintainer, but also are up to
the package installer and help system.
As mentioned already in my preface, the FPDoc Editor is of my actual
interest. As I could figure out till now, everything boils down to the
(fragile) determination of the owner of an source file, based on only(?)
the module name. When that module name is unique, knowledge of the owner
is not required, it only can speed up the first search for the according
help file. My impression is that all(?) registered packages are scanned
at IDE startup, so that instead the registered help directories could be
scanned as well.
DoDi
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
