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.
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.
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.
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 id”)
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 these “canonical URLs”
are intended to be permanent.
At the moment, the following persons
(in alphabetical order)
take care of CTAN:
-
Erik Braun
(upload management and system administration),
-
Ina Dau
(upload management),
-
Manfred Lotz
(upload management),
-
Gerd Neugebauer
(web developer),
-
Petra Rübe-Pugliese
(upload management).
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”,
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.
-
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 question, exclamation, and quotation marks,
asterisks, ampersands,
apostrophes,
slashes, backslashes, pipe symbols,
dollar signs,
any sort of brackets, and parentheses.
-
Filenames should
not start with a dot
(“invisible files” in UNIX-like
operating systems).
-
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”.
-
You may however be pleased
to learn that we have not been asking for
MS-DOS-style
8.3 filenames
for a long time ;-)
-
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.)
-
Of course, all the
conditions on filenames
described above
also apply to package ids.
-
Moreover, package ids have to be all
lowercase,
and they must
not start with a digit.
(To ease some of the harshness of this particular 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”.)
-
CTAN and TeX Live have a preference for
hyphens
in package ids, rather than underscores.
There are at the moment (February 2021)
1275 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 ;-) .
-
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.
-
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.)
-
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.
-
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
-
Either (only) a version
number,
i.e. something like
“1.0”, or
“3.0.17”, or
“2.1a”,
-
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”,
-
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.
-
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 …
-
…
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!)
-
…
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.
-
Generated .ins
files:
These are a recent development.
Having immediate access to them may be helpful to some users.
We therefore agree that they may be kept unpacked, too.
Indeed, one may be of the opinion that
keeping .ins files unpacked
should be generally recommended.
-
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,
.cb,
.cb2,
.ent,
.fdb_latexmk,
.fff,
.fls,
.fmt,
.fot,
.gaux,
.glog,
.gtex,
.ilg,
.ind,
.idx,
.glo,
.lg,
.loa,
.lod,
.lof,
.lol,
.los,
.lot,
.lox,
.nav,
.out,
.pre,
.pyg,
.snm,
.soc,
.toc,
.vrb,
.cpt,
.dvi,
.glg,
.gls,
.glsdefs,
.idv,
.maf,
.mlf,
.mlt,
.mtc,
.nlg,
.nlo,
.nls,
.spl,
.thm,
.tmb,
.tmp,
.tuc,
.upa,
.upb,
.o,
.sta,
.swp,
.tdo,
.trc,
.ttt,
.url,
.w18,
.xdv,
.xref,
.4ct,
.4tc,
.run.xml,
.pdfsync,
.synctex,
.synctex.gz,
and potentially others we have
not yet encountered):
Please leave them out of your upload!
Note for git users wishing to keep exported
.zip files “git rubbish free”:
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 MacOSX-rubbish-free
zipfiles. (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).”
-
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.
-
File permissions:
-
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.
-
Rules about README files:
-
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
without BOM (byte order mark).
-
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
(“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.
-
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 field,
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 a few hours until the
Catalogue page
of the website
has been regenerated from the source file,
and up to 24 hours
until the new files have arrived
on all the
mirrors
worldwide.
-
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 appeared
after more than 48 hours,
you should write a message to
ctan (at) ctan (dot) org
to enquire if anything has gone wrong.
-
It is always helpful if you
check what you see
at the URLs indicated in the acknowledgement mail
around 24 hours after installation and
inform us
about any 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,
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!
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: 2021-02-15