summaryrefslogtreecommitdiff
path: root/support/ctanify/ctanify.1
diff options
context:
space:
mode:
Diffstat (limited to 'support/ctanify/ctanify.1')
-rw-r--r--support/ctanify/ctanify.1398
1 files changed, 398 insertions, 0 deletions
diff --git a/support/ctanify/ctanify.1 b/support/ctanify/ctanify.1
new file mode 100644
index 0000000000..62f7089f05
--- /dev/null
+++ b/support/ctanify/ctanify.1
@@ -0,0 +1,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.