1tepam::doc_gen(n)Tcl's Enhanced Procedure and Argument Managertepam::doc_gen(n)
2______________________________________________________________________________
6
8 tepam::doc_gen - TEPAM DOC Generation, reference manual
9
11 package require Tcl 8.3
12 package require tepam 0.5
14 package require tepam::doc_gen ?0.1?
16 tepam::doc_gen::generate ?-format format? ?-style style?
18 ?-header_footer? ?-dest_file dest_file? name
19 tepam::doc_gen::patch ?-format format? ?-style style? ?-search_pattern
21 search_pattern? ?-src_string src_string | -src_file src_file?
22 ?-dest_file dest_file? ?name?
23______________________________________________________________________________
25
27 This package generates documentations of TEPAM procedures (procedures
28 that have been declared with tepam::procedure). The documents are gen‐
29 erated in the classic UNIX document style using the following document
30 sections: Name, Synopsis, Description, Arguments and Example. TEPAM Doc
31 Gen provides support for various document formats. Support for addi‐
32 tional formats can be added if necessary.
33 The TEPAM Doc Gen package provides the following commands:
35 tepam::doc_gen::generate ?-format format? ?-style style?
37 ?-header_footer? ?-dest_file dest_file? name
38 This command generates the documentation for a specified proce‐
39 dure (name) in one of the supported formats (TXT, HTML, POD
40 (Perl Doc), DT (TclLib DocTool), or in a custom specific format.
41 The format is specified via ?format?. The flag ?-header_footer?
42 adds to the documentation file header and footer. If ?dest_file?
43 is specified the documentation is stored in a file (the file
44 header and footer are added automatically in this case) and the
45 file name is returned. Otherwise the documentation string is re‐
46 turned by generate.
47 tepam::doc_gen::patch ?-format format? ?-style style? ?-search_pattern
49 search_pattern? ?-src_string src_string | -src_file src_file?
50 ?-dest_file dest_file? ?name?
51 This command inserts procedure documentations into an existing
52 master document at the locations indicated by insertion place‐
53 holders which are matching the pattern of ?search_pattern?. The
54 existing master document is either provided as data to the argu‐
55 ment (?src_string?) or via a file (?src_file?). The final docu‐
56 ment is returned by patch if no destination file is defined
57 (?dest_file?). Otherwise, the document is stored in the speci‐
58 fied file, and the number of insertion placeholders that could
59 be handled successfully is returned.
60 Any insertion placeholders of the master document are handled by
62 default. By defining the argument ?name? the documentation in‐
63 sertion will be restricted to a particular procedure.
64
66 ?-format format?
67 Specifies the documentation format. TEPAM Doc Gen provides sup‐
68 port for the following formats:
69 • TXT - Text format (default)
71 • HTML
73 • POD - Perl Plain Old Documentation format (PerlPOD)
75 • DT - TclLib DocTool format
77 Section ADDING SUPPORT FOR NEW DOCUMENT FORMATS shows how sup‐
79 port for additional formats can be added.
80 ?-style style?
82 The documentation is by default generated in Tcl style (e.g.
83 command arg1 arg2 ...). C-style documentation can be generated
84 by setting this argument to 'C' (e.g. command(arg1,arg2,...)).
85 ?-dest_file dest_file?
87 If ?dest_file? is defined the documentation is written into the
88 specified destination file. Otherwise the documentation string
89 is returned by the commands generate and patch.
90 name / ?name?
92 This is the name of the procedure for which the documentation
93 has to be generated. This is a mandatory argument for generate,
94 but an optional argument for patch.
95 ?-header_footer?
97 Generate adds to the generated procedure documentation the file
98 header and footer only if a file is generated. By selecting the
99 flag ?-header_footer? the header and footer are also generated
100 if the documentation is returned as string by generate.
101 ?-src_string src_string | -src_file src_file?
103 Patch inserts procedure documentations into an existing document
104 that is either provided as string to the argument (?src_string?)
105 or as a file (?src_file?). One of these two arguments need to be
106 specified.
107 ?-search_pattern search_pattern?
109 The argument ?search_pattern? defines the documentation inser‐
110 tion placeholder used in a document. It is a regular expression
111 accepted by regexp and needs to contain a parenthesized sub-ex‐
112 pression that contains the procedure name for which the documen‐
113 tation needs to be inserted.
114 The default insertion placeholder pattern is \{!(.*?)!\}, which
116 means that the procedure name will be embedded between {! and
117 !}. The section EXAMPLES contains a custom insertion placeholder
118 pattern example.
119
121 TEPAM Doc Gen pre-defines the following document formats:
122 TXT - TEXT FORMAT
124 The documentation will be generated in a simple text format if this
125 format is selected. The format can be customized via the following
126 variable:
127 tepam::doc_gen::Option(TXT,MaxLineLength)
129 Default: 80
130 This variable defines the line wrapping limit (character posi‐
132 tion).
133 HTML - HTML FORMAT
135 TEPAM Doc Gen generates CSS styled HTML files. The HTML documentation
136 can be customized via the following variable:
137 tepam::doc_gen::Option(HTML,CssFile)
139 Default: "tepam_doc_stylesheet.css"
140 This variable specifies the CSS stylesheet file that is referred
142 by the generated HTML files.
143 The CSS stylesheet can be customized to change the documentation for‐
145 matting. A good starting point to create a customized CSS stylesheet is
146 to use the CSS file provided by the TEPAM Doc Gen example/demo. The
147 HTML documentation uses the following CSS class styles:
148 • h1.tepam_page_title - Document page title. Only used by generate
150 if a file is created or if the header and footer are built (flag
151 ?-header_footer? selected).
152 • div.tepam_command_help - Documentation container. The entire
154 procedure documentation is placed inside this container.
155 • p.tepam_section_title - Section title (e.g. Name, Synopsis, De‐
157 scription, ...)
158 • p.tepam_sub_section_title - Sub-section title (used to separate
160 the documentation of multiple sub-procedures)
161 • p.tepam_name - Name section
163 • p.tepam_synopsis - Synopsis section
165 • p.tepam_description - Single description paragraph
167 • ul.tepam_description_list - Item of a HTML bulleted/unordered
169 list inside the description section
170 • dt.tepam_argument - Item of a HTML description list used to list
172 the procedure arguments
173 • p.tepam_argument_description - Argument description paragraph
175 • p.tepam_argument_attribute - Argument attribute line
177 • pre.tepam_example - Example section
179 POD - PERL DOCUMENT FORMAT
181 The documentation is generated in the Perl Plain Old Documentation for‐
182 mat (PerlPOD) if this format is selected.
183 DT - TCLLIB DOCTOOLS FORMAT
185 The documentation is generated in the Tcllib DocTools format if this
186 format is selected.
187
189 Support for a new document format can be added by defining in the
190 tepam::doc_gen namespace a set of procedures that generate the differ‐
191 ent document components.
192 The following documentation listing contains tokens that refer to the
194 different document generation procedures:
195 <01>
197 <03> <20s> NAME<20e>
198 <30s> message_box - Displays text in a message box<30e>
199 <20s> SYNOPSYS<20e>
200 <40s> message_box [-mtype <mtype>] <text><40e>
201 <20s> DESCRIPTION<20e>
202 <21s> message_box<21e>
203 <54s> message_box [-mtype <mtype>] <text><54e>
204 <50s> This procedure allows displaying a text in an message box. The following
205 message types are supported:<50e>
206 <51> <53s> * Info<53e>
207 <53s> * Warning<53e>
208 <53s> * Error<53e> <52>
209 <50s> If the text parameter is use multiple times the different texts are
210 concatenated to create the message text.<50e>
211 <20s> ARGUMENTS<20e>
212 <60> <62s> [-mtype <mtype>]<62e>
213 <63> <65s> Message type<65e>
214 <66s> Default: "Warning"<66e>
215 <66s> Multiple: yes<66e>
216 <66s> Choices: Info, Warning, Error<66e> <64>
217 <62s> <text><62e>
218 <63> <65s> One or multiple text lines to display<65e>
219 <66s> Type: string<66e>
220 <66s> Multiple: yes<66e> <64><61>
221 <20s> EXAMPLE<20e>
222 <70> <72s> message_box "Please save first the document"<72e>
223 <73s> -> 1<73e> <71><04>
224 <02>
225 There are 2 types of document generation procedures:
226 Content generation procedures (e.g. <40s>...<40e>)
228 These procedures generate some document content based on the
229 text that is provided as procedure argument. The listing above
230 shows two tokens for these procedures to indicate the beginning
231 and the end of the generated content.
232 Control generation procedures (e.g. <03>)
234 These procedures generate control constructs, for example to
235 generate the prolog code and epilog code for lists, sections,
236 etc. These procedures have no argument.
237 The following set of procedures needs to be defined to provide support
239 for a new document format:
240 01 - gen($Format,Header) {Text}
242 Only called if doc_gen generates a file or if it is called with
243 the flag ?-header_footer?. The procedure creates the file
244 header. The provided parameter is the procedure name for which
245 the documentation has to be generated.
246 02 - gen($Format,Footer) {Text}
248 Only called if doc_gen generates a file or if it is called with
249 the flag ?-header_footer?. The procedure creates the file
250 footer.
251 03 - gen($Format,Begin) {}
253 Generates the documentation prolog (preamble)
254 04 - gen($Format,End) {}
256 Generates the documentation epilog
257 20 - gen($Format,SectionTitle) {Text}
259 Generates a section title (e.g. Name, Synopsis, Description,
260 ...). The raw title text is provided as parameter
261 21 - gen($Format,SubSectionTitle) {Text}
263 Generates a sub-section title. Sub-sections are used if a single
264 documentation is generated for multiple sub-commands to make a
265 separation between them. The raw title text is provided as pa‐
266 rameter
267 30 - gen($Format,Name) {Text}
269 Generates the name section (without title). The raw section text
270 is provided as parameter.
271 40 - gen($Format,Synopsis) {Text}
273 Generates the synopsis section (without title). The section text
274 provided as parameter is pre-formatted (the argument strings are
275 generated by gen($Format,ArgumentString)).
276 50 - gen($Format,Description) {Text}
278 Generates a description paragraph. The raw paragraph text is
279 provided as parameter.
280 51 - gen($Format,DescriptionListBegin) {}
282 Generates the prolog of a bulleted/unordered list inside the de‐
283 scription section. This prolog is usually the start code of a
284 list structure.
285 52 - gen($Format,DescriptionListEnd) {}
287 Generates the epilog of a bulleted/unordered list inside the de‐
288 scription section. This epilog is usually the end code of a list
289 structure.
290 53 - gen($Format,DescriptionListItem) {Text}
292 Generates a text item in a bulleted/unordered description list.
293 The raw item text is provided as parameter.
294 54 - gen($Format,DescriptionSynopsis) {Text}
296 Generates the synopsis line on the beginning of the description
297 section. The command can return an empty string if no synopsys
298 line is required at this place.
299 Some formats (e.g. Tcl DocTools) require that the synopsis line
301 is defined in the description section, to build then automati‐
302 cally the synopsis section. The section text provided as parame‐
303 ter is pre-formatted (the argument strings are generated by
304 gen($Format,ArgumentString)).
305 60 - gen($Format,ArgumentListBegin) {}
307 Generates the prolog of argument list (definition/non-bulleted
308 list). This prolog is usually the start code of a definition
309 list.
310 61 - gen($Format,ArgumentListEnd) {}
312 Generates the epilog of the argument list. This epilog is usu‐
313 ally the end string of a list structure.
314 62 - gen($Format,ArgumentListItem) {Name IsOptional IsNamed Type}
316 Generates an argument item line inside the argument list. This
317 command can rely on gen($Format,ArgumentDetailBegin) since the
318 parameters are identical.
319 63 - gen($Format,ArgumentDetailBegin) {}
321 Generates the argument details prolog (preamble).
322 64 - gen($Format,ArgumentDetailEnd) {}
324 Generates the argument details epilog
325 65 - gen($Format,ArgumentDescription) {Text}
327 Generates the argument description (single paragraph).
328 66 - gen($Format,ArgumentAttribute) {Text}
330 Generates a single argument attribute string. The command is
331 called individually for each attribute.
332 70 - gen($Format,ExampleBegin) {}
334 Generates the example section prolog (preamble)
335 71 - gen($Format,ExampleEnd) {}
337 Generates the example section epilog
338 72 - gen($Format,ExampleCommandLine) {Text}
340 Generates a single command line in the example section. The com‐
341 mand is called for each individual command line.
342 73 - gen($Format,ExampleResultLine) {Text}
344 Generates a command result line
345 80 - gen($Format,ArgumentString) {Name IsOptional IsNamed Type}
347 Generates the part of the command line or the synopsis that is
348 specific to an argument. The generated string has to indicate if
349 an argument is optional, named and if it is a flag.
350 The following parameters are provided to this procedure:
352 Name Name of the argument
354 IsOptional
356 If true (=1) the argument is optional which should be in‐
357 dicated by the generated string (for example by putting
358 the argument into brackets {[]} or into question marks
359 '?'):
360 gen(TXT,ArgumentString) mtype 1 0 string -> "[mtype]"
362 IsNamed
364 If true (=1) an argument is a named argument (option).
365 The generated string should in this case contain the ar‐
366 gument/option name, followed by the argument itself:
367 gen(TXT,ArgumentString) mtype 0 1 string -> "-mtype <mtype>"
369 Named arguments can also be optional:
371 gen(TXT,ArgumentString) mtype 1 1 string -> "[-mtype <mtype>]"
373 Type Indicates the type of the argument. If the type is set to
375 none the argument is a flag, which needs to be indicated
376 by the generated string. Example:
377 gen(TXT,ArgumentString) close 1 1 none -> "[-close]"
379
381 TEPAM::DOC_GEN::GENERATE
382 The TEPAM Doc Gen package can be explored by generating the documenta‐
383 tion of the command tepam::doc_gen::generate. The following example
384 generates the document in text format (default format):
385 tepam::doc_gen::generate tepam::doc_gen::generate
387 The next example generates the documentation in HTML format:
388 tepam::doc_gen::generate -format HTML tepam::doc_gen::generate
390 The flag ?header_footer? adds also the file header and footer:
391 tepam::doc_gen::generate -format HTML -header_footer tepam::doc_gen::generate
393 The documentation can directly be stored in a file. The file header and
394 footer are automatically generated in this way:
395 tepam::doc_gen::generate -format HTML -dest_file doc_gen.html tepam::doc_gen::generate
397 The generated HTML file refers a CSS stylesheet file (default:
398 tepam_doc_stylesheet.css). To display the HTML file correctly this CSS
399 stylesheet file needs to be copied into the directory of the generated
400 HTML file.
401 The Tcl DOC Tools format can be used as intermediate format to generate
403 other formats, for example HTML:
404 # Generate the documentation in Tcl Doc Tool format
407 set dt [tepam::doc_gen::generate -format DT -header_footer tepam::doc_gen::generate]
408 # Create a new doc tools object (HTML format)
409 package require doctools
410 ::doctools::new myDoc -format html
411 # Open the HTML file, and write the HTML formatted documentation
412 set fHtml [open doc_gen.dt.html w]
413 puts $fHtml [myDoc format $dt]
414 close $fHtml
415 TEPAM::DOC_GEN::PATCH
418 While generate provides a limited number of possibilities to vary the
419 document structure, patch offers more flexibility. Multiple documenta‐
420 tions for different procedures and meta information can for example be
421 added.
422 The following listing shows how the patch command works. It defines
424 first a HTML master document string that contains 2 procedure documen‐
425 tation placeholders ({*<ProcedureName>*}). There placeholders are re‐
426 placed by patch with the generated documentation of the referred proce‐
427 dures. Since nonstandard placeholders are used, patch is called with an
428 explicit placeholder pattern definition (argument search_pattern).
429 # Define the HTML master document
432 set HtmlMasterDoc {\
433 <html>
434 <head>
435 <title>tepam::doc_gen</title>
436 <link rel="stylesheet" href="tepam_doc_stylesheet.css">
437 <meta content="documentation" name="keywords"></meta>
438 </head>
439 <body>
440 <h1>tepam::doc_gen</h1>
441 <h2>Generate</h2>
442 {*tepam::doc_gen::generate*}
443 <h2>Patch</h2>
444 {*tepam::doc_gen::patch*}
445 </body>
446 <html>\
447 }
448 # Patch the master document: This will replace the placeholders by the
449 # procedure documentation divisions:
450 tepam::doc_gen::patch -format HTML -search_pattern {\{\*(.*?)\*\}} \
451 -src_string $HtmlMasterDoc -dest_file tepam_doc_gen.html
452
455 tepam(n), tepam::procedure(n)
456
458 automatic documentation, documentation, procedure documentation
459
461 Documentation tools
462
464 Copyright (c) 2013, Andreas Drollinger
465tcllib 0.5.0 tepam::doc_gen(n)