Context Navigation

source: trunk/SRC/Documentation/idldoc_html_output/idldoc-dev-help2.html @ 103

Last change on this file since 103 was 89, checked in by pinsard, 18 years ago
add idldoc html output. see Documentation/idldoc_html_output/index.html
File size: 13.2 KB

Line
1
2	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5	<!-- Template needs structure with the following fields:
6	version : IDLdoc version
7	date : string containing date of file creation
8	embed : 0 for link to CSS, 1 for embed CSS
9	css_location : if embed then string filename of CSS file location, o/w href to CSS file
10	idldoc_syntax_filename : file containing IDLdoc output for the idldoc routine
11	navbar_filename : filename of navbar template
12	footer : filename of footer file to include
13	tagline_filename : filename of tagline template
14	Plus stuff needed by the templates: navbar, tagline
15	-->
16
17	<!-- Generated by IDLdoc 2.0 -->
18
19	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
20	<head>
21	<title>IDLdoc Developer's Help (IDLdoc API documentation)</title>
22
23
24	<link rel="stylesheet" type="text/css" href=".//main_files.css" media="all"/>
25	<link rel="stylesheet" type="text/css" href=".//main_files_print.css" media="print"/>
26
27
28	<script type="text/javascript">
29	function setTitle() {
30	parent.document.title="IDLdoc Developer's Help (IDLdoc API documentation)";
31	}
32	</script>
33	</head>
34
35
36	<body onload="setTitle();">
37
38	<div id="navbar_title">
39	<h1>IDLdoc API documentation</h1>
40	</div>
41
42
43	<div id="main_navbar">
44
45	<table cellspacing="0">
46	<tr>
47
48	<td><a href="overview.html?format=raw" title="Overview of library">Overview</a></td>
49
50
51
52	<td >Directory</td>
53
54
55
56	<td><a href="idldoc-categories.html?format=raw" title="Browse library by category">Categories</a></td>
57
58
59
60	<td><a href="idldoc-index.html?format=raw" title="Index of files, routines, and parameters">Index</a></td>
61
62
63
64	<td><a href="search-page.html?format=raw" title="Search library">Search</a></td>
65
66
67	<td >File</td>
68
69
70	<td >Source</td>
71
72
73
74	<td id="selected">Help</td>
75
76
77	<td >Etc</td>
78
79	<td id="flexible">Developer documentation</td>
80	</tr>
81	</table>
82
83	</div>
84
85	<div id="secondary_navbar">
86
87	<< prev file \| next file >>    <a href="idldoc-dev-help2.html" target="_TOP">view single page</a> \| <a href="index.html?format=raw" target="_TOP">view frames</a>    summary: fields \| routine    details: routine
88
89	</div>
90
91
92	<div id="container">
93
94	<h1>Modifying IDLdoc's output</h1>
95
96	<p>This guide discusses how to modify the output from IDLdoc by
97	modifying the template files (*.tt) that are provided with
98	IDLdoc. Currently, only the templates directly documenting *.pro
99	files (pro-file.tt), templates included by pro-file.tt
100	(navbar.tt and tagline.tt) and objects implementing the template
101	interface used by pro-file.tt (IDLdocRoutine and IDLdocParam)
102	are documented for user customization. The plans is to release
103	the documentation for other templates as they become more stable
104	in future releases of IDLdoc.</p>
105
106	<p>In general, if one of the below variables is not
107	defined/not-appropriate it will be set to '' or -1.</p>
108
109	<h2>navbar.tt</h2>
110
111	<p>This template is included by many other templates requiring
112	those templates to provide the following variables:</p>
113
114	<dl class="variables">
115	<dt>title</dt>
116	<dd>title of the IDLdoc library</dd>
117
118	<dt>subtitle</dt>
119	<dd>subtitle of the IDLdoc library</dd>
120
121	<dt>categories_href</dt>
122	<dd>relative link to the categories page</dd>
123
124	<dt>categories_selected</dt>
125	<dd>boolean on whether the current page is the categories page</dd>
126
127	<dt>dir_overview_href</dt>
128	<dd>relative link to the directory overview page</dd>
129
130	<dt>dir_overview_selected</dt>
131	<dd>boolean on whether the current page is the directory overview page</dd>
132
133	<dt>etc_selected</dt>
134	<dd>boolean on whether the current page is an "Etc" page</dd>
135
136	<dt>file_selected</dt>
137	<dd>boolean on whether the current page is documentation of a PRO or SAV file</dd>
138
139	<dt>help_href</dt>
140	<dd>relative link to the help page</dd>
141
142	<dt>help_selected</dt>
143	<dd>boolean on whether the current page is the help page</dd>
144
145	<dt>index_href</dt>
146	<dd>relative link to the full index</dd>
147
148	<dt>index_selected</dt>
149	<dd>boolean on whether the current page is the full index page</dd>
150
151	<dt>overview_href</dt>
152	<dd>relative link to the library overview page</dd>
153
154	<dt>overview_selected</dt>
155	<dd>boolean on whether the current page is the library overview page</dd>
156
157	<dt>search_href</dt>
158	<dd>relative link to the search page</dd>
159
160	<dt>search_selected</dt>
161	<dd>boolean on whether the current page is the search page</dd>
162
163	<dt>source_href</dt>
164	<dd>relative link to the source code of a PRO file</dd>
165
166	<dt>source_selected</dt>
167	<dd>boolean on whether the current page is a source code page</dd>
168
169	<dt>user</dt>
170	<dd>boolean on whether the current documentation is generated for a user (as opposed to a developer)</dd>
171
172	<dt>prev_file_href</dt>
173	<dd>relative link to the previous PRO or SAV file page</dd>
174
175	<dt>next_file_href</dt>
176	<dd>relative link the next PRO or SAV file page</dd>
177
178	<dt>view_single_page_href</dt>
179	<dd>link to the current page</dd>
180
181	<dt>view_frames_href</dt>
182	<dd>link to the library index.html page</dd>
183
184	<dt>summary_fields_href</dt>
185	<dd>internal link to the fields summary; '' if no fields</dd>
186
187	<dt>summary_routine_href</dt>
188	<dd>internal link to the routine summary, '' if only one routine</dd>
189
190	<dt>details_routine_href</dt>
191	<dd>internal link to the start of the routine details</dd>
192	</dl>
193
194	<h2>tagline.tt</h2>
195
196	<p>This template is included by many other templates requiring
197	those templates to provide the following variables:</p>
198
199	<dl class="variables">
200	<dt>version</dt>
201	<dd>IDLdoc version as a string</dd>
202
203	<dt>date</dt>
204	<dd>string containing date of file creation</dd>
205	</dl>
206
207
208	<h2>pro-file.tt</h2>
209
210	<p>This file produces the output for the documentation of IDL
211	source code files. Variables provided to this template are all
212	those required by the navbar.tt and tagline.tt templates and
213	those listed below:</p>
214
215	<dl class="variables">
216	<dt>has_fields</dt>
217	<dd>base filename</dd>
218
219	<dt>is_class</dt>
220	<dd>boolean on whether this file corresponds to a class definition (and class variable is present)</dd>
221
222	<dt>class</dt>
223	<dd>IDLdocClass object</dd>
224
225	<dt>fields</dt>
226	<dd>base filename</dd>
227
228	<dt>pro_file</dt>
229	<dd>base filename</dd>
230
231	<dt>pro_dir</dt>
232	<dd>directory for file</dd>
233
234	<dt>root</dt>
235	<dd>relative path to the root of the library</dd>
236
237	<dt>last_modified</dt>
238	<dd>date last modified as a string</dd>
239
240	<dt>file_comments</dt>
241	<dd>file level comments</dd>
242
243	<dt>nroutines</dt>
244	<dd>number of IDLdocRoutine objects in routines array</dd>
245
246	<dt>routines</dt>
247	<dd>array of IDLdocRoutine objects; see below for variables in
248	these objects</dd>
249
250	<dt>nonavbar</dt>
251	<dd>set to 1 to indicate no navbar, otherwise set to 0</dd>
252
253	<dt>navbar_filename</dt>
254	<dd>filename of navbar template; appropriate for
255	INCLUDE_TEMPLATE directive</dd>
256
257	<dt>embed</dt>
258	<dd>0 for link to CSS, 1 for embed CSS</dd>
259
260	<dt>css_location</dt>
261	<dd>if embed then string filename of CSS file location, o/w
262	href to CSS file; for all media types</dd>
263
264	<dt>print_css_location</dt>
265	<dd>if embed then string filename of CSS file location, o/w
266	href to CSS file; for printing only</dd>
267
268	<dt>footer</dt>
269	<dd>filename of user-created footer to insert; appropriate for
270	the INCLUDE directive</dd>
271
272	<dt>separator</dt>
273	<dd>correct path separator, / or \ depending on Unix or
274	Windows system</dd>
275
276	<dt>tagline_filename</dt>
277	<dd>name of template for the bottom of the file; appropriate
278	for the INCLUDE_TEMPLATE directive</dd>
279	</dl>
280
281
282	<h3>IDLdocRoutine objects in pro-file.tt</h3>
283
284	<dl class="variables">
285	<dt>routine_name</dt>
286	<dd>string name of the routine</dd>
287
288	<dt>routine_url</dt>
289	<dd>internal url to the start of the routine details</dd>
290
291	<dt>is_func</dt>
292	<dd>boolean on whether the routine is a function</dd>
293
294	<dt>obsolete</dt>
295	<dd>boolean on whether the routine is marked obsolete</dd>
296
297	<dt>abstract</dt>
298	<dd>boolean on whether the routine is abstract (i.e. not implemented)</dd>
299
300	<dt>private</dt>
301	<dd>boolean on whether the routine is private (i.e. not visible in USER mode)</dd>
302
303	<dt>categories_present</dt>
304	<dd>boolean on whether the routine is marked with categories</dd>
305
306	<dt>categories</dt>
307	<dd>string array of list of categories as listed in the source</dd>
308
309	<dt>ntotalparams</dt>
310	<dd>total number of positional parameters and keywords</dd>
311
312	<dt>nparams</dt>
313	<dd>number of positional parameters</dd>
314
315	<dt>params</dt>
316	<dd>array of IDLdocParam objects</dd>
317
318	<dt>nkeywords</dt>
319	<dd>number of keywords</dd>
320
321	<dt>keywords</dt>
322	<dd>array of IDLdocParam objects</dd>
323
324	<dt>short_comment</dt>
325	<dd>first sentence of the routine comments</dd>
326
327	<dt>statistics</dt>
328	<dd>boolean on whether the McCabe complexity statistics have been calculated</dd>
329
330	<dt>mccabe_cyclic</dt>
331	<dd>McCabe Cyclic complexity (computed)</dd>
332
333	<dt>mccabe_essential</dt>
334	<dd>McCabe Essential complexity (computed)</dd>
335
336	<dt>mccabe_mod_design</dt>
337	<dd>McCabe Modular Design complexity (computed)</dd>
338
339	<dt>routine_comments</dt>
340	<dd>string array of comments for the routine</dd>
341
342	<dt>preformat</dt>
343	<dd>true if the comments are to be stripped from the source code and placed in the output with the same line breaks and formatting as the source code</dd>
344
345	<dt>returns_present</dt>
346	<dd>boolean on whether the returns tag is present</dd>
347
348	<dt>returns</dt>
349	<dd>documents the return value of a function</dd>
350
351	<dt>examples_present</dt>
352	<dd>boolean on whether the examples tag is present</dd>
353
354	<dt>examples</dt>
355	<dd>string array of example code using the routine</dd>
356
357	<dt>author_present</dt>
358	<dd>boolean on whether the author tag is present</dd>
359
360	<dt>author</dt>
361	<dd>author(s) of the routine</dd>
362
363	<dt>version_present</dt>
364	<dd>boolean on whether the version tag is present</dd>
365
366	<dt>version</dt>
367	<dd>version of the routine</dd>
368
369	<dt>history_present</dt>
370	<dd>boolean on whether the history tag is present</dd>
371
372	<dt>history</dt>
373	<dd>string array of history of the routine</dd>
374
375	<dt>copyright_present</dt>
376	<dd>boolean on whether the copyright tag is present</dd>
377
378	<dt>copyright</dt>
379	<dd>string array of copyright information about the routine</dd>
380
381	<dt>obsolete_comments_present</dt>
382	<dd>boolean on whether the obsolete tag is present</dd>
383
384	<dt>obsolete_comments</dt>
385	<dd>comments following the obsolete tag and further explaining the status of the routine (and alternatives)</dd>
386
387	<dt>bugs_present</dt>
388	<dd>boolean on whether the bugs tag is present</dd>
389
390	<dt>bugs</dt>
391	<dd>string array describing known issues with the routine</dd>
392
393	<dt>todo_present</dt>
394	<dd>boolean on whether the todo tag is present</dd>
395
396	<dt>todo</dt>
397	<dd>string array of items that still need to be done for the routine</dd>
398
399	<dt>restrictions_present</dt>
400	<dd>boolean on whether the restrictions tag is present</dd>
401
402	<dt>restrictions</dt>
403	<dd>restrictions on the use of the routine</dd>
404
405	<dt>inherits_present</dt>
406	<dd>boolean on whether the inherits tag is present</dd>
407
408	<dt>inherits</dt>
409	<dd>desribes other classes the class inherits from (this is not needed any longer)</dd>
410
411	<dt>requires_present</dt>
412	<dd>boolean on whether the requires tag is present</dd>
413
414	<dt>requires</dt>
415	<dd>which IDL verion is necessary to run this routine</dd>
416
417	<dt>uses_present</dt>
418	<dd>boolean on whether the uses tag is present</dd>
419
420	<dt>uses</dt>
421	<dd>which routines this routine calls</dd>
422
423	<dt>common_blocks_present</dt>
424	<dd>boolean on whether the common block information is present</dd>
425
426	<dt>common_blocks</dt>
427	<dd>names of common blocks used by routine</dd>
428
429	<dt>precondition_present</dt>
430	<dd>boolean on whether the routine is marked with a precondition tag</dd>
431
432	<dt>precondition</dt>
433	<dd>condition that should be satisfied before the routine is executed</dd>
434
435	<dt>postcondition_present</dt>
436	<dd>boolean on whether the routine is marked with a postcondition tag</dd>
437
438	<dt>postcondition</dt>
439	<dd>condition that should be satisfied after the routine is executed</dd>
440
441	</dl>
442
443
444	<h3>IDLdocParam objects in pro-file.tt</h3>
445
446	<dl class="variables">
447	<dt>name</dt>
448	<dd>name of the parameter</dd>
449
450	<dt>in</dt>
451	<dd>true if parameter is an input to the routine</dd>
452
453	<dt>out</dt>
454	<dd>true if the parameter is an output to the routine</dd>
455
456	<dt>optional</dt>
457	<dd>true if parameter is optional</dd>
458
459	<dt>required</dt>
460	<dd>true if parameter is required</dd>
461
462	<dt>private</dt>
463	<dd>hidden if parameter is supposed to be hidden from users of the routine, but visible to developers</dd>
464
465	<dt>hidden</dt>
466	<dd>true if parameter is supposed to be hidden</dd>
467
468	<dt>type</dt>
469	<dd>data type of the parameter</dd>
470
471	<dt>boolean</dt>
472	<dd>true if the param is a switch</dd>
473
474	<dt>default</dt>
475	<dd>default value of the parameter</dd>
476
477	<dt>comments</dt>
478	<dd>string array of comments for parameter</dd>
479
480	<dt>delim</dt>
481	<dd>appropriate delimiter preceeding parameter in a syntax listing of the routine (i.e. always a comma unless it's the first parameter of a function call)</dd>
482	</dl>
483
484
485
486	<div id="tagline">Produced by IDLdoc 2.0.</div>
487
488	</div>
489
490	</body>
491	</html>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: