11

I'm going to upload my first package to CTAN. But after reading all the upload guides from CTAN and TeXLive I'm still feeling daunted by the directory structure. My package is rather complex and by now consists of >160 files which will become a lot more when the package matures (for example there are a bunch of small pdf files used by the package, along with the sources to recreate them).

So I'm far from being able to produce a package with four or five files in one single directory.

Do such large numbers of files and changing package contents present special problems for CTAN (and the distros consecutively)? Has best practice for uploading and maintaining such large packages been documented?

Details: the package is in good shape, and a few testers fetched it from Github and got it to run without problems.

If you want to have a look: the package resides at https://github.com/openlilylib/lilyglyphs

Edit

Right now I'm trying to understand the TDS and how I can prepare a lilyglyphs.tds.zip file.

Am I right that I
a) provide the directory as I would use it myself, and when someone downloads from CTAN she will put the complete directory under texmf/tex/latex/lilyglyphs
b) provide a tds.zip that will allow the distributions to put my files in the right locations in their distribution (that is, the files are stored at different locations)
?

If that's true I still have a few questions about where some of my files should go, but I will come back to this after having tried to tackle the tds documentation.

Charles Stewart
  • 21,014
  • 5
  • 65
  • 121
uli_1973
  • 1,920
  • 2
    No it will not be a problem. There are larger packages (e.g. cm-super) but you should arrange the files so that they know where all the files belong (e.g. by providing a tds-zip) to make life for the maintainer easier and to prevent that an image needed by the package ends in the doc-folder. – Ulrike Fischer Sep 03 '13 at 15:12
  • 2
    Related question: What is good practice when preparing a package for CTAN? – Alan Munn Sep 03 '13 at 15:40
  • For b): The base of a tds.zip is texmf. So it contains at least /tex/latex/lilyglyphs and maybe a /tex/latex/lilyglyphs/pics. – Josef Sep 03 '13 at 15:44
  • I don't understand the questions in a) and b) but you can find examples of tds.zip here http://mirror.ctan.org/tex-archive/install/macros/latex/contrib – Ulrike Fischer Sep 03 '13 at 15:50
  • a) I develop the package in one directory structure (that is also present in the Git repo). When installing the package from CTAN a user would 'recreate' that structure in texmf/tex/latex/lilyglyphs. Is that right? – uli_1973 Sep 03 '13 at 15:56
  • b) Should I place the manual in /doc (or /doc/lilyglyphs), then some fonts in ' /fonts/opentype/...', lilyglyphs.sty in /tex/latex/lilyglyphs etc.? I also have helper scripts that a user should run when she wants to extend the package. And there is an archive that the user should unpack to somewhere in her home directory if she wants to extend the package. If you don't quite understand these questions you'll understand why I said 'complex' ... – uli_1973 Sep 03 '13 at 15:59
  • @uli_1973 b) For the tds.zip the doc belongs in /doc/latex/lilyglyphs! It's part of the big TeX tree. The user should just download package.tds.zip an unzip it in the root of the (local) TeX tree. Just take a look at the main TeX tree of your distribution. – Josef Sep 03 '13 at 17:36
  • @uli_1973 a) In the CTAN package directory you are free to place your files where you want. – Josef Sep 03 '13 at 17:38
  • @uli_1973 Something i forgot to add for a): The user will have to move the files to the right place on his own in the TeX tree, e.g. Your fonts must be moved to /texmf/fonts/opentype/xxxxx. That's why tds.zips do exist! ;-) – Josef Sep 03 '13 at 17:46
  • The tip to inspect existing tds.zips was very helpful. By now I realized that I'm not so sure if my package is so compatible with being part of a distribution. There are many files (scripts, templates etc.) that can be used to extend the package with individual commands, and I don't really see how one would use them once they are buried somewhere in the main TeX tree. Would it be acceptable to put everything in the CTAN directory structure and only put those files in the tds.zip that are needed for using the package (and documenting this in the manual of course)? – uli_1973 Sep 04 '13 at 08:09
  • @Josef: Thank you for the comments. Quite helpful – uli_1973 Sep 04 '13 at 08:42
  • This is not a duplicate of the referenced question. The specific concerns of the current questions (number of files, relation to the TDS structure/tds.zip) aren't addressed at all in the other question. – uli_1973 Jan 30 '14 at 06:23
  • If this question is reopened I'll write an answer myself. – uli_1973 Jan 30 '14 at 06:26
  • I agree that this qn raises issues not addressed in any of the other how-to qns related to CTAN uploads. I've edited the qn to emphasise that it deals with large packages whose set of files is expected to evolve. – Charles Stewart Jan 30 '14 at 07:25
  • Thanks. This clarifies and improves the question. As mentioned, I'm ready to write an answer. – uli_1973 Jan 30 '14 at 08:10
  • the only significant reason to create a .tds.zip file is if the package is a font, and there are reasons to expect that it won't go into the distributions. the distributions are far better than most, at creating valid tds, and even if the user has a pre-installed dist, it's easy to suck a single package from a distribution and to use that. (note we do check each .tds.zip against the "main tree", but that can miss particularly egregious errors.) all that said, if the .tds.zip is valid, we will install it. – wasteofspace Jan 30 '14 at 10:15

1 Answers1

5

OK, by now my package is on CTAN and in TeXLive, so I can answer this question myself (it is different from the questions referenced in the comments).

  • A large number of files in a package isn't a problem, if they are needed for the working of the package.
  • There is no requirement to provide a TDS.zip.
    Quite the contrary, it is strongly discouraged if you don't know exactly what you're doing.
  • CTAN and distro maintainers have practical tools to handle your package, provided they know what to do with what.
  • For this you should at least provide a README (or dedicated additional README files) that clearly show(s) any maintainer what everything does.
  • Use meaningful subdirectory names

This is the general idea. Additionally I'll give a few hints concerning concrete types of files I encountered with my package:

  • If you have to supply fonts (and have the license to redistribute them), please put them in a dedicated directory, together with appropriate licensing information).
  • I was advised to put everything that has to be seen by LaTeX into a dedicated tex directory. In my case this contained the .sty file, input files and the large number of .pdf files that are used by the package's commands. If you have pdf files it is particularly important to tell potential distro maintainers that they will have to be put into the LaTeX search path. Otherwise you'd risk that they are interpreted as documentation files.
  • One thing to note is that file names of these pdf files have a global scope, so they should be unique among everything LaTeX might ever want to search for.
  • My package provided sources as a convenience: those used to generate the pdf files and those used to generate the fonts. These aren't needed to use the package but should be included, in a dedicated sources directory.
  • My package provided a number of Python scripts, which aren't necessary to use the package but to extend it. They have to be placed in a script directory and will then be placed in the system search path by distro maintainers. (Of course you will have to tell the user to install Python).
uli_1973
  • 1,920