Debian Codegraph @

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

raw
1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
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 >0, 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 "STY2DTX 1"
136 .TH STY2DTX 1 "2022-10-18" "perl v5.30.0" "User Contributed Perl Documentation"
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 sty2dtx \-\- Converts a LaTeX .sty file to a documented .dtx file
143 .SH "VERSION"
144 .IX Header "VERSION"
145 Version: v2.4 \- 2022/10/18
146 .SH "LINKS"
147 .IX Header "LINKS"
148 \&\s-1CTAN:\s0 https://ctan.org/pkg/sty2dtx
149 .PP
150 Repository: https://github.com/MartinScharrer/sty2dtx
151 .PP
152 Issues: https://github.com/MartinScharrer/sty2dtx/issues
153 .SH "COPYRIGHT"
154 .IX Header "COPYRIGHT"
155 Copyright (c) 2010\-2022 Martin Scharrer <[email protected]>
156 .PP
157 This program is free software: you can redistribute it and/or modify
158 it under the terms of the \s-1GNU\s0 General Public License as published by
159 the Free Software Foundation, either version 3 of the License, or
160 (at your option) any later version.
161 .PP
162 This program is distributed in the hope that it will be useful,
163 but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
164 \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the
165 \&\s-1GNU\s0 General Public License for more details.
166 .PP
167 You should have received a copy of the \s-1GNU\s0 General Public License
168 along with this program. If not, see <https://www.gnu.org/licenses/>.
169 .SH "DESCRIPTION"
170 .IX Header "DESCRIPTION"
171 Converts a .sty file (LaTeX package) to .dtx format (documented LaTeX source),
172 by surrounding macro definitions with 'macro' and 'macrocode' environments.
173 The macro name is automatically inserted as an argument to the 'macro'
174 environemnt.
175 Code lines outside macro definitions are wrapped only in 'macrocode'
176 environments. Empty lines are removed.
177 The script is not thought to be fool proof and 100% accurate but rather
178 as a good start to convert undocumented style files to .dtx files.
179 .SS "Basic Usage"
180 .IX Subsection "Basic Usage"
181 .Vb 1
182 \& perl sty2dtx.pl infile [infile ...] outfile
183 .Ve
184 .PP
185 or
186 .PP
187 .Vb 1
188 \& perl sty2dtx.pl < file.sty > file.dtx
189 .Ve
190 .SS "Supported Definitions"
191 .IX Subsection "Supported Definitions"
192 The following macro definitions are detected when they are at the start of a
193 line (can be prefixed by \eglobal, \elong, \eprotected and/or \eouter):
194 .PP
195 .Vb 8
196 \& \edef \eedef \egdef \exdef
197 \& \enewcommand{\ename} \enewcommand*{\ename}
198 \& \enewcommand\ename \enewcommand*\ename
199 \& \erenewcommand{\ename} \erenewcommand*{\ename}
200 \& \erenewcommand\ename \erenewcommand*\ename
201 \& \eprovidecommand{\ename} \eprovidecommand*{\ename}
202 \& \eprovidecommand\ename \eprovidecommand*\ename
203 \& \e@namedef{\ename} \e@namedef\ename
204 .Ve
205 .PP
206 The following environment definitions are detected when they are at the start
207 of a line:
208 .PP
209 .Vb 1
210 \& \enewenvironment{name} \erenewenvironemnt{name} \eprovideenvironment{name}
211 .Ve
212 .PP
213 The macro and environment definition must either end at the same line or with
214 a '\f(CW\*(C`}\*(C'\fR' on its own on a line.
215 .SH "USAGE"
216 .IX Header "USAGE"
217 .Vb 1
218 \& sty2dtx [<options>] [\-\-<VAR>=<VALUE> ...] [\-\-] [<infile(s)>] [<outfile>]
219 .Ve
220 .SS "Files"
221 .IX Subsection "Files"
222 .IP "\(bu" 2
223 can be '\f(CW\*(C`\-\*(C'\fR' for \s-1STDIN\s0 or \s-1STDOUT,\s0 which is the default if no files are given
224 .IP "\(bu" 2
225 multiple input files are merged to one output file
226 .SS "Variables"
227 .IX Subsection "Variables"
228 Variables can be defined using
229 .PP
230 .Vb 1
231 \& \-\-<VAR>=<VALUE>
232 .Ve
233 .PP
234 or
235 .PP
236 .Vb 1
237 \& \-\-<VAR> <VALUE>
238 .Ve
239 .PP
240 and will be used for substitutions in the template file.
241 .PP
242 \fICommon variables:\fR
243 .IX Subsection "Common variables:"
244 .PP
245 .Vb 4
246 \& author, email, maintainer, year (for copyright),
247 \& version, date, description (of package/class),
248 \& type (either \*(Aqpackage\*(Aq default or \*(Aqclass\*(Aq),
249 \& filebase (automatically set from output or input file name),
250 .Ve
251 .SS "Options"
252 .IX Subsection "Options"
253 .IP "\fB\-h\fR \ \ \ \ \ \ \ \ \ \ Print this help text" 8
254 .IX Item "-h Print this help text"
255 .PD 0
256 .IP "\fB\-H\fR \ \ \ \ \ \ \ \ \ \ Print extended help" 8
257 .IX Item "-H Print extended help"
258 .IP "\fB\-V\fR \ \ \ \ \ \ \ \ \ \ Print version and copyright" 8
259 .IX Item "-V Print version and copyright"
260 .IP "\fB\-v\fR \ \ \ \ \ \ \ \ \ \ Be verbose" 8
261 .IX Item "-v Be verbose"
262 .IP "\fB\-o\fR \fIoutput\fR \ \ \ Use given file as output" 8
263 .IX Item "-o output Use given file as output"
264 .IP "\fB\-O\fR \ \ \ \ \ \ \ \ \ \ Overwrite already existing output file(s)" 8
265 .IX Item "-O Overwrite already existing output file(s)"
266 .IP "\fB\-B\fR \ \ \ \ \ \ \ \ \ \ Use basename of single input file for output file" 8
267 .IX Item "-B Use basename of single input file for output file"
268 .IP "\fB\-I\fR \ \ \ \ \ \ \ \ \ \ Also create .ins (install) file" 8
269 .IX Item "-I Also create .ins (install) file"
270 .IP "\fB\-c\fR \ \ \ \ \ \ \ \ \ \ Only use code section (like v1.0)" 8
271 .IX Item "-c Only use code section (like v1.0)"
272 .IP "\fB\-r\fR \ \ \ \ \ \ \ \ \ \ Remove existing 'macro', 'macrocode', etc. environments." 8
273 .IX Item "-r Remove existing 'macro', 'macrocode', etc. environments."
274 .IP "\fB\-R\fR \ \ \ \ \ \ \ \ \ \ Do not remove existing 'macro', 'macrocode', etc. environments." 8
275 .IX Item "-R Do not remove existing 'macro', 'macrocode', etc. environments."
276 .IP "\fB\-i\fR \fIins-file\fR \ Create .ins file with given name" 8
277 .IX Item "-i ins-file Create .ins file with given name"
278 .IP "\fB\-t\fR \fItemplate\fR \ Use this file as template instead of the default one" 8
279 .IX Item "-t template Use this file as template instead of the default one"
280 .IP "\fB\-T\fR \fItemplate\fR \ Use this file as template for the .ins file" 8
281 .IX Item "-T template Use this file as template for the .ins file"
282 .IP "\fB\-e\fR \fIfile\fR \ \ \ \ \ Export default .dtx template to file and exit" 8
283 .IX Item "-e file Export default .dtx template to file and exit"
284 .IP "\fB\-E\fR \fIfile\fR \ \ \ \ \ Export default .ins template to file and exit" 8
285 .IX Item "-E file Export default .ins template to file and exit"
286 .IP "\fB\-D\fR \ \ \ \ \ \ \ \ \ \ Use current date as file date" 8
287 .IX Item "-D Use current date as file date"
288 .IP "\fB\-F\fR \fIfile\fR \ \ \ \ \ Read more options and variables from file." 8
289 .IX Item "-F file Read more options and variables from file."
290 .IP "\fB\-N\fR \ \ \ \ \ \ \ \ \ \ Do not read default config file; must be the first option" 8
291 .IX Item "-N Do not read default config file; must be the first option"
292 .PD
293 .SS "Config files"
294 .IX Subsection "Config files"
295 A default config file either named 'sty2dtx.cfg' or '.sty2dtx.cfg' is searched
296 in the current directory, the users home directory and the directory of this
297 script, in this order. The first one found is loaded. If none is found the
298 \&'texmf' tree is searched for a 'sty2dtx.cfg' config file. As with \-F files the
299 config file should contain one option or variable per line.
300 Lines starting with '\f(CW\*(C`%\*(C'\fR' or '\f(CW\*(C`#\*(C'\fR' are ignored.
301 .SH "Examples"
302 .IX Header "Examples"
303 Produce 'file.dtx' from 'file.sty':
304 .PP
305 .Vb 1
306 \& sty2dtx.pl < file.sty > file.dtx
307 .Ve
308 .PP
309 or
310 .PP
311 .Vb 1
312 \& sty2dtx.pl file.sty file.dtx
313 .Ve
314 .PP
315 or
316 .PP
317 .Vb 1
318 \& sty2dtx.pl \-B file.sty
319 .Ve
320 .PP
321 Produce 'file.dtx' and 'file.ins' from 'file.sty':
322 .PP
323 .Vb 1
324 \& sty2dtx.pl \-I file.sty file.dtx
325 .Ve
326 .PP
327 or
328 .PP
329 .Vb 1
330 \& sty2dtx.pl file.sty \-i file.sty file.dtx
331 .Ve
332 .PP
333 or
334 .PP
335 .Vb 1
336 \& sty2dtx.pl \-IB file.sty
337 .Ve
338 .PP
339 Set custom variable values:
340 .PP
341 .Vb 1
342 \& sty2dtx.pl \-\-author Me \-\-email [email protected] mypkg.sty mypkg.dtx
343 .Ve
344 .PP
345 Produce \s-1DTX\s0 file for a class:
346 .PP
347 .Vb 1
348 \& sty2dtx.pl \-\-type class mycls.sty mycls.dtx
349 .Ve
350 .SH "AUTHOR"
351 .IX Header "AUTHOR"
352 Martin Scharrer
353 .PP
354 E\-mail: [email protected]
355 .PP
356 \&\s-1WWW:\s0 <http://www.scharrer\-online.de>