CTAN
Comprehensive TeX Archive Network

Ad­di­tional In­for­ma­tion for CTAN Upload­ers

Be­fore study­ing these ad­di­tional notes, you should have read and un­der­stood the fol­low­ing ba­sic texts:

  1. the “Prepa­ra­tion” sec­tion of CTAN's up­load page,
  2. the TeX Live in­struc­tions, and
  3. the cor­re­spond­ing ar­ti­cle of the UK TeX FAQ.

The fol­low­ing pa­per tries to give some back­ground in­for­ma­tion about CTAN it­self, fol­lowed by a list of more as­pects we ask you keep in mind when prepar­ing your up­load, some hints about how to use the up­load form and fi­nally in­for­ma­tion about what will hap­pen to your sub­mis­sion once it has ar­rived at our place.


Some back­ground in­for­ma­tion

Struc­ture of the net­work

The Com­pre­hen­sive TeX Archive Net­work con­sists of a cen­tral server at Cologne in Ger­many and a great num­ber of mir­rors all over the world.

All these servers should in prin­ci­ple present the same con­tent – an ideal that is of course reg­u­larly dis­turbed with ev­ery in­stal­la­tion of a new up­load; but ev­ery mir­ror should syn­chro­nize with the cen­tral server once ev­ery day, so that the ap­prox­i­ma­tion to that ideal is in­deed quite close.

Struc­ture of the archive

The greater part of the archive is taken up by what we re­fer to as the un­packed tree”. It is meant for be­ing vis­ited by means of a browser. To make this not too painful an ex­pe­ri­ence, the in­di­vid­ual sub­trees of this part of the archive are re­quired to be as “flat” as pos­si­ble, i.e. they should con­tain as few di­rec­tory lev­els as pos­si­ble, re­gard­less of the po­si­tion of the in­di­vid­ual files in a “real” TeX sys­tem.
We do how­ever not im­pose any def­i­nite up­per limit on the num­ber of di­rec­tory lev­els in a pack­age's lay­out as there seems to be no up­per bound to pack­ages' com­plex­ity. Please con­tact the CTAN team for ad­vice if your pack­age is very com­plex and you are in doubt about how best to ar­range your ma­te­rial.

In ad­di­tion to this there is what we call the in­stall tree”, which is a col­lec­tion of .tds.zip files.

Please note that ev­ery pack­age on the archive must be present in the “un­packed” part. The .tds.zip files are op­tional ad­di­tions that may be use­ful for big and com­plex pack­ages, but are in no way re­quired by the CTAN team, whereas we do not ac­cept up­loads that con­tain noth­ing but a .tds.zip file.

URLs

There are many ways of re­fer­ring to CTAN pack­ages on the in­ter­net, but our pre­ferred, “canon­i­cal” ones are of the fol­low­ing form:

  1. http://www.ctan.org/pkg/… (where the “…” equal the pack­age name) if you are in­ter­ested in in­for­ma­tion about the pack­age, and
  2. http://mir­ror.ctan.org/… (where the “…” equal the “path” to the pack­age's files on the archive) if you are in­ter­ested in the pack­age it­self.

In par­tic­u­lar, URLs con­tain­ing the string “tex-archive ” are gen­er­ally “sus­pi­cious”, be­cause they usu­ally re­fer to the cen­tral server, and we try des­per­ately to redi­rect down­load de­mands from the cen­tral server to the mir­rors. More­over, the in­di­vid­ual servers and their ad­dresses may change over the times, whereas the “canon­i­cal URLs” are in­tended to be per­ma­nent.

The CTAN team

At the mo­ment, the fol­low­ing per­sons (in al­pha­bet­i­cal or­der) are tak­ing care of CTAN:

  • Erik Braun (up­load man­age­ment),
  • Ina Dau (up­load man­age­ment),
  • Man­fred Lotz (up­load man­age­ment),
  • Gerd Neuge­bauer (web de­vel­oper),
  • Pe­tra Rübe-Pugliese (up­load man­age­ment),
  • Rainer Schöpf (sys­tem ad­min­is­tra­tion and su­per­vi­sion of mir­rors),
  • Joachim Schrod (sys­tem ad­min­is­tra­tion).

