edtx2dtx(1)

✨ edtx2dtx — the little glow-up machine for your .edtx files ✨

okay bestie, so this is edtx2dtx, a User Manual classic, and it's literally the tool that takes a .edtx and turns it into a .dtx. that's it. that's the whole vibe. 💅

---

🌸 NAME 🌸

edtx2dtx — convert .edtx into .dtx 🦋

---

✨ SYNOPSIS ✨

edtx2dtx filename.edtx > filename.dtx

like. redirect it. it's giving pipeline couture. 🎀

---

💖 DESCRIPTION 💖

So here's the tea ☕ — this utility wraps code chunks in a commented-and-properly-indented \begin{macrocode} / \end{macrocode} pair. and a "code chunk", per the lore, is any sequence of lines that is NOT introduced by a single (possibly indented) comment character (%). which means:

• plain non-commented lines? code. ✅
• lines introduced by multiple comment characters? also code. ✅ (yes queen, multiple %s still count as code)
• documentation lines? they may be indented, it's fine. ✅

Then: the part of the file that should actually get processed has to be marked by a \begin{macrocode} and \end{macrocode} pair. in other words, bestie —

• everything preceding \begin{macrocode} = the header, and it is not changed. not a single character.
• everything following \end{macrocode} = the trailer, and it is not changed either.

and fr fr, you can have any number of \begin{macrocode} — \end{macrocode} pairs. go wild. 🫶

the system allows for the driver to remain as is, and it also makes it super easy to paste a .dtx file into an .edtx — because using this utility on a .dtx does not change the file. iconic behaviour honestly.

Oh and ALSO 💅 — the utility replaces the first occurrence of <filename>.edtx in the header — followed by an optional parenthesized note — with <filename>.dtx, plus the note on how the file was generated. cute, right?

---

👑 OPTIONS 👑

• -c, --comment — the input comment character. default is %. and heads up: any input comment characters in the header and the trailer will be replaced by the output comment character, which is always %.
• -b, --begin-macrocode regex — change the default input \begin{macrocode} marker.
• -e, --end-macrocode regex — change the default input \end{macrocode} marker.

okay so both of those together: use these options to change the default input \begin{macrocode} and \end{macrocode} markers. (the output markers are always \begin{macrocode} and \end{macrocode}, no negotiating.) the markers should be given as regular expressions matching the entire line. and note: the input markers are not kept in the file, i.e. they get replaced by the output markers.

• -B, --Begin-macrocode regex — same as -b, but the input markers are kept in the output. (capital letter, capital energy 👑)
• -E, --End-macrocode regex — same as -e, but the input markers are kept in the output.
• -s, --strip-empty — if this option is given, empty lines are not included in the output. bye bye blank space. 🍓
• -h, --help — show help and exit. we love a helpful queen.
• -V, --version — show the version number and exit. ⭐

---

🌈 EXAMPLES 🌈

🦋 example the first

if input.edtx is just like a dtx file — just without \begin{macrocode} and \end{macrocode} around every chunk of code:

edtx2dtx input.edtx > output.dtx

slay. done. ✨

🧚 example the second

Memoize uses the invocation below to produce a .dtx from documented Python code of memoize-extract.py.

• the value of -c adapts edtx2dtx to Python comments.
• -B marks everything preceding the version number statement as a header, and keeps the version number statement in the output.
• similarly, -E says the processing should stop when encountering Emacs' local variables — which are kept, unchanged, in the output.

edtx2dtx -s -c '#' -B '^__version__' -E '^# Local Variables:' $< \

(and yes, that trailing \ is really there. don't @ me. 💀)

---

💜 SEE ALSO 💜

• easydoctex.el

---

💖 and that's the whole page, bestie. go forth and convert. no cap. 🫶

---

edtx2dtx 0.2.0 🌸 — November 23, 2024 🎀 — that's the version and the date, mwah, thanks for reading, ily, bye!! 💅✨