33

I just downloaded the installation files for a LaTeX package from CTAN. They mostly comprised a load of DTX files, and an INS file. The instructions said to run latex on the INS file, and I did. It produced a load of STY files, and a message appeared telling me to copy these STY files to my TeX directory tree. I did as instructed, and everything works fine.

But what was the point of all this DTX/INS shenanigans? Why aren't STY files just made available for immediate download in the first place?

Improve this question
6
  • 1
    Partial answer: tex.ac.uk/FAQ-dtx.html and additional information in dickimaw-books.com/latex/novices/html/dtxins.html. In summary: historical reasons and there are packages which have not been prepared in the TDS format.
    – R. Schumacher
    Dec 17, 2016 at 23:52
  • 1
    you are asking what is the point of documenting code. there are lots of reasons, not least to remind yourself how it works when answering questions about it 30 years later on this site, but these days almost every package that is useful is in texlive/miktex so installing via a ins file downloaded from ctan is increasingly rare.
    – David Carlisle
    Dec 18, 2016 at 0:11
  • Thanks for your comments. Unfortunately I'm not equipped to get much out of them. @R.Schumacher: clearly I'm not an expert in these matters, as you can tell from my question, and I don't know what TDS is.
    – Jamie Vicary
    Dec 18, 2016 at 1:52
  • 1
    @JamieVicary but this is a typesetting system so it is not unnatural to go the other way and have a typeset document out of which executable code can be extracted rather than have a file that is primarily code with inline comments.
    – David Carlisle
    Dec 18, 2016 at 14:29
  • 3
    @JamieVicary basically don't think of dtx as a weirdly packaged .sty file, think of it as a tex document, so if you have downloaded foobar.dtx then pdflatex foobar.dtx will produce the package manual. the fact that the package itself can be extracted from the same file can be thought of as an installation detail.
    – David Carlisle
    Dec 18, 2016 at 14:33

2 Answers 2

Reset to default
20

The starting point for having a 'source' format is that it's a good idea to have code comments and it's also a good idea to have user documentation. The simplest way to do that of course is to put it all directly in the .sty file.

% Some info for the user
% ...
% Some code comment
\a \code \line

That is seen a a good number of packages.

The next consideration is that as TeX is a typesetting system we'd like to be able to typeset the documentation, not just read the 'raw' sources. That can be arranged by setting up the comments appropriately and reading in the source using some form of 'driver' (a small file that sets up to typeset rather than use the code/documentation).

This brings us to two partly-historical considerations. First, if comments are in the source, TeX has to read those lines each time the code is used. In general, the code will be used many more times than the documentation is read, so it makes sense to speed the process up if possible. Historically, stripping out comments made a significant different here, so this was worth it: today you probably don't notice the improvement very much!

One could split the user documentation into a separate file from the code, and again this is common, particularly for larger packages. However, that means more files. Again, historically sources were exchanged by 'direct' methods (email, etc.), and so minimising the number of files had a strong point. This is of course not so much of a consideration today.

All of the above assumes our source extracts to exactly one .sty file. However, by using the DocStrip system we can extract multiple files from one source, reorder lines, etc. For example, if we have several related files (e.g. drivers for graphics inclusion, input encoding support, ...), they will have shared lines and code comments plus some unique lines. Using a .dtx we can have them in one place and extract out the separate parts. We can also combined multiple sources into one .sty: file loading depends on the number of files used, so there is a benefit in putting a large code block together (sources don't want to be too long!). This is seen in for example expl3 or the LaTeX kernel itself.

As the above details, there are technical and historical reasons for using the .dtx format. As it's used by the LaTeX team, there is a reasonably strong sense of 'community by-in' for the approach. Notably, for almost all end users today this is not a significant factor: the vast majority of users get code pre-extracted in TeX Live/MiKTeX, and CTAN also hold installable .tds.zip files for many packages. So other than developers, actually using .dtx files is not something that is widely done today.

Improve this answer
5
  • Not an answer, but for almost any other application one would expect to have to build the code from source to a usable form: much the same concept applies here.
    – Joseph Wright ♦
    Dec 18, 2016 at 14:32
  • 2
    one thing that's not really stressed here is the value of having the documentation and code in the same file, so when changes are necessary, you don't have to remember to make corresponding changes in more than one place. this keeps the documentation in synch with the source, a benefit that's often underestimated.
    – barbara beeton
    Dec 18, 2016 at 19:11
  • 1
    @barbarabeeton In my experience, that depends on the scale. For a small package it works well, but for a bigger one can get tricky. For example, I'm moving siunitx to separate files for the sources/code interfaces and user interface documentation: at 12k lines in one file the current set is too long.
    – Joseph Wright ♦
    Dec 20, 2016 at 19:31
  • i was mainly referring to the code documentation. indeed, it very often does make better sense to have the user documentation separate. but there's definitely value in having neatly typeset code documentation; it's lots easier to read and find things in than slogging through comments in a source file. of course, it does require some extra effort when writing it, but i've found it usually pays off some months later, when a modification has to be made.
    – barbara beeton
    Dec 20, 2016 at 20:12
  • Comments have been moved to chat; please do not continue the discussion here. Before posting a comment below this one, please review the purposes of comments. Comments that do not request clarification or suggest improvements usually belong as an answer, on TeX - LaTeX Meta, or in TeX - LaTeX Chat. Comments continuing discussion may be removed.
    – Joseph Wright ♦
    Nov 10 at 15:34
11

After a bit of research, here is an excerpt on the reason for the 'dtx' and 'ins' format for file transfer.

Why dtx at all?

The first question to consider is why people bother with the dtx format. Not everyone does, and there are good arguments for and against each different approach. I could easily write an entire post just discussing the various alternatives, but that’s not what I want to do here!

The dtx format is favoured by the LaTeX team, and so is something of a standard for LaTeX package authors. The idea of the dtx format is that it allows the package author to put the user documentation, code documentation and code itself in one place. The user documentation can be typeset on its own, or the user and code documentation can be typeset together (literate programming). The code can also be extracted from the source for use: this means that more than one file can be included in the same source. This last point is perhaps the biggest selling point of the dtx format: you can include LaTeX package, class and some configuration files in one source. There is also a speed gain from removing redundant (comment) lines from a package: on a modern PC, this is pretty tiny, but was a bigger point in the past.

Extracted from http://www.texdev.net/2009/10/05/the-dtx-format/

And further discussion in http://www.texdev.net/2009/10/06/a-model-dtx-file/

While the format is not used in the CTAN archives, it is still around and the only way to install some packages. Fortunately there are excellent resources on how to use them.

Improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .