Direc­tory support/sty2dtx

README

NAME
sty2dtx -- Converts a LaTeX .sty file to a documented .dtx file
VERSION
Version: v2.3
COPYRIGHT
Copyright (c) 2010-2012 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/>.
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.
Basic Usage
perl sty2dtx.pl infile [infile ...] outfile
or
perl sty2dtx.pl < file.sty > file.dtx
Supported Definitions
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.
USAGE
sty2dtx [<options>] [--<VAR>=<VALUE> ...] [--] [<infile(s)>] [<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
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
-c Only use code section (like v1.0)
-r Remove existing 'macro', 'macrocode', etc. environments.
-R Do not remove existing 'macro', 'macrocode', etc.
environments.
-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.
-N Do not read default config file; must be the first option
Config files
A default config file either named 'sty2dtx.cfg' or '.sty2dtx.cfg' is
searched in the current directory, the users home directory and the
directory of this script, in this order. The first one found is loaded.
If none is found the 'texmf' tree is searched for a 'sty2dtx.cfg' config
file. As with -F files the config file should contain one option or
variable per line. Lines starting with '"%"' or '"#"' are ignored.
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
AUTHOR
Martin Scharrer
E-mail: martin@scharrer-online.de
WWW: <http://www.scharrer-online.de>

sty2dtx – Create a .dtx file from a .sty file

The pack­age pro­vides a Perl script that con­verts a .sty
file (LaTeX pack­age) to .dtx for­mat (doc­u­mented LaTeX
source), by sur­round­ing macro def­i­ni­tions with macro and
macrocode en­vi­ron­ments. The macro name is au­to­mat­i­cally
in­serted as an ar­gu­ment to the macro en­vi­ronemnt.

The script should not be thought to be fool proof and 100%
ac­cu­rate but rather as a good start to the busi­ness of mak­ing a
.dtx file from an un­doc­u­mented style file.

Full .dtx files are gen­er­ated. A tem­plate based on the skele­ton file
from 'dtx­tut' is used. User level macros are added au­to­mat­i­cally to
the 'Usage' sec­tion of the .dtx file. A cor­re­spond­ing .ins file can
be gen­er­ated as well.