1tcldocstrip(n) Textprocessing toolbox tcldocstrip(n)
2______________________________________________________________________________
6
8 tcldocstrip - Tcl-based Docstrip Processor
9
11 tcldocstrip output ?options? input ?guards?
12 tcldocstrip ?options? output (?options? input guards)...
14 tcldocstrip -guards input
16______________________________________________________________________________
18
20 The application described by this document, tcldocstrip, is a relative
21 of docstrip, a simple literate programming tool for LaTeX.
22 tcldocstrip is based upon the package docstrip.
24 USE CASES
26 tcldocstrip was written with the following three use cases in mind.
27 [1] Conversion of a single input file according to the listed guards
29 into the stripped output. This handles the most simple case of a
30 set of guards specifying a single document found in a single
31 input file.
32 [2] Stitching, or the assembly of an output from several sets of
34 guards, in a specific order, and possibly from different files.
35 This is the second common case. One document spread over several
36 inputs, and/or spread over different guard sets.
37 [3] Extraction and listing of all the unique guard expressions and
39 guards used within a document to help a person which did not
40 author the document in question in familiarizing itself with it.
41 COMMAND LINE
43 tcldocstrip output ?options? input ?guards?
44 This is the form for use case [1]. It converts the input file
45 according to the specified guards and options. The result is
46 written to the named output file. Usage of the string - as the
47 name of the output signals that the result should be written to
48 stdout. The guards are document-specific and have to be known to
49 the caller. The options will be explained later, in section
50 OPTIONS.
51 path output (in)
53 This argument specifies where to write the generated doc‐
54 ument. It can be the path to a file or directory, or -.
55 The last value causes the application to write the gener‐
56 ated documented to stdout.
57 If the output does not exist then [file dirname $output]
59 has to exist and must be a writable directory.
60 path inputfile (in)
62 This argument specifies the path to the file to process.
63 It has to exist, must be readable, and written in doc‐
64 strip format.
65 tcldocstrip ?options? output (?options? input guards)...
68 This is the form for use case [2]. It differs from the form for
69 use case [1] by the possibility of having options before the
70 output file, which apply in general, and specifying more than
71 one inputfile, each with its own set of input specific options
72 and guards.
73 It extracts data from the various input files, according to the
75 specified options and guards, and writes the result to the given
76 output, in the order of their specification on the command line.
77 Options specified before the output are global settings, whereas
78 the options specified before each input are valid only just for
79 this input file. Unspecified values are taken from the global
80 settings, or defaults. As for form [1] using the string - as
81 output causes the application to write to stdout. Using the
82 string . for an input file signals that the last input file
83 should be used again. This enables the assembly of the output
84 from one input file using multiple and different sets of guards,
85 without having to specify the full name of the file every time.
86 tcldocstrip -guards input
88 This is the form for use case [3]. It determines the guards,
89 and unique guard expressions used within the provided input doc‐
90 ument. The found strings are written to stdout, one string per
91 line.
92 OPTIONS
94 This section describes all the options available to the user of the
95 application, with the exception of the option -guards. This option was
96 described already, in section COMMAND LINE.
97 -metaprefix string
99 This option is inherited from the command docstrip::extract pro‐
100 vided by the package docstrip.
101 It specifies the string by which the '%%' prefix of a metacom‐
103 ment line will be replaced. Defaults to '%%'. For Tcl code this
104 would typically be '#'.
105 -onerror mode
107 This option is inherited from the command docstrip::extract pro‐
108 vided by the package docstrip.
109 It controls what will be done when a format error in the text
111 being processed is detected. The settings are:
112 ignore Just ignore the error; continue as if nothing happened.
114 puts Write an error message to stderr, then continue process‐
116 ing.
117 throw Throw an error. ::errorCode is set to a list whose first
119 element is DOCSTRIP, second element is the type of error,
120 and third element is the line number where the error is
121 detected. This is the default.
122 -trimlines bool
124 This option is inherited from the command docstrip::extract pro‐
125 vided by the package docstrip.
126 Controls whether spaces at the end of a line should be trimmed
128 away before the line is processed. Defaults to true.
129 -preamble text
131 -postamble text
133 -nopreamble
135 -nopostamble
137 The -no*amble options deactivate file pre- and postambles alto‐
138 gether, whereas the -*amble options specify the user part of the
139 file pre- and postambles. This part can be empty, in that case
140 only the standard parts are shown. This is the default.
141 Preambles, when active, are written before the actual content of
143 a generated file. In the same manner postambles are, when
144 active, written after the actual content of a generated file.
145
147 This document, and the package it describes, will undoubtedly contain
148 bugs and other problems. Please report such in the category docstrip
149 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
150 also report any ideas for enhancements you may have for either package
151 and/or documentation.
152 When proposing code changes, please provide unified diffs, i.e the out‐
154 put of diff -u.
155 Note further that attachments are strongly preferred over inlined
157 patches. Attachments can be made by going to the Edit form of the
158 ticket immediately after its creation, and then using the left-most
159 button in the secondary navigation bar.
160
162 docstrip
163
165 \.dtx, LaTeX, conversion, docstrip, documentation, literate program‐
166 ming, markup, source
167
169 Documentation tools
170
172 Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net>
173tcllib 1.0 tcldocstrip(n)