Working with dtx files

I’ve talked a bit about the dtx file format and given an example of a skeleton dtx file. I thought I’d talk next about working with sources, which will be a bit of a scattered post but will hopefully be interesting!

Editing dtx files

As with any TeX source, you don’t have to have a special editor to work with dtx files, but it can be helpful. Many people say that Emacs (using AUC-TeX) has the best dtx editing mode of all: I’ve only tried it briefly, but the AUC-TeX homepage has the details. On Windows, WinEdt has a pretty strong DTX Submode which does similar things. As I mainly use TeXworks, I’ve made a few modifications to get something similar to those two ‘leaders’: at the moment I use the following settings for syntax highlighting:

[LaTeX DTX]

# comments
red        Y    \^\^A.*

# Guards
orange        N    %<(?:[A-Za-z0-9!\|]+|.)>
limegreen    N    %<\*(?:[A-Za-z0-9!\|]+|.)>
crimson        N    %</(?:[A-Za-z0-9!\|]+|.)>

# special characters
darkred        N    \^\^\^\^\^[0-9a-z]{5}
darkred        N    \^\^\^\^[0-9a-z]{4}
darkred        N    \^\^\^[0-9a-z]{3}
darkred        N    \^\^[0-9a-z]{2}
darkred        N    [$#^_{}&]
gray        N    ^%%.*
gray        N    ^%

# Macrocode
green        N    \\(?:begin|end)\{macrocode\}

# LaTeX environments
darkgreen    N    \\(?:begin|end)\s*\{[^}]*\}

# control sequences
blue        N    \\(?:[A-Za-z@:_]+|.)

plus a few special auto-complete entries. Not quite up with the best just yet, but it’s still early days for TeXworks.

What to document

Getting documentation right is not easy. My general approach is to try to include lots of examples, so I always load the package being talked about for the documentation. That means I can use the package ‘in place’. Unfortunately, ltxdoc does not have a built-in example environment. I use the listings package, and although it’s a bit complex looking, the following code works well:

