Nuweb Version 0.87b
A Simple Literate Programming Tool

Table of Contents

• Introduction
  • Nuweb
    • Nuweb and HTML
  • Writing Nuweb
    • The Major Commands
      • Scraps
      • Flags
    • The Minor Commands
  • Running Nuweb
  • Generating HTML
  • Restrictions
  • Acknowledgements
• The Overall Structure
  • Files
    • The Main Files
    • Support Files
  • The Main Routine
    • Command-Line Arguments
    • File Names
  • Pass One
    • Accumulating Definitions
    • Fixing the Cross References
  • Writing the Latex File
    • Formatting Definitions
      • Formatting Cross References
      • Formatting a Scrap
    • Generating the Indices
  • Writing the LaTeX File with HTML Scraps
    • Formatting Definitions
      • Formatting Cross References
      • Formatting a Scrap
    • Generating the Indices
  • Writing the Output Files
• The Support Routines
  • Source Files
    • Global Declarations
    • Local Declarations
    • Reading a File
    • Opening a File
  • Scraps
    • Collecting Page Numbers
  • Names
  • Searching for Index Entries
    • Building the Automata
    • Searching the Scraps
      • Rejecting Matches
  • Memory Management
    • Allocating Memory
    • Freeing Memory
• Indices
  • Files
  • Macros
  • Identifiers

Introduction

Running tangle on the web file would produce a complete Pascal program, ready for compilation by an ordinary Pascal compiler. The primary function of tangle is to allow the programmer to present elements of the program in any desired order, regardless of the restrictions imposed by the programming language. Thus, the programmer is free to present his program in a top-down fashion, bottom-up fashion, or whatever seems best in terms of promoting understanding and maintenance.

Running weave on the web file would produce a TeX file, ready to be processed by TeX. The resulting document included a variety of automatically generated indices and cross-references that made it much easier to navigate the code. Additionally, all of the code sections were automatically pretty printed, resulting in a quite impressive document.

Knuth also wrote the programs for TeX and METAFONT entirely in WEB, eventually publishing them in book form [cite tex:program,metafont:program]. These are probably the largest programs ever published in a readable form.

Inspired by Knuth's example, many people have experimented with WEB. Some people have even built web-like tools for their own favorite combinations of programming language and typesetting language. For example, CWEB, Knuth's current system of choice, works with a combination of C (or C++) and TeX [cite levy:90]. Another system, FunnelWeb, is independent of any programming language and only mildly dependent on TeX [cite funnelweb]. Inspired by the versatility of FunnelWeb and by the daunting size of its documentation, I decided to write my own, very simple, tool for literate programming. [There is another system similar to mine, written by Norman Ramsey, called noweb [cite noweb]. It perhaps suffers from being overly Unix-dependent and requiring several programs to use. On the other hand, its command syntax is very nice. In any case, nuweb certainly owes its name and a number of features to his inspiration.]

Nuweb

No pretty printing

Both WEB and CWEB are able to pretty print the code sections of their documents because they understand the language well enough to parse it. Since we want to use any language, we've got to abandon this feature.

No index of identifiers

Because WEB knows about Pascal, it is able to construct an index of all the identifiers occurring in the code sections (filtering out keywords and the standard type identifiers). Unfortunately, this isn't as easy in our case. We don't know what an identifiers looks like in each language and we certainly don't know all the keywords. (On the other hand, see the end of Section 1.3)

Simplicity

The majority of the commands in WEB are concerned with control of the automatic pretty printing. Since we don't pretty print, many commands are eliminated. A further set of commands is subsumed by LaTeX and may also be eliminated. As a result, our set of commands is reduced to only four members (explained in the next section). This simplicity is also reflected in the size of this tool, which is quite a bit smaller than the tools used with other approaches.

No pretty printing

Everyone disagrees about how their code should look, so automatic formatting annoys many people. One approach is to provide ways to control the formatting. Our approach is simpler---we perform no automatic formatting and therefore allow the programmer complete control of code layout.

Control

We also offer the programmer complete control of the layout of his output files (the files generated during tangling). Of course, this is essential for languages that are sensitive to layout; but it is also important in many practical situations, e.g., debugging.

Speed

Since nuweb doesn't do to much, the nuweb tool runs quickly. I combine the functions of tangle and weave into a single program that performs both functions at once.

Page numbers

Inspired by the example of noweb, nuweb refers to all scraps by page number to simplify navigation. If there are multiple scraps on a page (say page 17), they are distinguished by lower-case letters (e.g., 17a, 17b, and so forth).

Multiple file output

The programmer may specify more than one output file in a single nuweb file. This is required when constructing programs in a combination of languages (say, Fortran and C). It's also an advantage when constructing very large programs that would require a lot of compile time.

A further reduction in compilation time is achieved by first writing each output file to a temporary location, then comparing the temporary file with the old version of the file. If there is no difference, the temporary file can be deleted. If the files differ, the old version is deleted and the temporary file renamed. This approach works well in combination with make (or similar tools), since make will avoid recompiling untouched output files.

Nuweb and HTML

Writing Nuweb

The Major Commands

@o file-name flags scrap

Output a file. The file name is terminated by whitespace.

@d macro-name scrap

Define a macro. The macro name is terminated by a return or the beginning of a scrap.

Scraps

@{anything@}

where the scrap body includes every character in anything---all the blanks, all the tabs, all the carriage returns.

@<macro-name@>

Causes the macro macro-name to be expanded inline as the code is written out to a file. It is an error to specify recursive macro invocations.

@d Check for terminating at-sequence and return name if found

@d Check for terminating...

When scraps are written to a program file or a documentation file, tabs are expanded into spaces by default. Currently, I assume tab stops are set every eight characters. Furthermore, when a macro is expanded in a scrap, the body of the macro is indented to match the indentation of the macro invocation. Therefore, care must be taken with languages (e.g., Fortran) that are sensitive to indentation. These default behaviors may be changed for each output file (see below).

Flags

-d

Forces the creation of #line directives in the output file. These are useful with C (and sometimes C++ and Fortran) on many Unix systems since they cause the compiler's error messages to refer to the web file rather than the output file. Similarly, they allow source debugging in terms of the web file.

-i

Suppresses the indentation of macros. That is, when a macro is expanded in a scrap, it will not be indented to match the indentation of the macro invocation. This flag would seem most useful for Fortran programmers.

-t

Suppresses expansion of tabs in the output file. This feature seems important when generating make files.

The Minor Commands

@@

Causes a single ``at sign'' to be copied into the output.

@i file-name

Includes a file. Includes may be nested, though there is currently a limit of 10 levels. The file name should be complete (no extension will be appended) and should be terminated by a carriage return.

@f

Create an index of file names.

@m

Create an index of macro name.

@u

Create an index of user-specified identifiers.

Identifiers must be explicitly specified for inclusion in the @u index. By convention, each identifier is marked at the point of its definition; all references to each identifier (inside scraps) will be discovered automatically. To ``mark'' an identifier for inclusion in the index, we must mention it at the end of a scrap. For example,

@d a scrap @{
Let's pretend we're declaring the variables FOO and BAR
inside this scrap.
@| FOO BAR @}

In the generated index, each identifier appears with a list of all the scraps using and defining it, where the defining scraps are distinguished by underlining. Note that the identifier doesn't actually have to appear in the defining scrap; it just has to be in the list of definitions at the end of a scrap.

Running Nuweb

nuweb flags file-name...

nuweb /foo/bar/quux

By default, nuweb performs both tangling and weaving at the same time. Normally, this is not a bottleneck in the compilation process; however, it's possible to achieve slightly faster throughput by avoiding one or another of the default functions using command-line flags. There are currently three possible flags:

-t

Suppress generation of the documentation file.

-o

Suppress generation of the output files.

-c

Avoid testing output files for change before updating them.

nuweb -to /foo/bar/quux

There are two additional command-line flags:

-v

For ``verbose,'' causes nuweb to write information about its progress to stderr.

-n

Forces scraps to be numbered sequentially from 1 (instead of using page numbers). This form is perhaps more desirable for small webs.

Generating HTML

