1. Manuals
  2. Tumbleweed
  3. tcllib
  4. dtplite(n)

Scroll to navigation

dtplite(n) Documentation toolbox 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



  

  
This is the form for use case [1]. The options will be explained
      later, in section OPTIONS.







  

  
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.

  

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









  

  
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.

  

  
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.

  

  

  
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.



  

  
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.

  

  
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.

  

  
  
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.

  

  
  
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.

  

  

  
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.

  

  

  
This option specifies a doctoc file to use for the table of contents
      instead of generating our own.
    
When used multiple times only the last definition is
      relevant.

  

  

  

  

  
This option specifies additional doctoc files (or texts) to use in the
      navigation bar.
    
Positioning and handling of multiple uses is like for options
        -prenav and -postnav, see below.

  

  
  

  

  
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.

    
The url can be relative. In that case it is assumed to be
        relative to the main files (TOC and Keyword index), and will be
        transformed for all others to still link properly.

  

  

  
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 last definition shown at the right
        edge and the first definition to the left.

    
The url can be relative. In that case it is assumed to be
        relative to the main files (TOC and Keyword index), and will be
        transformed for all others to still link properly.

  








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:



  

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

  

  
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.

  

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

  

  
The processor generates LaTeX output.

  

  
The processor generates Wiki markup as understood by wikit.

  

  
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.

  

  
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 package it describes, will undoubtedly
    contain bugs and other problems. Please report such in the category
    doctools of the Tcllib Trackers
    [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for
    enhancements you may have for either package and/or documentation.


When proposing code changes, please provide unified diffs,
    i.e the output of diff -u.


Note further that attachments are strongly preferred over
    inlined patches. Attachments can be made by going to the Edit form of
    the ticket immediately after its creation, and then using the left-most
    button in the secondary navigation bar.






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-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>








  

    1.0.5
    tcllib