%\lst@RequireAspects{writefile}
%\newsavebox{\LaTeXdemo@box}
%\lstnewenvironment{LaTeXdemo}[1][code and example]{^^A
%  \global\let\lst@intname\@empty
%  \expandafter\let\expandafter\LaTeXdemo@end
%    \csname LaTeXdemo@#1@end\endcsname
%  \@nameuse{LaTeXdemo@#1}^^A
%}{^^A
%  \LaTeXdemo@end
%}
%\newcommand*\LaTeXdemo@new[3]{^^A
%  \expandafter\newcommand\expandafter*\expandafter
%    {\csname LaTeXdemo@#1\endcsname}{#2}^^A
%  \expandafter\newcommand\expandafter*\expandafter
%    {\csname LaTeXdemo@#1@end\endcsname}{#3}^^A
%}
%\newcommand*\LaTeXdemo@common{^^A
%  \setkeys{lst}{
%    basicstyle   = \small\ttfamily,
%    basewidth    = 0.51em,
%    gobble       = 3,
%    keywordstyle = \color{blue},
%    language     = [LaTeX]{TeX},
%    moretexcs    = {
%      examplemacro,
%      ^^A Add you command names here!
%    }
%  }^^A
%}
%\newcommand*\LaTeXdemo@input{^^A
%  \MakePercentComment
%  \catcode`\^^M=10\relax
%  \small
%  \begingroup
%    \setkeys{lst}{
%      SelectCharTable=\lst@ReplaceInput{\^\^I}{\lst@ProcessTabulator}
%    }^^A
%    \leavevmode
%      \input{\jobname.tmp}^^A
%  \endgroup
%  \MakePercentIgnore
%}
%\LaTeXdemo@new{code and example}{^^A
%  \setbox\LaTeXdemo@box=\hbox\bgroup
%    \lst@BeginAlsoWriteFile{\jobname.tmp}^^A
%    \LaTeXdemo@common
%}{^^A
%    \lst@EndWriteFile
%  \egroup
%  \begin{center}
%    \ifdim\wd\LaTeXdemo@box>0.48\linewidth\relax
%      \hbox to\linewidth{\box\LaTeXdemo@box\hss}^^A
%        \begin{minipage}{\linewidth}
%          \LaTeXdemo@input
%        \end{minipage}
%    \else
%      \begin{minipage}{0.48\linewidth}
%        \LaTeXdemo@input
%      \end{minipage}
%      \hfill
%      \begin{minipage}{0.48\linewidth}
%        \hbox to\linewidth{\box\LaTeXdemo@box\hss}^^A
%      \end{minipage}
%    \fi
%  \end{center}
%}
%\LaTeXdemo@new{code only}{^^A
%  \LaTeXdemo@common
%}{^^A
%}

This gets pasted in at the start of the document (after the driver): not great coding style, but not too bad for this job. The idea is that I can then write something like:

%\begin{LaTeXdemo}
%  Some clever demo here
%\end{LaTeXdemo}

and the demonstration will be both typeset as code and actually used. So the user can see the input and the result of whatever I’ve designed.
Of course, if you are writing LaTeX classes or the like, then this won’t work. For my achemso class, I include a demo document in the dtx. This then gets extracted as a separate file (achemso-demo.tex), which includes lots of hints in the text and demonstrates as much as possible about the class. Again, the idea is to show how things are done by example: much better than trying to explain in the abstract.

Releasing stuff to CTAN

In my next post, I’m hoping to talk about automating the process of getting stuff ready for CTAN. So here I’ll just mention a few general ideas. One is that users shouldn’t need to read the code to use a LaTeX package (unless of course you are aiming at supporting other package authors). So I tend to typeset only the user part of the documentation. Normally, it’s a good idea to also include an index and list of changes in the pdf documentation, so a typical ‘recipe’ would be

pdflatex -draftmode "\AtBeginDocument{\OnlyDescription} \input demopkg.dtx"
makeindex -s gglo.ist -o demopkg.gls demopkg.glo
makeindex --s gind.ist -o demopkg.ind demopkg.idx
pdflatex "\AtBeginDocument{\OnlyDescription} \input demopkg.dtx"
pdflatex "\AtBeginDocument{\OnlyDescription} \input demopkg.dtx"

The idea of all this is to only typeset what is needed (hence the -draftmode in the first line), to miss out the code (\OnlyDescription), and to index both the changes and the user functions (the two makeindex lines). This recipe will turn up in the next post as the basis for doing things without needing to remember everything yourself!

CTAN like to have a zip file containing the source, documentation and ins file. They also prefer Unix line endings, so those of us working on Windows have to use something like Info-ZIP or the Swiss File Knife to alter the line endings. The idea of a TDS-ready zip is also popular, so there are normally two files to get ready. All of that is a bit awkward, especially if like me you keep having to do bug fix releases. So I always do this using an automated tool. I’ll talk about this in the next post.

13 thoughts on “Working with dtx files

  1. Pingback: Jürgen Fenn (juergenfenn) 's status on Sunday, 11-Oct-09 21:45:35 UTC - Identi.ca
  2. Nice template for including inline examples. I’ve been meaning to switch to listings for my code snippets for ages. Do you know if there’s anything like this on CTAN? (Also, any idea if scantokens would speed this up at all? I’m still using the old write-then-input approach as well.) Lars Madsen was once working on something like this but I don’t think it was ever released.

    If not, perhaps it’s time to finally write a package for this. (In association with l3doc perhaps.) Would be a good trial for template-new for me. On the other hand, right now is exactly the worst time for me to be starting any new mini-projects, so let’s say I’ll put it off for six months 🙂 No rush.

  3. The examples code is basically just a refinement of that in the listings manual. I guess you could consider a scantokens approach if you read everything verbatim (to typeset the code) then rescanned to get the actual code to work: not tried this!

    I’d suggest that it might be best to think bigger than another ltxdoc patch. I’ve got another couple of posts in mind on this subject, then I thought I might talk about what a successor should do: “big ideas”. That seems like a suitable LaTeX3 challenge!

    Joseph

  4. I use gedit for writing dtx source files and it is perfect and I do not think TeXWorks or any other text editor can ever compete with that. Its windows and Mac versions are also available.

    Could I suggest you that for writting example codes and documentation, you can try my bidicode package. It .sty file that comes with bidi package (it has of course nothing to do with bidirectional typesetting) and it is very useful. It combines several packages, such as listings, showexpl and fvrb-ex and provides a very strong set of commands for writing codes and example codes.

    If you want to typeset an example, you can try LTXexample environment, it both shows the TeX code and the output that user gets automatically, for example

    begin{LTXexample}
    documentclass{article}
    title{Test}
    author{A. U. Thor}
    begin{document}
    maketitle
    end{document}
    end{LTXexample}

    It also has optional orguments, that you can change the background colour, place of the frames (source and output) in adiition to many other things. In addition, it highlights your TeX code very well.

    And also some useful definitions are provided for explaining general syntax, for example, if you want to say

    usepackage[options]{package-name}

    You can say
    begin{BDef}
    Lcs{usepackage}OptArgsLargb{package-name}
    end{BDef}

    It put the code in a box, in addition it puts [options] in a gray box and uses appropriate fonts for all sections.

    I extremely find the code typeset by bidicode package attractive.

  5. HI Vafa,

    That looks really interesting!
    Is there any documentation? I couldn’t even see any for the bidi package itself?

    Will

  6. Hi Will,
    Unfortunately there is no documentation, but I am going to write one for next version of bidi. bidi at the moment is massive and the documentation including implementation would be something like 500 pages so getting it done, takes some time. and I am hoping to get it done by the end of January.

  7. Hello Vafa,

    AS I’ve said elsewhere, there is no one editor that will suit everyone. I’m happy with TeXworks, having used WinEdt previously. That doesn’t mean I won’t also be happy with something else!

    On the formatting examples ideas, I’ve tended to go for something quite “light”. I’ll certainly take a look at the stuff you do in bidi.

    Joseph

  8. The thing that I said about gedit and TeXworks, was in no way saying that TeXworks is weak or putting it down. What I meant was that in my case, where I have to do heaps of bidirectional testing for the packages that I maintain such as ledmac, xepersian and bidi, gedit makes my job very easy comparing to TeXworks and there are things in gedit that TeXWorks lacks and of course there are things in TeXWorks that gedit lacks, but I find personally gedit more useful. TeXWorks as Jonathan Kew mentioned is designed for new comers to TeX and it may or may not contain all the tools that an advanced TeXhacker needs in a editor, but TeXworks is still in its early stages of development and I hope in future, it becomes a choice of editor for most people, further, I hope, it will support perfect bidirectional typesetting as gedit almost does now.

  9. It also would be a nice idea if LTX people consider supporting bidi typesetting in LaTeX kernel. With bidi typesetting, a lot of LTX codes, needs modifications. ConTeXt does this in MKIV and it would be wonderful if this also happens in LTX, otherwise some eventually might migrate to ConTeXt from LTX.

  10. Hello Vafa,

    If you mean “beyond LaTeX2e”, then I’d be confident of a define “yes” to bidi support in LaTeX. However, the LaTeX2e kernel is not going to change, other than fixing bugs. So at that level you’ll be disappointed.

    Joseph

Leave a Reply