While preparing a web, you may want to view the program's scraps without taking the time to run LaTeX2HTML. Simply rename the generated LaTeX source so that its file name ends with .html, and view that file. The documentations section will be jumbled, but the scraps will be clear.

Restrictions

• The handling of errors is not completely ideal. In some cases, I simply warn of a problem and continue; in other cases I halt immediately. This behavior should be regularized.
• I warn about references to macros that haven't been defined, but don't halt. This seems most convenient for development, but may change in the future.
• File names and index entries should not contain any @ signs.
• Macro names may be (almost) any well-formed TeX string. It makes sense to change fonts or use math mode; however, care should be taken to ensure matching braces, brackets, and dollar signs. When producing HTML, macros are displayed in a preformatted element (PRE), so macros may contain one or more A, B, I, U, or P elements or data characters.
• Anything is allowed in the body of a scrap; however, very long scraps (horizontally or vertically) may not typeset well.
• Temporary files (created for comparison to the eventual output files) are placed in the current directory. Since they may be renamed to an output file name, all the output files should be on the same file system as the current directory.
• Because page numbers cannot be determined until the document has been typeset, we have to rerun nuweb after LaTeX to obtain a clean version of the document (very similar to the way we sometimes have to rerun LaTeX to obtain an up-to-date table of contents after significant edits). Nuweb will warn (in most cases) when this needs to be done; in the remaining cases, LaTeX will warn that labels may have changed.

Acknowledgements

The Overall Structure

1. Read the source, accumulating file names, macro names, scraps, and lists of cross-references.
2. Reread the source, copying out to the documentation file, with protection and cross-reference information for all the scraps.
3. Traverse the list of files names. For each file name:
   1. Dump all the defining scraps into a temporary file.
   2. If the file already exists and is unchanged, delete the temporary file; otherwise, rename the temporary file.

Files

<global.h>=
<Include files>
<Type declarations>
<Global variable declarations>
<Function prototypes>

This code is written to a file (or else not used).

We'll need at least three of the standard system include files.

<Include files>=
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>

Defines exit, fclose, FILE, fopen, fprintf, fputs, getc, isgraph, islower, isspace, isupper, malloc, putc, remove, size_t, stderr, strlen, tempnam, toupper (links are to index).

Used above.

<Type declarations>=
#ifndef FALSE
#define FALSE 0
#endif
#ifndef TRUE
#define TRUE 1
#endif

Defines FALSE, TRUE (links are to index).

Used above; next definition.

The Main Files

<main.c>=
#include "global.h"

This code is written to a file (or else not used).

Next definition.

The first pass over the source file is contained in pass1.c. It handles collection of all the file names, macros names, and scraps (see Section [->]).

<pass1.c>=
#include "global.h"

This code is written to a file (or else not used).

Next definition.

The .tex file is created during a second pass over the source file. The file latex.c contains the code controlling the construction of the .tex file (see Section [->]).

<latex.c>=
#include "global.h"

This code is written to a file (or else not used).

Next definition.

The file html.c contains the code controlling the construction of the .tex file appropriate for use with LaTeX2HTML (see Section [->]).

<html.c>=
#include "global.h"

This code is written to a file (or else not used).

Next definition.

The code controlling the creation of the output files is in output.c (see Section [->]).

<output.c>=
#include "global.h"

This code is written to a file (or else not used).

Next definition.

Support Files

<input.c>=
#include "global.h"

This code is written to a file (or else not used).

Next definition.

Creation and lookup of scraps is handled by routines in scraps.c (see Section [->]).

<scraps.c>=
#include "global.h"

This code is written to a file (or else not used).

Next definition.

The handling of file names and macro names is detailed in names.c (see Section [->]).

<names.c>=
#include "global.h"

This code is written to a file (or else not used).

Next definition.

Memory allocation and deallocation is handled by routines in arena.c (see Section [->]).

<arena.c>=
#include "global.h"

This code is written to a file (or else not used).

Next definition.

Finally, for best portability, I seem to need a file containing (useless!) definitions of all the global variables.

<global.c>=
#include "global.h"
<Global variable definitions>

This code is written to a file (or else not used).

The Main Routine

<main.c>+=
int main(argc, argv)
     int argc;
     char **argv;
{
  int arg = 1;
  <Interpret command-line arguments>
  <Process the remaining arguments (file names)>
  exit(0);
}

Defines main (links are to index).

Previous definition.

Command-Line Arguments

-t

Suppresses generation of the .tex file.

-o

Suppresses generation of the output files.

-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).

Global flags are declared for each of the arguments.

<Global variable declarations>=
extern int tex_flag;      /* if FALSE, don't emit the documentation file */
extern int html_flag;     /* if TRUE, emit HTML instead of LaTeX scraps. */
extern int output_flag;   /* if FALSE, don't emit the output files */
extern int compare_flag;  /* if FALSE, overwrite without comparison */
extern int verbose_flag;  /* if TRUE, write progress information */
extern int number_flag;   /* if TRUE, use a sequential numbering scheme */

Defines compare_flag, html_flag, number_flag, output_flag, tex_flag, verbose_flag (links are to index).

Used above; next definition.

The flags are all initialized for correct default behavior.

<Global variable definitions>=
int tex_flag = TRUE;
int html_flag = FALSE;
int output_flag = TRUE;
int compare_flag = TRUE;
int verbose_flag = FALSE;
int number_flag = FALSE;

Used above; next definition.

We save the invocation name of the command in a global variable command_name for use in error messages.

<Global variable declarations>+=
extern char *command_name;

Defines command_name (links are to index).

Used above; previous and next definitions.

<Global variable definitions>+=
char *command_name = NULL;

Used above; previous and next definitions.

The invocation name is conventionally passed in argv[0].

<Interpret command-line arguments>=
command_name = argv[0];

Used above; next definition.

We need to examine the remaining entries in argv, looking for command-line arguments.

<Interpret command-line arguments>+=
while (arg < argc) {
  char *s = argv[arg];
  if (*s++ == '-') {
    <Interpret the argument string s>
    arg++;
  }
  else break;
}

Used above; previous definition.

Several flags can be stacked behind a single minus sign; therefore, we've got to loop through the string, handling them all.

<Interpret the argument string s>=
{
  char c = *s++;
  while (c) {
    switch (c) {
      case 'c': compare_flag = FALSE;
                break;
      case 'n': number_flag = TRUE;
                break;
      case 'o': output_flag = FALSE;
                break;
      case 't': tex_flag = FALSE;
                break;
      case 'v': verbose_flag = TRUE;
                break;
      default:  fprintf(stderr, "%s: unexpected argument ignored.  ",
                        command_name);
                fprintf(stderr, "Usage is: %s [-cnotv] file...\n",
                        command_name);
                break;
    }
    c = *s++;
  }
}

Used above.

File Names

<Process the remaining arguments (file names)>=
{
  if (arg >= argc) {
    fprintf(stderr, "%s: expected a file name.  ", command_name);
    fprintf(stderr, "Usage is: %s [-cnotv] file-name...\n", command_name);
    exit(-1);
  }
  do {
    <Handle the file name in argv[arg]>
    arg++;
  } while (arg < argc);
}

Used above.

<Handle the file name in argv[arg]>=
{
  char source_name[100];
  char tex_name[100];
  char aux_name[100];
  <Build source_name and tex_name>
  <Process a file>
}

Used above.

I bump the pointer p through all the characters in argv[arg], copying all the characters into source_name (via the pointer q).

At each slash, I update trim to point just past the slash in source_name. The effect is that trim will point at the file name without any leading directory specifications.

The pointer dot is made to point at the file name extension, if present. If there is no extension, we add .w to the source name. In any case, we create the tex_name from trim, taking care to get the correct extension. The html_flag is set in this scrap.

<Build source_name and tex_name>=
{
  char *p = argv[arg];
  char *q = source_name;
  char *trim = q;
  char *dot = NULL;
  char c = *p++;
  while (c) {
    *q++ = c;
    if (c == '/') {
      trim = q;
      dot = NULL;
    }
    else if (c == '.')
      dot = q - 1;
    c = *p++;
  }
  *q = '\0';
  if (dot) {
    *dot = '\0'; /* produce HTML when the file extension is ".hw" */
    html_flag = dot[1] == 'h' && dot[2] == 'w' && dot[3] == '\0';
    sprintf(tex_name, "%s.tex", trim);
    sprintf(aux_name, "%s.aux", trim);
    *dot = '.';
  }
  else {
    sprintf(tex_name, "%s.tex", trim);
    sprintf(aux_name, "%s.aux", trim);
    *q++ = '.';
    *q++ = 'w';
    *q = '\0';
  }
}

