Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

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.

share|improve this question
3  
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
1  
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
add comment

3 Answers

up vote 9 down vote accepted

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.

share|improve this answer
    
Thanks! Pretty clear. Prepare for more docstrip questions in the near future. ;-) –  mhelvens Nov 22 '12 at 21:16
add comment

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.

share|improve this answer
    
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
add comment

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.
share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.