Noweb Frequently Asked Questions

Problems Building Noweb
Indentation of code, especially FORTRAN
Formatting the printed documentation
Microsoft Madness
Noweb and Emacs
Other Questions

Problems Building Noweb

Q. The build fails because it can't find notangle. What am I doing wrong?

A. Your source files have the wrong timestamps. The noweb files are carefully distributed so that the C code is more recent than the literate source code. Retrieving that noweb distribution as a compressed tar file preserves these stamps. The CTAN sites will create a compressed tar file on the fly for any directory. Your best bet is to get the tar file, unpack it, and try again, because your abortive attempt will probably have stomped on a C file that you need.
I have reports that the former CTAN site ftp.shsu.edu fouled the timestamps. Don't use the site! If you get bad timestamps, you can try `make touch' as soon as you unpack the distribution, which should touch all of the derived files. This trick won't work on NeXT systems, which have a strange idea of 'touch'.

Q. The system builds OK, but when I try to run noweave, I get an error in /usr/public/pkg/noweb/lib/totex (or some similar place) complaining about being out of environment space or something equally unpleasant.

A. The awk versions of the noweb scripts pass the awk programs as arguments on the command line. Some shells or systems are too broken to handle a real awk program on the command line. This problem is one of many reasons that the awk versions are officially deprecated. The Icon versions will make you happy, but if you prefer, you can edit the offending scripts so that the awk programs reside in separate files and the scripts call awk -f.

Q. I'm unable to run noweb on Windows NT 4.0. The problem is that the Icon programs use a DOS extender which doesn't work in an NT console.

A. Clint Jeffery, the Icon Master for Windows, says to use the NT console binaries (nticont.exe and nticonx.exe) rather than wiconx.exe with its faux console. Only applications that use the graphics facilities require wiconx.exe and its kin. The nticonx* binaries should run fine on Win95 also.

Q. I'm having trouble getting noweb to work on Windows XP.

A. Bad news. There used to be a distribution from literateprogramming.org, but as of January 2010, that domain is no longer registered, and I don't know where the distribution went.

Indentation of code, especially FORTRAN

Q. Has anyone devised a clean way of handling FORTRAN 77 using a litprog tool such as noweb? If I have the following:

<<Block>>=
      <<Nicely Indented Chunk Title>>
@
<<Nicely Indented Chunk Title>>=
C   A comment in a chunk!
      Z = X * 
     + Y
@

I'll get the "C" in column 7, and the continuation character "+" in column 12, neither of which is desirable.

A. As noted on the man page, notangle's -L option suppresses the usual behavior with respect to indentation. Thus, a command like
notangle -L'%N' pgm.nw > pgm.f
should do the job.

Q. I noticed the -L option to notangle turns off the usual indentation. Is there an easy way to get both -L and indentation?

A. No. It was my design decision that -L should preserve the column numbers in the original source code. This behavior is extremely useful in cases where a compiler reports an error in the source by line and column number. Of course, this decision precludes changing the indentation of the input.

Formatting the printed documentation

Q. There's too much white space at the bottom of the pages, especially if a code chunk is followed by a section. How do I fix it?

A. Noweb is set up never to break chunks across pages. You can get better results by relaxing this constraint, e.g., by
\def\nwendcode{\endtrivlist \endgroup \vfil\penalty10\vfilneg}
\let\nwdocspar=\smallbreak
or the even less liberal
\def\nwendcode{\endtrivlist \endgroup}
\let\nwdocspar=\par

Q. In a noweb source file, what is the difference between a line beginning with "@" followed by a space and some text versus a line with nothing but "@"?

