5.5.21 ‘@o’: Open output file (local scope)

This behaves like ‘@O’, except that the new file name is in effect only for the current section. A subsequent ‘@o’ issued in a different section but for the same file name accretes material to the file.

An annoying problem arises in C programming when ‘@o’s are used to create multiple source files that are subsequently compiled under the control of a Makefile. Remember that by default line-number information is written into the C files. This means that a change in the web file code for one source file can affect all of the others, because the line numbering in the web file changes. Therefore, a trivial change to the code for just one source file can cause all of the others to be recompiled.

As long as one desires debugging information relative to the original web file, there is really no solution to this problem; one needs the proper line information in each file in order to work with the debugger, so if line numbers change the sources must be recompiled. One can, of course, turn off the line numbering with the command-line option ‘-#’ (see -#), but then debugger statements will refer to the tangled C code, which is undesirable. A better partial solution is to use ‘@q’ (see ATq) to turn off the line numbering for output code that is currently stable. In the following example, the code for each file is put into a module, then the modules are output in the unnamed section; it is assumed that the programmer is currently making changes to the code for file2.c:

@
@a
@q0
@o file1.c
        @<File 1@>@;
@q1
@o file2.c
        @<File 2@>@;
@q0
@o file3.c
        @<File 3@>@;

For very large projects, another solution is to maintain multiple web source files. To avoid losing the substantial benefits of the automatic index, refer to the discussion in Merging indexes to learn how to create a master index that contains information about several web files.