Used above.

Now that we're finally ready to process a file, it's not really too complex. We bundle most of the work into four routines pass1 (see Section [->]), write_tex (see Section [->]), write_html (see Section [->]), and write_files (see Section [->]). After we're finished with a particular file, we must remember to release its storage (see Section [->]). The sequential numbering of scraps is forced when generating HTML.

<Process a file>=
{
  pass1(source_name);
  if (tex_flag) {
    if (html_flag) {
      int saved_number_flag = number_flag; 
      number_flag = TRUE;
      collect_numbers(aux_name);
      write_html(source_name, tex_name);
      number_flag = saved_number_flag;
    }
    else {
      collect_numbers(aux_name);
      write_tex(source_name, tex_name);
    }
  }
  if (output_flag)
    write_files(file_names);
  arena_free();
}

Used above.

Pass One

<Function prototypes>=
extern void pass1();

Used above; next definition.

The routine pass1 takes a single argument, the name of the source file. It opens the file, then initializes the scrap structures (see Section [->]) and the roots of the file-name tree, the macro-name tree, and the tree of user-specified index entries (see Section [->]). After completing all the necessary preparation, we make a pass over the file, filling in all our data structures. Next, we seach all the scraps for references to the user-specified index entries. Finally, we must reverse all the cross-reference lists accumulated while scanning the scraps.

<pass1.c>+=
void pass1(file_name)
     char *file_name;
{
  if (verbose_flag)
    fprintf(stderr, "reading %s\n", file_name);
  source_open(file_name);
  init_scraps();
  macro_names = NULL;
  file_names = NULL;
  user_names = NULL;
  <Scan the source file, looking for at-sequences>
  if (tex_flag)
    search();
  <Reverse cross-reference lists>
}

Defines pass1 (links are to index).

Previous definition.

The only thing we look for in the first pass are the command sequences. All ordinary text is skipped entirely.

<Scan the source file, looking for at-sequences>=
{
  int c = source_get();
  while (c != EOF) {
    if (c == '@')
      <Scan at-sequence>
    c = source_get();
  }
}

Used above.

Only four of the at-sequences are interesting during the first pass. We skip past others immediately; warning if unexpected sequences are discovered.

<Scan at-sequence>=
{
  c = source_get();
  switch (c) {
    case 'O':
    case 'o': <Build output file definition>
              break;
    case 'D':
    case 'd': <Build macro definition>
              break;
    case '@':
    case 'u':
    case 'm':
    case 'f': /* ignore during this pass */
              break;
    default:  fprintf(stderr,
                      "%s: unexpected @ sequence ignored (%s, line %d)\n",
                      command_name, source_name, source_line);
              break;
  }
}

Used above.

Accumulating Definitions

1. Build an entry for the name so we can look it up later.
2. Collect the scrap and save it in the table of scraps.
3. Attach the scrap to the name.

<Build output file definition>=
{
  Name *name = collect_file_name(); /* returns a pointer to the name entry */
  int scrap = collect_scrap();      /* returns an index to the scrap */
  <Add scrap to name's definition list>
}

Used above.

<Build macro definition>=
{
  Name *name = collect_macro_name();
  int scrap = collect_scrap();
  <Add scrap to name's definition list>
}

Used above.

Since a file or macro may be defined by many scraps, we maintain them in a simple linked list. The list is actually built in reverse order, with each new definition being added to the head of the list.

<Add scrap to name's definition list>=
{
  Scrap_Node *def = (Scrap_Node *) arena_getmem(sizeof(Scrap_Node));
  def->scrap = scrap;
  def->next = name->defs;
  name->defs = def;
}

Used above (1), above (2).

Fixing the Cross References

<Reverse cross-reference lists>=
{
  reverse_lists(file_names);
  reverse_lists(macro_names);
  reverse_lists(user_names);
}

Used above.

Writing the Latex File

Note that all the formatting is handled in this section. If you don't like the format of definitions or indices or whatever, it'll be in this section somewhere. Similarly, if someone wanted to modify nuweb to work with a different typesetting system, this would be the place to look.

<Function prototypes>+=
extern void write_tex();

Used above; previous and next definitions.

We need a few local function declarations before we get into the body of write_tex.

<latex.c>+=
static void copy_scrap();               /* formats the body of a scrap */
static void print_scrap_numbers();      /* formats a list of scrap numbers */
static void format_entry();             /* formats an index entry */
static void format_user_entry();

Previous and next definitions.

The routine write_tex takes two file names as parameters: the name of the web source file and the name of the .tex output file.

<latex.c>+=
void write_tex(file_name, tex_name)
     char *file_name;
     char *tex_name;
{
  FILE *tex_file = fopen(tex_name, "w");
  if (tex_file) {
    if (verbose_flag)
      fprintf(stderr, "writing %s\n", tex_name);
    source_open(file_name);
    <Copy source_file into tex_file>
    fclose(tex_file);
  }
  else
    fprintf(stderr, "%s: can't open %s\n", command_name, tex_name);
}

Defines write_tex (links are to index).

Previous and next definitions.

We make our second (and final) pass through the source web, this time copying characters straight into the .tex file. However, we keep an eye peeled for @ characters, which signal a command sequence.

<Copy source_file into tex_file>=
{
  int scraps = 1;
  int c = source_get();
  while (c != EOF) {
    if (c == '@')
      <Interpret at-sequence>
    else {
      putc(c, tex_file);
      c = source_get();
    }
  }
}

Used above.

<Interpret at-sequence>=
{
  int big_definition = FALSE;
  c = source_get();
  switch (c) {
    case 'O': big_definition = TRUE;
    case 'o': <Write output file definition>
              break;
    case 'D': big_definition = TRUE;
    case 'd': <Write macro definition>
              break;
    case 'f': <Write index of file names>
              break;
    case 'm': <Write index of macro names>
              break;
    case 'u': <Write index of user-specified names>
              break;
    case '@': putc(c, tex_file);
    default:  c = source_get();
              break;
  }
}

Used above.

Formatting Definitions

\begin{flushleft} \small
\begin{minipage}{\linewidth} \label{scrap37}
$\langle$Interpret at-sequence {\footnotesize 18}$\rangle\equiv$
\vspace{-1ex}
\begin{list}{}{} \item
\mbox{}\verb@{@\\
\mbox{}\verb@  int big_definition = FALSE;@\\
\mbox{}\verb@  c = source_get();@\\
\mbox{}\verb@  switch (c) {@\\
\mbox{}\verb@    case 'O': big_definition = TRUE;@\\
\mbox{}\verb@    case 'o': @$\langle$Write output file definition {\footnotesize 19a}$\rangle$\verb@@\\

\mbox{}\verb@    case '@{\tt @}\verb@': putc(c, tex_file);@\\
\mbox{}\verb@    default:  c = source_get();@\\
\mbox{}\verb@              break;@\\
\mbox{}\verb@  }@\\
\mbox{}\verb@}@$\Diamond$
\end{list}
\vspace{-1ex}
\footnotesize\addtolength{\baselineskip}{-1ex}
\begin{list}{}{\setlength{\itemsep}{-\parsep}\setlength{\itemindent}{-\leftmargin}}
\item Macro referenced in scrap 17b.
\end{list}
\end{minipage}\\[4ex]
\end{flushleft}

The flushleft environment is used to avoid LaTeX warnings about underful lines. The minipage environment is used to avoid page breaks in the middle of scraps. The verb command allows arbitrary characters to be printed (however, note the special handling of the @ case in the switch statement).

Macro and file definitions are formatted nearly identically. I've factored the common parts out into separate scraps.

