dtp

What is dtp? edit

dtp is the "DocTools Processor", which is an application for handling and showcasing the doctools format (usual suffix .man). See http://core.tcl.tk/tclapps/doc/trunk/apps/dtp/README.txt

. The sources are in the tclapps Fossil repository (parallel to tcllib).

A starkit can be found in the sdarchive.

Note that DTP in the outside world mostly is understood as Desktop Publishing, which this is not.

Building the dtp starkit edit

KJN The starkit in the sdarchive is quite old - for example, it cannot handle document subsections. The dtp sources can be found in 8.4 versions of ActiveTcl, in folder demos/TclApps/apps/dtp, with instructions for creating a starkit: you will also need to fetch the source of tcllib.

Get the latest cvs head of tclapps - a module in tcllib.sf.net . Activestate has an ftp site where you can get a snapshot of the latest cvs [add pointer to the page for their ftp site]. If you use the tar.gz file from the ActiveState web site, expand it into a folder/directory structure.
Get the latest cvs head of tcllib into a folder/directory
Get/build a copy of tclsh8.5
Get a copy of sdx
Rename the apps/dtp directory to apps/dtp.vfs
Run

 tclsh8.5 dtp.vfs/main.tcl assemble /my/path/to/latest/cvshead/tcllib
 sdx.kit wrap dtp.vfs
 mv dtp dtp.kit

[Describe the purpose of dtp and provide examples of its use. Point to online documentation. Point to a description of the formatting language itself.]

The languages are specified in

http://tcllib.sourceforge.net/doc/doctoc_fmt.html ---- doctools language (manpages)
http://tcllib.sourceforge.net/doc/doctools_fmt.html -- doctoc language (table of contents)
http://tcllib.sourceforge.net/doc/docidx_fmt.html ---- docidx language (indices)

How to output man ...

Get dtp from sdarchive : [1]
Get tcllib sources as source of .man files, ex. : [2]
Then:

            dtp doc html tcllib/modules/struct/graph.man

(under Windows one may have to enter the following in order to let the arguments read correctly, when using dtp.kit):

            wish dtp.kit doc html tcllib/modules/struct/graph.man > graph.html

Sarnold tclsh dtp.kit doc html mypackage.man > mypackage.html or the same with tclkitsh instead of tclsh will work. AFAIK wish and tclkit (which are graphical and do not have access to stdout on Windows) will not work properly.

generates HTML from the manpage for struct/graph. And

            dtp doc nroff tcllib/modules/struct/graph.man

generates nroff

"dtp script" returns a shell script using some of the advanced features of dtp itself (toc and indices)

Note: Discussion of documentation issues is encouraged, either here, on the doctools page, or the user documentation project.

LV Note that, in the examples above, the file.man may surprise/mislead old Unix hackers. That is because through the years, file.man was one way of specifying that the contents were nroff -man formatted files.

tcllib currently uses file.man file naming convention to imply that the contents are to be formatted with dtp (no, I can't explain why .dtp wasn't used...).

AK: Usage of the .man extension for the doctools files predates the existence of dtp.

LV But with the introduction of dtp, a change could have been introduced.

kroc 26 May 2003 Added dtp command line documentation.

dtp assemble tcllibdir ?appfile?

Takes the relevant files from the textutil and doctools modules found in the directory tcllibdir and copies them into the appropiate places of the directory hierarchy this application is under. Note that tcllibdir has to refer to the sources of tcllib. An installation of tcllib does not have all the required files (documentation) in its hierarchy. If, and only if the argument appfile is present the method will not only assemble the sources, but also wrap the copleted directory hierarchy and write the generated starkit to the named file, creating all directories as necessary.

dtp changelog label module logfile...

This command takes a number of ChangeLog files as they are generated and handled by emacs', parses them, and converts the result into a document in doctools format. This document is written to stdout. The arguments label and module are specifying texts for use in the header of the created document which cannot be supplied by the changelogs themselves.

dtp copyright ?-label text? ?-logo path? ?-link url?

Creates a piece of HTML containing a copyright clause. Note that while any two of the options are allowed to be missing at least one option has to be present. The result is written to stdout. If the -label is specified its argument will be used as the name of the entity having the copyright. If -logo is specified its argument is the name of an image file to insert. If a -link is present both label and logo will be hyperlinks to its argument.

dtp doc ?options...? format docfile ?metafile?

This command was added to aid in the quick conversion of a single file without causing the user to have to jump through all the hoops required by gen-doc to make the batch processing of large sets efficient. It processes one file (docfile) and converts it into the requested output format. The result of the conversion is written to stdout. If the metafile is present it is used for the creation of cross-references, assuming that this is supported by the chosen format. Providing a metafile to a format not supporting cross-references is an error. The conversion can be influenced by the options listed below.

-varstring varname string

This option is used to set format/engine specific parameters to some value. The parameter is specified by varname, the new value by string. Currently only the HTML engine supports engine parameters.

-varfile varname file

This option is used to set format specific/engine parameters to some value. The parameter is specified by varname, the new value by the contents of the file file. Currently only the HTML engine supports engine parameters.

dtp gen-doc ?options...? format iomap ?meta?

Processes all input files listed in iomap and converts into the requested output format. The results are written to the output files listed in iomap. If meta is present the meta information containied in it is read and used to create cross-references between the manpages, if supported by the engine for the chosed output format. The conversion can be influenced by the options listed below.

-varstring varname string

-varfile varname file

-subst varname marker path

