doc
Name
Property
doc -- The location of online-documentation for a configuration option.
Synopsis
cdl_option <name> {
doc <URL;>
…
} |
Description
Users can only be expected to manipulate configuration options
sensibly if they are given sufficient information about these options.
There are three properties which serve to explain an option in plain
text: the display property gives a textual alias for an option,
which is usually more comprehensible than something like
CYGPKG_LIBC_TIME_ZONES; the description property
gives a longer description, typically a paragraph or so; the doc
property specifies the location of additional on-line documentation
related to a configuration option. In the context of a graphical tool
the display string will be the primary way for users to identify
configuration options; the description paragraph will be visible
whenever the option is selected; the on-line documentation will only
be accessed when the user explicitly requests it.
The documentation may be an absolute URL, but more generally the
on-line documentation will be shipped with the package and can be
accessed via a relative URL. If the package follows the directory layout conventions then
the configuration tools will search for the specified html file
first in the doc subdirectory
of the package, then relative to the package directory itself. The URL
may contain a # character to specify an anchor
within a page.
| Warning |
At the time of writing the eCos packages in the standard
distribution do not conform to the directory layout conventions when
it comes to the documentation. Instead of organizing the documentation
on a per-package basis and placing it in the corresponding
doc sub-directories, all the
documentation is kept in a central location. This should get addressed
in a future release of the system. Third party component writers
should follow the layout conventions. |
Example
cdl_package CYGPKG_KERNEL {
display "eCos kernel"
doc ref/ecos-ref.4.html
include_dir cyg/kernel
description "
This package contains the core functionality of the eCos
kernel. It relies on functionality provided by various HAL
packages and by the eCos infrastructure. In turn the eCos
kernel provides support for other packages such as the device
drivers and the uITRON compatibility layer."
…
} |