<Write output file definition>=
{
  Name *name = collect_file_name();
  <Begin the scrap environment>
  fprintf(tex_file, "\\verb@\"%s\"@ {\\footnotesize ", name->spelling);
  write_single_scrap_ref(tex_file, scraps++);
  fputs(" }$\\equiv$\n", tex_file);
  <Fill in the middle of the scrap environment>
  <Write file defs>
  <Finish the scrap environment>
}

Used above.

I don't format a macro name at all specially, figuring the programmer might want to use italics or bold face in the midst of the name.

<Write macro definition>=
{
  Name *name = collect_macro_name();
  <Begin the scrap environment>
  fprintf(tex_file, "$\\langle$%s {\\footnotesize ", name->spelling);
  write_single_scrap_ref(tex_file, scraps++);
  fputs("}$\\rangle\\equiv$\n", tex_file);
  <Fill in the middle of the scrap environment>
  <Write macro defs>
  <Write macro refs>
  <Finish the scrap environment>
}

Used above.

<Begin the scrap environment>=
{
  fputs("\\begin{flushleft} \\small", tex_file);
  if (!big_definition)
    fputs("\n\\begin{minipage}{\\linewidth}", tex_file);
  fprintf(tex_file, " \\label{scrap%d}\n", scraps);
}

Used above (1), above (2).

The interesting things here are the <> inserted at the end of each scrap and the various spacing commands. The diamond helps to clearly indicate the end of a scrap. The spacing commands were derived empirically; they may be adjusted to taste.

<Fill in the middle of the scrap environment>=
{
  fputs("\\vspace{-1ex}\n\\begin{list}{}{} \\item\n", tex_file);
  copy_scrap(tex_file);
  fputs("$\\Diamond$\n\\end{list}\n", tex_file);
}

Used above (1), above (2).

Note also the whitespace eater. I use it to remove any blank lines that appear after a scrap in the source file. This way, text following a scrap will not be indented. Again, this is a matter of personal taste.

<Finish the scrap environment>=
{
  if (!big_definition)
    fputs("\\end{minipage}\\\\[4ex]\n", tex_file);
  fputs("\\end{flushleft}\n", tex_file);
  do
    c = source_get();
  while (isspace(c));
}

Used above (1), above (2).

Formatting Cross References

<Write file defs>=
{
  if (name->defs->next) {
    fputs("\\vspace{-1ex}\n", tex_file);
    fputs("\\footnotesize\\addtolength{\\baselineskip}{-1ex}\n", tex_file);
    fputs("\\begin{list}{}{\\setlength{\\itemsep}{-\\parsep}", tex_file);
    fputs("\\setlength{\\itemindent}{-\\leftmargin}}\n", tex_file);
    fputs("\\item File defined by scraps ", tex_file);
    print_scrap_numbers(tex_file, name->defs);
    fputs("\\end{list}\n", tex_file);
  }
  else
    fputs("\\vspace{-2ex}\n", tex_file);
}

Used above.

<Write macro defs>=
{
  fputs("\\vspace{-1ex}\n", tex_file);
  fputs("\\footnotesize\\addtolength{\\baselineskip}{-1ex}\n", tex_file);
  fputs("\\begin{list}{}{\\setlength{\\itemsep}{-\\parsep}", tex_file);
  fputs("\\setlength{\\itemindent}{-\\leftmargin}}\n", tex_file);
  if (name->defs->next) {
    fputs("\\item Macro defined by scraps ", tex_file);
    print_scrap_numbers(tex_file, name->defs);
  }
}

Used above.

<Write macro refs>=
{
  if (name->uses) {
    if (name->uses->next) {
      fputs("\\item Macro referenced in scraps ", tex_file);
      print_scrap_numbers(tex_file, name->uses);
    }
    else {
      fputs("\\item Macro referenced in scrap ", tex_file);
      write_single_scrap_ref(tex_file, name->uses->scrap);
      fputs(".\n", tex_file);
    }
  }
  else {
    fputs("\\item Macro never referenced.\n", tex_file);
    fprintf(stderr, "%s: <%s> never referenced.\n",
            command_name, name->spelling);
  }
  fputs("\\end{list}\n", tex_file);
}

Used above.

<latex.c>+=
static void print_scrap_numbers(tex_file, scraps)
     FILE *tex_file;
     Scrap_Node *scraps;
{
  int page;
  write_scrap_ref(tex_file, scraps->scrap, TRUE, &page);
  scraps = scraps->next;
  while (scraps) {
    write_scrap_ref(tex_file, scraps->scrap, FALSE, &page);
    scraps = scraps->next;
  }
  fputs(".\n", tex_file);
}

Defines print_scrap_numbers (links are to index).

Previous and next definitions.

Formatting a Scrap

<latex.c>+=
static void copy_scrap(file)
     FILE *file;
{
  int indent = 0;
  int c = source_get();
  fputs("\\mbox{}\\verb@", file);
  while (1) {
    switch (c) {
      case '@':  <Check at-sequence for end-of-scrap>
                 break;
      case '\n': fputs("@\\\\\n\\mbox{}\\verb@", file);
                 indent = 0;
                 break;
      case '\t': <Expand tab into spaces>
                 break;
      default:   putc(c, file);
                 indent++;
                 break;
    }
    c = source_get();
  }
}

Defines copy_scrap (links are to index).

Previous and next definitions.

<Expand tab into spaces>=
{
  int delta = 8 - (indent % 8);
  indent += delta;
  while (delta > 0) {
    putc(' ', file);
    delta--;
  }
}

Used above (1), below (2), below (3).

<Check at-sequence for end-of-scrap>=
{
  c = source_get();
  switch (c) {
    case '@': fputs("@{\\tt @}\\verb@", file);
              break;
    case '|': <Skip over index entries>
    case '}': putc('@', file);
              return;
    case '<': <Format macro name>
              break;
    default:  /* ignore these since pass1 will have warned about them */
              break;
  }
}

Used above.

There's no need to check for errors here, since we will have already pointed out any during the first pass.

<Skip over index entries>=
{
  do {
    do
      c = source_get();
    while (c != '@');
    c = source_get();
  } while (c != '}');
}

Used above (1), below (2).

<Format macro name>=
{
  Name *name = collect_scrap_name();
  fprintf(file, "@$\\langle$%s {\\footnotesize ", name->spelling);
  if (name->defs)
    <Write abbreviated definition list>
  else {
    putc('?', file);
    fprintf(stderr, "%s: scrap never defined <%s>\n",
            command_name, name->spelling);
  }
  fputs("}$\\rangle$\\verb@", file);
}

Used above.

<Write abbreviated definition list>=
{
  Scrap_Node *p = name->defs;
  write_single_scrap_ref(file, p->scrap);
  p = p->next;
  if (p)
    fputs(", \\ldots\\ ", file);
}

Used above.

Generating the Indices

<Write index of file names>=
{
  if (file_names) {
    fputs("\n{\\small\\begin{list}{}{\\setlength{\\itemsep}{-\\parsep}",
          tex_file);
    fputs("\\setlength{\\itemindent}{-\\leftmargin}}\n", tex_file);
    format_entry(file_names, tex_file, TRUE);
    fputs("\\end{list}}", tex_file);
  }
  c = source_get();
}

Used above.

<Write index of macro names>=
{
  if (macro_names) {
    fputs("\n{\\small\\begin{list}{}{\\setlength{\\itemsep}{-\\parsep}",
          tex_file);
    fputs("\\setlength{\\itemindent}{-\\leftmargin}}\n", tex_file);
    format_entry(macro_names, tex_file, FALSE);
    fputs("\\end{list}}", tex_file);
  }
  c = source_get();
}

Used above.

<latex.c>+=
static void format_entry(name, tex_file, file_flag)
     Name *name;
     FILE *tex_file;
     int file_flag;
{
  while (name) {
    format_entry(name->llink, tex_file, file_flag);
    <Format an index entry>
    name = name->rlink;
  }
}

Defines format_entry (links are to index).

Previous and next definitions.

<Format an index entry>=
{
  fputs("\\item ", tex_file);
  if (file_flag) {
    fprintf(tex_file, "\\verb@\"%s\"@ ", name->spelling);
    <Write file's defining scrap numbers>
  }
  else {
    fprintf(tex_file, "$\\langle$%s {\\footnotesize ", name->spelling);
    <Write defining scrap numbers>
    fputs("}$\\rangle$ ", tex_file);
    <Write referencing scrap numbers>
  }
  putc('\n', tex_file);
}

