1dtplite(n)                   Documentation toolbox                  dtplite(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       dtplite - Lightweight DocTools Markup Processor
9

SYNOPSIS

11       package require dtplite  ?1.3?
12
13       dtplite -o output ?options? format inputfile
14
15       dtplite validate inputfile
16
17       dtplite -o output ?options? format inputdirectory
18
19       dtplite -merge -o output ?options? format inputdirectory
20
21______________________________________________________________________________
22

DESCRIPTION

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
30       dtplite  is based upon the package doctools, like the other two proces‐
31       sors.
32
33   USE CASES
34       dtplite was written with the following three use cases in mind.
35
36       [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
42       [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
46       [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
50       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
56       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
62   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
67              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
73                     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
80              (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
86              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
91
92       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
98       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
105              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
109       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
113              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
121   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
126       -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
132       -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
140              When used multiple times only the last definition is relevant.
141
142       -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
152              When used multiple times only the last definition is relevant.
153
154       -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
159              When used multiple times only the last definition is relevant.
160
161       -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
169              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
175              When used multiple times only the last definition is relevant.
176
177       -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
181              When used multiple times only the last definition is relevant.
182
183       -pre+toc label path|text
184
185       -post+toc label path|text
186              This  option specifies additional doctoc files (or texts) to use
187              in the navigation bar.
188
189              Positioning and handling of multiple uses is  like  for  options
190              -prenav and -postnav, see below.
191
192       -nav label url
193
194       -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
202              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
206              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
210       -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
218              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
222              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
226   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
232       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
238       List of predefined formats, i.e. as provided by the package doctools:
239
240       nroff  The processor generates *roff output, the  standard  format  for
241              unix manpages.
242
243       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
248       tmml   The processor generates TMML output, the Tcl Manpage Markup Lan‐
249              guage, a derivative of XML.
250
251       latex  The processor generates LaTeX output.
252
253       wiki   The processor generates Wiki markup as understood by wikit.
254
255       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
260       null   The processor does not generate any output. This  is  equivalent
261              to validate.
262
263   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
269       [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
274
275                  output/
276                      toc.html
277                      index.html
278                      files/
279                          path/to/FOO.html
280
281
282              The  last line in the example shows the document generated for a
283              file FOO located at
284
285
286                  inputdirectory/path/to/FOO
287
288
289       [3]    When merging many packages into a unified set of  documents  the
290              generated directory structure is a bit deeper:
291
292
293                  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
308
309              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
314              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
320              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

BUGS, IDEAS, FEEDBACK

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
334       When proposing code changes, please provide unified diffs, i.e the out‐
335       put of diff -u.
336
337       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

SEE ALSO

343       docidx introduction, doctoc introduction, doctools introduction
344

KEYWORDS

346       HTML,  TMML,  conversion,  docidx,  doctoc,  doctools, manpage, markup,
347       nroff
348

CATEGORY

350       Documentation tools
351
353       Copyright (c) 2004-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>
354
355
356
357
358tcllib                                1.3                           dtplite(n)
Impressum