10.1.6.1 Package fwebinsert: Inserting FWEAVE’s output into a LaTeX document

Beginning with version 1.61, it is (barely) possible to insert the TeX output woven by FWEAVE into a LaTeX document. For example, a code listing could be an appendix to a dissertation, or a handbook on numerical methods could insert fragments of code formatted by FWEAVE.

Suppose one has the file test.web and used FWEAVE to create test.tex. Unfortunately, it does not work to simply \input test.tex into a LaTeX document, because by default test.tex operates in a “stand-alone” mode and tries to issue a \begin{document} command.

Instead, one must use the package fwebinsert and the special input command \FWEBinput, as in the following example. There are two important steps.

1. Use FWEAVE to create test.tex. [You may wish to use the ‘-x’ flag (see -x) to prevent some of the lists at the end, such as the index or module list, from being printed.]
2. Now ‘latex test’ until all of the section numbering is up-to-date. (This step is necessary because information in the aux file is used in processing the section headings.)

Now test.tex is ready to be inserted in a code like the following:

\documentclass{article}
\usepackage{fwebinsert}

\begin{document}

\section{Body}

The body of the document.

\appendix

\FWEBinput{test}

\end{document}

Note that the ‘@*’ commands in test.web are converted into LaTeX sectioning commands such as \section. The above example works correctly because the first ‘@*’ in test.web is equivalent to a \section (level 0) command, which should indeed immediately follow an \appendix command. Suppose, however, that you wanted to input test.web as part of the body of the above example, and wanted the ‘@*’s to be treated as subsections (level 1) rather than sections. To tell fwebinsert what level number to assign to the ‘@*’s, provide that number as an optional argument to \FWEBinput, as in the following example:

\documentclass{article}
\usepackage{fwebinsert}

\begin{document}

\section{Body}

The body of the document.

\FWEBinput[1]{test}

\end{document}

Alternatively, say \FWEBlevel{1} before the \FWEBinput. (The optional argument construction merely calls \FWEBlevel.)

Here are some caveats about fwebinsert:

• Implementing this package was tricky. It may work in simple circumstances, but it is not fully debugged.
• The \FWEBinput command surrounds the included TeX code with \begingroup...\endgroup, in an attempt to prevent various macro conflicts. As it stands, the command \fwebinput is \let equal to \FWEBinput. If necessary, one could redefine \fwebinput to not include the enclosing \begingroup...\endgroup.
• For anything except level-0 inclusions, one should have just one \FWEBinput command following each sectioning command. (This is a bug.)
• One is supposed to be able to use the package fwebnum (see Numbering) in conjunction with fwebinsert. One can apply that to either the included file (via a LaTeX.package entry in fweb.sty), the including file (via a \usepackage command), or both. Try out these various combinations to see what emerges.