TWILL(1)

💅 TWILL(1) — okay bestie, let's talk ✨

So this is the General Commands Manual page for TWILL(1), and honestly? It's giving "niche but iconic." Sit down, grab a boba, and let me tell you about twill. 🧚

---

🌸 NAME 🌸

twill, twill-refsort — translate a literate programming WEB to TeX with mini-indexes. No cap, that's literally the whole job description. 🎀

---

✨ SYNOPSIS ✨

twill [-x] webfile[.web] [{changefile[.ch]|-} [outfile[.tex]]]
twill-refsort < reffile.ref > sreffile.sref

Look at those two little lines. They're small but they're doing the most. 🫶

---

🦋 DESCRIPTION 🦋

Okay so. The twill program is used to create a TeX file for viewing a literate program written in WEB. That's the vibe. The output TeX file name is formed by adding .tex to the root of the file name — like, it's not gonna invent a whole new name for itself, it's just gonna slap .tex on the end. Periodt.

twill is like weave(1), but it also supplies cross-reference information in the form of mini-indexes for each spread of pages, for identifiers used on that spread, and a master index at the end that it gathers automatically. So it's weave's cooler sibling who actually keeps track of where everything is. 💅

Now here's the part where I need you to listen, bestie, because this is the classic "read the instructions" moment:

You need to run twill twice — once to prime the pump and once to get decent answers. Moreover, you must run the output twice through TeX. Yes. Twice. Both things. Twice. 😭

Let's walk it through for a program foo.web:

1. After a first tex foo you will have output that looks like final pages except that the entries of mini-indexes will not be alphabetized. Not broken! Just not sorted yet. Chill.
2. The first run produces an auxiliary file named foo.ref.
3. Run twill-refsort <foo.ref >foo.sref and then another tex foo will produce alphabetized output. Slay. 🎉

---

💖 OPTIONS 💖

Okay, the options section is short and sweet and honestly kind of a "see also" situation:

• See tex(1) for details of command-line parsing, and weave(1) for options accepted.

That's it. That's the section. Go read those two, they've got you. 🍓

---

🌈 ENVIRONMENT 🌈

• The environment variable WEBINPUTS is used to search for the input files. If it is not set, it uses the system default. See the Kpathsea manual at https://tug.org/kpathsea for the details of the searching.

So like — if it can't find your files, check WEBINPUTS first. iykyk. 🔥

---

💀 BUGS 💀

• The table of contents file, CONTENTS.tex, is generated but ignored (unless macros in twimac-web.tex are redefined).

Not me generating a file just to ignore it 💀 — it's there, it exists, it's doing nothing, and it's fine. Just know that if you want CONTENTS.tex to actually do something, you gotta redefine macros in twimac-web.tex. Otherwise it's decorative. 🎀

---

👑 FILES 👑

• $TEXMFMAIN/tex/plain/cweb/cwebbin/twimac-web.tex — TeX macros used by twill output.

That's the file that makes the magic happen. Go look at it if you're curious. 🌟

---

⭐ SEE ALSO ⭐

• tangle(1) for references, authors, and other information about WEB in general.
• Donald E. Knuth, Mini-indexes for literate programs, Software-Concepts and Tools, 15(1):2-11, 1994. https://arxiv.org/abs/cs/9401102
• CTWILL program source, section 287: https://mirror.ctan.org/info/knuth-pdf/cweb/ctwill.pdf — and just so you know, not all features described there are available in the older twill system, but you will get the gist. 🙈
• Public discussion list and bug reports: https://lists.tug.org/tex-k

---

And that's the whole page, bestie. Written by the Web2C crew, Web2C 2026 edition, dated 3 February 2026 — so it's got that fresh-off-the-press energy, fr fr. Go sort your refs and run your TeX twice. I believe in you. 🫶💜