1CTANIFY(1) CTANIFY(1)
2
6 ctanify - Prepare a package for upload to CTAN
7
9 ctanify [--pkgname=string] [--[no]auto] [--tdsonly=filespec ...]
10 [--[no]unixify] [--[no]skip] [--tdsdir=dirname ...] [--tex=macro_pkg]
11 [--[no]miscify] [--[no]tds] filespec[=dirname] ...
12 ctanify [--help]
14 ctanify [--version]
16
18 ctanify is intended for developers who have a LaTeX package that they
19 want to distribute via the Comprehensive TeX Archive Network (CTAN).
20 Given a list of filenames, ctanify creates a tarball (a .tar.gz file)
21 with the files laid out in CTAN's preferred structure. The tarball
22 additionally contains a ZIP (.zip) file with copies of all files laid
23 out in the standard TeX Directory Structure (TDS), which facilitates
24 inclusion of the package in the TeX Live distribution.
25
27 ctanify accepts the following command-line options:
28 -h, --help
30 Output basic usage information and exit.
31 -V, --version
33 Output ctanify's version number and exit.
34 -p string, --pkgname=string
36 Specify explicitly a package name. Normally, ctanify uses the
37 base name of the first .ins or .sty file listed as the package
38 name. The package name forms the base name of the tarball that
39 ctanify produces.
40 --noauto
42 Do not automatically add files to the tarball. Normally, ctanify
43 automatically includes all files mentioned in a .ins file.
44 -t filespec, --tdsonly=filespec
46 Specify a subset of the files named on the command line to include
47 only in the TDS ZIP file, not in the CTAN package directory.
48 Wildcards are allowed (quoted if necessary), and --tdsonly can be
49 used multiple times on the same command line.
50 At least one filename must be specified on the command line. ctanify
52 automatically places files in the TDS tree based on their extension,
53 but this can be overridden by specifying explicitly a target TDS
54 directory using the form filespec=dirname. Wildcards are allowed for
55 the filespec (quoted if necessary).
56
58 The following options are unlikely to be necessary in ordinary usage.
59 They are provided for special circumstances that may arise.
60 -d dirname, --tdsdir=dirname
62 Instead of creating a tarball for CTAN, merely create the package
63 TDS tree rooted in directory dirname.
64 -T macro_pkg, --tex=macro_pkg
66 Assert that the files being packaged for CTAN target a TeX macro
67 package other than LaTeX. Some common examples of macro_pkg are
68 "generic", "plain", and "context".
69 -nou, --no-unixify
71 Store text files unmodified instead of converting their end-of-
72 line character to Unix format (a single linefeed character with no
73 carriage-return character), even though CTAN prefers receiving all
74 files with Unix-format end-of-line characters.
75 -nok, --no-skip
77 Force ctanify to include files such as Unix hidden files, Emacs
78 backup files, and version-control metadata files, all of which
79 CTAN dislikes receiving.
80 -m, --miscify
82 Rename directories containing a single file to "misc". (For
83 example, rename "tex/latex/mypackage/mypackage.sty" to
84 "tex/latex/misc/mypackage.sty".) This was common practice in the
85 past but is now strongly discouraged.
86 -nos, --no-tds
88 Do not embed a .tds.zip file in the generated tarball.
89
91 "Failed to copy filename (No such file or directory)"
92 This message is typically caused by a .ins file that generates
93 filename but that has not already been run through tex or latex to
94 actually produce filename. ctanify does not automatically run tex
95 or latex; this needs to be done manually by the user. See
96 "CAVEATS" for more information.
97 "Modified filename to use Unix line endings (use --no-unixify to
99 prevent this)"
100 For consistency, CTAN stores all text files with Unix-style line
101 endings (a single linefeed character with no carriage-return
102 character). To help in this effort, ctanify automatically
103 replaces non-Unix-style line endings. The preceding merely
104 message notifies the user that he should not be alarmed to see a
105 different size for filename in the tarball versus the original
106 filename on disk (which ctanify never modifies). If there's a
107 good reason to preserve the original line endings (and there
108 rarely is), the --no-unixify option can be used to prevent ctanify
109 from altering any files when storing them in the tarball.
110 "Excluding filename (use --no-skip to force inclusion)"
112 ctanify normally ignores files--even when specified explicitly on
113 the command line--that CTAN prefers not receiving. These include
114 files whose names start with "." (Unix hidden files), end in "~"
115 (Emacs automatic backups), or that come from a CVS or .svn
116 directory (version-control metadata files). If there's a good
117 reason to submit such files to CTAN (and there rarely is), the
118 --no-skip option can be used to prevent ctanify from ignoring
119 them.
120 "CTAN prefers having only PDF documentation (re: filename)"
122 Because of the popularity of the PDF format, CTAN wants to have as
123 much documentation as possible distributed in PDF. The preceding
124 message asks the user to replace any PostScript or DVI
125 documentation with PDF if possible. (ctanify will still include
126 PostScript and DVI documentation in the tarball; the preceding
127 message is merely a polite request.)
128 "Not including filename in the TDS tree (unknown extension)"
130 ctanify places files in the TDS tree based on a table of file
131 extensions. For example, all .sty files are placed in
132 tex/latex/package-name. If ctanify does not know where to put a
133 file it does not put it anywhere. See the last paragraph of
134 "OPTIONS" for an explanation of how to specify explicitly a file's
135 target location in the TDS tree. For common file extensions that
136 happen to be absent from ctanify's table, consider also notifying
137 ctanify's author at the address shown below under "AUTHOR".
138
140 The Common Case
141 Normally, all that's needed is to tell ctanify the name of the .ins
142 file (or .sty if the package does not use DocStrip) and the prebuilt
143 documentation, if any:
144 $ ctanify mypackage.ins mypackage.pdf README
146 490347 mypackage.tar.gz
148 1771 mypackage/README
150 15453 mypackage/mypackage.dtx
151 1957 mypackage/mypackage.ins
152 277683 mypackage/mypackage.pdf
153 246935 mypackage.tds.zip
154 1771 doc/latex/mypackage/README
156 277683 doc/latex/mypackage/mypackage.pdf
157 15453 source/latex/mypackage/mypackage.dtx
158 1957 source/latex/mypackage/mypackage.ins
159 1725 tex/latex/mypackage/mypackage.sty
160 ctanify outputs the size in bytes of the resulting tarball, each file
162 within it, and each file within the contained ZIP file. In the
163 preceding example, notice how ctanify automatically performed all of
164 the following operations:
165 · including mypackage.dtx (found by parsing mypackage.ins) in both
167 the mypackage directory and the ZIP file,
168 · including mypackage.sty (found by parsing mypackage.ins) in the
170 ZIP file but, because it's a generated file, not in the mypackage
171 directory, and
172 · placing all files into appropriate TDS directories (documentation,
174 source, main package) within the ZIP file.
175 Consider what it would take to manually produce an equivalent
177 mypackage.tar.gz file. ctanify is definitely a simpler, quicker
178 alternative.
179 Advanced Usage
181 ctanify assumes that PostScript files are documentation and therefore
182 stores them under doc/latex/package-name/ in the TDS tree within the
183 ZIP File. Suppose, however, that a LaTeX package uses a set of
184 PostScript files to control dvips's output. In this case, ctanify must
185 be told to include those PostScript files in the package directory, not
186 the documentation directory.
187 $ ctanify mypackage.ins "mypackage*.ps=tex/latex/mypackage"
189
191 perl ctanify is written in Perl and needs a Perl installation to run.
192 tar, gzip
194 ctanify requires the GNU tar and gzip programs to create a
195 compressed tarball (.tar.gz).
196 zip ctanify uses a zip program to archive the TDS tree within the main
198 tarball.
199
201 ctanify does not invoke tex or latex on its own, e.g., to process a
202 .ins file. The reason is that ctanify does not know in the general
203 case how to produce all of a package's generated files. It was deemed
204 better to do nothing than to risk overwriting existing .sty (or other)
205 files or to include outdated generated files in the tarball. In short,
206 before running ctanify you should manually process any .ins files and
207 otherwise generate any files that should be sent to CTAN.
208 ctanify has been tested only on Linux. It may work on OS X. I've been
210 told that it works on Windows when run using Cygwin. Volunteers
211 willing to help port ctanify to other platforms are extremely welcome.
212
214 tar(1), zip(1), latex(1), Guidelines for uploading TDS-Packaged
215 materials to CTAN (<http://www.ctan.org/TDS-guidelines>), A Directory
216 Structure for TeX Files (<http://tug.org/tds/>),
217
219 Scott Pakin, scott+ctify@pakin.org
220
222 Copyright 2017 Scott Pakin
223 This work may be distributed and/or modified under the conditions of
225 the LaTeX Project Public License, either version 1.3c of this license
226 or (at your option) any later version. The latest version of this
227 license is in
228 <http://www.latex-project.org/lppl.txt>
230 and version 1.3c or later is part of all distributions of LaTeX version
232 2008/05/04 or later.
233v1.9.1 2017-04-22 CTANIFY(1)