1CTANIFY(1)                                                          CTANIFY(1)
2
3
4

NAME

6       ctanify - Prepare a package for upload to CTAN
7

SYNOPSIS

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
13       ctanify [--help]
14
15       ctanify [--version]
16

DESCRIPTION

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

OPTIONS

27       ctanify accepts the following command-line options:
28
29       -h, --help
30            Output basic usage information and exit.
31
32       -V, --version
33            Output ctanify's version number and exit.
34
35       -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
41       --noauto
42            Do not automatically add files to the tarball.  Normally, ctanify
43            automatically includes all files mentioned in a .ins file.
44
45       -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
51       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

ADDITIONAL OPTIONS

58       The following options are unlikely to be necessary in ordinary usage.
59       They are provided for special circumstances that may arise.
60
61       -d dirname, --tdsdir=dirname
62            Instead of creating a tarball for CTAN, merely create the package
63            TDS tree rooted in directory dirname.
64
65       -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
70       -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
76       -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
81       -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
87       -nos, --no-tds
88            Do not embed a .tds.zip file in the generated tarball.
89

DIAGNOSTICS

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
98       "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
111       "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
121       "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
129       "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

EXAMPLES

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
145           $ ctanify mypackage.ins mypackage.pdf README
146
147             490347  mypackage.tar.gz
148
149                         1771  mypackage/README
150                        15453  mypackage/mypackage.dtx
151                         1957  mypackage/mypackage.ins
152                       277683  mypackage/mypackage.pdf
153                       246935  mypackage.tds.zip
154
155                                   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
161       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
166       ·    including mypackage.dtx (found by parsing mypackage.ins) in both
167            the mypackage directory and the ZIP file,
168
169       ·    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
173       ·    placing all files into appropriate TDS directories (documentation,
174            source, main package) within the ZIP file.
175
176       Consider what it would take to manually produce an equivalent
177       mypackage.tar.gz file.  ctanify is definitely a simpler, quicker
178       alternative.
179
180   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
188           $ ctanify mypackage.ins "mypackage*.ps=tex/latex/mypackage"
189

FILES

191       perl ctanify is written in Perl and needs a Perl installation to run.
192
193       tar, gzip
194            ctanify requires the GNU tar and gzip programs to create a
195            compressed tarball (.tar.gz).
196
197       zip  ctanify uses a zip program to archive the TDS tree within the main
198            tarball.
199

CAVEATS

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
209       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

SEE ALSO

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

AUTHOR

219       Scott Pakin, scott+ctify@pakin.org
220
222       Copyright 2017 Scott Pakin
223
224       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
229           <http://www.latex-project.org/lppl.txt>
230
231       and version 1.3c or later is part of all distributions of LaTeX version
232       2008/05/04 or later.
233
234
235
236v1.9.1                            2017-04-22                        CTANIFY(1)
Impressum