# What does the “driver” section do in a .dtx file?

I've read the `docstrip` documentation, but have yet to form an intuition about how package documentation is extracted when I simply run `pdflatex package.dtx`.

Let's say I'm using the simple `dtxtut` skeleton file for generating both a `.sty` file and a `.pdf` file which documents it.

Intuitively, `pdflatex` simply discards all comments and compiles what's left. I can also understand that the `\DocInput` command inside the `driver` section takes the same file again and parses it with some different 'filters'.

But what does the `<*driver></driver>` section do? I never defined the `driver` boolean, and I can't find it defined anywhere else.

-
In olden times you couldn't directly typeset a `.dtx` file, so it had to contain some directives to produce a `.drv` file. Now the `<*driver>`/`</driver>` tags are just signposts to make the contents between them not to leak in the `.sty` file. They could be named in any way one likes. Let's wait for @FrankMittelbach for an ultimate answer. – egreg Nov 22 '12 at 19:05
If you would run the `ins` file of a package with a `driver` section (like `ragged2e`) through docstrip, TeX would tell you what you can do with it `:-)`. – Martin Schröder Nov 22 '12 at 23:37

In the original plan of `docstrip` the documented source would be in the `.dtx` file and a separate LaTeX "driver" document, which could be `.tex` except that might clash with files that are being generated, would be used to input the `doc` package and produce the documentation, and a third `.ins` file would be used with `docstrip` to control the generation of the files.

By putting suitably arcane `\if` constructs and guards into the `dtx` file it is possible to dispense with the two extra files and just distribute a single `dtx` file that can be used to drive documentation or code generation depending how it is called.

When we standardised things for the LaTeX2e distribution getting rid of the `ins` file was thought too weird but we did hide the documentation driver in the `dtx` files thus avoiding the need for a separate file for each package to produce the documentation. However we put `docstrip` guards there so that the documentation driver files could be generated as separate files if anyone wanted them (by specifying the driver guard to `docstrip`). I would guess they are never used now directly although you need to put that block into some guard top stop it being written to the top of the generated `.sty` files.

-
Thanks! Pretty clear. Prepare for more docstrip questions in the near future. ;-) – mhelvens Nov 22 '12 at 21:16

A 'classical' (~LaTeX2.09) `.dtx` file contained the source and documentation for (usually) a LaTeX package, but not the instructions to extract the package from the source or to typeset the documentation. As such, `latex foo.dtx` would not result in useful output. To allow extracting, an installation (`.ins`) file was needed, and to allow typesetting a driver (`.drv`) file was used. So to get the documentation you needed to `latex foo.drv`.

With appropriate set up, both of these additional files can be avoided. For many years it has been standard practice to integrate the driver into the `.dtx`. This is still typically done using guards called `driver`, meaning that one could create an `.ins` file to extract the driver from the source. (You still find some packages on CTAN where the `.ins` file is set up in this way.) The result of integrating the driver is that `latex foo.dtx` will (usually) typeset the documentation.

While not directly asked in the question, it's worth noting that you do not have to have a separate `.ins` file either. My model `.dtx` file is set up to be 'self-extracting', so neither a `.drv` not a `.ins` file are required.

-
Thanks! Your answer was helpful. But, you know, only one green tick to go around. :-) Cheers! – mhelvens Nov 22 '12 at 21:17
@mhelvens That's OK: I see more DocStrip questions are promised, so I should have a chance! – Joseph Wright Nov 22 '12 at 21:18

A separate driver file makes it much easier (and more legal) to modify it to change the way the documentation is produced (e.g. which indizes are produced).

``````%% To produce the documentation in the way you like you are allowed
%% to change this driver file.
``````
-