# What is good practice when preparing a package for CTAN?

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?

-
I've just seen How can I contribute to CTAN? so I'm probably duplicating, but as I have specific doubts, I'll leave the question for now. Please feel free to close, though. –  Brent.Longborough Aug 7 '11 at 19:22
It matters what you are uploading. If you are sending a font or font support package, for instance, I'd suggest that a doc with font tables would be useful to a person who visits your dir. But if you are uploading, say, a thesis style in LaTeX then just the files mycollege.sty, README, mycollege.tex, and mycollege.pdf, put together in a .zip, would be perfectly suitable. –  Jim Hefferon Feb 20 '12 at 0:46

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.

-
Martin, thank you, just what I needed to give me confidence... –  Brent.Longborough Aug 7 '11 at 20:02
while there are not many constraints on what you provide, you'll get sniffy reactions if you use a "private" class and/or "private" packages for the documentation. doesn't often happen, but do remember... –  wasteofspace Aug 8 '11 at 21:45
the only way a private package in your doc is a problem is if it's not generally available; that situation makes your package "nosource", since it can't be re-typeset by someone else; nosource packages won't be included in tex live (and shouldn't be in miktex, but i'm not so sure about the rules there). some people include such a package with their upload, while others upload it separately and reference it. –  wasteofspace Nov 27 '11 at 15:28

There is one (minor) issue which might come in handy: choose the name of your documentation file (your pdf) in accordance with your package, i.e. `<package>.pdf`.

This allows others to call `texdoc <package>` and the command will launch the appropriate documentation file.

Furthermore, I think the CTAN guys appreciate hints about the format of your submission. For example, it is worth to note whether your .zip file contains a TDS directory structure or simply the files which make up your package - without much of a directory structure.

-
please do not tds structure your submissions; if you know what you're doing (a lot of people submitting tds-structured stuff obviously don't) make a .tds.zip file; that is automatically checkable, and is separately referenced from the catalogue entry for the package. (.tds.zip files also simplify life for the tex live team, aiui -- but they sometimes spot things that ctan's automatic checking hasn't picked up) –  wasteofspace Nov 27 '11 at 16:11
@anon you are right: the best-practise to "note whether the .zip contains TDS or not" is use the naming convention `.tds.zip` . In general, I would agree with your hint to avoid TDS structure. TDS is only appropriate (perhaps even a must-be) for huge projects (especially multi-platform-projects). –  Christian Feuersänger Nov 27 '11 at 16:58

I just want to add that the creation of a .dtx and .ins file is a REALLY SIMPLE issue, and is a very powerful tool to create in one step the documentation for your code.

Just open the terminal and type

``````texdoc dtxtut
``````

Enjoy!

-
Personally the `dtxtut` manual and the DTX format first confused me quite a bit and I didn't enjoyed it. ;-) Added the required documentation macros to each and every of your own macros is a pain if done manually (I then wrote `sty2dtx` for it). Also writing a good and comprehensive manual for your package is always a small challenge at the very least. –  Martin Scharrer Aug 8 '11 at 17:31
Also note that `texdoc` might not be available for every TeX installation (not sure about Windows for example; if installed it might not be in the PATH). Therefore I would always point to the manual itself, e.g. using something like "see the `dtxtut` document/manual". –  Martin Scharrer Aug 8 '11 at 17:33
Although `.dtx` format is helpful for documenting the code of a package, it becomes quite cumbersome to use at the same time for maintaining the user documentation, I think. –  Alan Munn Aug 8 '11 at 17:52
Sam, thank you for your encouragement to learn about the world of .dtx. The reason I've not taken the time to study it so far is that I haven't had a need to. I do respect it as "literate programming", though my lazier half tends to agree with Alan Munn. And then, there's so much else to get through!!! –  Brent.Longborough Aug 8 '11 at 19:51
I would completely agree with Alan and Martin in that a) `.dtx` is mainly useful as API documentation and b) that a comprehensive user's guide is always a small challenge at the very least. While it is certainly good to have both, I would encourage you to put all of your effort into the user's guide - and comment the rest using TeX comments into the source code. After all, you will probably have much more users than contributors. To be honest: I have never read the automatically generated API doc of any LaTeX package. If I needed to, I looked into the code (ok, in the `.dtx` if available). –  Christian Feuersänger Nov 29 '11 at 22:06

In addition to what Martin has replied (and I would reiterate the non-requirement of the `.dtx` format), a very useful utility is Scott Pakin's `ctanify` script, which packages your stuff into a format specifically designed for upload to CTAN and inclusion into TeXLive. The script works out of the box on Linux and OS X and under Cygwin for Windows.

For example, a fairly simple package or class would likely have the following components:

• `mypackage.sty` (the package itself)
• `mypackage.tex` (the package documentation source)
• `mypackage.pdf` (the compiled package documentation)
• `README` (a plain text README file (with no extension))

Using `ctanify` all I need to do is issue the following command (assuming I'm within the directory of the package):

``````ctanify mypackage.* *.tex=doc README
``````

and this will produce a `tar.gz` file containing copies of all the files, plus a `.tds.zip` version of the files with the `.sty` file in `/tex/latex/mypackage`, the documentation in `/doc/latex/mypackage`. This latter file is used for TeXLive.

Here's a breakdown of the arguments I gave to the command:

``````mypackage.* % will automatically deal with .sty, .cls, .pdf, .dtx and .ins
*.tex=doc % put all .tex files into the doc folder
README % include the README file (will go into the /doc folder)
``````

I've just described the simple use. Of course if your package or class has a more complicated set of files, the command would need to be modified appropriately. For example, if you have `.tex` files that are part of the package itself and not part of the documentation you wouldn't use `*.tex` but would specify `mypackage.tex=doc` for the documentation source and a separate specification for the other `.tex` files.

-
Alan, many thanks, a useful complement to Martin's answer –  Brent.Longborough Aug 7 '11 at 20:37
@Brent: Indeed, I use `ctanify` myself. It is very useful to produce the TDS ZIP file and the final tar.gz file. –  Martin Scharrer Aug 7 '11 at 20:58