Man Linux: Main Page and Category List

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.

       -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>