A. A line with nothing but @ begins the `documentation chunk' with a blank line. TeX thinks blank lines are new paragraphs and good places to put page breaks. By default, TeX thinks that if a new documentation chunk starts with a new paragraph, this is an especially good place for a page break.

Q. I know how to switch between code and documentation via <<*>>= and @, but sometimes, after a <<*>>= section, automatically a new page is started, even if I do not want this but prefer to go on with commenting directly after the inserted programm code. How can I avoid this?

A. The @ sign you use to switch back to documentation should not appear on a line by itself, but should be followed by a blank space and some text. You should then put a bare @ sign on a line by itself at the next place that is suitable for a page break.

Q. I don't quite understand noweb's default page breaking.

Here is some text
that leads up to a chunk
<<chunk>>=
  a = b;
  c = d;
@ and here is some more text.
Sometimes this appears on a new page even though
there is plenty of room on this page.  Can I fix it by adding
the following line (which I  haven't been doing) ?
@
New paragraph here.

A. Sad but true. Perhaps a future version of noweb will provide better facilities for controlling page breaking.

Q. I ran into a problem when trying to use several files in a single noweb project. In my project, I have a LaTeX master file (say, doc.tex) that \include's three others: say, a.tex, b.tex, and copyright.tex. These later files are generated from a.nw, b.nw, and copyright.nw, respectively, using the command "noweave -n -index" I really want to keep these noweb files separated. In the code chunks appearing in both a.nw and b.nw a copyright notice chunk (defined in copyright.nw) is included.

Tangling works fine, provided that copyright.nw appears in the notangle command. Problems arise with noweave. Copyright chunks appear as "(never defined)" in a.tex and b.tex, what is obvious, because I cannot use copyright.nw for weaving a.nw or b.nw (otherwise the copyright notice chunk would appear several times in my printed document).

Does someone know how to solve this problem?

A. This is a form of question that arises repeatedly, which is to say, ``what is the scope of chunk names?'' In Noweb, chunk names are in the same scope if the files in which the chunks appear are used on the same command line. Thus, the normal rule is one Noweb file per command line, and therefore each file is its own scope.
You want to have chunks in the same scope for purposes of tangling, but not to weave files together. If you want files a.nw and b.nw in separate scopes, the situation is hopeless, because ``being in the same scope'' has to be a transitive property, and if a.nw and b.nw are both in the same scope as copyright.nw, they must be in the same scope as each other.
However, if you want all files to be in the same scope, there is a solution, although it is a bit ugly. The solution is to weave all the files together, then use a special back end to split them into separate .tex files. This back end, called scopehack, could be used as follows:
noweave -n -index -backend scopehack *.nw
and this results in multiple *.tex files as required.

Q. I have problems using LaTeX \ifthenelse with noweb--- code chunks inside an \ifthenelse are not typeset correctly and a %def directive causes (La)TeX groups to be unbalanced.

A. Noweb code chunks are ``moving arguments'' (like \verb) and can't be arguments to macros. I suggest you combine \ifthenelse with the noweb 'elide' filter to remove the offending code chunks.

Q. I embed the build instructions for a noweb-based project in a code chunk called build-script that I don't wish to have show up in the printed documentation. So, I surround the section with LaTeX \iffalse ... \fi. If I do this at the same time as using noweb's index, the \fi shows up in the generated TeX file at the end of the index information, resulting in an empty index.

A. Make sure that the \fi appears before the last documentation chunk, by creating an empty documentation chunk (with @) if necessary. Then use noweave -delay to insert the index information.
Incidentally, it is recommended that, in addition to using \iffalse ... \fi, you remove unwanted code chunks by using the elide filter provided with noweb. Latex can get confused if chunk cross-reference anchors are hidden away inside \iffalse ... \fi.

Q. When I write C code and use the decrement operator --, it appears in the resulting document as a single -. This unpleasantness seems to be a side effect of \usepackage[T1]{fontenc}.

A. Indeed. We don't understand this behavior, but as an ill-understood workaround, you can add
\catcode`\-=\active
to \def\setupcode, and things may work better.

Microsoft Madness

Q. Using the precompiled MS-DOS and Windows binaries for noweb, many of the programs throw their output to the screen and not to whatever receiving program/file they ought to go to. A typical example: I go to /noweb/examples and type

        notangle wc.nw > wc.c

I see the tangled program scroll by on the screen, but it isn't piped to the file wc.c as requested. Any solutions?

A. This is a known COMMAND.COM problem. Try:
        command /c notangle wc.nw > wc.c
