diff options
Diffstat (limited to 'help/ctan/CTAN-upload-addendum.html')
-rw-r--r-- | help/ctan/CTAN-upload-addendum.html | 1515 |
1 files changed, 1515 insertions, 0 deletions
diff --git a/help/ctan/CTAN-upload-addendum.html b/help/ctan/CTAN-upload-addendum.html new file mode 100644 index 0000000000..7673be2cbd --- /dev/null +++ b/help/ctan/CTAN-upload-addendum.html @@ -0,0 +1,1515 @@ +<?xml version="1.0" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Additional Information for CTAN Uploaders</title> + <!-- + <link rel="stylesheet" type="text/css" href="tugstyle.css" /> + --> + <link rel="stylesheet" type="text/css" href="https://www.tug.org/tugstyle.css" /> + <meta name="author" content="Petra Rübe-Pugliese" /> + <meta name="date" content="2019-04-22" /> + <meta http-equiv="content-type" content="text/html; charset=us-ascii" /> + <style type="text/css"> + .highlight { color:navy;} + .abstandoben { margin-top:1em;} + .kleinerabstandoben { margin-top:0.8ex;} + </style> + </head> + + <body> + + <!-- ======================================================== --> + + <h1> + Additional Information for CTAN Uploaders + </h1> + + <p> + Before studying these <em>additional</em> + notes, + you should have read and understood + the following + <a id="basictexts">basic texts</a>: + </p> + + <ol style="list-style-type:lower-alpha;"> + <li> + CTAN's help page + “<a href="https://ctan.org/help/upload-pkg">How can I upload a package?</a>”, + </li> + <li> + the + <a href="https://tug.org/texlive/pkgcontrib.html"> + TeX Live instructions</a>, and + </li> + <li> + the corresponding + <a href="http://www.tex.ac.uk/FAQ-uploads.html"> + article of the UK TeX FAQ</a>. + </li> + </ol> + + <p> + The following paper tries to give some + <a href="#backgroundinfo">background information about CTAN itself</a>, + followed by a list of more aspects we ask you keep in mind when + <a href="#uploadpreparation">preparing your upload</a>, + some hints about + <a href="#uploading">how to use the upload form</a> + and finally information about + <a href="#furtherprocessing">what will happen to your + submission</a> + once it has arrived at our place. + </p> + + <!-- ======================================================== --> + <hr/> + + <h2> + <a id="backgroundinfo">Some background information</a> + </h2> + + <h3> + <a id="networkstructure">Structure of the network</a> + </h3> + + <p> + The + <span class="highlight">Comprehensive TeX Archive Network</span> + consists of + <a id="centralserver"> + <span class="highlight">a central server</span> + </a> + at Cologne in Germany and a great number of + <a href="http://dante.ctan.org/mirmon/">mirrors</a> + all over the world. + </p> + <p> + 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. + </p> + + <h3> + <a id="archivestructure">Structure of the archive</a> + </h3> + + <p> + The greater part of the archive + is taken up by what we refer to as the + <a id="unpackedtree"></a> + “<a href="http://mirror.ctan.org/">unpacked tree</a>”. + It is meant for being visited by means of a + <span class="highlight">browser</span>. + To make this not too painful an experience, + the individual subtrees of this part of the + archive are required to be + <a id="flatstructure"> + <em>as “flat” as possible</em>, + </a> + i.e. they should contain as few directory levels + as possible, + regardless of the position of the individual files + in a “real” TeX system. + <br/> + 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 <a href="#ctanemail">contact</a> the CTAN team + for advice if your package is very complex + and you are in doubt about how best to arrange + your material. + </p> + <p> + In addition to this there is what we call the + <a id="installtree"></a> + “<a href="http://mirror.ctan.org/install/">install tree</a>”, + which is a collection of + <a href="https://tug.org/texlive/pkgcontrib.html#advanced"> + <tt>.tds.zip</tt> files</a>. + </p> + <p> + Please note that + <a id="unpackednecessary"> + every package on the archive + <em>must</em> be present in the + “unpacked” part. + </a> + The <tt>.tds.zip</tt> 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 <em>do not accept</em> + uploads that contain nothing but + a <tt>.tds.zip</tt> file. + </p> + + <h3> + <a id="urls">URLs</a> + </h3> + + <p> + There are many ways of referring to + CTAN packages on the internet, + but our <em>preferred</em>, + <a id="canonicalurls1"> + “canonical” ones + </a> + are of the following form: + </p> + + <ol style="list-style-type:lower-alpha;"> + <li> + <tt style="font-weight:bold;">https://ctan.org/pkg/…</tt> + (where the “…” equal the + “<a href="#packageids">package id</a>”) + if you are interested in <em>information about</em> + the package, and + </li> + + <li> + <tt style="font-weight:bold;">http://mirror.ctan.org/…</tt> + (where the “…” equal the “path” + to the package's files on the archive) + if you are interested in the package itself. + </li> + </ol> + + <p> + <a id="tex-archive-deprecated"> + In particular, URLs containing the string + “<tt>tex-archive</tt>” + are generally “suspicious”, + </a> + because they usually refer to the + <a href="#centralserver">central server</a>, + 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. + </p> + + <h3> + <a id="ctanteam">The CTAN team</a> + </h3> + + <p> + At the moment, the following persons + (in alphabetical order) + take care of CTAN: + </p> + + <ul> + <li> + <strong>Erik Braun</strong> + (upload management), + </li> + <li> + <strong>Ina Dau</strong> + (upload management), + </li> + <!-- + <li> + <strong>Robin Fairbairns</strong> + (Catalogue specialist), + </li> + --> + <li> + <strong>Manfred Lotz</strong> + (upload management), + </li> + <li> + <strong>Gerd Neugebauer</strong> + (web developer), + </li> + <li> + <strong>Petra Rübe-Pugliese</strong> + (upload management), + </li> + <li> + <strong>Rainer Schöpf</strong> + (system administration + and supervision of mirrors), + </li> + <li> + <strong>Joachim Schrod</strong> + (system administration). + </li> + </ul> + + <p> + All these people are acting + as <em>volunteers</em> + 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. + </p> + + + + <h3> + <a id="ctanemail">Email address</a> + </h3> + + <p> + All CTAN-related correspondence should + be directed + <em>in English</em> + to + <tt style="font-weight:bold;">ctan (at) ctan (dot) org</tt>, + the common email address of + all “CTAN people”, + <!-- + concerned with upload management or system administration, + --> + 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 <em>quick</em> + response to your enquiry. + (Always consider that no CTAN member can be available + all the time.) + </p> + <p> + <a id="nohtmlmails"> + Please take care + that the emails you send to this address + are + </a> + <strong>plain text</strong> only, + <strong>without</strong> any + <strong>HTML</strong> 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 <em>always</em> + be sent in plain text mode when you access + google's webmail via the “basic HTML view” + interface.) + </p> + + <p> + <a id="alwaysusetheuploadform"> + <strong>Never </strong>try to + </a> + <strong>upload</strong> + (or re-upload) + <strong>by email</strong>, + <strong> + always use the + <a href="https://ctan.org/upload">upload form</a></strong>, + 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 + <a href="https://ctan.org/upload">upload form</a> + 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. + </p> + + <p> + <a id="nobigattachments"></a> + More generally, + <strong>no big attachments</strong> + should be sent to this email address, + mainly because of argument (a) + in the preceding paragraph. + </p> + + <!-- ======================================================== --> + <hr/> + + <h2> + <a id="uploadpreparation"> + More requirements on your upload … + </a> + </h2> + + <ol> + <li> + <a id="filenames"> + <strong> + Conditions on filenames: + </strong> + </a> + <ol style="list-style-type:lower-alpha;"> + <li class="kleinerabstandoben"> + Filenames should + <span class="highlight">no</span>t + contain any + <a id="nospaces"> + <span class="highlight">spaces</span>, + </a> + <span class="highlight">tabs</span>, + <span class="highlight">newlines</span>, + or other whitespace characters + because filenames with whitespaces in them + can make work on a UNIX command line + extremely awkward. + </li> + <li class="kleinerabstandoben"> + Filenames should + <span class="highlight">no</span>t + contain any + <a id="onlyascii"> + <span class="highlight">non-ascii</span> + </a> + characters, for portability reasons. + </li> + <li class="kleinerabstandoben"> + Filenames should + <span class="highlight">no</span>t + contain any characters that have a + <a id="nounixspecialcharacters"> + <span class="highlight">special meaning + for UNIX shells</span> + (or other systems), + </a> + such as exclamation and question marks, + asterisks, ampersands, + slashes, backslashes, pipe symbols, + dollar signs, + any sort of brackets, and parentheses. + </li> + <li class="kleinerabstandoben"> + Filenames should + <a id="noinvisiblefiles"> + <span class="highlight">not start with a dot</span> + </a> + (“invisible files” in UNIX-like + operating systems). + </li> + <li class="kleinerabstandoben"> + <a id="uniquefilenames"> + <span class="highlight"> + Unique filenames: + </span> + </a> + This topic has been dealt with in detail + in two of the three + “<a href="#basictexts">basic texts</a>” + 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 <em>approached</em> as closely as possible. + In particular, + we strongly recommend uniqueness of filenames + <em>within every single package</em>. + Ambiguity is never a good thing, + and it may prove harmful in unexpected situations. + <br /> + (b) Let us remind you that there are operating + systems unable to distinguish between + <tt>myfile</tt> and + <tt>MyFile</tt>. + That's why we check for “identical filenames” + after converting everything to “lowercase”. + </li> + <li class="kleinerabstandoben"> + You may however be pleased + to learn that we have not been asking for + MS-DOS-style + <a id="eightplusthree"></a> + <a href="https://en.wikipedia.org/wiki/8.3_filename"> + 8.3 filenames</a> + for a long time <tt>;-)</tt> + </li> + </ol> + </li> + + <li class="abstandoben"> + <a id="packageids"> + <strong> + Conditions on package ids: + </strong> + </a> + <br/> + Every CTAN package is uniquely identified by its + “<span class="highlight">package id</span>”, + which appears, for instance, as the last part in URLs + like + <a href="https://ctan.org/pkg/geometry">https://ctan.org/pkg/geometry</a> + (here “geometry” is the package's + <em>id</em>.) + <ol style="list-style-type:lower-alpha;"> + <li class="kleinerabstandoben"> + <a id="packageidslikefilenames"></a> + Of course, all the + <a href="#filenames">conditions on filenames</a> + described above + also apply to package ids. + </li> + <li class="kleinerabstandoben"> + <a id="packageidrestriction"></a> + Moreover, package ids have to be all + <span class="highlight">lowercase</span>, + and they must + <span class="highlight">not start with a digit</span>. + <br/> + (To ease some of the harshness of this particular rule, + <span class="highlight">package <a id="packagenames"><em>names</em></a></span> + 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 + <a href="https://ctan.org/pkg/arsclassica">https://ctan.org/pkg/arsclassica</a> + you see “ArsClassica”, + at the top of + <a href="https://ctan.org/pkg/mathtype">https://ctan.org/pkg/mathtype</a> + you see “MathType”, + at the top of + <a href="https://ctan.org/pkg/one2many">https://ctan.org/pkg/one2many</a> + you see “12many”, etc. + Of course, the CTAN team <em>prefer</em>, + for the sake of simplicity, to have + “package name = package id”, + but small variants like CamelCase are accepted + for the “names”.) + </li> + <li class="kleinerabstandoben"> + CTAN and TeX Live have a preference for + <a id="hyphenvsunderscore"><span class="highlight">hyphens</span></a> + in package ids, rather than underscores. + There are at the moment (April 2019) + 1195 Catalogue entries with a hyphen in their name vs. + 10 with an underscore. + You will therefore have to give <em>very</em> good reasons + if you want us to accept the 11th package + with an underscore in its id <tt>;-)</tt> . + </li> + <li class="kleinerabstandoben"> + <a id="l3names"> + Package ids starting with + “<tt><span class="highlight">l3</span></tt>” + </a> + are reserved for official LaTeX Project + <tt>expl3</tt> packages. + Package authors are encouraged to consider using + “<tt>l<u>t</u>3...</tt>” for third-party + <tt>expl3</tt> packages. + </li> + <li class="kleinerabstandoben"> + New packages and bundles should + <a id="noauthornames"> + <span class="highlight">not</span> be + <span class="highlight">named after their authors</span>, + </a> + 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.) + </li> + <li class="kleinerabstandoben"> + In the same way, + <a id="nocrypticids"> + “<span class="highlight">cryptic</span>” + </a> + package ids like + “acs”, + “mxd”, + “tpx”, or + “tcvn” + are nowadays strongly + <span class="highlight">discouraged</span>. + Modern package ids should as best as possible + convey to the average user an idea of what + the package is about. + </li> + </ol> + </li> + + <li class="abstandoben"> + <a id="versionnumber"></a> + <a id="versionidentifier"> + <strong> + Version identifier: + </strong> + </a> + <br /> + Every submission of every CTAN package has to contain a + “<span class="highlight">version identifier</span>” + that permits to distinguish this version + of the package from earlier or later ones. + (Mind that what counts here are the actual + <em>installations</em> 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 + <a href="https://ctan.org/upload">upload form</a>. + <br /> + This version identifier may consist of + <ol style="list-style-type:lower-roman;"> + <li> + Either (only) a version + <span class="highlight">number</span>, + i.e. something like + “1.0”, or + “3.0.17”, or + “2.1a”, + </li> + <li> + or (only) a version + <span class="highlight">date</span>, + preferably in YYYY-MM-DD or YYYY/MM/DD notation, like + “2018-12-06” or + “2018/12/06”, + </li> + <li> + or a string consisting of <em>both</em> + the aforementioned data. + </li> + </ol> + For + <span class="highlight">simple LaTeX packages</span>, + the optional argument of + the <tt>\ProvidesPackage</tt> + or <tt>\ProvidesClass</tt> + command of the <tt>.sty</tt> or <tt>.cls</tt> file + should be a good place + where to put this information. + <br /> + For <span class="highlight">bundles</span> + 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 <em>as a whole</em>. + A good way to achieve this + is “tagging” + the bundle with the date of the latest + change of <em>any</em> of its files. + Put this “tag” + into a place where it is easy to find, + such as + the latest entry of a <tt>Changes</tt> file, + a <tt>VERSION</tt> file, + or an easily accessible place + (preferably: the top part) + in the + <a href="#readme"><tt>README</tt></a> file. + <br/> + Please note that in our mind the + <span class="highlight">documentation</span> + is considered <em>part of</em> 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. + </li> + + <li class="abstandoben"> + <a id="lowredundancy"> + <strong> + Low redundancy: + </strong> + </a> + <br /> + 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 … + <ol style="list-style-type:lower-alpha;"> + <li class="kleinerabstandoben"> + … + we do not wish to hold + identical copies of one and the same file + <a id="noduplicatefiles"> + (“<span class="highlight">duplicate files</span>”) + </a> + in different places, + such as for instance + <tt>README</tt> and <tt>doc/README</tt>. + <br /> + If you <em>really</em> 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 <tt>zip</tt>, + you will have to call it + with the <tt>--symlinks</tt> 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! + <br /> + (Mind that this request concerns only the + <a href="#unpackedtree">unpacked part</a> + and that a similar recommendation does <em>not</em> + hold for the contents of <tt>.tds.zip</tt> files: + <tt>.tds.zip</tt> files are supposed to be unpacked + without problems on <em>arbitrary</em> platforms, and this + cannot be guaranteed if they contain symbolic + links!) + </li> + + <li class="kleinerabstandoben"> + … + we do not wish to hold files + that can be easily + <a id="nogeneratedfiles"> + “<span class="highlight">generated</span>” + (“<span class="highlight">derived</span>”) + </a> + from other files contained in the submission. + <!-- + <br /> + --> + The standard examples of this are + <tt>.cls</tt>, <tt>.sty</tt>, <tt>.clo</tt>, + <tt>.fd</tt> or similar LaTeX files, + when they can be generated from their + <tt>.dtx</tt> source in a straightforward way. + <!-- + <br /> + Exceptions to this rule , when they cannot + be generated in a straightforward way; + example: <tt>jsclasses</tt>, + which needs a specially customized TeX system. + --> + <br /> + <a id="keeppdffiles"></a> + The <em>exception</em> to this rule are + the <tt>.pdf</tt> files of the documentation: + We do indeed wish to keep these, + ready for immediate access by visitors, + alongside with their sources. + <br /> + <a id="readmeunpacked"></a> + The same holds for + <a href="#readme">README files</a> + in cases where these, too, + can be generated from other sources: + We always want the + <span class="highlight">README unpacked</span>, + as a convenient starting point + for inspecting the package. + </li> + </ol> + </li> + + <li class="abstandoben"> + <a id="noauxfiles"> + <strong> + No auxiliary files: + </strong> + </a> + <br /> + This concerns operating system specific + data (like <tt>__MACOSX</tt> directories and + <tt>.DS_Store</tt> files), + <tt>.git</tt>, + <tt>.gitignore</tt>, + <tt>.hgignore</tt>, + <tt>.hgtags</tt>, + editor backup files + (<tt>.backup</tt>, + <tt>.bak</tt>, + <tt>.sav</tt>, + <tt>.~</tt>, + …), + as well as “leftovers” + from TeX & friends and other programs + (<tt>.aux</tt>, + <tt>.log</tt>, + <tt>.acn</tt>, + <tt>.acr</tt>, + <tt>.alg</tt>, + <tt>.bbl</tt>, + <tt>.bcf</tt>, + <tt>.blg</tt>, + <tt>.brf</tt>, + <tt>.cb</tt>, + <tt>.cb2</tt>, + <tt>.ent</tt>, + <tt>.fdb_latexmk</tt>, + <tt>.fff</tt>, + <tt>.fls</tt>, + <tt>.fmt</tt>, + <tt>.fot</tt>, + <tt>.gaux</tt>, + <tt>.glog</tt>, + <tt>.gtex</tt>, + <tt>.ilg</tt>, + <tt>.ind</tt>, + <tt>.idx</tt>, + <!-- This is indeed a user-supplied config file: + <tt>.ist</tt>, + --> + <tt>.glo</tt>, + <tt>.lg</tt>, + <tt>.loa</tt>, + <tt>.lod</tt>, + <tt>.lof</tt>, + <tt>.lol</tt>, + <tt>.los</tt>, + <tt>.lot</tt>, + <tt>.lox</tt>, + <tt>.nav</tt>, + <tt>.out</tt>, + <tt>.pre</tt>, + <tt>.pyg</tt>, + <tt>.snm</tt>, + <tt>.soc</tt>, + <tt>.toc</tt>, + <tt>.vrb</tt>, + <tt>.cpt</tt>, + <tt>.dvi</tt>, + <tt>.glg</tt>, + <tt>.gls</tt>, + <tt>.glsdefs</tt>, + <tt>.idv</tt>, + <tt>.maf</tt>, + <tt>.mlf</tt>, + <tt>.mlt</tt>, + <tt>.mtc</tt>, + <tt>.nlg</tt>, + <tt>.nlo</tt>, + <tt>.nls</tt>, + <tt>.spl</tt>, + <tt>.thm</tt>, + <tt>.tmb</tt>, + <tt>.tmp</tt>, + <tt>.tuc</tt>, + <tt>.upa</tt>, + <tt>.upb</tt>, + <tt>.o</tt>, + <tt>.sta</tt>, + <tt>.swp</tt>, + <tt>.tdo</tt>, + <tt>.trc</tt>, + <tt>.ttt</tt>, + <tt>.url</tt>, + <tt>.w18</tt>, + <tt>.xdv</tt>, + <tt>.xref</tt>, + <tt>.4ct</tt>, + <tt>.4tc</tt>, + <tt>.run.xml</tt>, + <tt>.pdfsync</tt>, + <tt>.synctex</tt>, + <tt>.synctex.gz</tt>, + and potentially others we have + not yet encountered): + Please leave them out of your upload! + <br/> + <a id="howtoavoidrubbish"></a> + Note for <tt>git</tt> users wishing to keep exported + <tt>.zip</tt> files “git rubbish free”: + This can be achieved by creating, adding and committing + a <tt>.gitattributes</tt> file containing lines like + the following: + <pre> + .gitignore export-ignore + .gitattributes export-ignore + </pre> + Hint for Mac OSX users: + A user told us that “it is possible to tell + Mac OSX's <tt>tar</tt> command line executable + to avoid polluting the archive with OSX specific + files, by setting the environment variable + <tt>COPYFILE_DISABLE</tt> (to whatever value).” + <!-- Didier Verna, Tue, 07 Mar 2017 13:48:01 +0100 --> + </li> + + <li class="abstandoben"> + <a id="noemptyfiles"> + <strong> + No empty files or directories: + </strong> + </a> + <br /> + 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. + <br /> + 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 + <a href="https://ctan.org/upload">upload form</a> + so that we can make a note of this exception + and do not bother you with unnecessary complaints. + </li> + + <li class="abstandoben"> + <a id="filepermissions"> + <strong> + File permissions: + </strong> + </a> + <ol style="list-style-type:lower-alpha;"> + <li class="kleinerabstandoben"> + Only files that are truly + <span class="highlight">executable</span> + (like Shell, Perl, Python, Ruby, and other scripts) + should be marked as such. + An “executable” + README or <tt>.tex</tt> file does not make any sense. + </li> + <li class="kleinerabstandoben"> + Files submitted to CTAN are obviously meant + for <em>publication</em>. + This implies that they should be + “<span class="highlight">world readable</span>”. + (In fact, exaggerated “privacy” + of file permissions can lead to serious + complications in the installation process.) + </li> + </ol> + </li> + + <li class="abstandoben"> + <a id="crlf"> + <strong> + Line terminators of text files: + </strong> + </a> + <br /> + This paragraph is about + <a id="textfiles"> + “<span class="highlight">text files</span>” + </a> + (like + <tt>.txt</tt>, + <tt>.tex</tt>, + <tt>.sty</tt>, + <tt>.cls</tt>, + <tt>.dtx</tt>, + <tt>.fd</tt>, + <tt>.bib</tt>, + <tt>.c</tt>, + or any other file that can be edited + with a text editor) + as opposed to + “<span class="highlight">binary files</span>” + (such as + <tt>.gif</tt>, + <tt>.jpg</tt>, + <tt>.wav</tt>, + <tt>.mp3</tt>, + <tt>.ogg</tt>, + <tt>.tfm</tt>, + <tt>.pdf</tt>, + <tt>.doc</tt>, + <tt>.xls</tt>, + <tt>.exe</tt>, + and a multitude of others). + <br /> + The problem with such text files is + that different operating systems have different ways + of marking the + <span class="highlight">line endings</span> + 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. + <br /> + 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. + <br /> + 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 + <a id="goodzipprogram"> + <span class="highlight">“good zip program”</span>, + </a> + this will mark all text files with a special + “flag” (or “tag”) + that will permit CTAN's <tt>unzip</tt> program + to recognize these text files and perform the + necessary conversions + (in this case: omitting the unwanted + “carriage return” characters) + <em>automatically</em> <tt>:-)</tt> + <br /> + <a id="badzipprograms"></a> + Unfortunately, not all zip programs are + “good zip programs” <tt>:-(</tt> + <br /> + In particular, + <span class="highlight">7zip</span>, + the GNOME archive manager, + the <tt>Compress</tt> facility + accessible via the <tt>File</tt> menu + in Mac OS X's <tt>Finder</tt>, + and the feature that permits + to export zip files directly from + <span class="highlight">git</span> + 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 <a href="#ctanemail">email</a>!) + <br /> + <a id="gitandcrlf"></a> + However, + <span class="highlight">git</span> + users may want to have a look at the + <tt>.gitattributes</tt> file + for the configuration of file types + and line endings! + <br /> + <span class="highlight"> + Known + <a id="goodzipprogramnames"> + “good zip programs” + </a> + </span> + are + the Windows7ff. builtins, + WinZip, + Windows “Total Commander”, + and the zippers from + <a href="http://www.info-zip.org/"> + info-zip.org</a>. + <br /> + Mac users in need of a “good zip program” + may either turn to + <a href="http://www.yellowmug.com/yemuzip/"> + YemuZip</a> + or the standard <tt>zip</tt> command on their + command line + (which is in fact the info-zip tool that is + also present in Linux systems). + The command line <tt>zipinfo</tt> utility + is extremely useful for checking + zip archives once they have been created. + <br /> + <a id="tarnotxtvsbintags"></a> + Unfortunately, <b><tt>tar</tt></b> does <em>not</em> + offer the “tagging” feature in question. + <br /> + Finally, there are two + <span class="highlight">exceptions</span> + to what has been said before: + <ol style="list-style-type:lower-alpha;"> + <li class="kleinerabstandoben"> + <em>If</em> your upload contains any + <tt>.bat</tt> or + <tt>.cmd</tt> or + <tt>.nsh</tt> or + other typical DOS/Windows files, + and <em>if</em> 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 + <a href="https://ctan.org/upload">upload page</a>, + and we will take care that this is done. + </li> + <li class="kleinerabstandoben"> + <a id="nocrlfintdszip"></a> + All the <tt>.tds.zip</tt> 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 <tt>.tds.zip</tt> files + to be submitted in exactly that way. + (<em>If</em> there should really be a problem + that prevents you from complying with this + requirement, we <em>may</em> 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.) + </li> + </ol> + </li> + + <li class="abstandoben"> + <a id="canonicalurls2"> + <strong> + “Canonical” URLs in documentation: + </strong> + </a> + <br /> + Please make sure when writing (or revising) + your documentation + that TeX software on CTAN archives + is referred to using our + <a href="#urls">preferred “canonical” URLs</a> + described + <a href="#urls">above</a> + rather that URLs pointing to individual CTAN servers. + </li> + + <li class="abstandoben"> + <a id="readme"> + <strong> + Rules about <tt>README</tt> files: + </strong> + </a> + <ol style="list-style-type:lower-alpha;"> + <li> + 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. + </li> + <li> + Its name can be either + <tt>README</tt> or + <tt>README.txt</tt> or + <tt>README.md</tt>, + but no other variants are permitted + at the moment. + </li> + <li> + Its contents must be easily readable using + the UNIX <tt>more</tt> or <tt>less</tt> commands + or an arbitrary editor. + </li> + <li> + It should be written in + <span class="highlight">English</span> + or at least comprise a short + abstract in English. + </li> + <li> + The encoding should be + <span class="highlight">ascii</span> + or + <span class="highlight">utf-8</span> + without BOM (byte order mark). + </li> + <li> + It has to be placed at the top level + of the + <a href="#unpackedtree">unpacked package</a> + (but in the <tt>doc/…/</tt> directory of + a possible <tt>.tds.zip</tt> file). + </li> + </ol> + </li> + + <!-- + I think we will omit the following part altogether, + at least for the time being ... + <li class="abstandoben"> + <a id="tdsequalunpacked"> + <strong> + Identical files in <tt>.tds.zip</tt> and outside: + </strong> + </a> + <br /> + Some general remarks … + <br /> + --> + <!-- + In particular, Vincent Belaïche, in an + email dated Mon, 15 Sep 2014 22:35:43 +0200, + Subject: Re: Lettre, + asks me to add the following sentence to + these additional instructions: + --> + <!-- + If you do not use DTX, and you are documenting your + sty/cls files with docTeX comments, then unpacked zip + and .tds.zip may contain either the files with docTeX + comments included, or with them stripped out ; you + must however be consistent and have the same files in + both the unpacked zip and in the .tds.zip. + --> + <!-- + But I do not really understand this at the moment. + His problems seem to be due to a very idiosyncratic + way of packaging his files ... + --> + <!-- + <br /> + Needs a good zip program, see above! + </li> + --> + + <!--- template + <li class="abstandoben"> + <a id="aaaa"> + <strong> + AAAA + </strong> + </a> + <br /> + </li> + --> + </ol> + + <!-- ======================================================== --> + <hr/> + + <h2> + <a id="uploading">Uploading to CTAN</a> + </h2> + + <p> + 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 <tt>zip</tt> or <tt>tar</tt>, + as described on our + <a href="https://ctan.org/help/upload-pkg">help page</a>. + + – + + <a id="topdirofzipfile"></a> + Do not forget the + <span class="highlight">top level directory</span> + of the upload file + (“<tt>my-package/</tt>” in the examples). + It simplifies our installation process + and makes it more secure. + + – + + <a id="zippreferred"></a> + Please opt for a + <a href="#goodzipprogram">good zip program</a> + (instead of <tt>tar</tt> or <em>any</em> + zip program) + if you are not one hundred percent sure + that none of your + <a href="#textfiles">text files</a> + contains any + “Microsoft style” line terminators! + </p> + + <p> + <a id="hintforupdates"></a> + If you want to submit an + <span class="highlight">update</span> to + a package that is already on CTAN, + we recommend you to go first to its + “CTAN homepage” + (<tt>https://ctan.org/pkg/<package_id></tt>) + and <em>then</em> 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 + <tt>:-)</tt> + + But please do not forget to + <span class="highlight"> + update the version field! + </span> + </p> + + <p> + <a id="authorsemail"></a> + Please pay also particular attention + to what you enter into the + <span class="highlight"> + “Your email” + </span> + field: + In fact, + we ask maintainers to use + <span class="highlight"> + always the same email address + </span> + 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 <em>change</em> + your “CTAN upload email address”, + do not forget to drop a line to + <a href="#ctanemail">ctan (at) ctan (dot) org</a>, + still using the <em>old</em> address, + and asking us to register the new one. + </p> + + + <!-- ======================================================== --> + <hr/> + + <h2> + <a id="furtherprocessing">What will happen next …</a> + </h2> + + <ul style="list-style-type:circle;"> + <li class="kleinerabstandoben"> + Every upload will be + <span class="highlight">unpacked</span> and + <span class="highlight">checked</span> + by an upload manager. + </li> + <li class="kleinerabstandoben"> + <span class="highlight">Small deficiencies</span> + will be + <span class="highlight">corrected</span> + immediately by that person. + You will receive + <span class="highlight">feedback</span> + about this and be asked to apply + the same sort of change(s) to your own file(s) + before your next upload. + </li> + <li class="kleinerabstandoben"> + If there is a + <span class="highlight">non-trivial problem</span> + 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. + </li> + <li class="kleinerabstandoben"> + After installation of the package on the archive + (i.e.: on our + <a href="#centralserver">central server</a>) + the corresponding <tt>.xml</tt> source file of the + <span class="highlight">Catalogue entry</span> + 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 + <a href="https://ctan.org/upload">upload form</a> + if you wish us to perform any other changes. + </li> + <li class="kleinerabstandoben"> + When all of this has been done, + we will send an + <span class="highlight">email</span> + to the + <a href="#authorsemail">address</a> + you entered into the + “Your email” field of the + <a href="https://ctan.org/upload">upload form</a>. + </li> + <li class="kleinerabstandoben"> + It may take a few hours until the + <span class="highlight">Catalogue page</span> + of the website + has been regenerated from the source file, + and up to 24 hours + until the new files have arrived + on all the + <span class="highlight">mirrors</span> + worldwide. + </li> + <li class="kleinerabstandoben"> + If your upload is a new one or + if you have requested an announcement, + the message to + <span class="highlight">CTAN-Announce</span> + 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 + <tt>ctan (at) ctan (dot) org</tt> + to enquire if anything has gone wrong. + </li> + <li class="kleinerabstandoben"> + It is always helpful if you + <span class="highlight">check</span> what you see + at the URLs indicated in the acknowledgement mail + around 24 hours after installation and + <span class="highlight">inform us</span> + about any possible flaws in the presentation. + </li> + </ul> + + <p> + <a id="patience"></a> + Please + <span class="highlight"> + do not re-upload when you do not hear from us + <em>at once</em>! + </span> + 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, + <em>and</em> have checked your spam folder to no avail, + you may enquire by email to + <tt>ctan (at) ctan (dot) org</tt> + (remember: No HTML mail please, because of the spam trap!). + </p> + + <p> + <span class="highlight">Thanks</span> + for your perseverance + and <span class="highlight">good luck</span> + with your submission! + </p> + + + <!-- ======================================================== --> + <hr/> + + <h2> + <a id="authoridanduseraccount" style="font-size:smaller"> + Some additional information about author ids and user accounts</a> + </h2> + + <p> + Every author/maintainer of a CTAN package is registered + in the database that is used for the administration + of <em>the archive itself</em> + with an <span class="highlight">author id</span> + that is assigned in the following way: + </p> + <p> + 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”. + </p> + <p> + 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 <em>Hildegard</em> Blümchen + were to join us as an author, she would be registered + as “bluemchen-h”. + </p> + <p> + These <em>author</em> ids must not be confused with the names + of the <span class="highlight"><em>user</em> accounts</span> + on the CTAN <span class="highlight"><em>website</em></span>: + The names of these user accounts can be chosen relatively + freely, as long as uniqueness is assured. + </p> + <p> + A relation between a person's author id and their + CTAN website user account can be established via the + <a href="#authorsemail">email address</a>. + In our webmaster's own words: + </p> + <blockquote> + Once you are logged into the CTAN site and visit the page + <a href="https://ctan.org/user/settings">https://ctan.org/user/settings</a> + (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. + <br/> + 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). + </blockquote> + + + <!-- ======================================================== --> + <hr/> + + <!-- To be activated when file is put into SVN: + <p> + $LastChangedDate$ + </p> + Until then: --> + Last updated: 2019-04-22 + </body> +</html> |