Debian Codegraph @

texmf-dist/doc/support/sty2dtx/README.txt

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