Additional Information for CTAN Uploaders

Before studying these additional notes, you should have read and understood the following basic texts:

  1. the “Preparation” section of CTAN's upload page,
  2. the TeX Live instructions , and
  3. the corresponding article of the English TeX-FAQ .

The following paper tries to give some background information about CTAN itself, followed by a list of more aspects we ask you keep in mind when preparing your upload, some hints about how to use the upload form and finally information about what will happen to your submission once it has arrived at our place.

Some background information

Structure of the network

The Comprehensive TeX Archive Network consists of a central server at Cologne in Germany and a great number of mirrors all over the world.

All these servers should in principle present the same content – an ideal that is of course regularly disturbed with every installation of a new upload; but every mirror should synchronize with the central server once every day, so that the approximation to that ideal is indeed quite close.

Structure of the archive

The greater part of the archive is taken up by what we refer to as the “unpacked tree”. It is meant for being visited by means of a browser. To make this not too painful an experience, the individual subtrees of this part of the archive are required to be as “flat” as possible, i.e. they should contain as few directory levels as possible, regardless of the position of the individual files in a “real” TeX system.

In addition to this there is what we call the “install tree”, which is a collection of .tds.zip files.

Please note that every package on the archive must be present in the “unpacked” part. The .tds.zip files are optional additions that may be useful for big and complex packages, but are in no way required by the CTAN team, whereas we do not accept uploads that contain nothing but a .tds.zip file.

URLs

There are many ways of referring to CTAN packages on the internet, but our preferred, “canonical” ones are of the following form:

  1. http://www.ctan.org/pkg/… (where the “…” equal the package name) if you are interested in information about the package, and
  2. http://mirror.ctan.org/… (where the “…” equal the „path” to the package's files on the archive) if you are interested in the package itself.

In particular, URLs containing the string “tex-archive” are generally “suspicious”, because they usually refer to a central server, and we try desperately to redirect download demands from the central server to the mirrors. Moreover, the individual servers and their addresses may change over the times, whereas the “canonical URLs” are intended to be permanent.

The CTAN team

At the moment, the following persons (in alphabetical order) are taking care of CTAN:

All these people are acting as volunteers in their spare time; so please do not get impatient if your request does not receive an immediate answer: they may be held up by „real life” problems or a sudden inrush of other uploads.

Email addresses

All CTAN related correspondence should be directed to ctan (at) dante (dot) de – or ctan (at) ctan (dot) org, which is an alias to the preceding one –, the common email address of all „CTAN people” concerned with upload management or system administration.

Please take care not to send any HTML mails to these addresses, because HTML mails are held in CTAN's spam filter, and it may take some time until a postmaster comes along to set them free.

Never try to upload (or re-upload) by email, always use the upload form , for the following reasons: (a) The many recipients of these mails are generally not happy to see their mailboxes bloated by software contributions, (b) email attachments end up on the wrong computer and we have to perform an additional file transfer, and (c) uploads via the upload form very conveniently generate a number of automated mails that help us with the documentation of our activities and can be easily converted to acknowledgement mails and announcements.

More generally, no big attachments should be sent to this email address, mainly because of argument (a) above.

