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
|
\documentclass{ydoc}
\title{The \textsf{ctanupload} script}
\author{Martin Scharrer}
\email{martin@scharrer.me}
\date{Version v1.2a -- 2012/05/03}
\providecommand\envvar{\texttt}
\makeatletter
\define@Macro@handler\DescribeScript{}
\makeatother
\begin{document}
\maketitle
\begin{abstract}
This Perl script allows the uploads of a contribution to CTAN from the command line.
It is intended to simplify the release process for LaTeX package authors.
\end{abstract}
\section{Introduction}
The Comprehensive TeX Archive Network (CTAN) is the place to get materials related to the \TeX\ typesetting system.
It provides an web form to upload contributions, like \LaTeX\ packages, to one of the main servers
\url{http://dante.ctan.org/upload} (DANTE server, German TeX users group) or
\url{http://www.tex.ac.uk/upload/} (UK-TUG server, UK TeX users group).
The third main server \url{http://tug.ctan.org/} (TUG, US and International TeX users group) currently does not accept uploads.
After uploading the contribution to one of these servers it will be distributed to the CTAN mirrors where it can be downloaded by other users.
The \texttt{ctanupload} script allows to automate these uploads which is from benefit for \LaTeX\ package authors which
write and maintain a larger number of packages. The script is designed to be used from the command line or from a Makefile or other script
in a full or semi-automatic way. Constant data like the package and author names can be passed automatically to the script while the
variable fields like the version number or announcement text can be entered manually.
The script first collects the required data, applies some sanity checks before it is displayed again for confirmation.
If the data is correct it is uploaded and the status and response from the CTAN upload server is printed.
\section{Usage}
\DescribeScript{ctanupload}<options>~'--'<name>'='<value>~!\ldots!
\DescribeScript{ctanupload}<options>~'--'<name>~<value>~!\ldots!
\DescribeScript{ctanupload}<options>~'--'<name>'-file='<file with value>~!\ldots!
\DescribeScript{ctanupload}<options>~'--'<name>'-file'~<file with value>~!\ldots!
The script accepts single letter options and awaits the upload form fields as double slash arguments.
These fields can also be read from text files or given using environment variables in the form
\MacroArgs'CTAN_'<NAME>, \MacroArgs'CTAN_'<name>, \MacroArgs<NAME> or \MacroArgs<name>\relax (in this order).
The support of environment variable simplifies the usage inside Makefiles.
All arguments can also be given using the \envvar{CTANUPLOAD} environment variable which are processed first, so that
explicit arguments will overwrite them.
\subsubsection*{Options}
The following options control the behaviour of the script. They can also be grouped together, i.e.\ a single dash
followed by multiple options.
\par\medskip\par\noindent
\begin{tabular}{>{\ttfamily}ll}
\toprule
\normalfont Option & Description \\
\midrule
-p & Prompt for missing values.\\
-P & Do not prompt for missing values. (default)\\
-y & Do not ask for confirmation, but submit immediately.\\
-u <URL> & CTAN URL to upload to.\\
-U <name> & CTAN server to upload to, either 'dante' or 'uktug'.\\
-F <file> & Read all data from file. (See below)\\
-f & Force upload even if input seems incorrect (unknown license etc.).\\
-l & Write log file. \\
-L & Do not write log file. (default) \\
-o <file> & Define log file. (still requires -l) \\
-v & Verbose mode. (Passed to the underlying WWW Perl module)\\
-q & Quiet mode. (Passed to the underlying WWW Perl module)\\
-h & Print help and exit.\\
-V & Print version number.\\
\bottomrule
\end{tabular}
\subsubsection*{Fields}
The following fields exists in the CTAN upload form. At least the ones marked as mandatory must be provided.
\par\medskip\par\noindent
\begin{tabular}{>{\ttfamily}llc}
\toprule
\normalfont Field & Description & ~~~~~\llap{Mandatory} \\
\midrule
contribution & Name of your contribution & * \\
version & Version number & *\\
name & Your name & *\\
email & Your email & *\\
summary & Summary description & *\\
directory & Suggested CTAN directory\\
DoNotAnnounce & No need to announce this update\\
announce & Short description for announcement\\
notes & Optional notes to the CTAN maintainers (DANTE only)\\
license & License type (see below) & *\\
freeversion & Which free license (see below)\\
file & File to upload & *\\
\bottomrule
\end{tabular}
\subsubsection*{Valid license types}
The \texttt{license} field can have the following values to indicate the license type:
\par\medskip\par\noindent
\begin{tabular}{>{\ttfamily}ll}
\toprule
\normalfont License Type & Description \\
\midrule
free & Free\\
nocommercial & Nocommercial\\
nosell & Nosell\\
nosource & Nosource\\
shareware & Shareware\\
artistic & Perl Artistic (Clarified or later)\\
other-nonfree & Other nonfree License\\
\bottomrule
\end{tabular}
\subsubsection*{Valid free licenses}
If a free license was choosen using \texttt{license=free}
the specific free license can be selected using the \texttt{freeversion} field which
can have one of the following values:
\par\medskip\par\noindent
\begin{tabular}{>{\ttfamily}ll}
\toprule
\normalfont License Type & Description \\
\midrule
apache2 & Apache License v2.0\\
artistic & Perl Artistic License (version 2)\\
fdl & GNU Free Documentation License\\
gfl & GUST Font License\\
gpl & GNU General Public License\\
lgpl & Lesser GPL\\
lppl & LaTeX Project\\
ofl & Open Font License\\
pd & Public Domain\\
other-free & Other Free\\
\bottomrule
\end{tabular}
\subsubsection*{File input and output}
The upload fields can also be loaded from a text file using the \texttt{-F} option.
Such a file needs to hold one field per line in the form `|name = value|'.
The name should start at the very beginning of a new line. The rest of the line after the equal sign is taken as value.
The \texttt{announce} and \texttt{notes} field can be followed by additional lines of content.
These lines should not start with any content similar to the `|name =|' format, where `|name|' is a single word.
Simply indenting such lines with a space suffices.
Empty lines and line which start with a `|#|', with or without leading spaces, are ignored.
This format is also used when the upload fields are written to a file. This is done when the edit (`|e|') or save (`|s|') option
is selected. This allows the direct editing of this file or the later reuse of all or selected fields, respectively.
Using the \texttt{-l} option the upload data and response can be stored in a log file.
This file is generated in the above format with all extra information starting with `|#|', so that it can be loaded again afterwards.
The log file name can be given using the \texttt{-o} option or using the \texttt{CTANUPLOAD\_LOGFILE} environment variable.
Otherwise the log file name defaults to \MacroArgs'ctanupload_'<contribution>'_'<date (YYYY-MM-DD\_HH-mm-SS)>'.log'
\section{Examples}
\def\example#1{\par\medskip\par\noindent\textbf{#1}\par}
\lstset{numbers=none,basicstyle=\ttfamily\small}
\example{Interactive mode (prompt for all values not read from environment variables):}
\begin{lstlisting}
ctanupload -p
\end{lstlisting}
\example{Fill complete form:}
\begin{lstlisting}
ctanupload --contribution=somepackage --version=v0.1 \
--name "John Doe" --email=john@doe.com \
--summary "New package to do something." \
--directory=/macros/latex/contrib/somepackage \
--DoNotAnnounce=0 \
--announce "This package allows to ..." \
--notes "Some note to the CTAN admins (if required)" \
--license=free --freeversion=lppl
--file=somepackage.tar.gz
\end{lstlisting}
\example{Use of environment variables:}
\noindent
The environment variables can be given in the command line or in a user specific configuration file
which is read by the shell (e.g.\ \texttt{~/.bashrc} for the Bash shell).
Shown here is the Bash shell syntax, which is the common shell for Linux.
The static author data is given as environment variables and the contribution name as argument, while
the script will prompt the user for the rest.
\par\noindent
\begin{lstlisting}
export CTAN_NAME="John Doe"
export CTAN_EMAIL="john@doe.com"
ctanupload --contribution=somepackage -p
\end{lstlisting}
\example{Read date from file:}
\noindent
Here the announcement text is read from a file \texttt{announcement.txt} while the script will prompt the user
for the rest of the fields.
\par\noindent
\begin{lstlisting}
ctanupload --announce-file announcement.txt -p
\end{lstlisting}
\example{Example Makefile:}
\noindent
The following Makefile (see \url{http://www.gnu.org/software/make/manual/make.html}) uses the \texttt{ctanify} script (\url{http://www.ctan.org/pkg/ctanify})
to create a compressed file for submission using \texttt{ctanupload}.
\lstinputlisting[basicstyle=\ttfamily\scriptsize,frame=lrbt]{Makefile.example}
\end{document}
|
