Debian Codegraph @

texmf-dist/doc/man/man1/ctanify.1

raw
1 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 . ds C`
42 . ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el .ds Aq '
48 .\"
49 .\" If the F register is turned on, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .nr rF 0
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{
60 . if \nF \{
61 . de IX
62 . tm Index:\\$1\t\\n%\t"\\$2"
63 ..
64 . if !\nF==2 \{
65 . nr % 0
66 . nr F 2
67 . \}
68 . \}
69 .\}
70 .rr rF
71 .\"
72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73 .\" Fear. Run. Save yourself. No user-serviceable parts.
74 . \" fudge factors for nroff and troff
75 .if n \{\
76 . ds #H 0
77 . ds #V .8m
78 . ds #F .3m
79 . ds #[ \f1
80 . ds #] \fP
81 .\}
82 .if t \{\
83 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84 . ds #V .6m
85 . ds #F 0
86 . ds #[ \&
87 . ds #] \&
88 .\}
89 . \" simple accents for nroff and troff
90 .if n \{\
91 . ds ' \&
92 . ds ` \&
93 . ds ^ \&
94 . ds , \&
95 . ds ~ ~
96 . ds /
97 .\}
98 .if t \{\
99 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 .\}
106 . \" troff and (daisy-wheel) nroff accents
107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114 .ds ae a\h'-(\w'a'u*4/10)'e
115 .ds Ae A\h'-(\w'A'u*4/10)'E
116 . \" corrections for vroff
117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119 . \" for low resolution devices (crt and lpr)
120 .if \n(.H>23 .if \n(.V>19 \
121 \{\
122 . ds : e
123 . ds 8 ss
124 . ds o a
125 . ds d- d\h'-1'\(ga
126 . ds D- D\h'-1'\(hy
127 . ds th \o'bp'
128 . ds Th \o'LP'
129 . ds ae ae
130 . ds Ae AE
131 .\}
132 .rm #[ #] #H #V #F C
133 .\" ========================================================================
134 .\"
135 .IX Title "CTANIFY 1"
136 .TH CTANIFY 1 "2017-04-22" "v1.9.1" ""
137 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
138 .\" way too many mistakes in technical documents.
139 .if n .ad l
140 .nh
141 .SH "NAME"
142 ctanify \- Prepare a package for upload to CTAN
143 .SH "SYNOPSIS"
144 .IX Header "SYNOPSIS"
145 ctanify
146 [\fB\-\-pkgname\fR=\fIstring\fR]
147 [\fB\-\-\fR[\fBno\fR]\fBauto\fR]
148 [\fB\-\-tdsonly\fR=\fIfilespec\fR ...]
149 [\fB\-\-\fR[\fBno\fR]\fBunixify\fR]
150 [\fB\-\-\fR[\fBno\fR]\fBskip\fR]
151 [\fB\-\-tdsdir\fR=\fIdirname\fR ...]
152 [\fB\-\-tex\fR=\fImacro_pkg\fR]
153 [\fB\-\-\fR[\fBno\fR]\fBmiscify\fR]
154 [\fB\-\-\fR[\fBno\fR]\fBtds\fR]
155 \&\fIfilespec\fR[=\fIdirname\fR] ...
156 .PP
157 ctanify
158 [\fB\-\-help\fR]
159 .PP
160 ctanify
161 [\fB\-\-version\fR]
162 .SH "DESCRIPTION"
163 .IX Header "DESCRIPTION"
164 \&\fBctanify\fR is intended for developers who have a LaTeX package that
165 they want to distribute via the Comprehensive TeX Archive Network
166 (\s-1CTAN\s0). Given a list of filenames, \fBctanify\fR creates a tarball (a
167 \&\fI.tar.gz\fR file) with the files laid out in \s-1CTAN\s0's preferred
168 structure. The tarball additionally contains a \s-1ZIP \s0(\fI.zip\fR) file
169 with copies of all files laid out in the standard TeX Directory
170 Structure (\s-1TDS\s0), which facilitates inclusion of the package in the TeX
171 Live distribution.
172 .SH "OPTIONS"
173 .IX Header "OPTIONS"
174 \&\fBctanify\fR accepts the following command-line options:
175 .IP "\fB\-h\fR, \fB\-\-help\fR" 5
176 .IX Item "-h, --help"
177 Output basic usage information and exit.
178 .IP "\fB\-V\fR, \fB\-\-version\fR" 5
179 .IX Item "-V, --version"
180 Output \fBctanify\fR's version number and exit.
181 .IP "\fB\-p\fR \fIstring\fR, \fB\-\-pkgname\fR=\fIstring\fR" 5
182 .IX Item "-p string, --pkgname=string"
183 Specify explicitly a package name. Normally, \fBctanify\fR uses the base
184 name of the first \fI.ins\fR or \fI.sty\fR file listed as the package name.
185 The package name forms the base name of the tarball that \fBctanify\fR
186 produces.
187 .IP "\fB\-\-noauto\fR" 5
188 .IX Item "--noauto"
189 Do not automatically add files to the tarball. Normally, \fBctanify\fR
190 automatically includes all files mentioned in a \fI.ins\fR file.
191 .IP "\fB\-t\fR \fIfilespec\fR, \fB\-\-tdsonly\fR=\fIfilespec\fR" 5
192 .IX Item "-t filespec, --tdsonly=filespec"
193 Specify a subset of the files named on the command line to include
194 only in the \s-1TDS ZIP\s0 file, not in the \s-1CTAN\s0 package directory.
195 Wildcards are allowed (quoted if necessary), and \fB\-\-tdsonly\fR can be
196 used multiple times on the same command line.
197 .PP
198 At least one filename must be specified on the command line.
199 \&\fBctanify\fR automatically places files in the \s-1TDS\s0 tree based on their
200 extension, but this can be overridden by specifying explicitly a
201 target \s-1TDS\s0 directory using the form \fIfilespec\fR=\fIdirname\fR. Wildcards
202 are allowed for the filespec (quoted if necessary).
203 .SH "ADDITIONAL OPTIONS"
204 .IX Header "ADDITIONAL OPTIONS"
205 The following options are unlikely to be necessary in ordinary usage.
206 They are provided for special circumstances that may arise.
207 .IP "\fB\-d\fR \fIdirname\fR, \fB\-\-tdsdir\fR=\fIdirname\fR" 5
208 .IX Item "-d dirname, --tdsdir=dirname"
209 Instead of creating a tarball for \s-1CTAN,\s0 merely create the package \s-1TDS\s0
210 tree rooted in directory \fIdirname\fR.
211 .IP "\fB\-T\fR \fImacro_pkg\fR, \fB\-\-tex\fR=\fImacro_pkg\fR" 5
212 .IX Item "-T macro_pkg, --tex=macro_pkg"
213 Assert that the files being packaged for \s-1CTAN\s0 target a TeX macro
214 package other than LaTeX. Some common examples of \fImacro_pkg\fR are
215 \&\f(CW\*(C`generic\*(C'\fR, \f(CW\*(C`plain\*(C'\fR, and \f(CW\*(C`context\*(C'\fR.
216 .IP "\fB\-nou\fR, \fB\-\-no\-unixify\fR" 5
217 .IX Item "-nou, --no-unixify"
218 Store text files unmodified instead of converting their end-of-line
219 character to Unix format (a single linefeed character with no
220 carriage-return character), even though \s-1CTAN\s0 prefers receiving all
221 files with Unix-format end-of-line characters.
222 .IP "\fB\-nok\fR, \fB\-\-no\-skip\fR" 5
223 .IX Item "-nok, --no-skip"
224 Force \fBctanify\fR to include files such as Unix hidden files, Emacs
225 backup files, and version-control metadata files, all of which \s-1CTAN\s0
226 dislikes receiving.
227 .IP "\fB\-m\fR, \fB\-\-miscify\fR" 5
228 .IX Item "-m, --miscify"
229 Rename directories containing a single file to \f(CW\*(C`misc\*(C'\fR. (For example,
230 rename \f(CW\*(C`tex/latex/mypackage/mypackage.sty\*(C'\fR to
231 \&\f(CW\*(C`tex/latex/misc/mypackage.sty\*(C'\fR.) This was common practice in the
232 past but is now strongly discouraged.
233 .IP "\fB\-nos\fR, \fB\-\-no\-tds\fR" 5
234 .IX Item "-nos, --no-tds"
235 Do not embed a .tds.zip file in the generated tarball.
236 .SH "DIAGNOSTICS"
237 .IX Header "DIAGNOSTICS"
238 .ie n .IP """Failed to copy \f(CIfilename\f(CW (No such file or directory)""" 5
239 .el .IP "\f(CWFailed to copy \f(CIfilename\f(CW (No such file or directory)\fR" 5
240 .IX Item "Failed to copy filename (No such file or directory)"
241 This message is typically caused by a \fI.ins\fR file that generates
242 \&\fIfilename\fR but that has not already been run through \fItex\fR or
243 \&\fIlatex\fR to actually produce \fIfilename\fR. \fBctanify\fR does not
244 automatically run \fItex\fR or \fIlatex\fR; this needs to be done manually
245 by the user. See \*(L"\s-1CAVEATS\*(R"\s0 for more information.
246 .ie n .IP """Modified \f(CIfilename\f(CW to use Unix line endings (use \-\-no\-unixify to prevent this)""" 5
247 .el .IP "\f(CWModified \f(CIfilename\f(CW to use Unix line endings (use \-\-no\-unixify to prevent this)\fR" 5
248 .IX Item "Modified filename to use Unix line endings (use --no-unixify to prevent this)"
249 For consistency, \s-1CTAN\s0 stores all text files with Unix-style line
250 endings (a single linefeed character with no carriage-return
251 character). To help in this effort, \fBctanify\fR automatically replaces
252 non-Unix-style line endings. The preceding merely message notifies
253 the user that he should not be alarmed to see a different size for
254 \&\fIfilename\fR in the tarball versus the original \fIfilename\fR on disk
255 (which \fBctanify\fR never modifies). If there's a good reason to
256 preserve the original line endings (and there rarely is), the
257 \&\fB\-\-no\-unixify\fR option can be used to prevent \fBctanify\fR from altering
258 any files when storing them in the tarball.
259 .ie n .IP """Excluding \f(CIfilename\f(CW (use \-\-no\-skip to force inclusion)""" 5
260 .el .IP "\f(CWExcluding \f(CIfilename\f(CW (use \-\-no\-skip to force inclusion)\fR" 5
261 .IX Item "Excluding filename (use --no-skip to force inclusion)"
262 \&\fBctanify\fR normally ignores files\*(--even when specified explicitly on
263 the command line\*(--that \s-1CTAN\s0 prefers not receiving. These include
264 files whose names start with "\fI.\fR\*(L" (Unix hidden files), end in \*(R"\fI~\fR"
265 (Emacs automatic backups), or that come from a \fI\s-1CVS\s0\fR or \fI.svn\fR
266 directory (version-control metadata files). If there's a good reason
267 to submit such files to \s-1CTAN \s0(and there rarely is), the \fB\-\-no\-skip\fR
268 option can be used to prevent \fBctanify\fR from ignoring them.
269 .ie n .IP """CTAN prefers having only PDF documentation (re: \f(CIfilename\f(CW)""" 5
270 .el .IP "\f(CWCTAN prefers having only PDF documentation (re: \f(CIfilename\f(CW)\fR" 5
271 .IX Item "CTAN prefers having only PDF documentation (re: filename)"
272 Because of the popularity of the \s-1PDF\s0 format, \s-1CTAN\s0 wants to have as
273 much documentation as possible distributed in \s-1PDF. \s0 The preceding
274 message asks the user to replace any PostScript or \s-1DVI\s0 documentation
275 with \s-1PDF\s0 if possible. (\fBctanify\fR will still include PostScript and
276 \&\s-1DVI\s0 documentation in the tarball; the preceding message is merely a
277 polite request.)
278 .ie n .IP """Not including \f(CIfilename\f(CW in the TDS tree (unknown extension)""" 5
279 .el .IP "\f(CWNot including \f(CIfilename\f(CW in the TDS tree (unknown extension)\fR" 5
280 .IX Item "Not including filename in the TDS tree (unknown extension)"
281 \&\fBctanify\fR places files in the \s-1TDS\s0 tree based on a table of file
282 extensions. For example, all \fI.sty\fR files are placed in
283 \&\fItex/latex/\fIpackage-name\fI\fR. If \fBctanify\fR does not know where to
284 put a file it does not put it anywhere. See the last paragraph of
285 \&\*(L"\s-1OPTIONS\*(R"\s0 for an explanation of how to specify explicitly a file's
286 target location in the \s-1TDS\s0 tree. For common file extensions that
287 happen to be absent from \fBctanify\fR's table, consider also notifying
288 \&\fBctanify\fR's author at the address shown below under \*(L"\s-1AUTHOR\*(R"\s0.
289 .SH "EXAMPLES"
290 .IX Header "EXAMPLES"
291 .SS "The Common Case"
292 .IX Subsection "The Common Case"
293 Normally, all that's needed is to tell \fBctanify\fR the name of the
294 \&\fI.ins\fR file (or \fI.sty\fR if the package does not use DocStrip) and the
295 prebuilt documentation, if any:
296 .PP
297 .Vb 1
298 \& $ ctanify mypackage.ins mypackage.pdf README
299 \&
300 \& 490347 mypackage.tar.gz
301 \&
302 \& 1771 mypackage/README
303 \& 15453 mypackage/mypackage.dtx
304 \& 1957 mypackage/mypackage.ins
305 \& 277683 mypackage/mypackage.pdf
306 \& 246935 mypackage.tds.zip
307 \&
308 \& 1771 doc/latex/mypackage/README
309 \& 277683 doc/latex/mypackage/mypackage.pdf
310 \& 15453 source/latex/mypackage/mypackage.dtx
311 \& 1957 source/latex/mypackage/mypackage.ins
312 \& 1725 tex/latex/mypackage/mypackage.sty
313 .Ve
314 .PP
315 \&\fBctanify\fR outputs the size in bytes of the resulting tarball, each
316 file within it, and each file within the contained \s-1ZIP\s0 file. In the
317 preceding example, notice how \fBctanify\fR automatically performed all
318 of the following operations:
319 .IP "\(bu" 5
320 including \fImypackage.dtx\fR (found by parsing \fImypackage.ins\fR) in both
321 the \fImypackage\fR directory and the \s-1ZIP\s0 file,
322 .IP "\(bu" 5
323 including \fImypackage.sty\fR (found by parsing \fImypackage.ins\fR) in the
324 \&\s-1ZIP\s0 file but, because it's a generated file, not in the \fImypackage\fR
325 directory, and
326 .IP "\(bu" 5
327 placing all files into appropriate \s-1TDS\s0 directories (documentation,
328 source, main package) within the \s-1ZIP\s0 file.
329 .PP
330 Consider what it would take to manually produce an equivalent
331 \&\fImypackage.tar.gz\fR file. \fBctanify\fR is definitely a simpler, quicker
332 alternative.
333 .SS "Advanced Usage"
334 .IX Subsection "Advanced Usage"
335 \&\fBctanify\fR assumes that PostScript files are documentation and
336 therefore stores them under \fIdoc/latex/\fIpackage-name\fI/\fR in the \s-1TDS\s0
337 tree within the \s-1ZIP\s0 File. Suppose, however, that a LaTeX package uses
338 a set of PostScript files to control \fBdvips\fR's output. In this case,
339 \&\fBctanify\fR must be told to include those PostScript files in the
340 package directory, not the documentation directory.
341 .PP
342 .Vb 1
343 \& $ ctanify mypackage.ins "mypackage*.ps=tex/latex/mypackage"
344 .Ve
345 .SH "FILES"
346 .IX Header "FILES"
347 .IP "\fIperl\fR" 5
348 .IX Item "perl"
349 \&\fBctanify\fR is written in Perl and needs a Perl installation to run.
350 .IP "\fItar\fR, \fIgzip\fR" 5
351 .IX Item "tar, gzip"
352 \&\fBctanify\fR requires the \s-1GNU \s0\fItar\fR and \fIgzip\fR programs to create a
353 compressed tarball (\fI.tar.gz\fR).
354 .IP "\fIzip\fR" 5
355 .IX Item "zip"
356 \&\fBctanify\fR uses a \fIzip\fR program to archive the \s-1TDS\s0 tree within the
357 main tarball.
358 .SH "CAVEATS"
359 .IX Header "CAVEATS"
360 \&\fBctanify\fR does not invoke \fItex\fR or \fIlatex\fR on its own, e.g.,\ to
361 process a \fI.ins\fR file. The reason is that \fBctanify\fR does not know
362 in the general case how to produce all of a package's generated files.
363 It was deemed better to do nothing than to risk overwriting existing
364 \&\fI.sty\fR (or other) files or to include outdated generated files in the
365 tarball. In short, before running \fBctanify\fR you should manually
366 process any \fI.ins\fR files and otherwise generate any files that should
367 be sent to \s-1CTAN.\s0
368 .PP
369 \&\fBctanify\fR has been tested only on Linux. It may work on \s-1OS\s0\ X.
370 I've been told that it works on Windows when run using Cygwin.
371 Volunteers willing to help port \fBctanify\fR to other platforms are
372 extremely welcome.
373 .SH "SEE ALSO"
374 .IX Header "SEE ALSO"
375 \&\fItar\fR\|(1),
376 \&\fIzip\fR\|(1),
377 \&\fIlatex\fR\|(1),
378 Guidelines for uploading TDS-Packaged materials to \s-1CTAN
379 \&\s0(<http://www.ctan.org/TDS\-guidelines>),
380 A Directory Structure for TeX Files (<http://tug.org/tds/>),
381 .SH "AUTHOR"
382 .IX Header "AUTHOR"
383 Scott Pakin, \[email protected]\fR
384 .SH "COPYRIGHT AND LICENSE"
385 .IX Header "COPYRIGHT AND LICENSE"
386 Copyright 2017 Scott Pakin
387 .PP
388 This work may be distributed and/or modified under the conditions of
389 the LaTeX Project Public License, either version\ 1.3c of this
390 license or (at your option) any later version. The latest version of
391 this license is in
392 .Sp
393 .RS 4
394 <http://www.latex\-project.org/lppl.txt>
395 .RE
396 .PP
397 and version\ 1.3c or later is part of all distributions of LaTeX
398 version 2008/05/04 or later.