NUWEB(1)

📦 version 1.64, in nixos 26.05, nixpkgs unstable

💖 NAME 💖

This is the NUWEB(1) page from the General Commands Manual, and it’s all about Nuweb, a literate programming tool. That’s the name, bestie — slay. ✨

🦋 SYNOPSIS 🦋

nuweb
nuweb [options] [file] ...

🔥 DESCRIPTION 🔥

Okay so Nuweb is a literate programming tool like Knuth’s WEB, only simpler. A nuweb file contains program source code interleaved with documentation.

When nuweb is given a nuweb file, it writes the program file(s), and also produces LaTeX source for typeset documentation. Iconic. 💅

🌈 COMMAND LINE OPTIONS 🌈

Bestie, here are the command-line flags, one by one, no skipping:

  • -t — suppresses generation of the {t .tex} file.
  • -o — suppresses generation of the output files.
  • -d — list dangling identifier references in indexes.
  • -c — forces output files to overwrite old files of the same name without comparing for equality first.
  • -v — the verbose flag. Forces output of progress reports.
  • -n — forces sequential numbering of scraps (instead of page numbers).
  • -s — doesn’t print the list of scraps making up the file at the end of each scrap.
  • -p path — prepend path to the filenames for all the output files.
  • -V string — provide the string for replacement of the @v operation. This is intended as a means for including version information in generated output.
  • -x — include cross-references in comments in output files.
  • -h options — turn on hyperlinks using the hyperref package of LaTeX and provide the options to the package.
  • -r — turn on hyperlinks using the hyperref package of LaTeX, with the package options being in the text.
  • -I path — provide a directory to search for included files. This may appear several times.

🦋 FORMAT OF NUWEB FILES 🦋

A nuweb file contains mostly ordinary LaTeX. The file is read and copied to output (.tex file) unless a nuweb command is encountered. All nuweb commands start with an “at-sign” (@). Files and fragments are defined with the following commands:

  • @o file-name flags scrap — where scrap is smaller than one page.
  • @O file-name flags scrap — where scrap is bigger than one page.
  • @d fragment-name scrap. — where scrap is smallar than one page.
  • @D fragment-name scrap. — where scrap is bigger than one page.
  • @q fragment-name scrap. — where scrap is smallar than one page. The scrap is not expanded in the output, allowing you to construct output files which can, perhaps after further processing, be input to nuweb.
  • @Q fragment-name scrap. — where scrap is bigger than one page. Likewise.

Scraps have specific begin and end markers; which begin and end marker you use determines how the scrap will be typeset in the .tex file:

  • @{...@} — verbatim “terminal style” formatting or, with the -l flag, LaTeX listing package.
  • @[...@] — LaTeX paragraph mode formatting.
  • @(...@) — LaTeX math mode formmating (yes, that spelling is in the original, keeping it 💅).

Any amount of whitespace (including carriage returns) may appear between a name and the begining of a scrap — and yes, the original really says “begining.” 🫶

Several code/file scraps may have the same name; nuweb concatenates their definitions to produce a single scrap. Code scrap definitions are like macro definitions; nuweb extracts a program by expanding one scrap. The definition of that scrap contains references to other scraps, which are themselves expanded, and so on. Nuweb’s output is readable; it preserves the indentation of expanded scraps with respect to the scraps in which they appear. No cap. 🔥

🌸 PER FILE OPTIONS 🌸

When defining an output file, the programmer has the option of using flags to control the output:

  • -d option — Nuweb will emit line number indications at scrap boundaries.
  • -i option — Nuweb supresses the indentation of fragments (useful for Fortran).
  • -t option — makes nuweb copy tabs untouched from input to output.
  • -cx — include comments in the output file. x may be c for C-style comments, + for C++ and p for perl and similar.

🎀 MINOR COMMANDS 🎀

These are the little side-quest commands:

  • @@ — causes a single “at-sign” to be copied into the output.
  • @_ — causes the text between it and the next {t @_} to be made bold (for keywords, etc.) in the formatted document. (Yes, {t @_} is literally what the original says. 💀)
  • @% — comments out a line so that it doesn’t appear in the output.
  • @i filename — causes the file named to be included.
  • @f — creates an index of output files.
  • @m — creates an index of fragments.
  • @u — creates an index of user-specified identifiers.

To mark an identifier for inclusion in the index, it must be mentioned at the end of the scrap it was defined in. The line starts with @| and ends with the end of scrap mark @}. Periodt. 🫶

💀 ERROR MESSAGES 💀

The original page has this heading but literally zero content under it — no error messages listed. Not me staring at an empty section. 🙈

😭 BUGS 😭

Same energy: the heading is here, but the original lists no bugs. 💀

👑 AUTHOR 👑

Preston Briggs. Internet address preston@cs.rice.edu.

💜 MAINTAINER 💜

  • Simon Wright — Internet address simon@pushface.org
  • Keith Harwood — Internet address Keith.Harwood@vitalmis.com

okay bye bestie — this is the NUWEB(1) manual, and the footer says local, dated 3/22/95. 💅🎀🫶

📦 where this page comes from