Additional Information for CTAN Uploaders

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

  1. CTAN's help page “How can I upload a package?”,
  2. the TeX Live instructions, and
  3. the corresponding article of the UK 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.

We do however not impose any definite upper limit on the number of directory levels in a package's layout as there seems to be no upper bound to packages' complexity. Please contact the CTAN team for advice if your package is very complex and you are in doubt about how best to arrange your material.

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. https://ctan.org/pkg/… (where the “…” equal the “package id”) if you are interested in information about the package, and
  2. https://mirrors.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 the 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 these “canonical URLs” are intended to be permanent.

The CTAN team

At the moment, the following persons (in alphabetical order) take 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 address

All CTAN-related correspondence should be directed in English to ctan (at) ctan (dot) org, the common email address of all “CTAN people”, rather than to an individual maintainer. This way (a) the whole team is informed about what is going on and (b) you are more likely to receive a fairly quick response to your enquiry. (Always consider that no CTAN member can be available all the time.)

Please take care that the emails you send to this address are plain text only, without any HTML part, 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. (If you are using gmail, you can select “plain text mode” clicking on the “more options” triangle in the bottom right corner of the window where you are composing your message. Also, your “gmails” will always be sent in plain text mode when you access google's webmail via the “basic HTML view” interface.)

Never try to upload (or re-upload) by email, always use the upload form, for the following reasons: (a) The many recipients of these emails are generally not happy to see their mailboxes bloated with 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) in the preceding paragraph.