All these peo­ple are act­ing as vol­un­teers in their spare time; so please do not get im­pa­tient if your re­quest does not re­ceive an im­me­di­ate an­swer: they may be held up by “real life” prob­lems or a sud­den in­rush of other up­loads.

Email ad­dresses

All CTAN re­lated cor­re­spon­dence should be di­rected in English to ctan (at) ctan (dot) org , the com­mon email ad­dress of all “CTAN peo­ple” con­cerned with up­load man­age­ment or sys­tem ad­min­is­tra­tion.

Please take care that the emails you send to this ad­dress are plain text only, with­out any HTML part, be­cause HTML mails are held in CTAN's spam fil­ter and it may take some time un­til a post­mas­ter comes along to set them free. (If you are us­ing gmail, you can se­lect “plain text mode” click­ing on the “more op­tions” tri­an­gle in the bot­tom right cor­ner of the win­dow where you are com­pos­ing your mes­sage.)

Never try to up­load (or re-up­load) by email, al­ways use the up­load form , for the fol­low­ing rea­sons: (a) The many re­cip­i­ents of these mails are gen­er­ally not happy to see their mail­boxes bloated with soft­ware con­tri­bu­tions, (b) email at­tach­ments end up on the wrong com­puter and we have to per­form an ad­di­tional file trans­fer, and (c) up­loads via the up­load form very con­ve­niently gen­er­ate a num­ber of au­to­mated mails that help us with the doc­u­men­ta­tion of our ac­tiv­i­ties and can be eas­ily con­verted to ac­knowl­edge­ment mails and an­nounce­ments.

More gen­er­ally, no big at­tach­ments should be sent to this email ad­dress, mainly be­cause of ar­gu­ment (a) above.