or get a COMMAND.COM replacement such as 4DOS. Better yet, help with the noweb 3 port.

Q. For Windows 95/NT systems: Why do I get the error message "This program cannot be run in DOS mode." when I run some of the programs (including noweave.bat)?

A. [Thanks to Chris Harris.] The problem is that some of the files used in the noweb system (including totex.exe and tohtml.exe used by noweave.bat) are written using an old version of icon that uses a DOS extender which is incompatible with 95/NT. The solution is to rebuild all of these files that were built using icon source:
Go get the console ICON executables for use on 95/NT. They are the files nticont.exe, nticonx.exe, noop.bat. Put them in your noweb/bin directory.
The other two were available on the noweb ftp site, from the FAQ, but noop.bat wasn't... it's availbe via FTP with the icon distribution, but it's pretty easy to build yourself, it's contents are the single line:
@rem this file prevents further batch processing after launching nticonx
So to build noop.bat, just type at the prompt "copy con noop.bat" and then paste in the above line (starting with the @) hit enter and ^Z and you're good to go. Note: This file could really be empty, the above line is a dos batch file comment, but you may want to put this in there just so you remember in 2 years why you haven't deleted this file! :)
Get the noweb source distribution and extract just the icon files (i.e. those located in the icon/ directory with a .icn extention)
Build a batch file for each one using "nticont .icn"
Copy all of the .bat files built in step #2 into your noweb/bin/ directory
For each new .bat file you have in the bin directory, delete the corresponding .exe file
Additionally, do NOT rename nticont to icont or nticonx to iconx. The batch files created with nticont REQUIRE nticonx to exist. So if you rename it, it'll get very confused.

Noweb and Emacs

Q. Emacs noweb-mode is driving me crazy. For example, I want 4-space tabs instead of the usual 8. I put this line in my file:

% -*- mode: Noweb; noweb-code-mode: c-mode; tab-width: 4 -*-

Or equivalently I do M-x set-variable tab-width 4. Everything is fine until the cursor moves from one chunk to another---then whammo! Tabs are 8 spaces again. What can I do??

A. If you have GNU emacs 20.4, or perhaps some other version, an undocumented internal function of files.el will do what you want. Try adding this to your ~/.emacs file:
    (add-hook 'noweb-select-mode-hook
              '(lambda () (hack-local-variables-prop-line)))
Thanks to Glenn Holloway for this discovery.

Q. Emacs noweb-mode is driving me crazy. I want to use Tab or Ctl-J to handle indentation, but when I'm in the middle of a code chunk, the indentation is wrong, and the cursor jumps to a strange place. How can I make emacs behave?

A. These symptoms indicate that perhaps emacs has lost track of the boundaries between noweb chunks, perhaps material in documentation chunks is confusing the auto-indenter, or perhaps both. As of Emacs 21 in 2008, you can now easily afford to fix these problems using scary Emacs macros:

  (defun my-newline-and-indent () 
    "Newline and indent that works better with noweb mode"
    (interactive "*")
    (if (and (boundp 'noweb-mode) noweb-mode)
        (save-restriction
          (noweb-update-chunk-vector)
          (noweb-narrow-to-chunk)
          (newline-and-indent))
        (newline-and-indent)))

  (defun my-tab-key () 
    "Tab that always tabs in Fundamental mode" (interactive)
    (if (string= "Fundamental" mode-name)
        (insert "\t")
      (if (and (boundp 'noweb-mode) noweb-mode)
          (save-restriction
            (noweb-update-chunk-vector)
            (noweb-narrow-to-chunk)
            (indent-for-tab-command))
        (indent-for-tab-command))))

  (defun use-my-indent-keys ()
    "Locally bind tab and ^J to keys that indent better" (interactive)
    (local-set-key "\t" 'my-tab-key)
    (local-set-key "\C-j" 'my-newline-and-indent))

  (add-hook 'noweb-select-code-mode-hook 'use-my-indent-keys)

Add these to your .emacs file and perhaps the problem will go away. Isn't Moore's law grand?