source: trunk/Documentation/idldoc/idldoc_files.html @ 60

Last change on this file since 60 was 60, checked in by pinsard, 18 years ago

upgrade of Documentation/idldoc according to cerbere.lodyc.jussieu.fr: /usr/home/smasson/SAXO_RD/
  • Property svn:executable set to *
File size: 18.7 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN""http://www.w3.org/TR/REC-html40/loose.dtd">
2<!-- Generated by IDLdoc on Wed Feb 09 12:40:46 2005 -->
3<HEAD>
4<TITLE>IDLdoc file</TITLE>
5<STYLE><!--
6a:link { color: #660000 }
7a:active { color: #660000 }
8a:visited {color: #660000 }
9
10/* Default font for body text */
11BODY {
12    FONT-SIZE: 10pt;
13    FONT-FAMILY: Arial;
14    BACKGROUND-COLOR: #FFFFF9
15}
16
17/* Default font for text in tables */
18TD {
19    FONT-SIZE: 10pt;
20    FONT-FAMILY: Arial
21}
22
23/* Format for body of all files */
24BODY.standard {
25    FONT-SIZE: 10pt;
26    FONT-FAMILY: Arial;
27    BACKGROUND-COLOR: #FFFFF9
28}
29
30TABLE.parameters {
31    BORDER-TOP: 1px solid #FFFFCC;
32    BORDER-BOTTOM: 1px solid #88AA66;
33    BORDER-LEFT: 1px solid #FFFFCC;
34    BORDER-RIGHT: 1px solid #88AA66;
35    WIDTH: 95%;
36    MARGIN-LEFT: 5%
37}
38
39TR.parameters {
40    BORDER-RIGHT-WIDTH: 0px;
41    BORDER-TOP-WIDTH: 1px;
42    BORDER-LEFT-WIDTH: 0px;
43    WIDTH: 100%;
44    BORDER-BOTTOM-WIDTH: 1px;
45    BORDER-STYLE: solid
46}
47
48TD.index_selection_header {
49    FONT-WEIGHT: bold;
50    FONT-SIZE: 14pt;
51    FONT-FAMILY: Arial, Helvetica, sans-serif
52}
53
54TABLE.minor_listing {
55    BORDER-TOP: 1px solid #EEEEFF;
56    BORDER-BOTTOM: 1px solid #6666AA;
57    BORDER-LEFT: 1px solid #EEEEFF;
58    BORDER-RIGHT: 1px solid #6666AA;
59    WIDTH: 100%
60}
61
62TABLE.listing {
63    BORDER-TOP: 1px solid #BBBBFF;
64    BORDER-BOTTOM: 1px solid #6666AA;
65    BORDER-LEFT: 1px solid #BBBBFF;
66    BORDER-RIGHT: 1px solid #6666AA;
67    WIDTH: 100%
68}
69
70TABLE.routine_listing {
71    BACKGROUND: #FFFFAA;
72    BORDER-TOP: 1px solid #FFEEAA;
73    BORDER-BOTTOM: 1px solid #AAAA66;
74    BORDER-LEFT: 1px solid #FFEEAA;
75    BORDER-RIGHT: 1px solid #AAAA66;
76    WIDTH: 100%
77}
78
79TD.title {
80    FONT-SIZE: 14pt;
81    BACKGROUND: #ccccff;
82    FONT-FAMILY: Arial, Helvetica, sans-serif
83}
84
85TR.small_title {
86    FONT-WEIGHT: bold;
87    BACKGROUND: #eeeeff;
88    FONT-FAMILY: Helvetica, sans-serif
89}
90
91/* #F0FFBA */
92TR.parameter_title {
93    FONT-WEIGHT: bold;
94    FONT-FAMILY: Helvetica, sans-serif;
95    BACKGROUND: #F0FFE0
96}
97
98/***** Navbar stuff *****/
99
100TD.navbar_unselected A:hover {
101    BACKGROUND: #AAAAFF;
102    BORDER-TOP: 3px solid #AAAAFF;
103    BORDER-BOTTOM: 3px solid #AAAAFF
104}
105
106/* Formatting for the row with the labels */
107TR.navbar {
108    FONT-WEIGHT: bold;
109    BACKGROUND: #ddddff;
110    FONT-FAMILY: Helvetica, sans-serif
111}
112
113/* Formatting for the table cell that is currently selected */
114TD.navbar_selected {
115    BORDER-TOP: 3px solid #0000AA;
116    BORDER-BOTTOM: 3px solid #DDDDFF
117}
118
119TD.navbar_unselected {
120    BORDER-TOP: 3px solid #DDDDFF;
121    BORDER-BOTTOM: 3px solid #DDDDFF
122}
123
124/* Formatting for the text that allows cycling through files and finding details vs. summary */
125TD.navbar_small {
126    FONT-WEIGHT: lighter;
127    FONT-SIZE: 8pt;
128    TEXT-TRANSFORM: lowercase;
129    FONT-FAMILY: Helvetica, sans-serif
130}
131
132/* Formatting for Research System's logo */
133FONT.logo {
134    FONT-SIZE: 16pt;
135    TEXT-TRANSFORM: uppercase;
136    FONT-FAMILY: 'Times New Roman', serif
137}
138
139/* Formatting for IDL version and User/Developer Documentation tag */
140FONT.version {
141    FONT-SIZE: 8pt;
142    FONT-FAMILY: Helvetica, sans-serif
143}
144
145/* Formatting for directory name on a file page */
146FONT.directory {
147    FONT-SIZE: 8pt;
148    FONT-FAMILY: Helvetica, sans-serif;
149    COLOR: darkolivegreen
150}
151
152/* Formatting for a file name on a file page */
153FONT.file {
154    FONT-WEIGHT: bold;
155    FONT-SIZE: 16pt;
156    FONT-FAMILY: Helvetica, sans-serif
157}
158
159/* Formatting for line at bottom of page indicating version of IDLdoc */
160FONT.tagline {
161    FONT-SIZE: 8pt;
162    FONT-STYLE: italic;
163    FONT-FAMILY: Helvetica, sans-serif
164}
165
166FONT.code {
167    FONT-SIZE: 10pt;
168    FONT-FAMILY: 'Courier New', monospace
169}
170
171/* Format for the attributes to a parameter or keyword in the table of parameters and keywords in the routine details */
172.param_attrib {
173    FONT-WEIGHT: 200;
174    FONT-SIZE: 8pt;
175    FONT-FAMILY: Helvetica, sans-serif;
176    COLOR: darkolivegreen
177}
178
179/* Format for a parameter or keyword name in the table of parameters and keywords in the routine details */
180FONT.param_name {
181    FONT-WEIGHT: bold;
182    FONT-SIZE: 10pt;
183    FONT-FAMILY: Helvetica, sans-serif
184}
185
186TD.listing {
187    BORDER-RIGHT: 0px solid;
188    BORDER-TOP: 0px solid;
189    BORDER-LEFT: 0px solid;
190    BORDER-BOTTOM: 1px solid
191}
192
193.list {
194    FONT-SIZE: 9pt;
195    FONT-FAMILY: Arial, Helvetica, sans-serif
196}
197
198.list_title {
199    FONT-SIZE: 9pt;
200    FONT-WEIGHT: bold;
201    FONT-FAMILY: Arial, Helvetica, sans-serif
202}
203
204/* Font for the number of files or directories in the side frames */
205.list_tagline {
206    FONT-WEIGHT: lighter;
207    FONT-SIZE: 8pt;
208    FONT-FAMILY: Helvetica, sans-serif;
209    COLOR: darkolivegreen
210}
211
212.list_tagline_caution {
213    FONT-SIZE: 8pt;
214    FONT-FAMILY: Helvetica, sans-serif
215}
216
217.list_tagline_error {
218    FONT-SIZE: 8pt;
219    FONT-FAMILY: Helvetica, sans-serif;
220    COLOR: #FF1111
221}
222
223P.code_header {
224    FONT-SIZE: 10pt;
225    MARGIN-TOP: 0pt;
226    MARGIN-BOTTOM: 0pt;
227    MARGIN-LEFT: 30pt;
228    TEXT-INDENT: -30pt;
229    FONT-FAMILY: 'Courier New', monospace
230}
231
232P.first_line {
233    MARGIN-TOP: 3pt;
234    MARGIN-BOTTOM: 0pt;
235    MARGIN-LEFT: 15pt;
236    FONT-WEIGHT: lighter;
237    FONT-SIZE: 8pt;
238    FONT-FAMILY: Helvetica, sans-serif;
239}
240
241.routine {
242    FONT-WEIGHT: bold;
243    FONT-SIZE: 12pt;
244    FONT-FAMILY: Arial, Helvetica, sans-serif
245}
246
247/* Formatting for the attributes of a routine */
248DT.attribute {
249    FONT-WEIGHT: bold;
250    FONT-SIZE: 9pt;
251    FONT-FAMILY: Helvetica, sans-serif
252}
253
254/* Formatting for the attributes of a routine */
255.attribute_item {
256    FONT-SIZE: 9pt;
257    FONT-FAMILY: Helvetica, sans-serif;
258    MARGIN-BOTTOM: 4px;
259    FONT-WEIGHT: lighter;
260    COLOR: darkolivegreen
261}
262
263/* Formatting for the attributes of a routine */
264DT.index_item {
265    FONT-SIZE: 9pt;
266    FONT-WEIGHT: lighter;
267    FONT-FAMILY: Helvetica, sans-serif
268
269}
270
271/* Formatting for the attributes of a routine */
272DD.index_description {
273    FONT-SIZE: 8pt;
274    FONT-FAMILY: Helvetica, sans-serif;
275    FONT-WEIGHT: lighter;
276    COLOR: darkolivegreen
277}
278
279HR.divider {
280    COLOR: lightslateblue;
281    BORDER-TOP-WIDTH: 1px;
282    BORDER-BOTTOM-WIDTH: 0px;
283    BORDER-LEFT-WIDTH: 0px;
284    BORDER-RIGHT-WIDTH: 0px;
285    HEIGHT: 1px
286}
287
288HR.table_divider {
289    COLOR: rgb(200, 200, 255);
290    BORDER-TOP-WIDTH: 1px;
291    BORDER-BOTTOM-WIDTH: 0px;
292    BORDER-LEFT-WIDTH: 0px;
293    BORDER-RIGHT-WIDTH: 0px;
294    BORDER-STYLE: dotted;
295    HEIGHT: 1px
296}
297
298TR.table_divider {
299    HEIGHT: 1px;
300    MARGIN: 0px;
301    PADDING: 0px
302}
303
304SPAN.index_selection {
305    FONT-WEIGHT: bold;
306    FONT-SIZE: 12pt;
307    FONT-FAMILY: Helvetica, sans-serif
308}
309--></STYLE>
310
311<SCRIPT>
312function setTitle()
313{
314parent.document.title="Etc (IDL Library)";
315}
316</SCRIPT>
317</HEAD>
318<BODY CLASS="standard" onload="setTitle();">
319
320<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" WIDTH="100%">
321<TR><TD VALIGN="TOP" BGCOLOR="#DDDDFF" style="BORDER-TOP: 1px solid #BBBBFF; BORDER-BOTTOM: 1px solid #6666AA; BORDER-LEFT: 1px solid #BBBBFF; BORDER-RIGHT: 1px solid #6666AA;">
322<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0">
323<TR CLASS="navbar">
324<TD class="navbar_unselected">&nbsp;<A HREF="../../overview.html">Overview</A>&nbsp;</TD>
325<TD class="navbar_unselected">&nbsp;Directory&nbsp;</TD>
326<TD class="navbar_unselected">&nbsp;<A HREF="../../full-index.html">Index</A>&nbsp;</TD>
327<TD class="navbar_unselected">&nbsp;<A HREF="../../search-page.html">Search</A>&nbsp;</TD>
328<TD class="navbar_unselected">&nbsp;File&nbsp;</TD>
329<TD class="navbar_unselected">&nbsp;Source&nbsp;</TD>
330<TD class="navbar_unselected">&nbsp;<A HREF="../../idldoc-help.html">Help</A>&nbsp;</TD>
331<TD class="navbar_selected">&nbsp;Etc&nbsp;</TD>
332</TR>
333</TABLE>
334</TD>
335<TD>&nbsp;&nbsp;&nbsp;</TD>
336<TD ROWSPAN="3" ALIGN="right"><FONT CLASS="logo"><NOBR>IDL Library</NOBR></FONT><BR><FONT CLASS="version"><NOBR>Michael Galloy, RSI</NOBR></FONT><BR><FONT CLASS="version" STYLE="font-weight: bold">Developer&nbsp;Documentation</FONT></TD>
337</TR>
338<TR><TD CLASS="navbar_small">&nbsp;prev&nbsp;file&nbsp;|&nbsp;next&nbsp;file&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<NOBR><A HREF=".\tools\idldoc\idldoc_files.html" TARGET="_top">view single page</A>&nbsp;|&nbsp;<A HREF="../../index.html" TARGET="_top">view frames</A>&nbsp;|&nbsp;update routines</NOBR></TD></TR>
339<TR><TD CLASS="navbar_small">SUMMARY:&nbsp;fields&nbsp;|&nbsp;routine&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DETAILS:&nbsp;routine</TD></TR>
340<TR><TD></TD></TR>
341</TABLE>
342
343<HR CLASS="divider">
344
345 <p> Only comments in between ;+ and ;- markers (as the first non-whitespace
346 items on their lines) before a routine are parsed by IDLdoc.  Text (including
347 HTML code) is simply copied verbatim to the IDLdoc HTML file until the first
348 tag is encountered.
349
350 <p> Tags are prefixed by an '@' sign which also serves as a delimiter
351 between the content of the previous tag and its own content.  The parameters
352 to the tags are whitespace delimited.  Often tags will have a parameter or
353 two and then use the remainder of the tag content as a single parameter.
354 Once an '@' sign appears in an IDLdoc comment, all remaining comment is
355 interpreted as tags or contents of tags.
356
357 <p> Also, certain tags accept further attributes.  Attributes are enclosed in
358 curly braces {}.  For example, the param and keyword tags to comment
359 positional parameters of a routine, accepts the attributes "in", "out",
360 "type=", "optional", "required", and "default=".
361
362 <p> The below tags are processed by IDLdoc in headings for routines.  Note to
363 use an @ sign in a routine's comments, it must be escaped with a \ immediately
364 before the @.
365
366 <p>
367
368 <table width="100%" border="1" cellspacing="0" cellpadding="3">
369 <tr bgcolor="#DDDDDD"><td colspan="2"><b>Routine Tags</b></td></tr>
370
371 <tr><td width="100" align="right" valign="top">abstract</td><td>Indicates
372     the method is abstract (ie. the routine is not implemented)</td></tr>
373 <tr><td width="100" align="right" valign="top">author</td><td>Author of the
374     routine</td></tr>
375 <tr><td width="100" align="right" valign="top">bugs</td><td>Comment to
376     describing the known bugs for the routine</td></tr>
377 <tr><td width="100" align="right" valign="top">copyright</td><td>Copyright
378     information</td></tr>
379 <tr><td width="100" align="right" valign="top">examples</td><td>Example
380     code</td></tr>
381 <tr><td width="100" align="right" valign="top">field</td><td>Comments
382     for fields of a class defined in a file that ends in __DEFINE.PRO</td></tr>
383 <tr><td width="100" align="right" valign="top">file_comments</td><td>Comments
384     for the entire file.</td></tr>
385 <tr><td width="100" align="right" valign="top">hidden</td><td>Hides this
386     routine from IDLdoc</td></tr>
387 <tr><td width="100" align="right" valign="top">hidden_file</td><td>Hides the
388     file this routine is part of from IDLdoc</td></tr>
389 <tr><td width="100" align="right" valign="top">history</td><td>History of
390     modifcations of the routine</td></tr>
391 <tr><td width="100" align="right" valign="top">inherits</td><td>parent class
392     of the class (if class definition)</td></tr>
393 <tr><td width="100" align="right" valign="top">keyword</td><td>Keyword
394     parameter; attributes of this tag are {in}, {out}, {optional},
395     {type=name}, {default=value}, {private}, {required}</td></tr>
396 <tr><td width="100" align="right" valign="top">obsolete</td><td>Indicates
397     the routines is obsolete</td></tr>
398 <tr><td width="100" align="right" valign="top">param</td><td>Positional
399     parameter; attributes of this tag are {in}, {out}, {optional},
400     {type=name}, {default=value}, {private}, {required}</td></tr>
401 <tr><td width="100" align="right" valign="top">pre</td><td>Indicates a
402     pre-condition (requirement) for the routine to run</td></tr>
403 <tr><td width="100" align="right" valign="top">post</td><td>Indicates
404     a post-condition that should be true when the routine has finished
405     </td></tr>
406 <tr><td width="100" align="right" valign="top">private</td><td>Indicates the
407     routine is not intended to be called by users. Routines with this tag set
408     will be hidden if the USER keyword to IDLdoc is set.</td></tr>
409 <tr><td width="100" align="right" valign="top">private_file</td><td>Indicates the
410     file this routine is part of is not intended to be called by users of the file.
411     Routines with this tag set will be hidden if the USER keyword to IDLdoc is
412     set.</td></tr>
413 <tr><td width="100" align="right" valign="top">returns</td><td>Return
414     information for a function</td></tr>
415 <tr><td width="100" align="right" valign="top">requires</td><td>Version of
416     IDL required to run routine</td></tr>
417 <tr><td width="100" align="right" valign="top">restrictions</td><td>
418     Restrictions on the use of the routine</td></tr>
419 <tr><td width="100" align="right" valign="top">uses</td><td>Which non-RSI
420     IDL routines this routine needs</td></tr>
421 <tr><td width="100" align="right" valign="top">version</td><td>Current version of the
422     routine</td></tr>
423 </table>
424
425<p> Below is the comment header for the IDLdoc routine itself and appears
426immediately before the IDLdoc routine definition:
427
428<pre>
429;+
430; Calling routine for IDLdoc.
431;
432; @file_comments IDLdoc is a hypertext documentation system for IDL code.  It
433; is intended to show the API of a library of code in an easy to browse
434; manner.  It produces HTML pages -- one page per '.pro' file, as
435; well as directory listing, overview pages, and an index of files, routines,
436; keywords, and parameter names.
437;
438; &#139;p&#155; Unmarked code may be processed by IDLdoc to produce a browseable
439; listing of routines and their arguments.  But to obtain more useful
440; results, the source can be marked to produce formatted comments in
441; the output. Each routine has special tags to indicate particular
442; information for IDLdoc formatting use. HTML markup tags may be used
443; anywhere comments are expected.  See the
444; &#139;A HREF="idldoc_files.html"&#155;help&#139;/A&#155; for individual files for specifics about
445; the tags available.
446;
447; &#139;p&#155; For a more an example of code that has been documented using IDLdoc,
448; check IDLdoc's source for its comments and compare to its output.
449;
450; &#139;p&#155; Class listings and fields summary will be generated for files which
451; end with __DEFINE.PRO.  Use the "field" tag to make comments on each
452; field of the class/structure defined.
453;
454; &#139;p&#155; An overview file can be specified with the OVERVIEW keyword to IDLdoc.
455; This file is a plain text file with comments (which can contain HTML codes)
456; that will be displayed on a summary page.  The below tags are processed by
457; IDLdoc.
458;
459; &#139;p&#155;
460;
461; &#139;table width="100%" border="1" cellspacing="0" cellpadding="3"&#155;
462; &#139;tr bgcolor="#DDDDDD"&#155;&#139;td colspan="2"&#155;&#139;b&#155;Overview Tags&#139;/b&#155;&#139;/td&#155;&#139;/tr&#155;
463; &#139;tr&#155;&#139;td width="100" align="right" valign="top"&#155;dir&#139;/td&#155;
464; &#139;td&#155;Comment for a directory.  The first parameter to dir is the directory
465; name relative to the root dir.  The rest of the tag content is the comment.
466; &#139;/td&#155;&#139;/tr&#155;
467; &#139;/table&#155;
468;
469; &#139;p&#155; The style of the output of IDLdoc can be changed by editing the
470; cascading style sheet used: idldoc.css found in the same directory
471; as IDLdoc.
472;
473; &#139;p&#155; This help was produced by IDLdoc.
474;
475; @examples To run IDLdoc, try:
476;      &#139;center&#155;&#139;code&#155;idldoc, root='C:\\mycode'&#139;/code&#155;&#139;/center&#155;
477;    where C:\\mycode is the root of a directory tree containing IDL
478;    .pro files.
479;
480; @keyword root {in}{required}{type=string} root directory for IDLdoc's
481;          recursive search for .pro files.  IDLdoc will find any
482;          files with the '.pro' suffix and include them in its file
483;          listings.  Only directories with '.pro' files in them are
484;          included in the directory listings.
485; @keyword browse_routines {in}{optional}{type=boolean} set to include a frame
486;          to browse through the routines of the current file
487; @keyword nonavbar {in}{optional}{type=boolean} set to exclude the
488;          navigation bar at the top of each page
489; @keyword output {in}{optional}{type=string}{default=same as root}
490;          directory in which to create the HTML output and possible
491;          subdirectories
492; @keyword overview {in}{optional}{type=string} filepath to a file containing
493;          the summary of the package information about each directory in the
494;          package.
495; @keyword quiet {in}{optional}{type=boolean} if set, print only
496;          warnings
497; @keyword silent {in}{optional}{type=boolean} if set, print no
498;          messages
499; @keyword user {in}{optional}{type=boolean} set to create a
500;          listing appropriate for &#139;em&#155;users&#139;/em&#155; of the given
501;          library hierarchy; the default is to create documentation
502;          suited to developers.  If set private routines are not
503;          shown in the documentation.
504; @keyword embed {in}{optional}{type=boolean} if set, embeds style
505;          sheet in each HTML document; if this is not set, each HTML
506;          file will be looking for the cascading style sheet idldoc.css
507;          in the directory specified for the ROOT keyword
508; @keyword footer {in}{optional}{type=string} filename for a footer
509;          to be placed at the bottom of files; this file can contain any valid
510;          HTML
511; @keyword n_warnings {out}{optional}{type=integer} set to a named variable to
512;          contain the total number of warnings issued during the run
513; @keyword title {in}{optional}{type=string}{default=Research Systems} title to
514;          place in the upper right of all generated pages
515; @keyword statistics {in}{optional}{type=boolean} set to include statistics
516;          about each file
517; @keyword subtitle {in}{optional}{type=string}{default=IDL version} subtitle to
518;          place in the upper right of all generated pages
519; @requires IDL 6.0
520; @author Michael D. Galloy
521; @copyright RSI, 2002
522;-
523</pre>
524<P>
525<HR CLASS="divider">
526<CENTER>
527<FONT STYLE="font-family: Arial; font-size: 8pt">
528Personal IDL library of Michael Galloy, Professional Services Engineer - Trainer/Consultant,
529<A HREF="http://www.rsinc.com">Research Systems</A> <BR>
530For more information about these routines contact <A HREF="mailto:mgalloy@rsinc.com">Michael Galloy</A> <BR>
531Feel free to <A HREF="mailto:mgalloy@rsinc.com">submit a bug or feature request</A> for any of these routines <BR> 
532</FONT>
533</CENTER>
534<HR CLASS="divider">
535<FONT CLASS="tagline">Produced by IDLdoc 1.6 on Wed Feb 09 12:40:46 2005</FONT><BR>
536</BODY></HTML>
Note: See TracBrowser for help on using the repository browser.