Used above.

<Write file's defining scrap numbers>=
{
  Scrap_Node *p = name->defs;
  fputs("{\\footnotesize Defined by scrap", tex_file);
  if (p->next) {
    fputs("s ", tex_file);
    print_scrap_numbers(tex_file, p);
  }
  else {
    putc(' ', tex_file);
    write_single_scrap_ref(tex_file, p->scrap);
    putc('.', tex_file);
  }
  putc('}', tex_file);
}

Used above.

<Write defining scrap numbers>=
{
  Scrap_Node *p = name->defs;
  if (p) {
    int page;
    write_scrap_ref(tex_file, p->scrap, TRUE, &page);
    p = p->next;
    while (p) {
      write_scrap_ref(tex_file, p->scrap, FALSE, &page);
      p = p->next;
    }
  }
  else
    putc('?', tex_file);
}

Used above.

<Write referencing scrap numbers>=
{
  Scrap_Node *p = name->uses;
  fputs("{\\footnotesize ", tex_file);
  if (p) {
    fputs("Referenced in scrap", tex_file);
    if (p->next) {
      fputs("s ", tex_file);
      print_scrap_numbers(tex_file, p);
    }
    else {
      putc(' ', tex_file);
      write_single_scrap_ref(tex_file, p->scrap);
      putc('.', tex_file);
    }
  }
  else
    fputs("Not referenced.", tex_file);
  putc('}', tex_file);
}

Used above.

<Write index of user-specified names>=
{
  if (user_names) {
    fputs("\n{\\small\\begin{list}{}{\\setlength{\\itemsep}{-\\parsep}",
          tex_file);
    fputs("\\setlength{\\itemindent}{-\\leftmargin}}\n", tex_file);
    format_user_entry(user_names, tex_file);
    fputs("\\end{list}}", tex_file);
  }
  c = source_get();
}

Used above.

<latex.c>+=
static void format_user_entry(name, tex_file)
     Name *name;
     FILE *tex_file;
{
  while (name) {
    format_user_entry(name->llink, tex_file);
    <Format a user index entry>
    name = name->rlink;
  }
}

Defines format_user_entry (links are to index).

Previous definition.

<Format a user index entry>=
{
  Scrap_Node *uses = name->uses;
  if (uses) {
    int page;
    Scrap_Node *defs = name->defs;
    fprintf(tex_file, "\\item \\verb@%s@: ", name->spelling);
    if (uses->scrap < defs->scrap) {
      write_scrap_ref(tex_file, uses->scrap, TRUE, &page);
      uses = uses->next;
    }
    else {
      if (defs->scrap == uses->scrap)
        uses = uses->next;
      fputs("\\underline{", tex_file);
      write_single_scrap_ref(tex_file, defs->scrap);
      putc('}', tex_file);
      page = -2;
      defs = defs->next;
    }
    while (uses || defs) {
      if (uses && (!defs || uses->scrap < defs->scrap)) {
        write_scrap_ref(tex_file, uses->scrap, FALSE, &page);
        uses = uses->next;
      }
      else {
        if (uses && defs->scrap == uses->scrap)
          uses = uses->next;
        fputs(", \\underline{", tex_file);
        write_single_scrap_ref(tex_file, defs->scrap);
        putc('}', tex_file);
        page = -2;
        defs = defs->next;
      }
    }
    fputs(".\n", tex_file);
  }
}

Used above.

Writing the LaTeX File with HTML Scraps

<Function prototypes>+=
extern void write_html();

Used above; previous and next definitions.

We need a few local function declarations before we get into the body of write_html.

<html.c>+=
static void copy_scrap();               /* formats the body of a scrap */
static void display_scrap_ref();        /* formats a scrap reference */
static void display_scrap_numbers();    /* formats a list of scrap numbers */
static void print_scrap_numbers();      /* pluralizes scrap formats list */
static void format_entry();             /* formats an index entry */
static void format_user_entry();

Previous and next definitions.

The routine write_html takes two file names as parameters: the name of the web source file and the name of the .tex output file.

<html.c>+=
void write_html(file_name, html_name)
     char *file_name;
     char *html_name;
{
  FILE *html_file = fopen(html_name, "w");
  if (html_file) {
    if (verbose_flag)
      fprintf(stderr, "writing %s\n", html_name);
    source_open(file_name);
    <Copy source_file into html_file>
    fclose(html_file);
  }
  else
    fprintf(stderr, "%s: can't open %s\n", command_name, html_name);
}

Defines write_html (links are to index).

Previous and next definitions.

We make our second (and final) pass through the source web, this time copying characters straight into the .tex file. However, we keep an eye peeled for @ characters, which signal a command sequence.

<Copy source_file into html_file>=
{
  int scraps = 1;
  int c = source_get();
  while (c != EOF) {
    if (c == '@')
      <Interpret HTML at-sequence>
    else {
      putc(c, html_file);
      c = source_get();
    }
  }
}

Used above.

<Interpret HTML at-sequence>=
{
  c = source_get();
  switch (c) {
    case 'O': 
    case 'o': <Write HTML output file definition>
              break;
    case 'D': 
    case 'd': <Write HTML macro definition>
              break;
    case 'f': <Write HTML index of file names>
              break;
    case 'm': <Write HTML index of macro names>
              break;
    case 'u': <Write HTML index of user-specified names>
              break;
    case '@': putc(c, html_file);
    default:  c = source_get();
              break;
  }
}

Used above.

Formatting Definitions

<pre>
<a name="nuweb68">&lt;Interpret HTML at-sequence 68&gt;</a> =
{
  c = source_get();
  switch (c) {
    case 'O': 
    case 'o': &lt;Write HTML output file definition <a href="#nuweb69">69</a>&gt;
              break;
    case 'D': 
    case 'd': &lt;Write HTML macro definition <a href="#nuweb71">71</a>&gt;
              break;
    case 'f': &lt;Write HTML index of file names <a href="#nuweb86">86</a>&gt;
              break;
    case 'm': &lt;Write HTML index of macro names <a href="#nuweb87">87</a>&gt;
              break;
    case 'u': &lt;Write HTML index of user-specified names <a href="#nuweb93">93</a>&gt;
              break;
    case '@': putc(c, html_file);
    default:  c = source_get();
              break;
  }
}&lt;&gt;</pre>
Macro referenced in scrap <a href="#nuweb67">67</a>.
<br>

<Write HTML output file definition>=
{
  Name *name = collect_file_name();
  <Begin HTML scrap environment>
  <Write HTML output file declaration>
  scraps++;
  <Fill in the middle of HTML scrap environment>
  <Write HTML file defs>
  <Finish HTML scrap environment>
}

Used above.

<Write HTML output file declaration>=
  fputs("<a name=\"nuweb", html_file);
  write_single_scrap_ref(html_file, scraps);
  fprintf(html_file, "\"><code>\"%s\"</code> ", name->spelling);
  write_single_scrap_ref(html_file, scraps);
  fputs("</a> =\n", html_file);

Used above.

<Write HTML macro definition>=
{
  Name *name = collect_macro_name();
  <Begin HTML scrap environment>
  <Write HTML macro declaration>
  scraps++;
  <Fill in the middle of HTML scrap environment>
  <Write HTML macro defs>
  <Write HTML macro refs>
  <Finish HTML scrap environment>
}

Used above.

I don't format a macro name at all specially, figuring the programmer might want to use italics or bold face in the midst of the name. Note that in this implementation, programmers may only use directives in macro names that are recognized in preformatted text elements (PRE).

<Write HTML macro declaration>=
  fputs("<a name=\"nuweb", html_file);
  write_single_scrap_ref(html_file, scraps);
  fprintf(html_file, "\">&lt;%s ", name->spelling);
  write_single_scrap_ref(html_file, scraps);
  fputs("&gt;</a> =\n", html_file);

Used above.

<Begin HTML scrap environment>=
{
  fputs("\\begin{rawhtml}\n", html_file);
  fputs("<pre>\n", html_file);
}