More re­quire­ments on your up­load …

  1. Con­di­tions on file­names:
    1. File­names should not con­tain any spaces, tabs, new­lines, or other whites­pace char­ac­ters be­cause file­names with whites­paces in them can make work on a UNIX com­mand line ex­tremely awk­ward.
    2. File­names should not con­tain any non-ascii char­ac­ters, for porta­bil­ity rea­sons.
    3. File­names should not con­tain any char­ac­ters that have a spe­cial mean­ing for UNIX shells (or other sys­tems), such as ex­cla­ma­tion and ques­tion marks, as­ter­isks, am­per­sands, slashes, back­slashes, pipe sym­bols, dol­lar signs, any sort of brack­ets, and paren­the­ses.
    4. TeX Live wishes at least pack­age and di­rec­tory names to be all low­er­case” in­stead of “MixedCase”(“CamelCase”), and CTAN shares this wish for the sake of sim­plic­ity.
    5. New pack­ages and bun­dles should not be named af­ter their au­thors, but af­ter what they are do­ing, be­cause they may be taken over later by other main­tain­ers. (We know that there are a few well es­tab­lished pack­ages that do not ful­fill this rule; but that comes un­der “pro­tec­tion of vested rights”, and we have now learned from his­tory.)
    6. There is an in­ter­nal tech­ni­cal re­stric­tion which for­bids that our “pack­age ids” (which equal the xxxx in http://www.ctan.org/pkg/xxxx ) start with a digit. We usu­ally choose the “pack­age id” equal to the “pack­age name”, which makes things nice and sim­ple. If you in­sist how­ever on a pack­age name start­ing with a digit, we will have to choose a “pack­age id” other than the “pack­age name”, which may cause some con­fu­sion.
      (Ex­am­ple: The pack­age “12many” has the pack­age id “one2­many”.)
    7. Unique file­names: This topic has been dealt with in de­tail in two of the three “ba­sic texts” men­tioned above, es­pe­cially with re­gard to “run­time files”. — Let's add here (a) that unique­ness of file­names over the whole archive would in­deed be our ideal (that is of course im­pos­si­ble to achieve – think of stan­dard­ised names like “README” and “Make­file”!); but nev­er­the­less that ideal should at least be ap­proached as closely as pos­si­ble. In par­tic­u­lar, we strongly rec­om­mend unique­ness of file­names within ev­ery sin­gle pack­age. Am­bi­gu­ity is never a good thing, and it may prove harm­ful in un­ex­pected sit­u­a­tions.
      (b) Let us re­mind you that there are op­er­at­ing sys­tems un­able to dis­tin­guish be­tween my­file and MyFile . That's why we check for “iden­ti­cal file­names” af­ter con­vert­ing ev­ery­thing to “low­er­case”.
    8. You may how­ever be pleased to learn that we have not been ask­ing for 8.3 file­names for a long time ;-) .
  2. In­creas­ing ver­sion num­ber:
    Every sub­mis­sion of ev­ery pack­age or bun­dle should con­tain a ver­sion num­ber and/or date that per­mits to dis­tin­guish this ver­sion of the soft­ware from ear­lier or later ones. This num­ber should of course co­in­cide with the one you will later en­ter into the cor­re­spond­ing field of the up­load form.
    For sim­ple LaTeX pack­ages, the \Pro­videsPack­age or \Pro­videsClass com­mand of the .sty or .cls file should be the in­di­cated place where to put this in­for­ma­tion.
    For bun­dles that con­sist of var­i­ous files with pos­si­bly dif­fer­ent ver­sion num­bers of their own, the whole bun­dle should be marked by a “ver­sion in­di­ca­tor” re­fer­ring to the bun­dle as a whole. A good way to achieve this is “tag­ging” the bun­dle with the date of the lat­est change of any of its files (even if it's “only” a file be­long­ing to the doc­u­men­ta­tion!). Put this “tag” into a place where it is easy to find, such as the lat­est en­try of a Changes file, a VERSION file or an eas­ily ac­ces­si­ble place (prefer­ably: the top part) in the README file.
  3. Low re­dun­dancy:
    Be­cause of the well known dis­ad­van­tages of re­dun­dancy – es­pe­cially the risk of in­con­sis­tency! – we try to keep it as low as pos­si­ble on the un­packed archive. In par­tic­u­lar …
    1. … we do not wish to hold iden­ti­cal copies of one and the same file (“du­pli­cate files”) in dif­fer­ent places, such as for in­stance README and doc/README .
      If you re­ally think you need copies of a file in other places, then please re­place these copies with sym­bolic links (a.k.a. sym­links or soft­links) point­ing to the “orig­i­nal” file. — Be­ware: When pack­ing your up­load file with zip , you will have to call it with the --sym­links op­tion (or some­thing equiv­a­lent, de­pend­ing on your par­tic­u­lar zip pro­gram) if you do not want the sym­link to be re­placed by a copy of the orig­i­nal file again!
      (Mind that this re­quest con­cerns only the un­packed part and that a sim­i­lar rec­om­men­da­tion does not hold for the con­tents of .tds.zip files: .tds.zip files are sup­posed to be un­packed with­out prob­lems on ar­bi­trary plat­forms, and this can­not be guar­an­teed if they con­tain sym­bolic links!)
    2. … we do not wish to hold files that can be eas­ily gen­er­ated” (“de­rived”) from other files con­tained in the sub­mis­sion. The stan­dard ex­am­ples of this are .cls , .sty , .clo , .fd or sim­i­lar LaTeX files, when they can be gen­er­ated from their .dtx source in a straight­for­ward way.
      The ex­cep­tion to this rule are the .pdf files of the doc­u­men­ta­tion: We do in­deed wish to keep these, ready for im­me­di­ate ac­cess by vis­i­tors, along­side with their sources.
      The same holds for README files in cases where these, too, can be gen­er­ated from other sources: We al­ways want the README un­packed, as a con­ve­nient start­ing point for in­spect­ing the pack­age.
  4. No aux­il­iary files:
    This con­cerns op­er­at­ing sys­tem spe­cific data (like __MACOSX di­rec­to­ries and .DS_Store files), .git , .git­ig­nore , .hgig­nore , .hg­tags , ed­i­tor backup files, as well as “left­overs” from TeX & friends and other pro­grams (.aux , .log , .bbl , .bcf , .blg , .brf , .ilg , .ind , .idx , .glo , .loa , .lof , .lot , .nav , .out , .snm , .vrb , .toc , .dvi , .glg , .gls , .tmp , .o , .bak , .swp , .sync­tex , and po­ten­tially oth­ers we have not yet en­coun­tered): Please leave them out of your up­load!
  5. No empty files or di­rec­to­ries:
    We tend to con­sider empty files and di­rec­to­ries as “rub­bish”. If you feel oth­er­wise and wish to con­serve such files for sys­tem­atic rea­sons, we rec­om­mend fill­ing them with some com­ment (in the case of “reg­u­lar files”) or a place­holder file (in the case of di­rec­to­ries) ex­plain­ing their pur­pose.
    If this is not pos­si­ble be­cause the pro­gram us­ing these files would get dis­turbed by com­ments or “dummy files”, please men­tion this in the “Ad­min­is­tra­tive notes” field of the up­load form so that we can make a note of this ex­cep­tion and do not bother you with un­nec­es­sary com­plaints.
  6. File per­mis­sions:
    1. Only files that are truly ex­e­cutable (like Shell, Perl, Python, Ruby, and other scripts) should be marked as such. An “ex­e­cutable” README or .tex file does not make any sense.
    2. Files sub­mit­ted to CTAN are ob­vi­ously meant for pub­li­ca­tion. This im­plies that they should be “world read­able”. (In fact, ex­ag­ger­ated “pri­vacy” of file per­mis­sions can lead to se­ri­ous com­pli­ca­tions in the in­stal­la­tion pro­cess.)
  7. Line ter­mi­na­tors of text files:
    This para­graph is about text files (like .txt , .tex , .sty , .cls , .dtx , .fd , .bib , .c , or any other file that can be edited with a text ed­i­tor) as op­posed to “bi­nary files” (such as .gif , .jpg , .wav , .mp3 , .ogg , .tfm , .pdf , .doc , .xls , .exe , and a mul­ti­tude of oth­ers).
    The prob­lem with such text files is that dif­fer­ent op­er­at­ing sys­tems have dif­fer­ent ways of mark­ing the line end­ings within them: Whereas Mi­crosoft sys­tems de­scribe a line end­ing in the good old type­writer fash­ion by a “car­riage re­turn” char­ac­ter fol­lowed by a “line feed” char­ac­ter, UNIX type op­er­at­ing sys­tems have al­ways omit­ted the “car­riage re­turn”, and mod­ern Mac OS X sys­tems do it the same way.
    As CTAN's servers are run­ning on UNIX-like op­er­at­ing sys­tems, the CTAN team have de­cided that all text files on the archive should have suit­able “line­feed only” line ter­mi­na­tors.
    Now, if you are a Win­dows user, you need not be alarmed, as there is an easy way to com­ply with this wish, with hardly any in­con­ve­nience for your­self: If you pack your up­load file with a “good zip pro­gram”, this will mark all text files with a spe­cial “flag” (or “tag”) that will per­mit CTAN's un­zip pro­gram to rec­og­nize these text files and per­form the nec­es­sary con­ver­sions (in this case: omit­ting the un­wanted “car­riage re­turn” char­ac­ters) au­to­mat­i­cally :-)
    Un­for­tu­nately, not all zip pro­grams are “good zip pro­grams” :-(
    In par­tic­u­lar, 7zip, the GNOME archive man­ager, the Com­press fa­cil­ity ac­ces­si­ble via the File menu in Mac OS X's Fin­der , and the fea­ture that per­mits to ex­port zip files di­rectly from git repos­i­to­ries do not seem to have the de­sired prop­erty. (Please cor­rect us if there has been re­cently some pos­i­tive de­vel­op­ment we are not aware of by writ­ing us an email!)
    How­ever, git users may want to have a look at the .gi­tat­tributes file for the con­fig­u­ra­tion of file types and line end­ings!
    Known “good zip pro­grams” are the Win­dows7ff. builtins, WinZip, Win­dows “To­tal Com­man­der”, and the zip­pers from info-zip.org.
    Mac users in need of a “good zip pro­gram” may ei­ther turn to Ye­muZip or the stan­dard zip com­mand on their com­mand line (which is in fact the info-zip tool that is also present in Linux sys­tems). The com­mand line zip­info util­ity is ex­tremely use­ful for check­ing zip archives once they have been cre­ated.
    Un­for­tu­nately, tar does not of­fer the “tag­ging” fea­ture in ques­tion.
    Fi­nally, there are two ex­cep­tions to what has been said be­fore:
    1. If your up­load con­tains any .bat or .cmd or .nsh or other typ­i­cal DOS/Win­dows files, and if you wish to pre­serve their CR+LF line end­ings, please drop us a line to that ef­fect in the “Ad­min­is­tra­tive notes (to the CTAN main­tain­ers)” field of our up­load page, and we will take care that this is done.
    2. All the .tds.zip files we of­fer on the archive are sup­posed to have noth­ing but UNIX style line ter­mi­na­tors in­side as well as the nec­es­sary .zip flags for un­pack­ing them in the best pos­si­ble way on any op­er­at­ing sys­tem. That's why we wish .tds.zip files to be sub­mit­ted in ex­actly that way. (If there should re­ally be a prob­lem that pre­vents you from com­ply­ing with this re­quire­ment, we may find a way to cor­rect this short­com­ing at our end, but we would of course much pre­fer not to have to re­sort to any such ma­nip­u­la­tions.)
  8. “Canon­i­cal” URLs in doc­u­men­ta­tion:
    Please make sure when writ­ing (or re­vis­ing) your doc­u­men­ta­tion that TeX soft­ware on CTAN archives is re­ferred to us­ing our pre­ferred “canon­i­cal” URLs de­scribed above rather that URLs point­ing to in­di­vid­ual CTAN servers. Thanks!
  9. Rules about README files:
    1. Every pack­age shall be ac­com­pa­nied by a README file giv­ing a short in­tro­duc­tion to the pack­age's pur­pose as well as sig­nif­i­cant data like au­thor's name and con­tact, li­cense etc.
    2. Its name can be ei­ther README or README.txt or README.md , but no other vari­ants are per­mit­ted at the mo­ment.
    3. Its con­tents must be eas­ily read­able us­ing the UNIX more or less com­mands or an ar­bi­trary ed­i­tor.
    4. It should be writ­ten in English or at least be headed by a short ab­stract in English.
    5. The en­cod­ing should be ascii or utf-8.
    6. It has to be placed at the top level of the un­packed pack­age (but in the doc/…/ di­rec­tory of a pos­si­ble .tds.zip file).

Upload­ing to CTAN

When you feel con­vinced that you have done all you can to com­ply with the re­quire­ments de­scribed up to now, you may go on to pack­age your sub­mis­sion us­ing ei­ther zip or tar , as de­scribed in the “Prepa­ra­tion” sec­tion of our up­load page. – Do not for­get the top level di­rec­tory of the up­load file (“xxx/ ” in our de­scrip­tion). It sim­pli­fies our in­stal­la­tion pro­cess and makes it more se­cure. – Please opt for a good zip pro­gram (in­stead of tar or any zip pro­gram) if you are not one hun­dred per­cent sure that none of your text files con­tains any “Mi­crosoft style” line ter­mi­na­tors!

If you want to sub­mit an up­date to a pack­age that is al­ready on CTAN, we rec­om­mend you to go first to its “CTAN home­page” (http://www.ctan.org/pkg/<pack­a­ge­name> ) and then click on the “Upload” but­ton. You will find that some of the more te­dious fields have al­ready been filled in with in­for­ma­tion from our Cat­a­logue :-)   But please do not for­get to up­date the ver­sion num­ber!

Please pay also par­tic­u­lar at­ten­tion to what you en­ter into the “Your email” field: In fact, we ask main­tain­ers to use al­ways the same email ad­dress when con­tact­ing the CTAN team. In par­tic­u­lar, given the (im­prob­a­ble, but not com­pletely un­real) dan­ger of unau­tho­rized up­load­ers over­writ­ing “good” pack­ages, we will refuse to in­stall an up­date if it is not sub­mit­ted us­ing an email ad­dress known to the CTAN team. — BTW: When­ever you plan to change your “CTAN up­load email ad­dress”, do not for­get to drop a line to ctan (at) ctan (dot) org, still us­ing the old ad­dress, and ask­ing us to reg­is­ter the new one.


What will hap­pen next …

  • Every up­load will be un­packed and checked by an up­load man­ager.
  • Small de­fi­cien­cies will be cor­rected im­me­di­ately by that per­son. You will re­ceive feed­back about this and be asked to ap­ply the same sort of change(s) to your own file(s) be­fore your next up­load.
  • If there is a non-triv­ial prob­lem we can­not or do not want to re­solve on our own, we will ask back and the in­stal­la­tion pro­cess will be mo­men­tar­ily stalled un­til we re­ceive an an­swer to our ques­tion. In some cases even a re-up­load may be­come nec­es­sary.
  • After in­stal­la­tion of the pack­age on the archive (i.e.: on our cen­tral server) the cor­re­spond­ing .xml source file of the Cat­a­logue en­try will ei­ther have to be cre­ated “from scratch” (for new pack­ages) or be up­dated (in all other cases; mostly only the ver­sion num­ber and/or date, some­times the copy­right line(s) or de­tails about the point­ers to the doc­u­men­ta­tion). Please use the “Ad­min­is­tra­tive notes (to the CTAN main­tain­ers)” field in the up­load form if you wish us to per­form any other changes.
  • When all of this has been done, we will send an email to the ad­dress you en­tered into the “Your email” field of the up­load form.
  • It may take up to 24 hours un­til the new files have ar­rived on all the mir­rors world­wide and un­til the Cat­a­logue page of the web­site has been re­gen­er­ated from the source file.
  • If your up­load is a new one or if you have re­quested an an­nounce­ment, the mes­sage to CTAN-An­nounce will be posted if pos­si­ble shortly af­ter the end of that 24 hour de­lay. There may how­ever be a fur­ther de­lay due to the main­tainer's work­ing hours or other en­gage­ments at that time. If the mes­sage has not got out even af­ter 48 hours, you may write a mes­sage to ctan@ctan.org to en­quire if any­thing has gone wrong.
  • It would be help­ful if you checked what you see at the URLs in­di­cated in the ac­knowl­edge­ment mails around 24 hours af­ter in­stal­la­tion and in­formed us about pos­si­ble flaws in the pre­sen­ta­tion.

Please do not re-up­load when you do not hear from us at once! There may have been a sud­den in­rush of up­loads and/or main­tain­ers may have been kept from at­tend­ing to your up­load by “real” work, fam­ily mat­ters, tech­ni­cal prob­lems, hol­i­days, ill­ness, or other causes. If you still haven't heard from us af­ter let's say three or four days, you may en­quire by email to ctan@ctan.org (re­mem­ber: No HTML mail please, be­cause of the spam trap!).

Thanks for your per­se­ver­ance and good luck with your sub­mis­sion!


Last Change: 2016-11-12
Guest Book Sitemap Contact Contact Author