doc/html/cdl-guide/ref.doc.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >doc</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="The eCos Component Writer's Guide"
  20 HREF="cdl-guide.html"><LINK
  21 REL="UP"
  22 TITLE="CDL Language Specification"
  23 HREF="reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="display"
  26 HREF="ref.display.html"><LINK
  27 REL="NEXT"
  28 TITLE="flavor"
  29 HREF="ref.flavor.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >The <SPAN
  50 CLASS="APPLICATION"
  51 >eCos</SPAN
  52 > Component Writer's Guide</TH
  53 ></TR
  54 ><TR
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="bottom"
  59 ><A
  60 HREF="ref.display.html"
  61 ACCESSKEY="P"
  62 >Prev</A
  63 ></TD
  64 ><TD
  65 WIDTH="80%"
  66 ALIGN="center"
  67 VALIGN="bottom"
  68 ></TD
  69 ><TD
  70 WIDTH="10%"
  71 ALIGN="right"
  72 VALIGN="bottom"
  73 ><A
  74 HREF="ref.flavor.html"
  75 ACCESSKEY="N"
  76 >Next</A
  77 ></TD
  78 ></TR
  79 ></TABLE
  80 ><HR
  81 ALIGN="LEFT"
  82 WIDTH="100%"></DIV
  83 ><H1
  84 ><A
  85 NAME="REF.DOC"><SPAN
  86 CLASS="PROPERTY"
  87 >doc</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN4278"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >doc</SPAN
  99 >&nbsp;--&nbsp;The location of online-documentation for a configuration option.</DIV
 100 ><DIV
 101 CLASS="REFSYNOPSISDIV"
 102 ><A
 103 NAME="AEN4282"><H2
 104 >Synopsis</H2
 105 ><TABLE
 106 BORDER="5"
 107 BGCOLOR="#E0E0F0"
 108 WIDTH="70%"
 109 ><TR
 110 ><TD
 111 ><PRE
 112 CLASS="SYNOPSIS"
 113 >cdl_option &lt;name&gt; {
 114     doc &lt;URL;&gt;
 115     &#8230;
 116 }</PRE
 117 ></TD
 118 ></TR
 119 ></TABLE
 120 ></DIV
 121 ><DIV
 122 CLASS="REFSECT1"
 123 ><A
 124 NAME="AEN4284"
 125 ></A
 126 ><H2
 127 >Description</H2
 128 ><P
 129 >Users can only be expected to manipulate configuration options
 130 sensibly if they are given sufficient information about these options.
 131 There are three properties which serve to explain an option in plain
 132 text: the <SPAN
 133 CLASS="PROPERTY"
 134 >display</SPAN
 135 > property gives a textual alias for an option,
 136 which is usually more comprehensible than something like
 137 <TT
 138 CLASS="LITERAL"
 139 >CYGPKG_LIBC_TIME_ZONES</TT
 140 >; the <SPAN
 141 CLASS="PROPERTY"
 142 >description</SPAN
 143 > property
 144 gives a longer description, typically a paragraph or so; the <SPAN
 145 CLASS="PROPERTY"
 146 >doc</SPAN
 147 >
 148 property specifies the location of additional on-line documentation
 149 related to a configuration option. In the context of a graphical tool
 150 the <SPAN
 151 CLASS="PROPERTY"
 152 >display</SPAN
 153 > string will be the primary way for users to identify
 154 configuration options; the <SPAN
 155 CLASS="PROPERTY"
 156 >description</SPAN
 157 > paragraph will be visible
 158 whenever the option is selected; the on-line documentation will only
 159 be accessed when the user explicitly requests it.</P
 160 ><P
 161 >The documentation may be an absolute URL, but more generally the
 162 on-line documentation will be shipped with the package and can be
 163 accessed via a relative URL. If the package follows the <A
 164 HREF="package.html#PACKAGE.HIERARCHY"
 165 >directory layout conventions</A
 166 > then
 167 the configuration tools will search for the specified html file
 168 first in the <TT
 169 CLASS="FILENAME"
 170 >doc</TT
 171 > subdirectory
 172 of the package, then relative to the package directory itself. The URL
 173 may contain a <TT
 174 CLASS="LITERAL"
 175 >#</TT
 176 > character to specify an anchor
 177 within a page.</P
 178 ><DIV
 179 CLASS="WARNING"
 180 ><P
 181 ></P
 182 ><TABLE
 183 CLASS="WARNING"
 184 BORDER="1"
 185 WIDTH="100%"
 186 ><TR
 187 ><TD
 188 ALIGN="CENTER"
 189 ><B
 190 >Warning</B
 191 ></TD
 192 ></TR
 193 ><TR
 194 ><TD
 195 ALIGN="LEFT"
 196 ><P
 197 >At the time of writing the <SPAN
 198 CLASS="APPLICATION"
 199 >eCos</SPAN
 200 > packages in the standard
 201 distribution do not conform to the directory layout conventions when
 202 it comes to the documentation. Instead of organizing the documentation
 203 on a per-package basis and placing it in the corresponding
 204 <TT
 205 CLASS="FILENAME"
 206 >doc</TT
 207 > sub-directories, all the
 208 documentation is kept in a central location. This should get addressed
 209 in a future release of the system. Third party component writers
 210 should follow the layout conventions.</P
 211 ></TD
 212 ></TR
 213 ></TABLE
 214 ></DIV
 215 ></DIV
 216 ><DIV
 217 CLASS="REFSECT1"
 218 ><A
 219 NAME="AEN4301"
 220 ></A
 221 ><H2
 222 >Example</H2
 223 ><TABLE
 224 BORDER="5"
 225 BGCOLOR="#E0E0F0"
 226 WIDTH="70%"
 227 ><TR
 228 ><TD
 229 ><PRE
 230 CLASS="PROGRAMLISTING"
 231 >cdl_package CYGPKG_KERNEL {
 232     display       "eCos kernel"
 233     doc           ref/ecos-ref.4.html
 234     include_dir   cyg/kernel
 235     description   "
 236         This package contains the core functionality of the eCos
 237         kernel. It relies on functionality provided by various HAL
 238         packages and by the eCos infrastructure. In turn the eCos
 239         kernel provides support for other packages such as the device
 240         drivers and the uITRON compatibility layer."
 241     &#8230;
 242 }</PRE
 243 ></TD
 244 ></TR
 245 ></TABLE
 246 ></DIV
 247 ><DIV
 248 CLASS="REFSECT1"
 249 ><A
 250 NAME="AEN4304"
 251 ></A
 252 ><H2
 253 >See Also</H2
 254 ><P
 255 >Properties <A
 256 HREF="ref.description.html"
 257 ><SPAN
 258 CLASS="PROPERTY"
 259 >description</SPAN
 260 ></A
 261 > and
 262 <A
 263 HREF="ref.display.html"
 264 ><SPAN
 265 CLASS="PROPERTY"
 266 >display</SPAN
 267 ></A
 268 >.</P
 269 ></DIV
 270 ><DIV
 271 CLASS="NAVFOOTER"
 272 ><HR
 273 ALIGN="LEFT"
 274 WIDTH="100%"><TABLE
 275 SUMMARY="Footer navigation table"
 276 WIDTH="100%"
 277 BORDER="0"
 278 CELLPADDING="0"
 279 CELLSPACING="0"
 280 ><TR
 281 ><TD
 282 WIDTH="33%"
 283 ALIGN="left"
 284 VALIGN="top"
 285 ><A
 286 HREF="ref.display.html"
 287 ACCESSKEY="P"
 288 >Prev</A
 289 ></TD
 290 ><TD
 291 WIDTH="34%"
 292 ALIGN="center"
 293 VALIGN="top"
 294 ><A
 295 HREF="cdl-guide.html"
 296 ACCESSKEY="H"
 297 >Home</A
 298 ></TD
 299 ><TD
 300 WIDTH="33%"
 301 ALIGN="right"
 302 VALIGN="top"
 303 ><A
 304 HREF="ref.flavor.html"
 305 ACCESSKEY="N"
 306 >Next</A
 307 ></TD
 308 ></TR
 309 ><TR
 310 ><TD
 311 WIDTH="33%"
 312 ALIGN="left"
 313 VALIGN="top"
 314 ><SPAN
 315 CLASS="PROPERTY"
 316 >display</SPAN
 317 ></TD
 318 ><TD
 319 WIDTH="34%"
 320 ALIGN="center"
 321 VALIGN="top"
 322 ><A
 323 HREF="reference.html"
 324 ACCESSKEY="U"
 325 >Up</A
 326 ></TD
 327 ><TD
 328 WIDTH="33%"
 329 ALIGN="right"
 330 VALIGN="top"
 331 ><SPAN
 332 CLASS="PROPERTY"
 333 >flavor</SPAN
 334 ></TD
 335 ></TR
 336 ></TABLE
 337 ></DIV
 338 ></BODY
 339 ></HTML
 340 >