Used above (1), above (2).

The end of a scrap is marked with the characters <>.

<Fill in the middle of HTML scrap environment>=
{
  copy_scrap(html_file);
  fputs("&lt;&gt;</pre>\n", html_file);
}

Used above (1), above (2).

The only task remaining is to get rid of the current at command and end the paragraph.

<Finish HTML scrap environment>=
{
  fputs("\\end{rawhtml}\n", html_file);
  c = source_get(); /* Get rid of current at command. */
}

Used above (1), above (2).

Formatting Cross References

<Write HTML file defs>=
{
  if (name->defs->next) {
    fputs("File defined by ", html_file);
    print_scrap_numbers(html_file, name->defs);
    fputs("<br>\n", html_file);
  }
}

Used above.

<Write HTML macro defs>=
{
  if (name->defs->next) {
    fputs("Macro defined by ", html_file);
    print_scrap_numbers(html_file, name->defs);
    fputs("<br>\n", html_file);
  }
}

Used above.

<Write HTML macro refs>=
{
  if (name->uses) {
    fputs("Macro referenced in ", html_file);
    print_scrap_numbers(html_file, name->uses);
  }
  else {
    fputs("Macro never referenced.\n", html_file);
    fprintf(stderr, "%s: <%s> never referenced.\n",
            command_name, name->spelling);
  }
  fputs("<br>\n", html_file);
}

Used above.

<html.c>+=
static void display_scrap_ref(html_file, num)
     FILE *html_file;
     int num;
{
  fputs("<a href=\"#nuweb", html_file);
  write_single_scrap_ref(html_file, num);
  fputs("\">", html_file);
  write_single_scrap_ref(html_file, num);
  fputs("</a>", html_file);
}

Defines display_scrap_ref (links are to index).

Previous and next definitions.

<html.c>+=
static void display_scrap_numbers(html_file, scraps)
     FILE *html_file;
     Scrap_Node *scraps;
{
  display_scrap_ref(html_file, scraps->scrap);
  scraps = scraps->next;
  while (scraps) {
    fputs(", ", html_file);
    display_scrap_ref(html_file, scraps->scrap);
    scraps = scraps->next;
  }
}

Defines display_scrap_numbers (links are to index).

Previous and next definitions.

<html.c>+=
static void print_scrap_numbers(html_file, scraps)
     FILE *html_file;
     Scrap_Node *scraps;
{
  fputs("scrap", html_file);
  if (scraps->next) fputc('s', html_file);
  fputc(' ', html_file);
  display_scrap_numbers(html_file, scraps);
  fputs(".\n", html_file);
}

Defines print_scrap_numbers (links are to index).

Previous and next definitions.

Formatting a Scrap

<html.c>+=
static void copy_scrap(file)
     FILE *file;
{
  int indent = 0;
  int c = source_get();
  while (1) {
    switch (c) {
      case '@':  <Check HTML at-sequence for end-of-scrap>
                 break;
      case '<' : fputs("&lt;", file);
                 indent++;
                 break;
      case '>' : fputs("&gt;", file);
                 indent++;
                 break;
      case '&' : fputs("&amp;", file);
                 indent++;
                 break;
      case '\n': fputc(c, file);
                 indent = 0;
                 break;
      case '\t': <Expand tab into spaces>
                 break;
      default:   putc(c, file);
                 indent++;
                 break;
    }
    c = source_get();
  }
}

Defines copy_scrap (links are to index).

Previous and next definitions.

<Check HTML at-sequence for end-of-scrap>=
{
  c = source_get();
  switch (c) {
    case '@': fputc(c, file);
              break;
    case '|': <Skip over index entries>
    case '}': return;
    case '<': <Format HTML macro name>
              break;
    default:  /* ignore these since pass1 will have warned about them */
              break;
  }
}

Used above.

There's no need to check for errors here, since we will have already pointed out any during the first pass.

<Format HTML macro name>=
{
  Name *name = collect_scrap_name();
  fprintf(file, "&lt;%s ", name->spelling);
  if (name->defs)
    <Write HTML abbreviated definition list>
  else {
    putc('?', file);
    fprintf(stderr, "%s: scrap never defined <%s>\n",
            command_name, name->spelling);
  }
  fputs("&gt;", file);
}

Used above.

<Write HTML abbreviated definition list>=
{
  Scrap_Node *p = name->defs;
  display_scrap_ref(file, p->scrap);
  if (p->next)
    fputs(", ... ", file);
}

Used above.

Generating the Indices

<Write HTML index of file names>=
{
  if (file_names) {
    fputs("\\begin{rawhtml}\n", html_file);
    fputs("<dl compact>\n", html_file);
    format_entry(file_names, html_file, TRUE);
    fputs("</dl>\n", html_file);
    fputs("\\end{rawhtml}\n", html_file);
  }
  c = source_get();
}

Used above.

<Write HTML index of macro names>=
{
  if (macro_names) {
    fputs("\\begin{rawhtml}\n", html_file);
    fputs("<dl compact>\n", html_file);
    format_entry(macro_names, html_file, FALSE);
    fputs("</dl>\n", html_file);
    fputs("\\end{rawhtml}\n", html_file);
  }
  c = source_get();
}

Used above.

<html.c>+=
static void format_entry(name, html_file, file_flag)
     Name *name;
     FILE *html_file;
     int file_flag;
{
  while (name) {
    format_entry(name->llink, html_file, file_flag);
    <Format an HTML index entry>
    name = name->rlink;
  }
}

Defines format_entry (links are to index).

Previous and next definitions.

<Format an HTML index entry>=
{
  fputs("<dt> ", html_file);
  if (file_flag) {
    fprintf(html_file, "<code>\"%s\"</code>\n<dd> ", name->spelling);
    <Write HTML file's defining scrap numbers>
  }
  else {
    fprintf(html_file, "&lt;%s ", name->spelling);
    <Write HTML defining scrap numbers>
    fputs("&gt;\n<dd> ", html_file);
    <Write HTML referencing scrap numbers>
  }
  putc('\n', html_file);
}

Used above.

<Write HTML file's defining scrap numbers>=
{
  fputs("Defined by ", html_file);
  print_scrap_numbers(html_file, name->defs);
}

Used above.

<Write HTML defining scrap numbers>=
{
  if (name->defs)
    display_scrap_numbers(html_file, name->defs);
  else
    putc('?', html_file);
}

Used above.

<Write HTML referencing scrap numbers>=
{
  Scrap_Node *p = name->uses;
  if (p) {
    fputs("Referenced in ", html_file);
    print_scrap_numbers(html_file, p);
  }
  else
    fputs("Not referenced.\n", html_file);
}

Used above.

<Write HTML index of user-specified names>=
{
  if (user_names) {
    fputs("\\begin{rawhtml}\n", html_file);
    fputs("<dl compact>\n", html_file);
    format_user_entry(user_names, html_file);
    fputs("</dl>\n", html_file);
    fputs("\\end{rawhtml}\n", html_file);
  }
  c = source_get();
}

Used above.

<html.c>+=
static void format_user_entry(name, html_file)
     Name *name;
     FILE *html_file;
{
  while (name) {
    format_user_entry(name->llink, html_file);
    <Format a user HTML index entry>
    name = name->rlink;
  }
}

Defines format_user_entry (links are to index).

Previous definition.

<Format a user HTML index entry>=
{
  Scrap_Node *uses = name->uses;
  if (uses) {
    Scrap_Node *defs = name->defs;
    fprintf(html_file, "<dt><code>%s</code>:\n<dd> ", name->spelling);
    if (uses->scrap < defs->scrap) {
      display_scrap_ref(html_file, uses->scrap);
      uses = uses->next;
    }
    else {
      if (defs->scrap == uses->scrap)
        uses = uses->next;
      fputs("<strong>", html_file);
      display_scrap_ref(html_file, defs->scrap);
      fputs("</strong>", html_file);
      defs = defs->next;
    }
    while (uses || defs) {
      fputs(", ", html_file);
      if (uses && (!defs || uses->scrap < defs->scrap)) {
        display_scrap_ref(html_file, uses->scrap);
        uses = uses->next;
      }
      else {
        if (uses && defs->scrap == uses->scrap)
          uses = uses->next;
        fputs("<strong>", html_file);
        display_scrap_ref(html_file, defs->scrap);
        fputs("</strong>", html_file);
        defs = defs->next;
      }
    }
    fputs(".\n", html_file);
  }
}

