11

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?

  • One file you cannot put into a .dtx file is a Makefile. Docstrip strips tab characters which are necessary for make's syntax. There are workarounds requiring post-docstrip processing of the generated Makefile, but I'm not sure it's worth the trouble. – Matthew Leingang Feb 6 '15 at 18:38
9

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.

6

A single .dtx is in some ways convenient as it means it is easy to send the entire package to others in one go. On the other hand, very few end users will actually use such a file: if I want to send someone a 'ready to go' package I either mail the TDS-style zip or link to it on CTAN.

For small packages a single .dtx does make sense, and including the .ins file in with the .sty and README in the source can make life quite convenient as a package author. However, that assumes that the source file stays a 'reasonable' size to edit. For example, for siunitx I currently have one source file but it's really too large and I'm planning to split it for a future release. On the other hand my notes2bib package works as a single file as it's not too long.

One area to consider is user versus programmer documentation. If you plan to work on anything that provides a 'programmer interface' as well as a 'user' one then a separate .tex source is useful. This applies for example to code using expl3 where the LaTeX Team strongly suggest that all user interfaces come with 'matching' programmer ones.

As David says test files should almost certainly not be included in your source. Unlike the code, documentation and examples these do not need to be distributed to end users. For example, the LaTeX Team have a large test suite for LaTeX2e and tests for expl3 but none of these go to CTAN as they are not needed outside of development work. (Aside: the team's building and testing system is available for general use.)

I'd say that if you are looking at multiple files including examples then you are probably better using one or more .dtx for the code, code comments and programmer interfaces and separate .tex file(s) for the user documentation and demos. On the other hand, a package made up of 10s of lines of code with a simple interface can be contained happily in one file.

0

This wep page explains in some way what you want to do (see item numer #2): http://www.aq.upm.es/Departamentos/Fisica/agmartin/webpublico/latex/FAQ-CervanTeX/FAQ-CervanTeX-8.html , but is in Spanish lenguage. I suppose there is probably a English version too. For example:

  • "Extrayendo archivos de estilo de los .dtx y .ins..."

And also:

  • .sty, .cls o .fd: $TEXMFLOCAL/tex/latex//
  • .dvi, .ps o .pdf: $TEXMFLOCAL/doc/latex//
  • .bib: $TEXMFLOCAL/doc/bibtex/bib
  • .bst: $TEXMFLOCAL/doc/bibtex/bst
  • .tfm: $TEXMFLOCAL/fonts/tfm///
  • .vf: $TEXMFLOCAL/fonts/vf///
  • .afm: $TEXMFLOCAL/fonts/afm///
  • .pfb: $TEXMFLOCAL/fonts/type1///
  • .ttf: $TEXMFLOCAL/fonts/truetype///
  • 1
    Welcome to TeX-sx! Answers are strongly encouraged to be self-contained on the site, so something which is primarily a link is usually given as a comment. Moreover, the link here seems to be where to install files rather than what a developer should put in a .dtx. – Joseph Wright Feb 10 '15 at 19:32

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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