The [doctools] processor. An application for handling and showcasing the doctools format. The sources are in tcllib, module ''tclapps''. A starkit can be found in the [sdarchive]. [[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) Note that DTP in the outside world mostly is understood as Desktop Publishing, which this is not. ---- How to output man ... * Get dtp from sdarchive : [http://mini.net/sdarchive/dtp.kit] * Get tcllib sources as source of .man files, ex. : [http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcllib/tcllib/modules/struct/graph.man] * Then: dtp doc html tcllib/modules/struct/graph.man * 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. ---- [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'' 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. '''-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'' 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-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'' 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'' 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''' '''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'''. ---- [Category Application] | [Category Documentation]