1dtplite(n) dtplite(n)
2______________________________________________________________________________
6
8 dtplite - Lightweight DocTools Markup Processor
9
11 dtplite -o output ?options? format inputfile
12 dtplite -o output ?options? format inputdirectory
14 dtplite -merge -o output ?options? format inputdirectory
16_________________________________________________________________
18
20 The application described by this document, dtplite, is the successor
21 to the extremely simple mpexpand. Influenced in its functionality by
22 the dtp doctools processor it is much more powerful than mpexpand, yet
23 still as easy to use; definitely easier than dtp with its myriad of
24 subcommands and options.
25 dtplite is based upon the package doctools, like the other two proces‐
27 sors .
28 USE CASES
30 dtplite was written with the following three use cases in mind.
31 [1] Validation of a single document, i.e. checking that it was writ‐
33 ten in valid doctools format. This mode can also be used to get
34 a preliminary version of the formatted output for a single docu‐
35 ment, for display in a browser, nroff, etc., allowing proofread‐
36 ing of the formatting.
37 [2] Generation of the formatted documentation for a single package,
39 i.e. all the manpages, plus a table of contents and an index of
40 keywords.
41 [3] An extension of the previous mode of operation, a method for the
43 easy generation of one documentation tree for several packages.
44 Especially unified table of contents and keyword index.
45 Beyond the above we also want to make use of the customization features
47 provided by the HTML formatter. It is not the only format the applica‐
48 tion should be able to generate, but we anticipiate it to be the most
49 commonly used, and it is one of the few which do provide customization
50 hooks.
51 We allow the caller to specify a header string, footer string, a
53 stylesheet, and data for a bar of navigation links at the top of the
54 generated document. While all can be set as long as the formatting
55 engine provides an appropriate engine parameter (See section OPTIONS)
56 the last two have internal processing which make them specific to HTML.
57 COMMAND LINE
59 dtplite -o output ?options? format inputfile
60 This is the form for use case [1]. The options will be explained
61 later, in section OPTIONS.
62 output path (in)
64 This argument specifies where to write the generated doc‐
65 ument. It can be the path to a file or directory, or -.
66 The last value causes the application to write the gener‐
67 ated documented to stdout.
68 If the output does not exist then [file dirname $output]
70 has to exist and must be a writable directory. The gen‐
71 erated document will be written to a file in that direc‐
72 tory, and the name of that file will be derived from the
73 inputfile, the format, and the value given to option -ext
74 (if present).
75 format (path|handle) (in)
77 This argument specifies the formatting engine to use when
78 processing the input, and thus the format of the gener‐
79 ated document. See section FORMATS for the possibilities
80 recognized by the application.
81 inputfile path (in)
83 This argument specifies the path to the file to process.
84 It has to exist, must be readable, and written in doc‐
85 tools format.
86 dtplite -o output ?options? format inputdirectory
89 This is the form for use case [2]. It differs from the form for
90 use case [1] by having the input documents specified through a
91 directory instead of a file. The other arguments are identical,
92 except for output, which now has to be the path to an existing
93 and writable directory.
94 The input documents are all files in inputdirectory or any of
96 its subdirectories which were recognized by fileutil::fileType
97 as containing text in doctools format.
98 dtplite -merge -o output ?options? format inputdirectory
100 This is the form for use case [3]. The only difference to the
101 form for use case [2] is the additional option -merge.
102 Each such call will merge the generated documents coming from
104 processing the input documents under inputdirectory or any of
105 its subdirectories to the files under output. In this manner it
106 is possible to incrementally build the unified documentation for
107 any number of packages. Note that it is necessary to run through
108 all the packages twice to get fully correct cross-references
109 (for formats supporting them).
110 OPTIONS
112 This section describes all the options available to the user of the
113 application, with the exception of the options -o and -merge. These two
114 were described already, in section COMMAND LINE.
115 -ext string
117 If the name of an output file has to be derived from the name of
118 an input file it will use the name of the format as the exten‐
119 sion by default. This option here will override this however,
120 forcing it to use string as the file extension. This option is
121 ignored if the name of the output file is fully specified
122 through option -o.
123 When used multiple times only the last definition is relevant.
125 -header file
127 This option can be used if and only if the selected format pro‐
128 vides an engine parameter named "header". It takes the contents
129 of the specified file and assign them to that parameter, for
130 whatever use by the engine. The HTML engine will insert the text
131 just after the tag <body>. If navigation buttons are present
132 (see option -nav below), then the HTML generated for them is
133 appended to the header data originating here before the final
134 assignment to the parameter.
135 When used multiple times only the last definition is relevant.
137 -footer file
139 Like -header, except that: Any navigation buttons are ignored,
140 the corresponding required engine parameter is named "footer",
141 and the data is inserted just before the tag </body>.
142 When used multiple times only the last definition is relevant.
144 -style file
146 This option can be used if and only if the selected format pro‐
147 vides an engine parameter named "meta". When specified it will
148 generate a piece of HTML code declaring the file as the
149 stylesheet for the generated document and assign that to the
150 parameter. The HTML engine will insert this inot the document,
151 just after the tag <head>.
152 When processing an input directory the stylesheet file is copied
154 into the output directory and the generated HTML will refer to
155 the copy, to make the result more self-contained. When process‐
156 ing an input file we have no location to copy the stylesheet to
157 and so just reference it as specified.
158 When used multiple times only the last definition is relevant.
160 -nav label url
162 Use this option to specify a navigation button with label to
163 display and the url to link to. This option can be used if and
164 only if the selected format provides an engine parameter named
165 "header". The HTML generated for this is appended to whatever
166 data we got from option -header before it is inserted into the
167 generated documents.
168 When used multiple times all definitions are collected and a
170 navigation bar is created, with the first definition shown at
171 the left edge and the last definition to the right.
172 FORMATS
174 At first the format argument will be treated as a path to a tcl file
175 containing the code for the requested formatting engine. The argument
176 will be treated as the name of one of the predefined formats listed
177 below if and only if the path does not exist.
178 Note a limitation: If treating the format as path to the tcl script
180 implementing the engine was sucessful, then this script has to imple‐
181 ment not only the engine API for doctools, i.e. doctools_api, but for
182 doctoc_api and docidx_api as well. Otherwise the generation of a table
183 of contents and of a keyword index will fail.
184 List of predefined formats, i.e. as provided by the package doctools:
186 nroff The processor generates *roff output, the standard format for
188 unix manpages.
189 html The processor generates HTML output, for usage in and display by
191 web browsers. This engine is currently the only one providing
192 the various engine parameters required for the additional cus‐
193 tomaization of the output.
194 tmml The processor generates TMML output, the Tcl Manpage Markup Lan‐
196 guage, a derivative of XML.
197 latex The processor generates LaTeX output.
199 wiki The processor generates Wiki markup as understood by wikit.
201 list The processor extracts the information provided by man‐
203 page_begin. This format is used internally to extract the meta
204 data from which both table of contents and keyword index are
205 derived from.
206 null The processor does not generate any output.
208 DIRECTORY STRUCTURES
210 In this section we describe the directory structures generated by the
211 application under output when processing all documents in an inputdi‐
212 rectory. In other words, this is only relevant to the use cases [2] and
213 [3].
214 [2] The following directory structure is created when processing a
216 single set of input documents. The file extension used is for
217 output in HTML, but that is not relevant to the structure and
218 was just used to have proper file names.
219 output/
221 toc.html
222 index.html
223 files/
224 path/to/FOO.html
225 The last line in the example shows the document generated for a
227 file FOO located at
228 inputdirectory/path/to/FOO
230 [3] When merging many packages into a unified set of documents the
233 generated directory structure is a bit deeper:
234 output
236 .toc
237 .idx
238 .xrf
239 toc.html
240 index.html
241 FOO1/
242 ...
243 FOO2/
244 toc.html
245 files/
246 path/to/BAR.html
247 Each of the directories FOO1, ... contains the documents gener‐
249 ated for the package FOO1, ... and follows the structure shown
250 for use case [2]. The only exception is that there is no per-
251 package index.
252 The files ".toc", ".idx", and ".xrf" contain the internal status
254 of the whole output and will be read and updated by the next
255 invokation. Their contents will not be documented. Remove these
256 files when all packages wanted for the output have been pro‐
257 cessed, i.e. when the output is complete.
258
260 docidx_api, docidx_fmt, doctoc_api, doctoc_fmt, doctools_api, doc‐
261 tools_fmt
262
264 HTML, TMML, conversion, doctools, manpage, markup, nroff
265
267 Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
268Documentation toolbox 1.0 dtplite(n)