1dtplite(n) Documentation toolbox dtplite(n)
2______________________________________________________________________________
6
8 dtplite - Lightweight DocTools Markup Processor
9
11 package require dtplite ?1.3?
12 dtplite -o output ?options? format inputfile
14 dtplite validate inputfile
16 dtplite -o output ?options? format inputdirectory
18 dtplite -merge -o output ?options? format inputdirectory
20______________________________________________________________________________
22
24 The application described by this document, dtplite, is the successor
25 to the extremely simple mpexpand. Influenced in its functionality by
26 the dtp doctools processor it is much more powerful than mpexpand, yet
27 still as easy to use; definitely easier than dtp with its myriad of
28 subcommands and options.
29 dtplite is based upon the package doctools, like the other two proces‐
31 sors.
32 USE CASES
34 dtplite was written with the following three use cases in mind.
35 [1] Validation of a single document, i.e. checking that it was writ‐
37 ten in valid doctools format. This mode can also be used to get
38 a preliminary version of the formatted output for a single docu‐
39 ment, for display in a browser, nroff, etc., allowing proofread‐
40 ing of the formatting.
41 [2] Generation of the formatted documentation for a single package,
43 i.e. all the manpages, plus a table of contents and an index of
44 keywords.
45 [3] An extension of the previous mode of operation, a method for the
47 easy generation of one documentation tree for several packages,
48 and especially of a unified table of contents and keyword index.
49 Beyond the above we also want to make use of the customization features
51 provided by the HTML formatter. It is not the only format the applica‐
52 tion should be able to generate, but we anticipiate it to be the most
53 commonly used, and it is one of the few which do provide customization
54 hooks.
55 We allow the caller to specify a header string, footer string, a
57 stylesheet, and data for a bar of navigation links at the top of the
58 generated document. While all can be set as long as the formatting
59 engine provides an appropriate engine parameter (See section OPTIONS)
60 the last two have internal processing which make them specific to HTML.
61 COMMAND LINE
63 dtplite -o output ?options? format inputfile
64 This is the form for use case [1]. The options will be explained
65 later, in section OPTIONS.
66 path output (in)
68 This argument specifies where to write the generated doc‐
69 ument. It can be the path to a file or directory, or -.
70 The last value causes the application to write the gener‐
71 ated documented to stdout.
72 If the output does not exist then [file dirname $output]
74 has to exist and must be a writable directory. The gen‐
75 erated document will be written to a file in that direc‐
76 tory, and the name of that file will be derived from the
77 inputfile, the format, and the value given to option -ext
78 (if present).
79 (path|handle) format (in)
81 This argument specifies the formatting engine to use when
82 processing the input, and thus the format of the gener‐
83 ated document. See section FORMATS for the possibilities
84 recognized by the application.
85 path inputfile (in)
87 This argument specifies the path to the file to process.
88 It has to exist, must be readable, and written in doc‐
89 tools format.
90 dtplite validate inputfile
93 This is a simpler form for use case [1]. The "validate" format
94 generates no output at all, only syntax checks are performed. As
95 such the specification of an output file or other options is not
96 necessary and left out.
97 dtplite -o output ?options? format inputdirectory
99 This is the form for use case [2]. It differs from the form for
100 use case [1] by having the input documents specified through a
101 directory instead of a file. The other arguments are identical,
102 except for output, which now has to be the path to an existing
103 and writable directory.
104 The input documents are all files in inputdirectory or any of
106 its subdirectories which were recognized by fileutil::fileType
107 as containing text in doctools format.
108 dtplite -merge -o output ?options? format inputdirectory
110 This is the form for use case [3]. The only difference to the
111 form for use case [2] is the additional option -merge.
112 Each such call will merge the generated documents coming from
114 processing the input documents under inputdirectory or any of
115 its subdirectories to the files under output. In this manner it
116 is possible to incrementally build the unified documentation for
117 any number of packages. Note that it is necessary to run through
118 all the packages twice to get fully correct cross-references
119 (for formats supporting them).
120 OPTIONS
122 This section describes all the options available to the user of the
123 application, with the exception of the options -o and -merge. These two
124 were described already, in section COMMAND LINE.
125 -exclude string
127 This option specifies an exclude (glob) pattern. Any files iden‐
128 tified as manpages to process which match the exclude pattern
129 are ignored. The option can be provided multiple times, each
130 usage adding an additional pattern to the list of exclusions.
131 -ext string
133 If the name of an output file has to be derived from the name of
134 an input file it will use the name of the format as the exten‐
135 sion by default. This option here will override this however,
136 forcing it to use string as the file extension. This option is
137 ignored if the name of the output file is fully specified
138 through option -o.
139 When used multiple times only the last definition is relevant.
141 -header file
143 This option can be used if and only if the selected format pro‐
144 vides an engine parameter named "header". It takes the contents
145 of the specified file and assign them to that parameter, for
146 whatever use by the engine. The HTML engine will insert the text
147 just after the tag <body>. If navigation buttons are present
148 (see option -nav below), then the HTML generated for them is
149 appended to the header data originating here before the final
150 assignment to the parameter.
151 When used multiple times only the last definition is relevant.
153 -footer file
155 Like -header, except that: Any navigation buttons are ignored,
156 the corresponding required engine parameter is named "footer",
157 and the data is inserted just before the tag </body>.
158 When used multiple times only the last definition is relevant.
160 -style file
162 This option can be used if and only if the selected format pro‐
163 vides an engine parameter named "meta". When specified it will
164 generate a piece of HTML code declaring the file as the
165 stylesheet for the generated document and assign that to the
166 parameter. The HTML engine will insert this inot the document,
167 just after the tag <head>.
168 When processing an input directory the stylesheet file is copied
170 into the output directory and the generated HTML will refer to
171 the copy, to make the result more self-contained. When process‐
172 ing an input file we have no location to copy the stylesheet to
173 and so just reference it as specified.
174 When used multiple times only the last definition is relevant.
176 -toc path|text
178 This option specifies a doctoc file (or text) to use for the ta‐
179 ble of contents instead of generating our own.
180 When used multiple times only the last definition is relevant.
182 -pre+toc label path|text
184 -post+toc label path|text
186 This option specifies additional doctoc files (or texts) to use
187 in the navigation bar.
188 Positioning and handling of multiple uses is like for options
190 -prenav and -postnav, see below.
191 -nav label url
193 -prenav label url
195 Use this option to specify a navigation button with label to
196 display and the url to link to. This option can be used if and
197 only if the selected format provides an engine parameter named
198 "header". The HTML generated for this is appended to whatever
199 data we got from option -header before it is inserted into the
200 generated documents.
201 When used multiple times all definitions are collected and a
203 navigation bar is created, with the first definition shown at
204 the left edge and the last definition to the right.
205 The url can be relative. In that case it is assumed to be rela‐
207 tive to the main files (TOC and Keyword index), and will be
208 transformed for all others to still link properly.
209 -postnav label url
211 Use this option to specify a navigation button with label to
212 display and the url to link to. This option can be used if and
213 only if the selected format provides an engine parameter named
214 "header". The HTML generated for this is appended to whatever
215 data we got from option -header before it is inserted into the
216 generated documents.
217 When used multiple times all definitions are collected and a
219 navigation bar is created, with the last definition shown at the
220 right edge and the first definition to the left.
221 The url can be relative. In that case it is assumed to be rela‐
223 tive to the main files (TOC and Keyword index), and will be
224 transformed for all others to still link properly.
225 FORMATS
227 At first the format argument will be treated as a path to a tcl file
228 containing the code for the requested formatting engine. The argument
229 will be treated as the name of one of the predefined formats listed
230 below if and only if the path does not exist.
231 Note a limitation: If treating the format as path to the tcl script
233 implementing the engine was sucessful, then this script has to imple‐
234 ment not only the engine API for doctools, i.e. doctools_api, but for
235 doctoc_api and docidx_api as well. Otherwise the generation of a table
236 of contents and of a keyword index will fail.
237 List of predefined formats, i.e. as provided by the package doctools:
239 nroff The processor generates *roff output, the standard format for
241 unix manpages.
242 html The processor generates HTML output, for usage in and display by
244 web browsers. This engine is currently the only one providing
245 the various engine parameters required for the additional cus‐
246 tomaization of the output.
247 tmml The processor generates TMML output, the Tcl Manpage Markup Lan‐
249 guage, a derivative of XML.
250 latex The processor generates LaTeX output.
252 wiki The processor generates Wiki markup as understood by wikit.
254 list The processor extracts the information provided by man‐
256 page_begin. This format is used internally to extract the meta
257 data from which both table of contents and keyword index are
258 derived from.
259 null The processor does not generate any output. This is equivalent
261 to validate.
262 DIRECTORY STRUCTURES
264 In this section we describe the directory structures generated by the
265 application under output when processing all documents in an inputdi‐
266 rectory. In other words, this is only relevant to the use cases [2] and
267 [3].
268 [2] The following directory structure is created when processing a
270 single set of input documents. The file extension used is for
271 output in HTML, but that is not relevant to the structure and
272 was just used to have proper file names.
273 output/
276 toc.html
277 index.html
278 files/
279 path/to/FOO.html
280 The last line in the example shows the document generated for a
283 file FOO located at
284 inputdirectory/path/to/FOO
287 [3] When merging many packages into a unified set of documents the
290 generated directory structure is a bit deeper:
291 output
294 .toc
295 .idx
296 .tocdoc
297 .idxdoc
298 .xrf
299 toc.html
300 index.html
301 FOO1/
302 ...
303 FOO2/
304 toc.html
305 files/
306 path/to/BAR.html
307 Each of the directories FOO1, ... contains the documents gener‐
310 ated for the package FOO1, ... and follows the structure shown
311 for use case [2]. The only exception is that there is no per-
312 package index.
313 The files ".toc", ".idx", and ".xrf" contain the internal status
315 of the whole output and will be read and updated by the next
316 invokation. Their contents will not be documented. Remove these
317 files when all packages wanted for the output have been pro‐
318 cessed, i.e. when the output is complete.
319 The files ".tocdoc", and ".idxdoc", are intermediate files in
321 doctoc and docidx markup, respectively, containing the main ta‐
322 ble of contents and keyword index for the set of documents
323 before their conversion to the chosen output format. They are
324 left in place, i.e. not deleted, to serve as demonstrations of
325 doctoc and docidx markup.
326
328 This document, and the package it describes, will undoubtedly contain
329 bugs and other problems. Please report such in the category doctools
330 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
331 also report any ideas for enhancements you may have for either package
332 and/or documentation.
333 When proposing code changes, please provide unified diffs, i.e the out‐
335 put of diff -u.
336 Note further that attachments are strongly preferred over inlined
338 patches. Attachments can be made by going to the Edit form of the
339 ticket immediately after its creation, and then using the left-most
340 button in the secondary navigation bar.
341
343 docidx introduction, doctoc introduction, doctools introduction
344
346 HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup,
347 nroff
348
350 Documentation tools
351
353 Copyright (c) 2004-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>
354tcllib 1.3 dtplite(n)