DTX submode

Description

The DTX submode contains Highlighting settings, Menu customizations, Active strings and Tree directives for documented LaTEX source files (dtx). It will also acquaint WinEdt with the structure of DTX files, so that some often-used shortcuts will work as expected.

Furthermore, it will dynamically highlight all commands defined in the DTX file and make them available for command completion.

Mode

Files with the extension .dtx will automatically be recognized as being of the mode "TeX:DTX". That is, DTX is a submode of TeX mode, inheriting its highlighting settings etc., only adding some features. Most notably, Wrapping will be turned off.

In contrast to WinEdt's default settings, files with the extensions .sty, .ins and .fd will not be regarded as DTX file, since they, -- well, they aren't. Instead, a STY submode will be installed, which only differs from the normal TeX mode in that wrapping and global switches are turned off.

Highlighting

The following switches will be highlighted (additionally to the default TEX highlighting):

• documentation parts (i.e. lines starting with a single percent character)
• guards (e.g. "%<driver>", "%<*package>", "%</package>")
• "%    \begin{macrocode}", "%    \end{macrocode}"
• |verbatim text|
• comments (^^A)

Here's a sample file (colours might be different on your system).

Furthermore, all commands that you define in the DTX file will be highlighted and made available for command completion.

Command Completion

In WinEdt's default settings, the TEX primitives and basic LaTEX commands are available for command completion (CTRL-Enter). The DTX mode will additionally make all macros that are defined in the DTX file (those enclosed in a macro environment) known to WinEdt.

After typing the beginning of a \command (at least the backslash), you can complete it by pressing CTRL-Enter. If there is more than one possible completion, you'll be prompted with a list to choose from. This also works for command names without backslash inside \cs{...}.

If no matching command is found, the default word completion will step in.

Menus and Active Strings

Since this mode will install the dynamicKeywords package, a new menu entry Update Dynamic Keywords will be added to the Tools menu if it doesn't already exist.

Using this command, you can update dynamic highlighting and command completion of the defined macros in the DTX file. (You can also use it for all other modes that take advantage of it.)

A DTX submenu will be added to the Insert menu.

All entries in the menu are also available as Active Strings (when typed at the beginning of the line):

• Macrocode environment (Active String: "%\\"):
  will insert a code block:

  %    \begin{macrocode}
  *
  %    \end{macrocode}
  

• Documentation block ("%%%"):
  will insert a documentation block:

  %    \end{macrocode}
  % *
  %    \begin{macrocode}
  

• Macro environment ("%mm"):
  will insert a macro environment, prompting for its name. Afterwards, dynamic keywords will be updated:

  %\begin{macro}{*}
  
  %\end{macro}
  

• Environment environment ("%ee"):
  will insert a environment environment, prompting for its name:

  %\begin{environment}{*}
  
  %\end{environment}
  

• Close Guard ("%>>"):
  will close the last opened guard.
• Changes ("%cc"):
  will insert a change entry:

  %\changes{<next version>}{<current date>}{*}
  

  where <next version> is taken either from the package identification string, an RCS tag, a \fileversion definition, or a custom tag.
• CheckSum (also accessible by double-clicking on "\CheckSum")
  will insert (or correct) the checksum (requires the .log file).

Shortcuts

The following shortcuts will be modified for DTX mode (and only for DTX mode):

In fact, they will behave (almost) as you would expect -- that is, you can select or navigate through paragraphs, even though they are preceded by "%". If you enter a new line and the first character of the current line is a percent character, it will be repeated in the next line with the indentation level retained. Insert/Remove Comment will insert/remove the DTX comment string "^^A" when inside a documentation block, the percent character otherwise.

Additionally, the active strings \begin{?}} resp. \end{{ (to complete the current environment) will be adjusted for DTX mode.

Tree directives

A TOC tree will be set up, which knows about the directives:

% \section
% \subsection
% \subsubsection

Furthermore, a tree of all DTX modules will be built. The closing guard will be the last child of the beginning guard. Modules may be nested. If the modules in the DTX file are improperly nested or not closed, you'll receive a warning.

You can select the respective text unit in the source file via the context menu for the section and module items.

Finally, all \change entries will be gathered in the tree and sorted. You can change the sorting criteria by right-clicking on any item:

• Group by version (toggle)
• Sort by date, string or occurrence in the file

Regular Expression filter 

WinEdt 5.5 introduced the nifty Regular Expression \E and its opposite \e, which may be used to run a macro file after the search string has been found, e.g. to filter the results further. The DTX mode includes one such macro: DTXdoc.edt.

If you want to search for an expression (using the Find/Replace dialog), but only if it occurs in the documentation part of your DTX file, append \E{DTXdoc} to the expression. Conversely, to only find an expression if it occurs in code blocks, append \e{DTXdoc} to the expression. Note that you must check the Regular Expression switch in the dialog, which means that you either have to escape special characters with a backslash or enclose the complete main expression in \"^...^, where ^ may be any character not appearing in the enclosed text.

For example, to search for the string \my@macro{}, but only if it occurs within code blocks, you could use either of the following expressions:

 \\my\@macro\{\}\e{DTXdoc}
 \"+\my@macro{}+\e{DTXdoc}

Customization

A number of options can be customized in the configuration file DTX.cfg:

• The right margin for formatting paragraphs (default: 80)
• Whether dynamic keywords should be automatically updated after inserting a new macro environment (default: yes)
• The default sorting criteria of the Changes tree
• The order for determining the next version for \changes, and the version prefix (default: v)
• The characters that a macro may consist of (default: $Alpha+["@"]$)

Installation

DTX submode requires WinEdt 5.5, build 20060814, or newer. Some components might work with builds as old as 20041213, however, if anything doesn't work -- which is actually more than likely -- you are on your own.

To install the DTX submode, extract the zip file to the directory %b\Config\DTX\, and run the macro _install_DTX.edt. The mode can be uninstalled by running _uninstall_DTX.edt. If you want to update the DTX submode, please uninstall the previous version before installing the new version.

The complete documentation can be found in _DTX.README or _DTX.pdf, both included in the zip file.

Download

DTX.zip [140 KB]

The package requires the

• addOrUpdate macro and the
• dynamicKeywords package (version 1.4),

which both must be saved in %b\Macros\macro (preferably) or %B\Macros\macro.

Mode contributed by Robert <w.m.lgmx.net>

Last revised on: 06.03.2016    |    Comments and suggestions to webmaster@winedt.org