[Tex/LaTex] What to put into the dtx file

docstripdtxpackage-writing

Many packages are written as a single dtx file from that everything that composes the package is extracted. Apart from documentation and package code (the sty or cls), the installation instructions (ins), configuration files, tests, or examples may all be included in this single file.

I understand that it makes sense to keep documentation and code together tightly, especially in the concept of literate programming, but I imagine that a project that consists of only one giant file complicates for example version control.

I am currently writing a package that will compose of

  • a .ins,
  • a .sty,
  • its user documentation,
  • tests, most likely performed through qstest,
  • a configuration file
  • usage examples, each of them may span multiple files itself.

Which of these parts should be dedicated files, which are better put into the dtx?

Best Answer

It all depends, If you look at the latex format source latex.ltx that is a single file made up from multiple dtx files mostly for the reason you stated of easier management in source control. User documentation is tricky choice as well, for small packages it makes sense to put it in the (single) dtx but for larger suites a separate document is good, but then these days you might need to give the maintainers of texdoc utility a hint for example for the graphics bundle in latex each dtx has some documentation at the start but there is a separate grfguide graphics guide documentation as well.

Currently texdoc graphics gives you grfguide, which is probably the right choice (it wasn't me that chose:-) but to see the doc generated from the actual package you need texdoc graphics.pdf which is sort of OK if you know it works, but if you know that you probably don't need to look in the doc anyway:-)

Tests I think are best kept separate.

So probably if as you indicate it is a fairly large multi-file suite I think I would put less user-documentation in the source dtx and just make it have the documented sources (the part traditionally after \StopEventually) and have separate document for user-facing documentation and examples.

Related Question