1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
|
<!doctype html public "-//W30//DTD W3 HTML 2.0//EN">
<HTML>
<!-- This file was generated using SDF 2.001 by
Ian Clatworthy (ianc@mincom.com). SDF is freely
available from http://www.mincom.com/mtr/sdf. -->
<HEAD>
<TITLE>SDF 2.001: SDF Reference: sdfget - Documentation Extraction Utility</TITLE>
</HEAD>
<BODY BGCOLOR="ffffff">
<DIV CLASS="header">
<P><IMG SRC="../sdflogo.gif" ALIGN="Right"></P>
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="re_sdf.html">Contents</A> | <A HREF="in_prog.html">Parent Topic</A> | <A HREF="sdfcli.html">Previous Topic</A> | <A HREF="sdftest.html">Next Topic</A> <BR><A HREF="../index.html">Home</A> | <A HREF="../catalog.html">Catalog</A></P>
</DIV>
<BR CLEAR="Right">
</DIV>
<DIV CLASS="main">
<H1><A NAME="sdfget">11.6. sdfget - Documentation Extraction Utility</A></H1>
<HR>
<H2><A NAME="Purpose">Purpose</A></H2>
<P><A HREF="../ref/sdfget.html">sdfget</A> extracts documentation embedded in source code.</P>
<HR>
<H2><A NAME="Usage">Usage</A></H2>
<PRE>
usage : sdfget [-h[help]] [-o[out_ext]]
[-l[log_ext]] [-O[out_dir]]
[-f formatting_filename] [-g[get_rule]]
[-r[rpt_file]] [-s scope] [-i]
[-v[verbose]] file ...
purpose: extract documentation embedded in source code
version: 2.000 (SDF 2.001)
</PRE>
<P>The options are:</P>
<TABLE CLASS="columns" BORDER>
<TR CLASS="heading">
<TD>
<STRONG>Option</STRONG>
</TD>
<TD>
<STRONG>Description</STRONG>
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfget_h">-h</A>
</TD>
<TD>
display help on options
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfget_o">-o</A>
</TD>
<TD>
output file extension
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfget_l">-l</A>
</TD>
<TD>
log file extension
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfget_O">-O</A>
</TD>
<TD>
output to input file's (or explicit) directory
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfget_f">-f</A>
</TD>
<TD>
filename to use when formatting the output
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfget_g">-g</A>
</TD>
<TD>
rule to use to get documentation
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfget_r">-r</A>
</TD>
<TD>
report file
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfget_s">-s</A>
</TD>
<TD>
scope of documentation to be extracted
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfget_i">-i</A>
</TD>
<TD>
only output lines not extracted
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfget_v">-v</A>
</TD>
<TD>
verbose mode
</TD>
</TR>
</TABLE>
<HR>
<H2><A NAME="Description">Description</A></H2>
<P><A NAME="sdfget_h">The -h option provides help. If it is specified without a parameter, a brief description of each option is displayed. To display the attributes for an option, specify the option letter as a parameter.</A></P>
<P><A NAME="sdfget_o">By default, generated output goes to standard output. To direct output to a file per input file, use the -o option to specify an extension for output files. If the -o option is specified without a parameter, an extension of <EM>out</EM> is assumed.</A></P>
<P><A NAME="sdfget_l">Likewise, error messages go to standard error by default. Use the -l option to create a log file per input file. If the -l option is specified without a parameter, an extension of <EM>log</EM> is assumed.</A></P>
<P><A NAME="sdfget_O">By default, generated output and log files are created in the current directory. Use the -O option to specify an explicit output directory. If the -O option is specified without a parameter, the input file's directory is used.</A></P>
<P><A NAME="sdfget_f">The -f option can be used to specify a filename to use when formatting the output. This is useful when the text is coming from the standard input stream.</A></P>
<P>The <EM>get-rule</EM> nominates the formatting of the embedded documentation to be extracted. All currently defined get-rules assume the documentation is in comment blocks in one of the following formats:</P>
<PRE>
>>section_title1::
text of section 1, line 1
text of section 1, line ..
>>section_title2::
text of section 2, line 1
text of section 2, line ..
>>END::
>>section_title3:: text of section 3
</PRE>
<P>The first form is most commonly used. In this format, the text in a section extends until the end of the current "comment block" or the start of the next section, whichever comes first. The second form (i.e. explicitly specifying where the section ends) is useful if you wish to add some normal comments (i.e. non-documentation) which you do not want extracted. If the text is short, the third form can be used. Regardless of the format, if a section is found which is already defined, the text of the section is concatenated onto the existing text. This permits the documentation for each entity to be specified immediately above where it is defined in the source code.</P>
<P><A NAME="sdfget_g">The -g option specifies the <EM>get-rule</EM> to use. The available get-rules differ on the prefix expected at the front of each line as shown below.</A></P>
<TABLE CLASS="columns" BORDER>
<TR CLASS="heading">
<TD>
<STRONG>Rule</STRONG>
</TD>
<TD>
<STRONG>Prefix</STRONG>
</TD>
</TR>
<TR>
<TD>
perl
</TD>
<TD>
#
</TD>
</TR>
<TR>
<TD>
cpp
</TD>
<TD>
//
</TD>
</TR>
<TR>
<TD>
c
</TD>
<TD>
* or /*
</TD>
</TR>
<TR>
<TD>
fortran
</TD>
<TD>
c (with 5 preceding spaces)
</TD>
</TR>
<TR>
<TD>
eiffel
</TD>
<TD>
--
</TD>
</TR>
<TR>
<TD>
bat
</TD>
<TD>
rem
</TD>
</TR>
</TABLE>
<P>Within C code, a trailing space is required after the characters above. For other languages, a trailing space is optional. Within FORTRAN code, the "c" character must be preceded by exactly 5 spaces. For other languages, zero or more whitespace characters are permitted before the characters above.</P>
<P>For example, embedded documentation within C code looks like:</P>
<PRE>
/* >>Purpose::
* This library provides a high level interface
* to commonly used network services.
*/
</PRE>
<P>If the -g option is not specified, <EM>perl</EM> is the default get-rule. If the -g option is specified without a parameter, the extension in lowercase of the filename (or the <EM>formatting filename</EM> if the text is coming from standard input) is used to guess the get_rule as shown below.</P>
<TABLE CLASS="columns" BORDER>
<TR CLASS="heading">
<TD>
<STRONG>Rule</STRONG>
</TD>
<TD>
<STRONG>Extensions</STRONG>
</TD>
</TR>
<TR>
<TD>
cpp
</TD>
<TD>
cpp, c++, cc, hpp, hpp, h, java, idl
</TD>
</TR>
<TR>
<TD>
c
</TD>
<TD>
c
</TD>
</TR>
<TR>
<TD>
fortran
</TD>
<TD>
fortran, for, f77, f
</TD>
</TR>
<TR>
<TD>
eiffel
</TD>
<TD>
eiffel, ada
</TD>
</TR>
<TR>
<TD>
bat
</TD>
<TD>
bat, cmd
</TD>
</TR>
</TABLE>
<P><A NAME="sdfget_r">A report filename can be specified using the -r option. If the name doesn't include an extension, sdg is assumed. Reports provide a mechanism for:</A></P>
<UL>
<LI>selectively extracting sections, and
<LI>rudimentary reformatting (e.g. to <A HREF="http://www.mincom.com/mtr/sdf/">SDF</A>)</UL>
<P>If no report is specified, all sections are output in the following format:</P>
<PRE>
section_title1
section_text1
section_title2
section_text2
</PRE>
<P>If -r is specified on its own, <TT>default.sdg</TT> is assumed. This report selects the set of sections (within the <A HREF="http://www.mincom.com/mtr/sdf/">SDF</A> documentation standards) which form the user documentation and formats them into <A HREF="http://www.mincom.com/mtr/sdf/">SDF</A>. Details on the report format are specified below. Reports are searched for in the current directory, then in the <EM>stdlib</EM> directory within SDF's library directory.</P>
<P><A NAME="sdfget_s">The -s option can be used to specify the scope of the documentation to be extracted. (This is an experimental feature and may change so most users should avoid using it.)</A></P>
<P><A NAME="sdfget_i">The -i option outputs only those lines which the get-rule did not match. This option is useful for extracting non-documentation from a file to give just the code.</A></P>
<P><HR WIDTH="80%" ALIGN="Left">
<STRONG>Note: </STRONG>The -r option is ignored if -i is specified.
<HR WIDTH="80%" ALIGN="Left"></P>
<P><A NAME="sdfget_v">The -v option enables verbose mode. This is useful for seeing which rule is being used for each file.</A></P>
<HR>
<H2><A NAME="Examples">Examples</A></H2>
<P>To extract the user documentation from a <A HREF="http://www.mincom.com/mtr/sdf/">SDF</A> application written in C++ (<CMD>xyz</CMD>, say) and save it into <TT>xyz.sdf</TT>:</P>
<PRE>
sdfget -gcpp -r -osdf xyz.cpp
</PRE>
<HR>
<H2><A NAME="Limitations and future directions">Limitations and future directions</A></H2>
<P>It would be nicer if the get-rule was always guessed from the filename extension but changing the default from perl could break existing scripts. Therefore, get-rule guessing must be explicitly enabled by specifging the -g option without a parameter.</P>
</DIV>
<DIV CLASS="footer">
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="re_sdf.html">Contents</A> | <A HREF="in_prog.html">Parent Topic</A> | <A HREF="sdfcli.html">Previous Topic</A> | <A HREF="sdftest.html">Next Topic</A> <BR><A HREF="../index.html">Home</A> | <A HREF="../catalog.html">Catalog</A></P>
</DIV>
</DIV>
</BODY>
</HTML>
|