When used multiple times the data accumulates, in contrast to the other options, where the last occurence is dominant. It declares that the data for the engine parameter varname contains a variable link, that all locations for this link are marked by the string marker, and that the link has to refer to the output file path. Based upon this information the formatter will, for each output file in the iomap, replace the marker with a proper link to the path, based upon the relative locations of the current file and the file linked to, i.e. path. An occurence of this option for a variable varname is ignored if no engine parameters for varname were specified via either -varfile or -varstring.

dtp gen-idx ?options...? format iomap idxfile

Reads the file idxfile and writes an index in the output format to stdout. Assumes that the idxfile is written in the docidx format. The resolution of symbolic to actual filenames is guided by the iomap. It is assumed that the map file is in the same format as generated by the subcommand map. The conversion can be influenced and manipulated by the options listed below.

-varstring varname string

This option is used to set format specific parameters to some value. The parameter is specified by varname, the new value by string. Currently only the HTML engine supports engine parameters.

-varfile varname file

This option is used to set format specific parameters to some value. The parameter is specified by varname, the new value by the contents of the file file. Currently only the HTML engine supports engine parameters.

-subst varname marker path

dtp gen-toc ?options...? format iomap tocfile

Reads the file tocfile and writes a table of contents in the output format to stdout. Assumes that the tocfile is written in the doctoc format. The resolution of symbolic to actual filenames is guided by the iomap. It is assumed that the map file is in the same format as generated by the subcommand map. The conversion can be influenced and manipulated by the options listed below.

-varstring varname string

This option is used to set format specific parameters to some value. The parameter is specified by varname, the new value by string. Currently only the HTML engine supports engine parameters.

-varfile varname file

-subst varname marker path

dtp help

Returns a description of the help subcommand, especially the available topics. This description will be in plain text.

dtp help topic format

The help for the topic is written to stdout, in the specified format.

dtp idx ?options...? meta

This method converts the information given to us via file meta into an index. The output of this subcommand is written to stdout and will be in the docidx format. It is expected that the contents of meta are in the format returned by the subcommand meta, modulo formatting which does not change the semantics of the output. The generation of the index can be influenced by the options listed below.

-title text

Provides the text used as the label of index_begin. Defaults to the empty string.

-desc text

Provides the text used as the descriptive title of the index in index_begin. Defaults to Keyword index.

dtp map ?options...? file...

This command returns on stdout an array mapping the paths of the given input files to the names and locations of the output files as specified and modifed per the accepted options, listed below. Each line of the output will be a valid tcl list containining two elements. First the path to the input file, followed by the path to the output file. The name of an output file is derived from the name of the input file by the following algorithm:

Remove an existing extension from the name of the input file and add the extension specified via option -ext.

If option -out is specified, then make the path coming out of step 1 a relative path and then prepend the output directory provided by the option.

If the path coming out of the steps above is identical to the path of the input file, then add the new extension at the end of the path to ensure that the output file is different from the input file.

-ext newextension

This option has to be specified; and provides the new extension to give to the output files.

-out directory

If this option is specified all output files will be placed into the given directory.

-trail n

The argument n has to be an integer number greater than 0. The value defaults to 0. If specified the last n elements of an input path are taken as the initial value for the output path.

dtp meta iomap

Extracts the meta information from all input files provided through the mapping file iomap and returns it on stdout. The input files have to be in doctools format. The output is a tcl script containing a series of manpage commands. The first and only argument will be a key/value-list acceptable to array set containing information about the manpage, like name of the file, keywords, cross references, title, etc. The output of the subcommand meta is an acceptable input for the option -meta of the subcommands doc, idx, and toc, if stored in a file.

dtp navbar iomap base (infile label /on|/off|/pass)...

Creates a piece of HTML containing a navigation bar. All infile's are mapped to their proper output file via the contents of the mapping file iomap. It is assumed that the navigation bar will be inserted into the output file for the input file base, this guides the generation of proper relative links. For files which are marked with /off only a label is generated. A link is generated if and only if the infile is marked with /on, or /pass. When an infile is marked with /pass the system will assume that the string infile is a fixed url and inserts it unchanged into the generated output.

dtp getscript

Returns a shell script stored in the application on stdout.

dtp subst inputfile key value...

Reads the contents of the inputfile and replaces all occurences of @key@ with the the associated value, for all keys and values. The result of this substitution is written to stdout. The special value - for inputfile instructs the application to read the data process from stdin.

dtp toc ?options...? meta

This method converts the information given to us via file meta into a table of contents. The output of this subcommand is written to stdout and will be in the doctoc format. It is expected that the contents of meta are in the format returned by the subcommand meta, modulo formatting which does not change the semantics of the output. The generation of the toc can be influenced by the options listed below.

-title text

Provides the text used as the label of toc_begin. Defaults to Table Of Contents.

-desc text

Provides the text used as the descriptive title of the toc in toc_begin. Defaults to Manual.

On top of the document I have added a modified example of invocation under windows. An output file must be specified using the pipe operator (any comments or other experiences?) -- RJM

AK: We have an RFE for specifying the output through an option. This RFE has been implemented, but the available dtp kits have not been updated yet to the new code.

Darren New: Since the version of dtp.kit on sdarchive no longer works with the release version of 8.5.2, one can use

   teacup get dtplite

to download into the current directory the ".tm" file. This is Tcl, and can be renamed to dtplite.tcl and invoked in the usual tclsh way.

The entire dtp.kit built by Larry Virden as of 6/2008 is available at [3] at least for a time.

Category Application

Category Documentation