STY2DTX(1)

💖 sty2dtx(1) 💖

ok bestie, gather round, because this one is sty2dtx, a little Perl script from the User Contributed Perl Documentation section of your man pages, and honestly? it's giving glow-up arc for your LaTeX files. ✨

---

🌸 NAME 🌸

sty2dtx — no cap, it converts a LaTeX .sty file to a documented .dtx file. that's it. that's the whole job. iconic. 🎀

---

🦋 VERSION 🦋

Version: v2.4 - 2022/10/18 — yeah she's a 2022 girlie but she still slays 💅

---

🔗 LINKS 🔗

• CTAN: https://ctan.org/pkg/sty2dtx
• Repository: https://github.com/MartinScharrer/sty2dtx
• Issues: https://github.com/MartinScharrer/sty2dtx/issues

if something's broken, that last one is literally where you go. do not come for me, come for the issue tracker 🫶

---

⭐ COPYRIGHT ⭐

Copyright (c) 2010-2022 Martin Scharrer <martin.scharrer@web.de>

ok so legally speaking, and I am being fr fr here: 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. that's the dramatic part, keep it. 💀 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 — and this is your sign — see https://www.gnu.org/licenses/.

---

💜 DESCRIPTION 💜

So what does she actually DO. She takes your .sty file (a LaTeX package) and turns it into .dtx format (documented LaTeX source) by wrapping those macro definitions in macro and macrocode environments. the macro name? auto-inserted as the argument to the macro environment. no manual labor, we love to see it 😌

and if there's code lines hanging around outside of macro definitions? those get wrapped in macrocode environments only. empty lines get removed entirely (they were not serving).

ngl, real talk: this script is not meant to be fool proof or 100% accurate. it's a good start for converting undocumented style files into .dtx files — a starting point, not a miracle worker. set your expectations accordingly bestie 🙈

✨ Basic Usage ✨

perl sty2dtx.pl infile [infile ...] outfile

or

perl sty2dtx.pl < file.sty > file.dtx

🔍 Supported Definitions 🔍

These macro definitions get detected when they're at the start of a line — and yes, they 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

And these environment definitions get detected when they're at the start of a line:

\newenvironment{name}  \renewenvironemnt{name}  \provideenvironment{name}

Now the rules, bestie, because there ARE rules: the macro and environment definition must either end at the same line or end with a "}" on its own on a line. that's the deal. 🤝

---

🌈 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. (those are the comment girlies, let them be 💜)

⭐ 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@web.de

WWW: <http://www.scharrer-online.de>

---

and that's the whole page bestie!! perl v5.30.0, dated 2022-10-18 — so if you ever see that footer floating around, that's this exact girl. go forth and document your style files, you main character. 🦋✨🎀