1STY2DTX(1) User Contributed Perl Documentation STY2DTX(1)
2
6 sty2dtx -- Converts a LaTeX .sty file to a documented .dtx file
7
9 Version: v2.4 - 2022/10/18
10
12 CTAN: https://ctan.org/pkg/sty2dtx
13 Repository: https://github.com/MartinScharrer/sty2dtx
15 Issues: https://github.com/MartinScharrer/sty2dtx/issues
17
19 Copyright (c) 2010-2022 Martin Scharrer <martin.scharrer@web.de>
20 This program is free software: you can redistribute it and/or modify it
22 under the terms of the GNU General Public License as published by the
23 Free Software Foundation, either version 3 of the License, or (at your
24 option) any later version.
25 This program is distributed in the hope that it will be useful, but
27 WITHOUT ANY WARRANTY; without even the implied warranty of
28 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
29 General Public License for more details.
30 You should have received a copy of the GNU General Public License along
32 with this program. If not, see <https://www.gnu.org/licenses/>.
33
35 Converts a .sty file (LaTeX package) to .dtx format (documented LaTeX
36 source), by surrounding macro definitions with 'macro' and 'macrocode'
37 environments. The macro name is automatically inserted as an argument
38 to the 'macro' environemnt. Code lines outside macro definitions are
39 wrapped only in 'macrocode' environments. Empty lines are removed. The
40 script is not thought to be fool proof and 100% accurate but rather as
41 a good start to convert undocumented style files to .dtx files.
42 Basic Usage
44 perl sty2dtx.pl infile [infile ...] outfile
45 or
47 perl sty2dtx.pl < file.sty > file.dtx
49 Supported Definitions
51 The following macro definitions are detected when they are at the start
52 of a line (can be prefixed by \global, \long, \protected and/or
53 \outer):
54 \def \edef \gdef \xdef
56 \newcommand{\name} \newcommand*{\name}
57 \newcommand\name \newcommand*\name
58 \renewcommand{\name} \renewcommand*{\name}
59 \renewcommand\name \renewcommand*\name
60 \providecommand{\name} \providecommand*{\name}
61 \providecommand\name \providecommand*\name
62 \@namedef{\name} \@namedef\name
63 The following environment definitions are detected when they are at the
65 start of a line:
66 \newenvironment{name} \renewenvironemnt{name} \provideenvironment{name}
68 The macro and environment definition must either end at the same line
70 or with a '"}"' on its own on a line.
71
73 sty2dtx [<options>] [--<VAR>=<VALUE> ...] [--] [<infile(s)>] [<outfile>]
74 Files
76 • can be '"-"' for STDIN or STDOUT, which is the default if no files
77 are given
78 • multiple input files are merged to one output file
80 Variables
82 Variables can be defined using
83 --<VAR>=<VALUE>
85 or
87 --<VAR> <VALUE>
89 and will be used for substitutions in the template file.
91 Common variables:
93 author, email, maintainer, year (for copyright),
95 version, date, description (of package/class),
96 type (either 'package' default or 'class'),
97 filebase (automatically set from output or input file name),
98 Options
100 -h Print this help text
101 -H Print extended help
102 -V Print version and copyright
103 -v Be verbose
104 -o output Use given file as output
105 -O Overwrite already existing output file(s)
106 -B Use basename of single input file for output file
107 -I Also create .ins (install) file
108 -c Only use code section (like v1.0)
109 -r Remove existing 'macro', 'macrocode', etc. environments.
110 -R Do not remove existing 'macro', 'macrocode', etc.
111 environments.
112 -i ins-file Create .ins file with given name
113 -t template Use this file as template instead of the default one
114 -T template Use this file as template for the .ins file
115 -e file Export default .dtx template to file and exit
116 -E file Export default .ins template to file and exit
117 -D Use current date as file date
118 -F file Read more options and variables from file.
119 -N Do not read default config file; must be the first option
120 Config files
122 A default config file either named 'sty2dtx.cfg' or '.sty2dtx.cfg' is
123 searched in the current directory, the users home directory and the
124 directory of this script, in this order. The first one found is loaded.
125 If none is found the 'texmf' tree is searched for a 'sty2dtx.cfg'
126 config file. As with -F files the config file should contain one
127 option or variable per line. Lines starting with '"%"' or '"#"' are
128 ignored.
129
131 Produce 'file.dtx' from 'file.sty':
132 sty2dtx.pl < file.sty > file.dtx
134 or
136 sty2dtx.pl file.sty file.dtx
138 or
140 sty2dtx.pl -B file.sty
142 Produce 'file.dtx' and 'file.ins' from 'file.sty':
144 sty2dtx.pl -I file.sty file.dtx
146 or
148 sty2dtx.pl file.sty -i file.sty file.dtx
150 or
152 sty2dtx.pl -IB file.sty
154 Set custom variable values:
156 sty2dtx.pl --author Me --email me@there.com mypkg.sty mypkg.dtx
158 Produce DTX file for a class:
160 sty2dtx.pl --type class mycls.sty mycls.dtx
162
164 Martin Scharrer
165 E-mail: martin.scharrer@web.de
167 WWW: <http://www.scharrer-online.de>
169perl v5.30.0 2022-10-18 STY2DTX(1)