dtplite(n)                                                          dtplite(n)



______________________________________________________________________________

NAME
       dtplite - Lightweight DocTools Markup Processor

SYNOPSIS
       dtplite -o output ?options? format inputfile

       dtplite validate inputfile

       dtplite -o output ?options? format inputdirectory

       dtplite -merge -o output ?options? format inputdirectory

_________________________________________________________________

DESCRIPTION
       The application described by this document, dtplite, is the successor
       to the extremely simple mpexpand. Influenced in its functionality by
       the dtp doctools processor it is much more powerful than mpexpand, yet
       still as easy to use; definitely easier than dtp with its myriad of
       subcommands and options.

       dtplite is based upon the package doctools, like the other two
       processors.

   USE CASES
       dtplite was written with the following three use cases in mind.

       [1]    Validation of a single document, i.e. checking that it was
              written in valid doctools format. This mode can also be used to
              get a preliminary version of the formatted output for a single
              document, for display in a browser, nroff, etc., allowing
              proofreading of the formatting.

       [2]    Generation of the formatted documentation for a single package,
              i.e. all the manpages, plus a table of contents and an index of
              keywords.

       [3]    An extension of the previous mode of operation, a method for the
              easy generation of one documentation tree for several packages,
              and especially of a unified table of contents and keyword index.

       Beyond the above we also want to make use of the customization features
       provided by the HTML formatter. It is not the only format the
       application should be able to generate, but we anticipiate it to be the
       most commonly used, and it is one of the few which do provide
       customization hooks.

       We allow the caller to specify a header string, footer string, a
       stylesheet, and data for a bar of navigation links at the top of the
       generated document.  While all can be set as long as the formatting
       engine provides an appropriate engine parameter (See section OPTIONS)
       the last two have internal processing which make them specific to HTML.

   COMMAND LINE
       dtplite -o output ?options? format inputfile
              This is the form for use case [1]. The options will be explained
              later, in section OPTIONS.

              path output (in)
                     This argument specifies where to write the generated
                     document. It can be the path to a file or directory, or
                     -.  The last value causes the application to write the
                     generated documented to stdout.

                     If the output does not exist then [file dirname $output]
                     has to exist and must be a writable directory.  The
                     generated document will be written to a file in that
                     directory, and the name of that file will be derived from
                     the inputfile, the format, and the value given to option
                     -ext (if present).

              (path|handle) format (in)
                     This argument specifies the formatting engine to use when
                     processing the input, and thus the format of the
                     generated document. See section FORMATS for the
                     possibilities recognized by the application.

              path inputfile (in)
                     This argument specifies the path to the file to process.
                     It has to exist, must be readable, and written in
                     doctools format.


       dtplite validate inputfile
              This is a simpler form for use case [1]. The "validate" format
              generates no output at all, only syntax checks are performed. As
              such the specification of an output file or other options is not
              necessary and left out.

       dtplite -o output ?options? format inputdirectory
              This is the form for use case [2]. It differs from the form for
              use case [1] by having the input documents specified through a
              directory instead of a file. The other arguments are identical,
              except for output, which now has to be the path to an existing
              and writable directory.

              The input documents are all files in inputdirectory or any of
              its subdirectories which were recognized by fileutil::fileType
              as containing text in doctools format.

       dtplite -merge -o output ?options? format inputdirectory
              This is the form for use case [3]. The only difference to the
              form for use case [2] is the additional option -merge.

              Each such call will merge the generated documents coming from
              processing the input documents under inputdirectory or any of
              its subdirectories to the files under output. In this manner it
              is possible to incrementally build the unified documentation for
              any number of packages. Note that it is necessary to run through
              all the packages twice to get fully correct cross-references
              (for formats supporting them).

   OPTIONS
       This section describes all the options available to the user of the
       application, with the exception of the options -o and -merge. These two
       were described already, in section COMMAND LINE.

       -exclude string
              This option specifies an exclude (glob) pattern. Any files
              identified as manpages to process which match the exclude
              pattern are ignored. The option can be provided multiple times,
              each usage adding an additional pattern to the list of
              exclusions.

       -ext string
              If the name of an output file has to be derived from the name of
              an input file it will use the name of the format as the
              extension by default. This option here will override this
              however, forcing it to use string as the file extension. This
              option is ignored if the name of the output file is fully
              specified through option -o.

              When used multiple times only the last definition is relevant.

       -header file
              This option can be used if and only if the selected format
              provides an engine parameter named "header". It takes the
              contents of the specified file and assign them to that
              parameter, for whatever use by the engine. The HTML engine will
              insert the text just after the tag <body>.  If navigation
              buttons are present (see option -nav below), then the HTML
              generated for them is appended to the header data originating
              here before the final assignment to the parameter.

              When used multiple times only the last definition is relevant.

       -footer file
              Like -header, except that: Any navigation buttons are ignored,
              the corresponding required engine parameter is named "footer",
              and the data is inserted just before the tag </body>.

              When used multiple times only the last definition is relevant.

       -style file
              This option can be used if and only if the selected format
              provides an engine parameter named "meta". When specified it
              will generate a piece of HTML code declaring the file as the
              stylesheet for the generated document and assign that to the
              parameter. The HTML engine will insert this inot the document,
              just after the tag <head>.

              When processing an input directory the stylesheet file is copied
              into the output directory and the generated HTML will refer to
              the copy, to make the result more self-contained. When
              processing an input file we have no location to copy the
              stylesheet to and so just reference it as specified.

              When used multiple times only the last definition is relevant.

       -nav label url
              Use this option to specify a navigation button with label to
              display and the url to link to. This option can be used if and
              only if the selected format provides an engine parameter named
              "header". The HTML generated for this is appended to whatever
              data we got from option -header before it is inserted into the
              generated documents.

              When used multiple times all definitions are collected and a
              navigation bar is created, with the first definition shown at
              the left edge and the last definition to the right.

   FORMATS
       At first the format argument will be treated as a path to a tcl file
       containing the code for the requested formatting engine. The argument
       will be treated as the name of one of the predefined formats listed
       below if and only if the path does not exist.

       Note a limitation: If treating the format as path to the tcl script
       implementing the engine was sucessful, then this script has to
       implement not only the engine API for doctools, i.e.  doctools_api, but
       for doctoc_api and docidx_api as well. Otherwise the generation of a
       table of contents and of a keyword index will fail.

       List of predefined formats, i.e. as provided by the package doctools:

       nroff  The processor generates *roff output, the standard format for
              unix manpages.

       html   The processor generates HTML output, for usage in and display by
              web browsers. This engine is currently the only one providing
              the various engine parameters required for the additional
              customaization of the output.

       tmml   The processor generates TMML output, the Tcl Manpage Markup
              Language, a derivative of XML.

       latex  The processor generates LaTeX output.

       wiki   The processor generates Wiki markup as understood by wikit.

       list   The processor extracts the information provided by
              manpage_begin.  This format is used internally to extract the
              meta data from which both table of contents and keyword index
              are derived from.

       null   The processor does not generate any output. This is equivalent
              to validate.

   DIRECTORY STRUCTURES
       In this section we describe the directory structures generated by the
       application under output when processing all documents in an
       inputdirectory. In other words, this is only relevant to the use cases
       [2] and [3].

       [2]    The following directory structure is created when processing a
              single set of input documents.  The file extension used is for
              output in HTML, but that is not relevant to the structure and
              was just used to have proper file names.

                  output/
                      toc.html
                      index.html
                      files/
                          path/to/FOO.html

       The last line in the example shows the document generated for a file
       FOO located at

                  inputdirectory/path/to/FOO


       [3]    When merging many packages into a unified set of documents the
              generated directory structure is a bit deeper:

                  output
                      .toc
                      .idx
                      .tocdoc
                      .idxdoc
                      .xrf
                      toc.html
                      index.html
                      FOO1/
                          ...
                      FOO2/
                          toc.html
                          files/
                              path/to/BAR.html

       Each of the directories FOO1, ... contains the documents generated for
       the package FOO1, ... and follows the structure shown for use case [2].
       The only exception is that there is no per-package index.

       The files ".toc", ".idx", and ".xrf" contain the internal status of the
       whole output and will be read and updated by the next invokation. Their
       contents will not be documented. Remove these files when all packages
       wanted for the output have been processed, i.e. when the output is
       complete.

       The files ".tocdoc", and ".idxdoc", are intermediate files in doctoc
       and docidx markup, respectively, containing the main table of contents
       and keyword index for the set of documents before their conversion to
       the chosen output format.  They are left in place, i.e. not deleted, to
       serve as demonstrations of doctoc and docidx markup.

BUGS, IDEAS, FEEDBACK
       This document, and the application it describes, will undoubtedly
       contain bugs and other problems.  Please report such in the category
       doctools of the Tcllib SF Trackers
       [http://sourceforge.net/tracker/?group_id=12883].  Please also report
       any ideas for enhancements you may have for either application and/or
       documentation.

SEE ALSO
       docidx introduction, doctoc introduction, doctools introduction

KEYWORDS
       HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup,
       nroff

CATEGORY
       Documentation tools

COPYRIGHT
       Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>




Documentation toolbox                 1.0                           dtplite(n)
