URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [ref.doc.html] - Blame information for rev 174

Details | Compare with Previous | View Log


<!-- Copyright (C) 2003 Red Hat, Inc.                                -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/).                           -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission is obtained from the copyright holder.               -->
<HTML
><HEAD
><TITLE
>doc</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="The eCos Component Writer's Guide"
HREF="cdl-guide.html"><LINK
REL="UP"
TITLE="CDL Language Specification"
HREF="reference.html"><LINK
REL="PREVIOUS"
TITLE="display"
HREF="ref.display.html"><LINK
REL="NEXT"
TITLE="flavor"
HREF="ref.flavor.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The <SPAN
CLASS="APPLICATION"
>eCos</SPAN
> Component Writer's Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="ref.display.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="ref.flavor.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="REF.DOC"><SPAN
CLASS="PROPERTY"
>doc</SPAN
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN4278"
></A
><H2
>Name</H2
>Property <SPAN
CLASS="PROPERTY"
>doc</SPAN
>&nbsp;--&nbsp;The location of online-documentation for a configuration option.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN4282"><H2
>Synopsis</H2
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SYNOPSIS"
>cdl_option &lt;name&gt; {
    doc &lt;URL;&gt;
    &#8230;
}</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN4284"
></A
><H2
>Description</H2
><P
>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 <SPAN
CLASS="PROPERTY"
>display</SPAN
> property gives a textual alias for an option,
which is usually more comprehensible than something like
<TT
CLASS="LITERAL"
>CYGPKG_LIBC_TIME_ZONES</TT
>; the <SPAN
CLASS="PROPERTY"
>description</SPAN
> property
gives a longer description, typically a paragraph or so; the <SPAN
CLASS="PROPERTY"
>doc</SPAN
>
property specifies the location of additional on-line documentation
related to a configuration option. In the context of a graphical tool
the <SPAN
CLASS="PROPERTY"
>display</SPAN
> string will be the primary way for users to identify
configuration options; the <SPAN
CLASS="PROPERTY"
>description</SPAN
> paragraph will be visible
whenever the option is selected; the on-line documentation will only
be accessed when the user explicitly requests it.</P
><P
>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 <A
HREF="package.html#PACKAGE.HIERARCHY"
>directory layout conventions</A
> then
the configuration tools will search for the specified html file
first in the <TT
CLASS="FILENAME"
>doc</TT
> subdirectory
of the package, then relative to the package directory itself. The URL
may contain a <TT
CLASS="LITERAL"
>#</TT
> character to specify an anchor
within a page.</P
><DIV
CLASS="WARNING"
><P
></P
><TABLE
CLASS="WARNING"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Warning</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
>At the time of writing the <SPAN
CLASS="APPLICATION"
>eCos</SPAN
> 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
<TT
CLASS="FILENAME"
>doc</TT
> 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.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN4301"
></A
><H2
>Example</H2
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>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."
    &#8230;
}</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN4304"
></A
><H2
>See Also</H2
><P
>Properties <A
HREF="ref.description.html"
><SPAN
CLASS="PROPERTY"
>description</SPAN
></A
> and
<A
HREF="ref.display.html"
><SPAN
CLASS="PROPERTY"
>display</SPAN
></A
>.</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="ref.display.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="cdl-guide.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="ref.flavor.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><SPAN
CLASS="PROPERTY"
>display</SPAN
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="reference.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><SPAN
CLASS="PROPERTY"
>flavor</SPAN
></TD
></TR
></TABLE
></DIV
></BODY
></HTML
>

Line No.	Rev	Author	Line
1	28	unneback	`<!-- 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			`> -- 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 <name> {`
114			`doc <URL;>`
115			`…`
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			`…`
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			`>`

Browse

Tools

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [ref.doc.html] - Blame information for rev 174