Used above.

Writing the Output Files

<Function prototypes>+=
extern void write_files();

Used above; previous and next definitions.

<output.c>+=
void write_files(files)
     Name *files;
{
  while (files) {
    write_files(files->llink);
    <Write out files->spelling>
    files = files->rlink;
  }
}

Defines write_files (links are to index).

Previous definition.

We call tempnam, causing it to create a file name in the current directory. This could cause a problem for rename if the eventual output file will reside on a different file system. Perhaps it would be better to examine files->spelling to find any directory information.

Note the superfluous call to remove before rename. We're using it get around a bug in some implementations of rename.

<Write out files->spelling>=
{
  char indent_chars[500];
  FILE *temp_file;
  char *temp_name = tempnam(".", 0);
  temp_file = fopen(temp_name, "w");
  if (!temp_file) {
    fprintf(stderr, "%s: can't create %s for a temporary file\n",
            command_name, temp_name);
    exit(-1);
  }  
  if (verbose_flag)
    fprintf(stderr, "writing %s\n", files->spelling);
  write_scraps(temp_file, files->defs, 0, indent_chars,
               files->debug_flag, files->tab_flag, files->indent_flag);
  fclose(temp_file);
  if (compare_flag)
    <Compare the temp file and the old file>
  else {
    remove(files->spelling);
    rename(temp_name, files->spelling);
  }
}

Used above.

Again, we use a call to remove before rename.

<Compare the temp file and the old file>=
{
  FILE *old_file = fopen(files->spelling, "r");
  if (old_file) {
    int x, y;
    temp_file = fopen(temp_name, "r");
    do {
      x = getc(old_file);
      y = getc(temp_file);
    } while (x == y && x != EOF);
    fclose(old_file);
    fclose(temp_file);
    if (x == y)
      remove(temp_name);
    else {
      remove(files->spelling);
      rename(temp_name, files->spelling);
    }
  }
  else
    rename(temp_name, files->spelling);
}

Used above.

The Support Routines

Source Files

Global Declarations

<Function prototypes>+=
extern void source_open(); /* pass in the name of the source file */
extern int source_get();   /* no args; returns the next char or EOF */

Used above; previous and next definitions.

There are also two global variables maintained for use in error messages and such.

<Global variable declarations>+=
extern char *source_name;  /* name of the current file */
extern int source_line;    /* current line in the source file */

Defines source_line, source_name (links are to index).

Used above; previous and next definitions.

<Global variable definitions>+=
char *source_name = NULL;
int source_line = 0;

Used above; previous and next definitions.

Local Declarations

<input.c>+=
static FILE *source_file;  /* the current input file */
static int source_peek;
static int double_at;
static int include_depth;

Defines double_at, include_depth, source_file, source_peek (links are to index).

Previous and next definitions.

<input.c>+=
static struct {
  FILE *file;
  char *name;
  int line;
} stack[10];

Defines stack (links are to index).

Previous and next definitions.

Reading a File

<input.c>+=
int source_get()
{
  int c = source_peek;
  switch (c) {
    case EOF:  <Handle EOF>
               return c;
    case '@':  <Handle an ``at'' character>
               return c;
    case '\n': source_line++;
    default:   source_peek = getc(source_file);
               return c;
  }
}

Defines source_get (links are to index).

Previous and next definitions.

This whole @ character handling mess is pretty annoying. I want to recognize @i so I can handle include files correctly. At the same time, it makes sense to recognize illegal @ sequences and complain; this avoids ever having to check anywhere else. Unfortunately, I need to avoid tripping over the @@ sequence; hence this whole unsatisfactory double_at business.

<Handle an ``at'' character>=
{
  c = getc(source_file);
  if (double_at) {
    source_peek = c;
    double_at = FALSE;
    c = '@';
  }
  else
    switch (c) {
      case 'i': <Open an include file>
                break;
      case 'f': case 'm': case 'u':
      case 'd': case 'o': case 'D': case 'O':
      case '{': case '}': case '<': case '>': case '|':
                source_peek = c;
                c = '@';
                break;
      case '@': source_peek = c;
                double_at = TRUE;
                break;
      default:  fprintf(stderr, "%s: bad @ sequence (%s, line %d)\n",
                        command_name, source_name, source_line);
                exit(-1);
    }
}

Used above.

<Open an include file>=
{
  char name[100];
  if (include_depth >= 10) {
    fprintf(stderr, "%s: include nesting too deep (%s, %d)\n",
            command_name, source_name, source_line);
    exit(-1);
  }
  <Collect include-file name>
  stack[include_depth].name = source_name;
  stack[include_depth].file = source_file;
  stack[include_depth].line = source_line + 1;
  include_depth++;
  source_line = 1;
  source_name = save_string(name);
  source_file = fopen(source_name, "r");
  if (!source_file) {
    fprintf(stderr, "%s: can't open include file %s\n",
     command_name, source_name);
    exit(-1);
  }
  source_peek = getc(source_file);
  c = source_get();
}

Used above.

<Collect include-file name>=
{
    char *p = name;
    do 
      c = getc(source_file);
    while (c == ' ' || c == '\t');
    while (isgraph(c)) {
      *p++ = c;
      c = getc(source_file);
    }
    *p = '\0';
    if (c != '\n') {
      fprintf(stderr, "%s: unexpected characters after file name (%s, %d)\n",
              command_name, source_name, source_line);
      exit(-1);
    }
}

Used above.

If an EOF is discovered, the current file must be closed and input from the next stacked file must be resumed. If no more files are on the stack, the EOF is returned.

<Handle EOF>=
{
  fclose(source_file);
  if (include_depth) {
    include_depth--;
    source_file = stack[include_depth].file;
    source_line = stack[include_depth].line;
    source_name = stack[include_depth].name;
    source_peek = getc(source_file);
    c = source_get();
  }
}

Used above.

Opening a File

<input.c>+=
void source_open(name)
     char *name;
{
  source_file = fopen(name, "r");
  if (!source_file) {
    fprintf(stderr, "%s: couldn't open %s\n", command_name, name);
    exit(-1);
  }
  source_name = name;
  source_line = 1;
  source_peek = getc(source_file);
  double_at = FALSE;
  include_depth = 0;
}

Defines source_open (links are to index).

Previous definition.

Scraps

<scraps.c>+=
#define SLAB_SIZE 500

typedef struct slab {
  struct slab *next;
  char chars[SLAB_SIZE];
} Slab;

Defines Slab, SLAB_SIZE (links are to index).

Previous and next definitions.

<scraps.c>+=
typedef struct {
  char *file_name;
  int file_line;
  int page;
  char letter;
  Slab *slab;
} ScrapEntry;

Defines ScrapEntry (links are to index).

Previous and next definitions.

<scraps.c>+=
static ScrapEntry *SCRAP[256];

#define scrap_array(i) SCRAP[(i) >> 8][(i) & 255]

static int scraps;

Defines SCRAP, scrap_array, scraps (links are to index).

Previous and next definitions.

<Function prototypes>+=
extern void init_scraps();
extern int collect_scrap();
extern int write_scraps();
extern void write_scrap_ref();
extern void write_single_scrap_ref();

Used above; previous and next definitions.

<scraps.c>+=
void init_scraps()
{
  scraps = 1;
  SCRAP[0] = (ScrapEntry *) arena_getmem(256 * sizeof(ScrapEntry));
}

Defines init_scraps (links are to index).

Previous and next definitions.

<scraps.c>+=
void write_scrap_ref(file, num, first, page)
     FILE *file;
     int num;
     int first;
     int *page;
{
  if (scrap_array(num).page >= 0) {
    if (first)
      fprintf(file, "%d", scrap_array(num).page);
    else if (scrap_array(num).page != *page)
      fprintf(file, ", %d", scrap_array(num).page);
    if (scrap_array(num).letter > 0)
      fputc(scrap_array(num).letter, file);
  }
  else {
    if (first)
      putc('?', file);
    else
      fputs(", ?", file);
    <Warn (only once) about needing to rerun after Latex>
  }
  *page = scrap_array(num).page;
}

