Additional Information for CTAN Uploaders
Before studying these additional notes, you should have read and understood the following basic texts:
- CTAN's help page “How can I upload a package?”,
- the TeX Live instructions, and
- 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.
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.
The greater part of the archive
is taken up by what we refer to as the
It is meant for being visited by means of a
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
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.
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.
There are many ways of referring to CTAN packages on the internet, but our preferred, “canonical” ones are of the following form:
- https://ctan.org/pkg/… (where the “…” equal the package name) if you are interested in information about the package, and
- 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 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 the “canonical URLs” are intended to be permanent.
At the moment, the following persons (in alphabetical order) are taking care of CTAN:
- Erik Braun (upload management),
- Ina Dau (upload management),
- Manfred Lotz (upload management),
- Gerd Neugebauer (web developer),
- Petra Rübe-Pugliese (upload management),
- Rainer Schöpf (system administration and supervision of mirrors),
- Joachim Schrod (system administration).
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.
All CTAN related correspondence should be directed in English to ctan (at) ctan (dot) org , the common email address of all “CTAN people” concerned with upload management or system administration.
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.)
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 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.
Conditions on filenames:
- Filenames should 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.
- Filenames should not contain any non-ascii characters, for portability reasons.
- Filenames should not contain any characters that have a special meaning for UNIX shells (or other systems), such as exclamation and question marks, asterisks, ampersands, slashes, backslashes, pipe symbols, dollar signs, any sort of brackets, and parentheses.
- 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.)
There is an internal technical restriction
which forbids that our
(which equal the xxxx
start with a
We usually choose the
equal to the
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”.) — Please note also that our “package ids” are always all lowercase, whereas “package names” may be “CamelCase”.
This topic has been dealt with in detail
in two of the three
mentioned above, especially with regard to
Let's add here
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”
but nevertheless that ideal should
at least be approached as closely as possible.
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”.
- You may however be pleased to learn that we have not been asking for 8.3 filenames for a long time ;-) .
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 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 (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.
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 …
we do not wish to hold
identical copies of one and the same file
in different places,
such as for instance
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!)
we do not wish to hold files
that can be easily
from other files contained in the submission.
The standard examples of this are
or similar LaTeX files,
when they can be generated from their
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.
- … 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 .
No auxiliary files:
This concerns operating system specific data (like __MACOSX directories and .DS_Store files), .git , .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 , .toc , .vrb , .dvi , .glg , .gls , .tmp , .o , .bak , .swp , .~ , .run.xml , .synctex , .synctex.gz , and potentially others we have not yet encountered): Please leave them out of your upload!
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.
- 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.
- 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.)
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:
- 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.
- 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.)
“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!
Rules about README
- 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.
- Its name can be either README or README.txt or README.md , but no other variants are permitted at the moment.
- Its contents must be easily readable using the UNIX more or less commands or an arbitrary editor.
- It should be written in English or at least comprise a short abstract in English.
- The encoding should be ascii or utf-8.
- It has to be placed at the top level of the unpacked package (but in the doc/…/ directory of a possible .tds.zip file).
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 (“xxx/ ” 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/<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 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.
- Every upload will be unpacked and checked by an upload manager.
- Small deficiencies will be corrected immediately by that person. You will receive feedback about this and be asked to apply the same sort of change(s) to your own file(s) before your next upload.
- If there is a non-trivial problem we cannot or do not want to resolve on our own, we will ask back and the installation process will be momentarily stalled until we receive an answer to our question. In some cases even a re-upload may become necessary.
- After installation of the package on the archive (i.e.: on our central server) the corresponding .xml source file of the Catalogue entry will either have to be created “from scratch” (for new packages) or be updated (in all other cases; mostly only the version number and/or date, sometimes the copyright line(s) or details about the pointers to the documentation). Please use the “Administrative notes (to the CTAN maintainers)” field in the upload form if you wish us to perform any other changes.
- When all of this has been done, we will send an email to the address you entered into the “Your email” field of the upload form.
- It may take up to 24 hours until the new files have arrived on all the mirrors worldwide and until the Catalogue page of the website has been regenerated from the source file.
- If your upload is a new one or if you have requested an announcement, the message to CTAN-Announce will be posted if possible shortly after the end of that 24 hour delay. There may however be a further delay due to the maintainer's working hours or other engagements at that time. If the message has not got out even after 48 hours, you may write a message to firstname.lastname@example.org to enquire if anything has gone wrong.
- It would be helpful if you checked what you see at the URLs indicated in the acknowledgement mails around 24 hours after installation and informed us about possible flaws in the presentation.
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 email@example.com (remember: No HTML mail please, because of the spam trap!).
Thanks for your perseverance and good luck with your submission!
Last Change: 2017-11-24