doc/html/cdl-guide/ref.description.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 >description</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="define_proc"
  26 HREF="ref.define-proc.html"><LINK
  27 REL="NEXT"
  28 TITLE="display"
  29 HREF="ref.display.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.define-proc.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.display.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.DESCRIPTION"><SPAN
  86 CLASS="PROPERTY"
  87 >description</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN4219"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >description</SPAN
  99 >&nbsp;--&nbsp;Provide a textual description for an option.</DIV
 100 ><DIV
 101 CLASS="REFSYNOPSISDIV"
 102 ><A
 103 NAME="AEN4223"><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     description &lt;text&gt;
 115     &#8230;
 116 }</PRE
 117 ></TD
 118 ></TR
 119 ></TABLE
 120 ></DIV
 121 ><DIV
 122 CLASS="REFSECT1"
 123 ><A
 124 NAME="AEN4225"
 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 >At present there is no way of providing any sort of formatting mark-up
 162 in a description. It is possible that future versions of the
 163 configuration tools will provide some control over the way the
 164 description text gets rendered.</P
 165 ></DIV
 166 ><DIV
 167 CLASS="REFSECT1"
 168 ><A
 169 NAME="AEN4235"
 170 ></A
 171 ><H2
 172 >Example</H2
 173 ><TABLE
 174 BORDER="5"
 175 BGCOLOR="#E0E0F0"
 176 WIDTH="70%"
 177 ><TR
 178 ><TD
 179 ><PRE
 180 CLASS="PROGRAMLISTING"
 181 >cdl_option CYGDBG_INFRA_DEBUG_TRACE_MESSAGE {
 182     display       "Use trace text"
 183     default_value 1
 184     description   "
 185         All trace calls within eCos contain a text message
 186         which should give some information about the circumstances.
 187         These text messages will end up being embedded in the
 188         application image and hence there is a significant penalty
 189         in terms of image size.
 190         It is possible to suppress the use of these messages by
 191         disabling this option.
 192         This results in smaller code size, but there is less
 193         human-readable information available in the trace output,
 194         possibly only filenames and line numbers."
 195 }</PRE
 196 ></TD
 197 ></TR
 198 ></TABLE
 199 ></DIV
 200 ><DIV
 201 CLASS="REFSECT1"
 202 ><A
 203 NAME="AEN4238"
 204 ></A
 205 ><H2
 206 >See Also</H2
 207 ><P
 208 >Properties <A
 209 HREF="ref.display.html"
 210 ><SPAN
 211 CLASS="PROPERTY"
 212 >display</SPAN
 213 ></A
 214 > and
 215 <A
 216 HREF="ref.doc.html"
 217 ><SPAN
 218 CLASS="PROPERTY"
 219 >doc</SPAN
 220 ></A
 221 >.</P
 222 ></DIV
 223 ><DIV
 224 CLASS="NAVFOOTER"
 225 ><HR
 226 ALIGN="LEFT"
 227 WIDTH="100%"><TABLE
 228 SUMMARY="Footer navigation table"
 229 WIDTH="100%"
 230 BORDER="0"
 231 CELLPADDING="0"
 232 CELLSPACING="0"
 233 ><TR
 234 ><TD
 235 WIDTH="33%"
 236 ALIGN="left"
 237 VALIGN="top"
 238 ><A
 239 HREF="ref.define-proc.html"
 240 ACCESSKEY="P"
 241 >Prev</A
 242 ></TD
 243 ><TD
 244 WIDTH="34%"
 245 ALIGN="center"
 246 VALIGN="top"
 247 ><A
 248 HREF="cdl-guide.html"
 249 ACCESSKEY="H"
 250 >Home</A
 251 ></TD
 252 ><TD
 253 WIDTH="33%"
 254 ALIGN="right"
 255 VALIGN="top"
 256 ><A
 257 HREF="ref.display.html"
 258 ACCESSKEY="N"
 259 >Next</A
 260 ></TD
 261 ></TR
 262 ><TR
 263 ><TD
 264 WIDTH="33%"
 265 ALIGN="left"
 266 VALIGN="top"
 267 ><SPAN
 268 CLASS="PROPERTY"
 269 >define_proc</SPAN
 270 ></TD
 271 ><TD
 272 WIDTH="34%"
 273 ALIGN="center"
 274 VALIGN="top"
 275 ><A
 276 HREF="reference.html"
 277 ACCESSKEY="U"
 278 >Up</A
 279 ></TD
 280 ><TD
 281 WIDTH="33%"
 282 ALIGN="right"
 283 VALIGN="top"
 284 ><SPAN
 285 CLASS="PROPERTY"
 286 >display</SPAN
 287 ></TD
 288 ></TR
 289 ></TABLE
 290 ></DIV
 291 ></BODY
 292 ></HTML
 293 >