NOWEB(1)

✨ NOWEB(1) ✨ — the manual page, but make it cute 💅

okay bestie, welcome to the noweb(1) page from the General Commands Manual, aka the manual page that is literally about being the simple one 🫶

---

🌸 NAME 🌸

noweb — a simple literate-programming tool 💖

---

🎀 SYNOPSIS 🎀

noweb [-t] [-o] [-Lformat] [-markup parser] [file] ...

---

🦋 DESCRIPTION 🦋

So noweb is a literate-programming tool, like FunnelWEB or nuweb… except it's giving simpler 🌈. A noweb file is program source code interleaved with documentation — code and vibes, together, no cap.

When you invoke noweb, it does two things:

• writes the program source code to the output files mentioned in the noweb file ✍️
• writes a TeX file for typeset documentation 📄

And like… the noweb(1) command itself? It's for people who don't like reading man pages, or who are switching over from nuweb. If you wanna get the most out of noweb, use notangle(1) and noweave(1) instead 👑 periodt.

---

💜 FORMAT OF NOWEB FILES 💜

A noweb file is a sequence of chunks, and they can show up in any order — no rules, main character energy. A chunk may contain code or documentation.

Documentation chunks begin with a line that starts with an at sign (@) followed by a space or a newline. They have no names, they're just out here being anonymous 💀.

Code chunks begin with

<<chunk name>>=

on a line by itself. And bestie, listen — the double left angle bracket (<<) must be in the first column. First column only, okay? Chunks get terminated by the beginning of another chunk, or by end of file. And if the first line in the file doesn't mark the beginning of a chunk, it's assumed to be the first line of a documentation chunk 🌸.

---

Documentation chunks contain text that's copied verbatim to the TeX file (except for quoted code, we'll get there). noweb works with LaTeX, and here's the checklist for that very first documentation chunk:

• it must contain a LaTeX \documentclass command 📝
• it must contain \usepackage{noweb} in the preamble 📦
• and finally it must also contain a LaTeX \begin{document} command 🎬

all three, no skipping, iykyk.

---

Code chunks contain program source code and references to other code chunks. Several code chunks may have the same name, and noweb just concatenates their definitions to produce a single chunk, exactly like other literate-programming tools do 🧚.

noweb looks for chunks that are defined but not used in the source file. If the name of such a chunk contains no spaces, that chunk is an ``output file;'' noweb expands it and writes the result onto the file of the same name 💅.

A code-chunk definition is like a macro definition — it contains references to other chunks, which are themselves expanded, and so on, and so on, forever ♾️. And noweb's output is readable; it preserves the indentation of expanded chunks with respect to the chunks in which they appear. The formatting ate, honestly.

---

If a star (*) is appended to the name of an output file, noweb includes line-number information as specified by the -Lformat option (or for C if no -Lformat option is given) ⭐.

Careful bestie: the name itself may not contain shell metacharacters 🚫

---

Code may be quoted within documentation chunks by placing double square brackets ([[...]]) around it 🎀. These double square brackets are used to give the code special typographic treatment in the TeX file.

And here's a cute little edge case: if quoted code ends with three or more square brackets, noweb chooses the rightmost pair, so that, for example, [[a[i]]] is parsed correctly ✨.

---

In code, noweb treats unpaired double left or right angle brackets as literal << and >> 🦋. And to force any such brackets — even paired brackets, even brackets in documentation — to be treated as literal, use a preceding at sign (e.g. @<<).

---

🌈 OPTIONS 🌈

• -t — Suppress generation of a TeX file 🙈
• -o — Suppress generation of output files 🚫
• -Lformat — Use format to format line-number information for starred output files. (If the option is omitted, a format suitable for C is used.) format is as defined by notangle(1);
• -markup parser — Use parser to parse the input file. This enables use of noweb tools on files in other formats; for example, the numarkup parser understands nuweb(1) format 🧚. See nowebfilters(7) for more information. For experts only 👑🔥

---

💀 BUGS 💀

Ignoring unused chunks whose names contain spaces sometimes causes problems — especially in the case when a chunk has multiple definitions and one is misspelled; the misspelled definition will be silently ignored 😭. noroots(1) can be used as a sanity checker to catch this sort of mistake 🩹.

noweb is intended for users who don't want the power or the complexity of command-line options. More sophisticated users should avoid noweb and use noweave and notangle instead. And, direct quote energy: If the design were better, we could all use the same commands. 💅

noweb requires the new version of awk. DEC nawk has a bug in that that causes problems with braces in TeX output. GNU gawk is reported to work ✅.

The default LaTeX pagestyles don't set the width of the boxes containing headers and footers. Since noweb code paragraphs are extra wide, this LaTeX bug sometimes results in extra-wide headers and footers 😭. The remedy is to redefine the relevant ps@* commands; ps@noweb in noweb.sty can be used as an example 🛠️.

---

🔥 SEE ALSO 🔥

notangle(1), noweave(1), noroots(1), nountangle(1), nowebstyle(7), nowebfilters(7), nuweb2noweb(1)

Norman Ramsey, Literate programming simplified, IEEE Software 11(5):97-105, September 1994 📚

---

⭐ VERSION ⭐

This man page is from noweb version 2.12 🎀

---

👑 AUTHOR 👑

Norman Ramsey, Tufts University. Internet address Norman.Ramsey@tufts.edu 📧

Noweb home page at http://www.cs.tufts.edu/~nr/noweb 🌐

---

and that's the whole page bestie!! this one's from the local build, dated 10/40/2008 — yes the date is silly, we love her — and it lives in section NOWEB(1) 🫶✨ bye!! 💖