1docstrip_util(n)           Literate programming tool          docstrip_util(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       docstrip_util - Docstrip-related utilities
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require docstrip::util  ?1.2?
14
15       docstrip::util::ddt2man text
16
17       docstrip::util::guards subcmd text
18
19       docstrip::util::thefile filename ?option value ...?
20
21_________________________________________________________________
22

DESCRIPTION

24       The docstrip::util package is meant for collecting various utility pro‐
25       cedures that may be useful for developers who make use of the  docstrip
26       package in some projects. It is separate from the main package to avoid
27       overhead for end-users.
28

Commands

30       docstrip::util::ddt2man text
31              The ddt2man command reformats text  from  the  general  docstrip
32              format  to  doctools ".man" format (Tcl Markup Language for Man‐
33              pages). The different line types are treated as follows:
34
35              comment and metacomment lines
36                     The '%' and '%%' prefixes are removed, the  rest  of  the
37                     text is kept as it is.
38
39              empty lines
40                     These  are kept as they are. (Effectively this means that
41                     they will count as comment lines after a comment line and
42                     as code lines after a code line.)
43
44              code lines
45                     example_begin  and example_end commands are placed at the
46                     beginning and end of  every  block  of  consecutive  code
47                     lines. Brackets in a code line are converted to lb and rb
48                     commands.
49
50              verbatim guards
51                     These are processed as usual, so they do not show  up  in
52                     the  result but every line in a verbatim block is treated
53                     as a code line.
54
55              other guards
56                     These are treated as code lines, except that  the  actual
57                     guard is emphasised.
58       At the time of writing, no project has employed doctools markup in mas‐
59       ter source files, so experience of what works well is not available.  A
60       source file could however look as follows
61
62          % [manpage_begin gcd n 1.0]
63          % [moddesc {Greatest Common Divisor}]
64          % [require gcd [opt 1.0]]
65          % [description]
66          %
67          % [list_begin definitions]
68          % [call [cmd gcd] [arg a] [arg b]]
69          %   The [cmd gcd] procedure takes two arguments [arg a] and [arg b] which
70          %   must be integers and returns their greatest common divisor.
71          proc gcd {a b} {
72          %   The first step is to take the absolute values of the arguments.
73          %   This relieves us of having to worry about how signs will be treated
74          %   by the remainder operation.
75             set a [expr {abs($a)}]
76             set b [expr {abs($b)}]
77          %   The next line does all of Euclid's algorithm! We can make do
78          %   without a temporary variable, since $a is substituted before the
79          %   [lb]set a $b[rb] and thus continues to hold a reference to the
80          %   "old" value of [var a].
81             while {$b>0} { set b [expr { $a % [set a $b] }] }
82          %   In Tcl 8.3 we might want to use [cmd set] instead of [cmd return]
83          %   to get the slight advantage of byte-compilation.
84          %<tcl83>  set a
85          %<!tcl83>   return $a
86          }
87          % [list_end]
88          %
89          % [manpage_end]
90
91       If  the  above  text  is  (suitably  unindented  and)  fed through doc‐
92       strip::util::ddt2man then the result will be  a  syntactically  correct
93       doctools manpage, even though its purpose is a bit different.
94
95       It  is suggested that master source code files with doctools markup are
96       given the suffix ".ddt", hence the "ddt" in ddt2man.
97
98       docstrip::util::guards subcmd text
99              The guards command returns information (mostly of a  statistical
100              nature)  about  the  ordinary  docstrip guards that occur in the
101              text. The subcmd selects what is returned.
102
103              counts List the guard expression terminals with counts. The for‐
104                     mat  of  the  return value is a dictionary which maps the
105                     terminal name to the number of occurencies of it  in  the
106                     file.
107
108              exprcount
109                     List the guard expressions with counts. The format of the
110                     return value is a dictionary which maps the expression to
111                     the number of occurencies of it in the file.
112
113              exprerr
114                     List  the syntactically incorrect guard expressions (e.g.
115                     parentheses do not match, or a terminal is missing).  The
116                     return  value is a list, with the elements in no particu‐
117                     lar order.
118
119              expressions
120                     List the guard expressions. The return value is  a  list,
121                     with the elements in no particular order.
122
123              exprmods
124                     List  the guard expressions with modifiers. The format of
125                     the return value is a dictionary where each  index  is  a
126                     guard  expression  and  each  entry  is a string with one
127                     character for every guard line that has this  expression.
128                     The  characters  in  the  entry specify what modifier was
129                     used in that line: +, -, *, /, or (for guard without mod‐
130                     ifier:)  space.  This  is  the most primitive form of the
131                     information gathered by guards.
132
133              names  List the guard expression terminals. The return value  is
134                     a list, with the elements in no particular order.
135
136              rotten List  the  malformed  guard  lines (this does not include
137                     lines where only the expression  is  malformed,  though).
138                     The format of the return value is a dictionary which maps
139                     line numbers to their contents.
140
141       docstrip::util::thefile filename ?option value ...?
142              The thefile command opens the file filename, reads  it  to  end,
143              closes  it, and returns the contents. The option-value pairs are
144              passed on to fconfigure  to  configure  the  open  file  channel
145              before anything is read from it.
146

SEE ALSO

148       docstrip, doctools, doctools_fmt
149

KEYWORDS

152       Copyright (c) 2003-2005 Lars Hellström <Lars dot Hellstrom at residenset dot net>
153
154
155
156
157docstrip                              1.2                     docstrip_util(n)
Impressum