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