1tepam::doc_gen(n)Tcl's Enhanced Procedure and Argument Managertepam::doc_gen(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       tepam::doc_gen - TEPAM DOC Generation, reference manual
9

SYNOPSIS

11       package require Tcl  8.3
12
13       package require tepam  0.5
14
15       package require tepam::doc_gen  ?0.1?
16
17       tepam::doc_gen::generate     ?-format     format?     ?-style    style?
18       ?-header_footer? ?-dest_file dest_file? name
19
20       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
24______________________________________________________________________________
25

DESCRIPTION

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
34       The TEPAM Doc Gen package provides the following commands:
35
36       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
48       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
61              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

ARGUMENTS

66       ?-format format?
67              Specifies the documentation format. TEPAM Doc Gen provides  sup‐
68              port for the following formats:
69
70              •      TXT - Text format (default)
71
72              •      HTML
73
74              •      POD - Perl Plain Old Documentation format (PerlPOD)
75
76              •      DT - TclLib DocTool format
77
78              Section  ADDING  SUPPORT FOR NEW DOCUMENT FORMATS shows how sup‐
79              port for additional formats can be added.
80
81       ?-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
86       ?-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
91       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
96       ?-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
102       ?-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
108       ?-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
115              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

PREDEFINED DOCUMENT FORMATS

121       TEPAM Doc Gen pre-defines the following document formats:
122
123   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
128       tepam::doc_gen::Option(TXT,MaxLineLength)
129              Default: 80
130
131              This  variable  defines the line wrapping limit (character posi‐
132              tion).
133
134   HTML - HTML FORMAT
135       TEPAM Doc Gen generates CSS styled HTML files. The  HTML  documentation
136       can be customized via the following variable:
137
138       tepam::doc_gen::Option(HTML,CssFile)
139              Default: "tepam_doc_stylesheet.css"
140
141              This variable specifies the CSS stylesheet file that is referred
142              by the generated HTML files.
143
144       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
149h1.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
153div.tepam_command_help  -  Documentation  container.  The entire
154              procedure documentation is placed inside this container.
155
156p.tepam_section_title - Section title (e.g. Name, Synopsis,  De‐
157              scription, ...)
158
159p.tepam_sub_section_title  - Sub-section title (used to separate
160              the documentation of multiple sub-procedures)
161
162p.tepam_name - Name section
163
164p.tepam_synopsis - Synopsis section
165
166p.tepam_description - Single description paragraph
167
168ul.tepam_description_list - Item of  a  HTML  bulleted/unordered
169              list inside the description section
170
171dt.tepam_argument - Item of a HTML description list used to list
172              the procedure arguments
173
174p.tepam_argument_description - Argument description paragraph
175
176p.tepam_argument_attribute - Argument attribute line
177
178pre.tepam_example - Example section
179
180   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
184   DT - TCLLIB DOCTOOLS FORMAT
185       The  documentation  is  generated in the Tcllib DocTools format if this
186       format is selected.
187

ADDING SUPPORT FOR NEW DOCUMENT FORMATS

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
193       The following documentation listing contains tokens that refer  to  the
194       different document generation procedures:
195
196                    <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
227       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
233       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
238       The following set of procedures needs to be defined to provide  support
239       for a new document format:
240
241       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
247       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
252       03 - gen($Format,Begin) {}
253              Generates the documentation prolog (preamble)
254
255       04 - gen($Format,End) {}
256              Generates the documentation epilog
257
258       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
262       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
268       30 - gen($Format,Name) {Text}
269              Generates the name section (without title). The raw section text
270              is provided as parameter.
271
272       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
277       50 - gen($Format,Description) {Text}
278              Generates  a  description  paragraph.  The raw paragraph text is
279              provided as parameter.
280
281       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
286       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
291       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
295       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
300              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
306       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
311       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
315       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
320       63 - gen($Format,ArgumentDetailBegin) {}
321              Generates the argument details prolog (preamble).
322
323       64 - gen($Format,ArgumentDetailEnd) {}
324              Generates the argument details epilog
325
326       65 - gen($Format,ArgumentDescription) {Text}
327              Generates the argument description (single paragraph).
328
329       66 - gen($Format,ArgumentAttribute) {Text}
330              Generates a single argument attribute  string.  The  command  is
331              called individually for each attribute.
332
333       70 - gen($Format,ExampleBegin) {}
334              Generates the example section prolog (preamble)
335
336       71 - gen($Format,ExampleEnd) {}
337              Generates the example section epilog
338
339       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
343       73 - gen($Format,ExampleResultLine) {Text}
344              Generates a command result line
345
346       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
351              The following parameters are provided to this procedure:
352
353              Name   Name of the argument
354
355              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
361                     gen(TXT,ArgumentString) mtype 1 0 string -> "[mtype]"
362
363              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
368                     gen(TXT,ArgumentString) mtype 0 1 string -> "-mtype <mtype>"
369
370                     Named arguments can also be optional:
371
372                     gen(TXT,ArgumentString) mtype 1 1 string -> "[-mtype <mtype>]"
373
374              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
378                     gen(TXT,ArgumentString) close 1 1 none -> "[-close]"
379

EXAMPLES

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
386              tepam::doc_gen::generate tepam::doc_gen::generate
387       The next example generates the documentation in HTML format:
388
389              tepam::doc_gen::generate -format HTML tepam::doc_gen::generate
390       The flag ?header_footer? adds also the file header and footer:
391
392              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
396              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
402       The Tcl DOC Tools format can be used as intermediate format to generate
403       other formats, for example HTML:
404
405
406              # 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
416
417   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
423       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
430
431              # 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
453

SEE ALSO

455       tepam(n), tepam::procedure(n)
456

KEYWORDS

458       automatic documentation, documentation, procedure documentation
459

CATEGORY

461       Documentation tools
462
464       Copyright (c) 2013, Andreas Drollinger
465
466
467
468
469tcllib                               0.5.0                   tepam::doc_gen(n)
Impressum