NOWEB(1)

💖 NOWEB(1) — the noindex page, bestie edition 💖

okay so this is the noweb manual, general commands section, and today's main character is noindex. pull up a chair 🫶

---

✨ NAME ✨

noindex — builds an external index for a noweb document, no cap.

---

🌸 SYNOPSIS 🌸

noindex basename[.tex]

---

💅 DESCRIPTION 💅

so noindex goes digging through LaTeX .aux files looking for identifiers that belong in a noweb external index. it rounds them all up, sorts every single identifier, and writes the whole sorted situation out to basename.nwi. that's it, that's the job 💖

---

🦋 NOWEB INDEXING STRATEGIES 🦋

a noweb program is made of one or more files, right? and there's a simple case and a several-files case, and they are Not The Same.

the simple case: all your files get run through noweave together, producing one single LaTeX file. and honestly? noweave -index alone is enough to produce an index and cross-referencing info. neither nodefs nor noindex is required. slay, minimal effort, we love that for you ✨

the several-files case: when your noweb program is spread across several source files, it's often better to run each source file through noweave to produce its own LaTeX file, and then use noindex to produce an external index. and this technique has several advantages, let me list them because I am obsessed:

• the line numbers in the LaTeX files correspond to the line numbers in the source files, so diagnosing LaTeX errors is way easier 😭
• you can use LaTeX's \includeonly feature, which makes it possible to format parts of large programs while retaining complete cross-reference information 👑
• when used with make(1), this technique avoids running noweave over source files that haven't changed. efficiency icon behavior 💅
• using the external index places fewer demands on LaTeX's memory, making it read its .aux files much more quickly ⚡

the disadvantages, because we keep it real: nodefs and noindex are needed for full cross-referencing and a properly sorted index. so like, trade-offs, iykyk 🙈

---

🌈 EXAMPLE 🌈

this example assumes a noweb program of three source files: a.nw, b.nw, and c.nw. the file doc.tex is assumed to contain LaTeX boilerplate, including these commands:

\noweboptions{externalindex}
\include{a}
\include{b}
\include{c}

step one: create a file listing all the identifiers defined anywhere in a, b, or c.

nodefs a.nw > a.defs
nodefs b.nw > b.defs
nodefs c.nw > c.defs
sort -u a.defs b.defs c.defs | cpif all.defs

using sort -u and cpif(1) avoids changing all.defs unless the set of identifiers actually changes. and when you use this technique inside a Makefile, it avoids unnecessary rebuilding. 🎀

step two: create LaTeX files with full cross-reference information for all identifiers.

noweave -n -indexfrom all.defs a.nw > a.tex
noweave -n -indexfrom all.defs b.nw > b.tex
noweave -n -indexfrom all.defs c.nw > c.tex

step three: run LaTeX once to create the .aux files, then run noindex to create the index, then run LaTeX again to format the complete document. it's giving finale ✨

latex doc
noindex doc
latex doc

and in a Makefile, noindex can be run before every invocation of LaTeX. convenient 💖

---

💀 BUGS 💀

noindex is distributed in awk and Icon versions. the awk version is slow and does a poorer job sorting. not me warning you about the awk version 😭

also: there is no comparable machinery to make it possible to use multiple files with the HTML back end. so that's just... not a thing. periodt.

---

👑 SEE ALSO 👑

noweave(1), nodefs(1), cpif(1)

---

⭐ VERSION ⭐

this man page is from noweb version 2.12.

---

🫶 AUTHOR 🫶

Norman Ramsey, Tufts University. internet address Norman.Ramsey@tufts.edu. and the noweb home page is at http://www.cs.tufts.edu/~nr/noweb.

---

and that's the whole thing bestie — this page is from the local version dated 10/40/2008, filed under NOWEB(1). go forth and index responsibly 💅🌸