More requirements on your upload …

  1. Conditions on filenames:
    1. Filenames should not contain any spaces, because filenames with spaces in them can make work on a UNIX command line extremely awkward.
    2. Filenames should not contain any non-ascii characters, for portability reasons.
    3. Filenames should not contain any characters that have a special meaning for UNIX shells (or other systems), such as question marks, asterisks, slashes, backslashes, brackets, and parentheses.
    4. TeX Live wishes at least package and directory names to be “all lowercase” instead of “MixedCase”(“CamelCase”), and CTAN shares this wish for the sake of simplicity.
    5. New packages and bundles should not be named after their authors, but after what they are doing, because they may be taken over later by other maintainers. (We know that there are a few well established packages that do not fulfill this rule; but that comes under “protection of vested rights”, and we have now learned from history.)
    6. There is an internal technical restriction which forbids that our “package ids” (which equal the xxxx in http://www.ctan.org/pkg/xxxx) start with a digit. We usually choose the “package id” equal to the “package name”, which makes things nice and simple. If you insist however on a package name starting with a digit, we will have to choose a “package id” other than the “package name”, which may cause some confusion.
      (Example: The package „12many” has the package id „one2many”.)
    7. Unique filenames: This topic has been dealt with in detail in two of the three “basic texts” mentioned above, especially with regard to “runtime files”. — Let's add here (a) that uniqueness of filenames over the whole archive would indeed be our ideal (that is of course impossible to achieve – think of standardised names like “README” and “Makefile”!); but nevertheless that ideal should at least be approached as closely as possible. In particular, we strongly recommend uniqueness of filenames within every single package. Ambiguity is never a good thing, and it may prove harmful in unexpected situations.
      (b) Let us remind you that there are operating systems unable to distinguish between myfile and MyFile. That's why we check for “identical filenames” after converting everything to “lowercase”.
    8. You may however be pleased to learn that we have not been asking for 8.3 filenames for a long time ;-) .
  2. Increasing version number:
    Every submission of every package or bundle should contain a version number and/or date that permits to distinguish this version of the software from earlier or later ones. This number should of course coincide with the one you will later enter into the corresponding field of the upload form.
    For simple LaTeX packages, the \ProvidesPackage or \ProvidesClass command of the .sty or .cls file should be the indicated place where to put this information.
    For bundles that consist of various files with possibly different version numbers of their own, the whole bundle should be marked by a “version indicator” referring to the package as a whole. A good way to achieve this is “tagging” the bundle with the date of the latest change of any of its files (even if it's “only” a file belonging to the documentation!). Put this “tag” into a place where it is easy to find, such as the latest entry of a Changes file, a VERSION file or an easily accessible place (preferably: the top part) in the README file.
  3. Low redundancy:
    Because of the well known disadvantages of redundancy – especially the risk of inconsistency! – we try to keep it as low as possible on the unpacked archive. In particular …
    1. … we do not wish to hold identical copies of one and the same file (“duplicate files”) in different places, such as for instance README and doc/README.
      If you really think you need copies of a file in other places, then please replace these copies with symbolic links (a.k.a. symlinks or softlinks) pointing to the “original” file. — Beware: When packing your upload file with zip, you will have to call it with the --symlinks option (or something equivalent, depending on your particular zip program) if you do not want the symlink to be replaced by a copy of the original file again!
      (Mind that this request concerns only the unpacked part and that a similar recommendation does not hold for the contents of .tds.zip files: .tds.zip files are supposed to be unpacked without problems on arbitrary platforms, and this cannot be guaranteed if they contain symbolic links!)
    2. … we do not wish to hold files that can be easily “generated” (“derived”) from other files contained in the submission. The standard examples of this are .cls, .sty, .clo, .fd or similar LaTeX files, when they can be generated from their .dtx source in a straightforward way.
      The exception to this rule are the .pdf files of the documentation: We do indeed wish to keep these, ready for immediate access by visitors, alongside with their sources.
      The same holds for README files in cases where these, too, can be generated from other sources: We always want the README unpacked, as a convenient starting point for inspecting the package.
  4. No auxiliary files:
    This concerns operating system specific data (like __MACOSX directories and .DS_Store files), .gitignore, .hgignore, .hgtags, editor backup files, as well as “leftovers” from TeX & friends and other programs (.aux, .log, .bbl, .bcf, .blg, .brf, .ilg, .ind, .idx, .glo, .loa, .lof, .lot, .nav, .out, .snm, .vrb, .toc, .dvi, .glg, .gls, .tmp, .o, .bak, and potentially others we have not yet encountered): Please leave them out of your upload!
  5. No empty files or directories:
    We tend to consider empty files and directories as “rubbish”. If you feel otherwise and wish to conserve such files for systematic reasons, we recommend filling them with some comment (in the case of “regular files”) or a placeholder file (in the case of directories) explaining their purpose.
    If this is not possible because the program using these files would get disturbed by comments or “dummy files”, please mention this in the “Administrative notes” field of the upload form so that we can make a note of this exception and do not bother you with unnecessary complaints.
  6. File permissions:
    1. Only files that are truly executable (like Shell, Perl, Python, Ruby, and other scripts) should be marked as such. An “executable” README or .tex file does not make any sense.
    2. Files submitted to CTAN are obviously meant for publication. This implies that they should be “world readable”. (In fact, exaggerated “privacy” of file permissions can lead to serious complications in the installation process.)
  7. Line terminators of text files:
    This paragraph is about “text files” (like .txt, .tex, .sty, .cls, .dtx, .fd, .bib, .c, or any other file that can be edited with a text editor) as opposed to “binary files” (such as .gif, .jpg, .wav, .mp3, .ogg, .tfm, .pdf, .doc, .xls, .exe, and a multitude of others).
    The problem with such text files is that different operating systems have different ways of marking the line endings within them: Whereas Microsoft systems describe a line ending in the good old typewriter fashion by a “carriage return” character followed by a “line feed” character, UNIX type operating systems have always omitted the “carriage return”, and modern MacOSX systems do it the same way.
    As CTAN's servers are running on UNIX-like operating systems, the CTAN team have decided that all text files on the archive should have suitable “linefeed only” line terminators.
    Now, if your are a Windows user, you need not be alarmed, as there is an easy way of complying with this wish, with hardly any inconvenience for yourself: If you pack your upload file with a “good zip program”, this will mark all text files with a special “flag” (or “tag”) that will permit CTAN's unzip program to recognize these text files and perform the necessary conversions (in this case: omitting the unwanted “carriage return” characters) automatically :-)
    Unfortunately, not all zip programs are “good zip programs” :-(
    In particular, 7zip, the feature that permits to export zip files directly from git repositories, and the GNOME archive manager do not seem to have the desired property. (Please correct us if there has been some positive recent development we are not aware of by writing us an email!)
    But: git users may want to have a look at the .gitattributes file for the configuration of file types and line endings!
    Known “good zip programs” are the Windows7ff. builtins, WinZip, Windows “Total Commander”, and the zippers from info-zip.org .
    Mac users in need of a “good zip program” may either turn to YemuZip or the standard zip command on their command line (which is in fact the info-zip tool that is also present in Linux systems).
    Unfortunately, tar does not offer the feature in question!
    Finally, there are two exceptions to what has been said before:
    1. If your upload contains any .bat or .cmd or .nsh or other typical DOS/Windows files, and if you wish to preserve their CR+LF line endings, please drop us a line to that effect in the “Administrative notes (to the CTAN maintainers)” field of our upload page, and we will take care that this is done.
    2. All the .tds.zip files we offer on the archive are supposed to have nothing but UNIX style line terminators inside as well as the necessary .zip flags for unpacking them in the best possible way on any operating system. That's why we wish .tds.zip files to be submitted in exactly that way. (If there should really be a problem that prevents you from complying with this requirement, we may find a way to correct this shortcoming at our end, but we would of course much prefer not to have to resort to any such manipulations.)
  8. “Canonical” URLs in documentation:
    Please make sure when writing (or revising) your documentation that TeX software on CTAN archives is referred to using our preferred “canonical” URLs described above rather that URLs pointing to individual CTAN servers. Thanks!

Uploading to CTAN

When you feel convinced that you have done all you can to comply with the requirements described up to now, you may go on to package your submission using either zip or tar, as described in the “Preparation” section of our upload page. – Do not forget the top level directory of the upload file (“xxx/” in our description). It simplifies our installation process and makes it more secure. – Please opt for a good zip program (instead of tar or any zip program) if you are not one hundred percent sure that none of your text files contains any “Microsoft style” line terminators!

If you want to submit an update to a package that is already on CTAN, we recommend you to go first to its “CTAN homepage” (http://www.ctan.org/pkg/<packagename>) and then click on the “Upload” button. You will find that some of the more tedious fields have already been filled in with information from our Catalogue :-)   But please do not forget to update the version number!

Please pay also particular attention to what you enter into the “Your email” field: In fact, we have an internal, confidential list, where every “uploader” is registered with one (and only one!) email address. We will refuse to install an update if it is not submitted using exactly that address because of the (improbable, but not completely unreal) danger of unauthorized uploaders overwriting “good” packages.

What will happen next …

Please do not re-upload when you do not hear from us at once! There may have been a sudden inrush of uploads and/or maintainers may have been kept from attending to your upload by “real” work, family matters, technical problems, holidays, illness, or other causes. If you still haven't heard from us after let's say three or four days, you may enquire by email to ctan@dante.de / ctan@ctan.org (remember: No HTML mail please, because of the spam trap!).

Thanks for your perseverance and good luck with your submission!

Last Change: 2015-06-07