1docstrip_util(n) Literate programming tool docstrip_util(n)
2______________________________________________________________________________
6
8 docstrip_util - Docstrip-related utilities
9
11 package require Tcl 8.4
12 package require docstrip::util ?1.2?
14 docstrip::util::ddt2man text
16 docstrip::util::guards subcmd text
18 docstrip::util::thefile filename ?option value ...?
20_________________________________________________________________
22
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
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 comment and metacomment lines
36 The '%' and '%%' prefixes are removed, the rest of the
37 text is kept as it is.
38 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 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 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 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 % [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 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 It is suggested that master source code files with doctools markup are
96 given the suffix ".ddt", hence the "ddt" in ddt2man.
97 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 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 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 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 expressions
120 List the guard expressions. The return value is a list,
121 with the elements in no particular order.
122 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 names List the guard expression terminals. The return value is
134 a list, with the elements in no particular order.
135 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 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
148 docstrip, doctools, doctools_fmt
149
152 Copyright (c) 2003-2005 Lars Hellström <Lars dot Hellstrom at residenset dot net>
153docstrip 1.2 docstrip_util(n)