[Tex/LaTex] good practice when preparing a package for CTAN

ctandocumentclass-writingpackage-writing

I'm thinking of submitting a package to CTAN, and would like some hints which will help keep the path as smooth as possible for me, the CTAN administators, and the final users.

Please tell me what I should take care with in doing this. In particular, the doubts I have are:

  1. I'm not a top-drawer TeXnician, so I don't really understand .dtx and .ins files. Can I get by without them, and is it OK just to submit a zip file containing a flat folder?

  2. I'll be preparing the package user documentation (by hand) as a PDF. Should I use a specific document class, or can I, for example, use memoir?

  3. How important is it to provide the source LaTeX code for the documentation?

  4. If I do provide the documentation source, should I "declare" the prerequisite packages for formatting the manual (as opposed to the prereqs for using the package) as prereqs for the package?

Best Answer

The CTAN admins don't require compliance to the DTX format at all. Your code and documentation must simply be in a usable form. You should add a short README text file which describes the package well enough so that people can decide if they want install it.

  1. DTX and INS files are not mandatory. You can just include the STY file and a TEX file for the documentation. If you want you can use the sty2dtx script (written by me) to convert a STY file into the DTX format.

  2. You can use any class you want. However, it should still be compilable by other people.

  3. CTAN itself will include documentation without sources, but e.g. TeX Live will not include it as long the source is not freely available ("Free documentation is as important as free software.")

  4. Simply provide a full main file which loads all required packages like for any other LaTeX document. The package and its documentation document are kind of "independent". You should keep package requirements of the manual away from the actual package.

IMHO the large majority of people will simply use the PDF file from CTAN or their used TeX distribution and not try to compile it by themselves. However, people should still be able to do so. Then however, it is OK to not explicitly list all packages again somewhere. A normal formatted LaTeX document with the required \usepackage statements should be just fine. Of course people then need to install the required class and packages when they want to compile the documentation themselves. This is fine as long these are also on CTAN (and best in the main distribution).

There is also now my ctanupload script to automate the uploading process to CTAN.

Related Question