Defines write_scrap_ref (links are to index).

Previous and next definitions.

<scraps.c>+=
void write_single_scrap_ref(file, num)
     FILE *file;
     int num;
{
  int page;
  write_scrap_ref(file, num, TRUE, &page);
}

Defines write_single_scrap_ref (links are to index).

Previous and next definitions.

<Warn (only once) about needing to rerun after Latex>=
{
  if (!already_warned) {
    fprintf(stderr, "%s: you'll need to rerun nuweb after running latex\n",
            command_name);
    already_warned = TRUE;
  }
}

Used above (1), below (2).

<Global variable declarations>+=
extern int already_warned;

Defines already_warned (links are to index).

Used above; previous and next definitions.

<Global variable definitions>+=
int already_warned = 0;

Used above; previous and next definitions.

<scraps.c>+=
typedef struct {
  Slab *scrap;
  Slab *prev;
  int index;
} Manager;

Defines Manager (links are to index).

Previous and next definitions.

<scraps.c>+=
static void push(c, manager)
     char c;
     Manager *manager;
{
  Slab *scrap = manager->scrap;
  int index = manager->index;
  scrap->chars[index++] = c;
  if (index == SLAB_SIZE) {
    Slab *new = (Slab *) arena_getmem(sizeof(Slab));
    scrap->next = new;
    manager->scrap = new;
    index = 0;
  }
  manager->index = index;
}

Defines push (links are to index).

Previous and next definitions.

<scraps.c>+=
static void pushs(s, manager)
     char *s;
     Manager *manager;
{
  while (*s)
    push(*s++, manager);
}

Defines pushs (links are to index).

Previous and next definitions.

<scraps.c>+=
int collect_scrap()
{
  Manager writer;
  <Create new scrap, managed by writer>
  <Accumulate scrap and return scraps++>
}

Defines collect_scrap (links are to index).

Previous and next definitions.

<Create new scrap, managed by writer>=
{
  Slab *scrap = (Slab *) arena_getmem(sizeof(Slab));
  if ((scraps & 255) == 0)
    SCRAP[scraps >> 8] = (ScrapEntry *) arena_getmem(256 * sizeof(ScrapEntry));
  scrap_array(scraps).slab = scrap;
  scrap_array(scraps).file_name = save_string(source_name);
  scrap_array(scraps).file_line = source_line;
  scrap_array(scraps).page = -1;
  scrap_array(scraps).letter = 0;
  writer.scrap = scrap;
  writer.index = 0;
}

Used above.

<Accumulate scrap and return scraps++>=
{
  int c = source_get();
  while (1) {
    switch (c) {
      case EOF: fprintf(stderr, "%s: unexpect EOF in scrap (%s, %d)\n",
                        command_name, scrap_array(scraps).file_name,
                        scrap_array(scraps).file_line);
                exit(-1);
      case '@': <Handle at-sign during scrap accumulation>
                break;
      default:  push(c, &writer);
                c = source_get();
                break;
    }
  }
}

Used above.

<Handle at-sign during scrap accumulation>=
{
  c = source_get();
  switch (c) {
    case '@': pushs("@@", &writer);
              c = source_get();
              break;
    case '|': <Collect user-specified index entries>
    case '}': push('\0', &writer);
              return scraps++;
    case '<': <Handle macro invocation in scrap>
              break;
    default : fprintf(stderr, "%s: unexpected @%c in scrap (%s, %d)\n",
                      command_name, c, source_name, source_line);
              exit(-1);
  }
}

Used above.

<Collect user-specified index entries>=
{
  do {
    char new_name[100];
    char *p = new_name;
    do 
      c = source_get();
    while (isspace(c));
    if (c != '@') {
      Name *name;
      do {
        *p++ = c;
        c = source_get();
      } while (c != '@' && !isspace(c));
      *p = '\0';
      name = name_add(&user_names, new_name);
      if (!name->defs || name->defs->scrap != scraps) {
        Scrap_Node *def = (Scrap_Node *) arena_getmem(sizeof(Scrap_Node));
        def->scrap = scraps;
        def->next = name->defs;
        name->defs = def;
      }
    }
  } while (c != '@');
  c = source_get();
  if (c != '}') {
    fprintf(stderr, "%s: unexpected @%c in scrap (%s, %d)\n",
            command_name, c, source_name, source_line);
    exit(-1);
  }
}

Used above.

<Handle macro invocation in scrap>=
{
  Name *name = collect_scrap_name();
  <Save macro name>
  <Add current scrap to name's uses>
  c = source_get();
}

Used above.

<Save macro name>=
{
  char *s = name->spelling;
  int len = strlen(s) - 1;
  pushs("@<", &writer);
  while (len > 0) {
    push(*s++, &writer);
    len--;
  }
  if (*s == ' ')
    pushs("...", &writer);
  else
    push(*s, &writer);
  pushs("@>", &writer);
}

Used above.

<Add current scrap to name's uses>=
{
  if (!name->uses || name->uses->scrap != scraps) {
    Scrap_Node *use = (Scrap_Node *) arena_getmem(sizeof(Scrap_Node));
    use->scrap = scraps;
    use->next = name->uses;
    name->uses = use;
  }
}

Used above.

<scraps.c>+=
static char pop(manager)
     Manager *manager;
{
  Slab *scrap = manager->scrap;
  int index = manager->index;
  char c = scrap->chars[index++];
  if (index == SLAB_SIZE) {
    manager->prev = scrap;
    manager->scrap = scrap->next;
    index = 0;
  }
  manager->index = index;
  return c;
}

Defines pop (links are to index).

Previous and next definitions.

<scraps.c>+=
static Name *pop_scrap_name(manager)
     Manager *manager;
{
  char name[100];
  char *p = name;
  int c = pop(manager);
  while (TRUE) {
    if (c == '@')
      <Check for end of scrap name and return>
    else {
      *p++ = c;
      c = pop(manager);
    }
  }
}

Defines pop_scrap_name (links are to index).

Previous and next definitions.

<Check for end of scrap name and return>=
{
  c = pop(manager);
  if (c == '@') {
    *p++ = c;
    c = pop(manager);
  }
  else if (c == '>') {
    if (p - name > 3 && p[-1] == '.' && p[-2] == '.' && p[-3] == '.') {
      p[-3] = ' ';
      p -= 2;
    }
    *p = '\0';
    return prefix_add(&macro_names, name);
  }
  else {
    fprintf(stderr, "%s: found an internal problem (1)\n", command_name);
    exit(-1);
  }
}

Used above.

<scraps.c>+=
int write_scraps(file, defs, global_indent, indent_chars,
                   debug_flag, tab_flag, indent_flag)
     FILE *file;
     Scrap_Node *defs;
     int global_indent;
     char *indent_chars;
     char debug_flag;
     char tab_flag;
     char indent_flag;
{
  int indent = 0;
  while (defs) {
    <Copy defs->scrap to file>
    defs = defs->next;
  }
  return indent + global_indent;
}

Defines write_scraps (links are to index).

Previous and next definitions.

<Copy defs->scrap to file>=
{
  char c;
  Manager reader;
  int line_number = scrap_array(defs->scrap).file_line;
  <Insert debugging information if required>
  reader.scrap = scrap_array(defs->scrap).slab;
  reader.index = 0;
  c = pop(&reader);
  while (c) {
    switch (c) {
      case '@':  <Check for macro invocation in scrap>
                 break;
      case '\n': putc(c, file);
                 line_number++;
                 <Insert appropriate indentation>
                 break;
      case '\t': <Handle tab characters on output>
                 break;
      default:   putc(c, file);
                 indent_chars[global_indent + indent] = ' ';
                 indent++;
                 break;
    }
    c = pop(&reader);
  }
}

Used above.

<Insert debugging information if required>=
if (debug_flag) {
  fprintf(file, "\n#line %d \"%s\"\n",
          line_number, scrap_array(defs->scrap).file_name);