More requirements on your upload …

  1. Conditions on filenames:
    1. Filenames must not contain any spaces, tabs, newlines, or other whitespace characters because filenames with whitespaces in them can make work on a UNIX command line extremely awkward.
    2. Filenames must not contain any non-ascii characters, for portability reasons.
    3. Filenames must not contain any characters that have a special meaning for UNIX shells (or other systems), such as question, exclamation, and quotation marks, asterisks, ampersands, apostrophes, slashes, backslashes, pipe symbols, dollar signs, any sort of brackets, and parentheses.
    4. Filenames must not start with a dot (“invisible files” in UNIX-like operating systems).
    5. 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”.
    6. You may however be pleased to learn that we have not been asking for MS-DOS-style 8.3 filenames for a long time ;-)
  2. Conditions on package ids:

    Every CTAN package is uniquely identified by its “package id”, which appears, for instance, as the last part in URLs like https://ctan.org/pkg/geometry (here “geometry” is the package's id.)

    1. Of course, all the conditions on filenames described above also apply to package ids.
    2. Moreover, package ids have to be all lowercase, they must not start with a digit, and they should be at least 4 characters long.
    3. To ease some of the harshness of the previous rule, package names have been introduced which can be seen at the beginning of the title line of their “CTAN home page”. For instance, at the top of https://ctan.org/pkg/arsclassica you see “ArsClassica”, at the top of https://ctan.org/pkg/mathtype you see “MathType”, at the top of https://ctan.org/pkg/one2many you see “12many”, etc. Of course, the CTAN team prefer, for the sake of simplicity, to have “package name = package id”, but small variants like CamelCase are accepted for the “names”.
    4. CTAN and TeX Live have a preference for hyphens in package ids, rather than underscores. There are at the moment (November 2024) 1493 Catalogue entries with a hyphen in their name vs. 10 with an underscore. You will therefore have to give very good reasons if you want us to accept the 11th package with an underscore in its id ;-) .
    5. Package ids starting with “l3” are reserved for official LaTeX Project expl3 packages. Package authors are encouraged to consider using “lt3...” for third-party expl3 packages.
    6. New packages and bundles should not be named after their authors, but after the purpose they are serving, because they may later be taken over by other maintainers. (We know that there are a few well established CTAN packages that do not fulfill this rule; but that comes under “protection of vested rights”, and we have now learned from history.)
    7. In the same way, “cryptic” package ids like “acs”, “mxd”, “tpx”, or “tcvn” are nowadays strongly discouraged. Modern package ids should as best as possible convey to the average user an idea of what the package is about.
  3. Version identifier:

    Every submission of every CTAN package has to contain a “version identifier” that permits to distinguish this version of the package from earlier or later ones. (Mind that what counts here are the actual installations on the archive; submissions that were for some reason refused and never installed may be neglected.) This identifier should of course coincide with the one you will later enter into the “Version” field of the upload form.

    This version identifier may consist of

    1. Either (only) a version number, i.e. something like “1.0”, or “3.0.17”, or “2.1a”,
    2. or (only) a version date (i.e.: the release date), preferably in YYYY-MM-DD or YYYY/MM/DD notation, like “2018-12-06” or “2018/12/06”,
    3. or a string consisting of both the aforementioned data.

    For simple LaTeX packages, the optional argument of the \ProvidesPackage or \ProvidesClass command of the .sty or .cls file should be a good place where to put this information.

    For bundles that consist of various files with possibly different version identifiers of their own, the whole bundle should be marked with a “bundle version identifier” referring to the bundle 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. 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.

    Please note that in our mind the documentation is considered part of the “package”. So even if “only” a tiny detail of the documentation (and nothing whatever in the “runtime files”!) has changed, the version number, if it is part of the version identifier, has to increase at least slightly.

  4. 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.

      There are however some exceptions to this rule:

      • The PDF files of the documentation: We do indeed wish to keep these, ready for immediate access by visitors, alongside with their sources.

      • README files: Even in cases where they can be generated from other sources, we want to keep them unpacked, as a convenient starting point for inspecting the package.

        Please note that we do not recommend, and in fact would like to discourage, “generated” README files, mainly because we have observed that such “generated” README files are often stale with respect to their source .dtx files; it is easy to forget to update them.

      • The same holds for generated .ins files.
  5. No auxiliary files:

    This concerns operating system specific data (like __MACOSX directories and .DS_Store files), .git, .gitignore, .hgignore, .hgtags, editor backup files (.backup, .bak, .sav, .~, …), as well as “leftovers” from TeX & friends and other programs ( .aux .log .acn .acr .alg .bbl .bcf .blg .brf .cb2 .cb .cpt .dvi .ent .fdb_latexmk .fff .fls .fmt .fot .gaux .glg .glo .glog .gls .glsdefs .gtex .hd .idv .idx .ilg .ind .lg .loa .lod .lof .lol .los .lot .lox .maf .mlf .mlt .mtc .nav .nlg .nlo .nls .o .obj .out .pdfsync .pre .pyg .run.xml .snm .soc .spl .sta .swp .synctex .synctex.gz .tdo .thm .tmb .tmp .toc .tpt .trc .ttt .tuc .upa .upb .url .vrb .w18 .xdv .xray .xref .4ct .4tc ).

    And there are surely more that we have not yet encountered. Please leave them all out of your upload!

    Note for git users wishing to keep exported .zip files free from git-specific material: This can be achieved by creating, adding and committing a .gitattributes file containing lines like the following: 

               .gitignore     export-ignore
           .gitattributes export-ignore

    Hints for Mac OSX users: (a) The zip program from YemuZip and the standard command line zip program both permit to create zipfiles without Mac-specific metadata. (Mind that for YemuZip you have to choose the appropriate option!) (b) A user told us that “it is possible to tell Mac OSX's tar command line executable to avoid polluting the archive with OSX specific files, by setting the environment variable COPYFILE_DISABLE (to whatever value).”

  6. No empty files or directories:

    We tend to consider empty files and directories as unnecessary leftovers. 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.

  7. 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.)
  8. 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 Mac OS X 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 you are a Windows user, you need not be alarmed, as there is an easy way to comply 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 GNOME archive manager, the Compress facility accessible via the File menu in Mac OS X's Finder, and the feature that permits to export zip files directly from git repositories do not seem to have the desired property. (Please correct us if there has been recently some positive development we are not aware of by writing us an email!)

    However, 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). The command line zipinfo utility is extremely useful for checking zip archives once they have been created.

    Unfortunately, tar does not offer the “tagging” 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.)
  9. “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.

  10. Rules about README files:
    1. Every package shall be accompanied by a README file giving a short introduction to the package's purpose as well as significant data like author's name and contact, license etc.
    2. Its name can be either README or README.txt or README.md, but no other variants are permitted at the moment.
    3. Its contents must be easily readable using the UNIX more or less commands or an arbitrary editor.
    4. It should be written in English or at least comprise a short abstract in English.
    5. The encoding should be ascii or utf-8 without BOM (byte order mark).
    6. It has to be placed at the top level of the unpacked package (but in the doc/…/ directory of a possible .tds.zip file).

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 on our help page. – Do not forget the top level directory of the upload file (“my-package/” in the examples). 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” (https://ctan.org/pkg/<package_id>) 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 field!

Please pay also particular attention to what you enter into the “Your email” field: In fact, we ask maintainers to use always the same email address when contacting the CTAN team. In particular, given the (improbable, but not completely unreal) danger of unauthorized uploaders overwriting “good” packages, we will refuse to install an update if it is not submitted using an email address known to the CTAN team. — BTW: Whenever you plan to change your “CTAN upload email address”, do not forget to drop a line to ctan (at) ctan (dot) org, still using the old address, and asking us to register the new one.

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, and have checked your spam folder to no avail, you may enquire by email to ctan (at) ctan (dot) org (remember: No HTML mail please, because of the spam trap!).

Thanks for your perseverance and good luck with your submission!

Some additional information about author ids and user accounts

Every author/maintainer of a CTAN package is registered in the database that is used for the administration of the archive itself with an author id that is assigned in the following way:

As a general rule, the author id equals the author's family name, downcased and with non-ascii characters converted to ascii. For instance, new author Benjamin Blümchen would receive the author id “bluemchen”.

If however another author of the same family name is already registered, the newer author's id will be modfied using the first letter(s) of his or her given name. For instance, if at a later time Hildegard Blümchen were to join us as an author, she would be registered as “bluemchen-h”.

These author ids must not be confused with the names of the user accounts on the CTAN website: The names of these user accounts can be chosen relatively freely, as long as uniqueness is assured.

A relation between a person's author id and their CTAN website user account can be established via the email address. In our webmaster's own words:

Once you are logged into the CTAN site and visit the page https://ctan.org/user/settings (link in the upper right corner), you will find the section “CTAN Contributor Confirmation” where you can confirm the relation between the author id and the current account by setting the check-mark. In the same way you can remove the relation by unchecking.

This feature is offered when one of the known email addresses in the author database matches the email address of the account (which can be edited on the same page).

Last updated: 2024-11-24