Tcl Library Source Code

Documentation
Login


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

docstrip_util - Docstrip-related utilities

Table Of Contents

SYNOPSIS

package require Tcl 8.5 9
package require docstrip ?1.3?
package require docstrip::util ?1.3.2?

pkgProvide name version terminals
pkgIndex ?terminal ...?
fileoptions ?option value ...?
docstrip::util::index_from_catalogue dir pattern ?option value ...?
docstrip::util::modules_from_catalogue target source ?option value ...?
docstrip::util::classical_preamble metaprefix message target ?source terminals ...?
docstrip::util::classical_postamble metaprefix message target ?source terminals ...?
docstrip::util::packages_provided text ?setup-script?
docstrip::util::ddt2man text
docstrip::util::guards subcmd text
docstrip::util::patch source-var terminals fromtext diff ?option value ...?
docstrip::util::thefile filename ?option value ...?
docstrip::util::import_unidiff diff-text ?warning-var?

DESCRIPTION

The docstrip::util package is meant for collecting various utility procedures that are mainly useful at installation or development time. It is separate from the base package to avoid overhead when the latter is used to source code.

Package indexing commands

Like raw ".tcl" files, code lines in docstrip source files can be searched for package declarations and corresponding indices constructed. A complication is however that one cannot tell from the code blocks themselves which will fit together to make a working package; normally that information would be found in an accompanying ".ins" file, but parsing one of those is not an easy task. Therefore docstrip::util introduces an alternative encoding of such information, in the form of a declarative Tcl script: the catalogue (of the contents in a source file).

The special commands which are available inside a catalogue are:

Other Tcl commands are supported too — a catalogue is parsed by being evaluated in a safe interpreter — but they are rarely needed. To allow for future extensions, unknown commands in the catalogue are silently ignored.

To simplify distribution of catalogues together with their source files, the catalogue is stored in the source file itself as a module selected by the terminal 'docstrip.tcl::catalogue'. This supports both the style of collecting all catalogue lines in one place and the style of putting each catalogue line in close proximity of the code that it declares.

Putting catalogue entries next to the code they declare may look as follows

%    First there's the catalogue entry
%    \begin{tcl}
%<docstrip.tcl::catalogue>pkgProvide foo::bar 1.0 {foobar load}
%    \end{tcl}
%    second a metacomment used to include a copyright message
%    \begin{macrocode}
%<*foobar>
%% This file is placed in the public domain.
%    \end{macrocode}
%    third the package implementation
%    \begin{tcl}
namespace eval foo::bar {
   # ... some clever piece of Tcl code elided ...
%    \end{tcl}
%    which at some point may have variant code to make use of a
%    |load|able extension
%    \begin{tcl}
%<*load>
   load [file rootname [info script]][info sharedlibextension]
%</load>
%<*!load>
   # ... even more clever scripted counterpart of the extension
   # also elided ...
%</!load>
}
%</foobar>
%    \end{tcl}
%    and that's it!

The corresponding set-up with pkgIndex would be

%    First there's the catalogue entry
%    \begin{tcl}
%<docstrip.tcl::catalogue>pkgIndex foobar load
%    \end{tcl}
%    second a metacomment used to include a copyright message
%    \begin{tcl}
%<*foobar>
%% This file is placed in the public domain.
%    \end{tcl}
%    third the package implementation
%    \begin{tcl}
package provide foo::bar 1.0
namespace eval foo::bar {
   # ... some clever piece of Tcl code elided ...
%    \end{tcl}
%    which at some point may have variant code to make use of a
%    |load|able extension
%    \begin{tcl}
%<*load>
   load [file rootname [info script]][info sharedlibextension]
%</load>
%<*!load>
   # ... even more clever scripted counterpart of the extension
   # also elided ...
%</!load>
}
%</foobar>
%    \end{tcl}
%    and that's it!

Source processing commands

Unlike the previous group of commands, which would use docstrip::extract to extract some code lines and then process those further, the following commands operate on text consisting of all types of lines.

SEE ALSO

docstrip, doctools, doctools_fmt

KEYWORDS

.ddt, .dtx, LaTeX, Tcl module, catalogue, diff, docstrip, doctools, documentation, literate programming, module, package indexing, patch, source

CATEGORY

Documentation tools

COPYRIGHT

Copyright © 2003–2010 Lars Hellström