Return to Main Contents
ctanify - Prepare a package for upload to CTAN
is intended for developers who have a LaTeX package that
they want to distribute via the Comprehensive TeX Archive Network
). Given a list of filenames, ctanify
creates a tarball (a
file) with the files laid out in CTAN
structure. The tarball additionally contains a ZIP
with copies of all files laid out in the standard TeX Directory
), which facilitates inclusion of the package in the TeX
accepts the following command-line options:
- -h, --help
Output basic usage information and exit.
- -V, --version
Output ctanify's version number and exit.
- -p string, --pkgname=string
Specify explicitly a package name. Normally, ctanify uses the base
name of the first .ins or .sty file listed as the package name.
The package name forms the base name of the tarball that ctanify
Do not automatically add files to the tarball. Normally, ctanify
automatically includes all files mentioned in a .ins file.
- -t filespec, --tdsonly=filespec
Specify a subset of the files named on the command line to include
only in the TDS ZIP file, not in the CTAN package directory.
Wildcards are allowed (quoted if necessary), and --tdsonly can be
used multiple times on the same command line.
At least one filename must be specified on the command line.
ctanify automatically places files in the TDS tree based on their
extension, but this can be overridden by specifying explicitly a
target TDS directory using the form filespec=dirname. Wildcards
are allowed for the filespec (quoted if necessary).
The following options are unlikely to be necessary in ordinary usage.
They are provided for special circumstances that may arise.
- -d dirname, --tdsdir=dirname
Instead of creating a tarball for CTAN, merely create the package TDS
tree rooted in directory dirname.
- -nou, --no-unixify
Store text files unmodified instead of converting their end-of-line
character to Unix format (a single linefeed character with no
carriage-return character), even though CTAN prefers receiving all
files with Unix-format end-of-line characters.
- -nok, --no-skip
Force ctanify to include files such as Unix hidden files, Emacs
backup files, and version-control metadata files, all of which CTAN
- -m, --miscify
Rename directories containing a single file to "misc". (For example,
rename "tex/latex/mypackage/mypackage.sty" to
"tex/latex/misc/mypackage.sty".) This was common practice in the
past but is now strongly discouraged.
- "Failed to copy filename (No such file or directory)"
This message is typically caused by a .ins file that generates
filename but that has not already been run through tex or
latex to actually produce filename. ctanify does not
automatically run tex or latex; this needs to be done manually
by the user. See ``CAVEATS'' for more information.
- "Modified filename to use Unix line endings (use --no-unixify to prevent this)"
For consistency, CTAN stores all text files with Unix-style line
endings (a single linefeed character with no carriage-return
character). To help in this effort, ctanify automatically replaces
non-Unix-style line endings. The preceding merely message notifies
the user that he should not be alarmed to see a different size for
filename in the tarball versus the original filename on disk
(which ctanify never modifies). If there's a good reason to
preserve the original line endings (and there rarely is), the
--no-unixify option can be used to prevent ctanify from altering
any files when storing them in the tarball.
- "Excluding filename (use --no-skip to force inclusion)"
ctanify normally ignores files---even when specified explicitly on
the command line---that CTAN prefers not receiving. These include
files whose names start with ".`` (Unix hidden files), end in ''~"
(Emacs automatic backups), or that come from a CVS or .svn
directory (version-control metadata files). If there's a good reason
to submit such files to CTAN (and there rarely is), the --no-skip
option can be used to prevent ctanify from ignoring them.
- "CTAN prefers having only PDF documentation (re: filename)"
Because of the popularity of the PDF format, CTAN wants to have as
much documentation as possible distributed in PDF. The preceding
message asks the user to replace any PostScript or DVI documentation
with PDF if possible. (ctanify will still include PostScript and
DVI documentation in the tarball; the preceding message is merely a
- "Not including filename in the TDS tree (unknown extension)"
ctanify places files in the TDS tree based on a table of file
extensions. For example, all .sty files are placed in
tex/latex/package-name. If ctanify does not know where to
put a file it does not put it anywhere. See the last paragraph of
``OPTIONS'' for an explanation of how to specify explicitly a file's
target location in the TDS tree. For common file extensions that
happen to be absent from ctanify's table, consider also notifying
ctanify's author at the address shown below under ``AUTHOR''.
The Common Case
Normally, all that's needed is to tell ctanify
the name of the
file (or .sty
if the package does not use DocStrip) and the
prebuilt documentation, if any:
$ ctanify mypackage.ins mypackage.pdf README
ctanify outputs the size in bytes of the resulting tarball, each
file within it, and each file within the contained ZIP file. In the
preceding example, notice how ctanify automatically performed all
of the following operations:
including mypackage.dtx (found by parsing mypackage.ins) in both
the mypackage directory and the ZIP file,
including mypackage.sty (found by parsing mypackage.ins) in the
ZIP file but, because it's a generated file, not in the mypackage
placing all files into appropriate TDS directories (documentation,
source, main package) within the ZIP file.
Consider what it would take to manually produce an equivalent
mypackage.tar.gz file. ctanify is definitely a simpler, quicker
assumes that PostScript files are documentation and
therefore stores them under doc/latex/package-name/
in the TDS
tree within the ZIP
File. Suppose, however, that a LaTeX package uses
a set of PostScript files to control dvips
's output. In this case,
must be told to include those PostScript files in the
package directory, not the documentation directory.
$ ctanify mypackage.ins "mypackage*.ps=tex/latex/mypackage"
ctanify is written in Perl and needs a Perl installation to run.
- tar, gzip
ctanify requires the GNU tar and gzip programs to create a
compressed tarball (.tar.gz).
ctanify uses a zip program to archive the TDS tree within the
does not invoke tex
on its own, e.g., to
process a .ins
file. The reason is that ctanify
does not know
in the general case how to produce all of a package's generated files.
It was deemed better to do nothing than to risk overwriting existing
(or other) files or to include outdated generated files in the
tarball. In short, before running ctanify
you should manually
process any .ins
files and otherwise generate any files that should
be sent to CTAN
ctanify has been tested only on Linux. It may work on OS X. It
probably does not work on Windows. Volunteers willing to help port
ctanify to other platforms are extremely welcome.
Guidelines for uploading TDS-Packaged materials to CTAN
A Directory Structure for TeX Files (<http://tug.org/tds/
Scott Pakin, firstname.lastname@example.org
COPYRIGHT AND LICENSE
Copyright 2013 Scott Pakin
This work may be distributed and/or modified under the conditions of
the LaTeX Project Public License, either version 1.3c of this
license or (at your option) any later version. The latest version of
this license is in
and version 1.3c or later is part of all distributions of LaTeX
version 2008/05/04 or later.
- ADDITIONAL OPTIONS
- The Common Case
- Advanced Usage
- SEE ALSO
- COPYRIGHT AND LICENSE