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