summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/sty2dtx/README
blob: f9f93a2a457a085bd6a5ebe76afcce9340002a1e (plain)
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
sty2dtx -- Converts a LaTeX .sty file to a documented .dtx file
Version: v2.1 2011/02/02

QUICK START:
To generate a .DTX and .INS file from an existing .STY file run:

    sty2dtx.pl -IB yourfile.sty

The script name might be only 'sty2dtx' without the '.pl' on your installation.
Also try to run it explicitly with perl: "perl sty2dtx.pl -IB yourfile.sty"



DESCRIPTION:
Converts a .sty file (LaTeX package) to .dtx format (documented LaTeX source),
by surrounding macro definitions with 'macro' and 'macrocode' environments.
The macro name is automatically inserted as an argument to the 'macro'
environemnt.
Code lines outside macro definitions are wrapped only in 'macrocode'
environments. Empty lines are removed.
The script is not thought to be fool proof and 100% accurate but rather
as a good start to convert undocumented style files to .dtx files.



LICENCE & COPYRIGHT
Copyright (c) 2010-2011 Martin Scharrer <martin@scharrer-online.de>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.



USAGE:

sty2dtx.pl [<options>] [--<VAR>=<VALUE> ...] [--] [<infile> ...] [<outfile>]

Files:
  * can be '-' for STDIN or STDOUT, which is the default if no files are given
  * multiple input files are merged to one output file

Variables:
  can be defined using --<VAR>=<VALUE> or --<VAR> <VALUE> and will be used for
  substitutions in the template file.
  Common variables:
      author, email, maintainer, year (for copyright),
      version, date, description (of package/class),
      type (either 'package' default or 'class'),
      filebase (automatically set from output or input file name),

Options:
  -h            : Print this help text
  -H            : Print extended help
  -V            : Print version and copyright
  -v            : Be verbose
  -o <output>   : Use given file as output
  -O            : Overwrite already existing output file(s)
  -B            : Use basename of single input file for output file
  -I            : Also create .ins (install) file
  -i <ins file> : Create .ins file with given name
  -t <template> : Use this file as template instead of the default one
  -T <template> : Use this file as template for the .ins file
  -e <file>     : Export default .dtx template to file and exit
  -E <file>     : Export default .ins template to file and exit
  -D            : Use current date as file date
  -F <file>     : Read more options and variables from file.
                  Should contain one option or variable per line only.

Examples:
  Produce 'file.dtx' from 'file.sty':
    sty2dtx.pl < file.sty > file.dtx
   or
    sty2dtx.pl file.sty file.dtx
   or
    sty2dtx.pl -B file.sty

  Produce 'file.dtx' and 'file.ins' from 'file.sty':
    sty2dtx.pl -I file.sty file.dtx
   or
    sty2dtx.pl file.sty -i file.sty file.dtx
   or
    sty2dtx.pl -IB file.sty

  Set custom variable values:
    sty2dtx.pl --author Me --email me@there.com mypkg.sty mypkg.dtx

  Produce DTX file for a class:
    sty2dtx.pl --type class mycls.sty mycls.dtx



SUPPORTED FORMAT
The following macro definitions are detected when they are at the start of a
line (can be prefixed by \global, \long, \protected and/or \outer):
  \def   \edef   \gdef   \xdef
  \newcommand{\name}     \newcommand*{\name}
  \newcommand\name       \newcommand*\name
  \renewcommand{\name}   \renewcommand*{\name}
  \renewcommand\name     \renewcommand*\name
  \providecommand{\name} \providecommand*{\name}
  \providecommand\name   \providecommand*\name
  \@namedef{\name}       \@namedef\name

The following environment definitions are detected when they are at the start
of a line:
  \newenvironment{name}  \renewenvironemnt{name}  \provideenvironment{name}

The macro and environment definition must either end at the same line or with
a '}' on its own on a line.


CHANGELOG
 v1.0  2011/01/29 :  First release. Generation of DTX code section only
 v2.0  2011/01/31 :  Generation of full DTX files with many available options
 v2.1  2011/02/02 :  Improved handling of comments included in the STY file


FEEDBACK & BUG REPORTS
Please do not hesitate to contact the author
Martin Scharrer <martin@scharrer-online.de> for any remarks, questions 
and errors about the script.
If you use and like it please tell him so!