For C or C++, the ‘-H’ option tells FWEAVE to do a phase-1 scan
of #include files for ‘typedef’ and/or ‘class’
declarations. This removes the necessity of including many redundant
‘@f’ format statements (see ATf), which would otherwise be
necessary in order that the code be pretty-printed correctly. For
example, if one uses the ‘-H’ option with the code
@c++ @ #include <Complex.h> Complex z;
the identifier Complex will be properly formatted as a reserved word (in boldface), as though one had said ‘@f Complex int’.
In addition to the basic ‘-H’, there are several more detailed options:
-HxMake index entries only for double-quoted include files.
-HXMake index entries for all include files.
-HrRetain temporary files generated by the preprocessor.
By default, index entries are not made for variables that are read during such scans. If one says ‘-Hx’, index entries will be made only for include files whose names are enclosed in double quotes rather than angle brackets, such as ‘#include "myheader.h"’ (usually these are defined by the user and reside in the local directory). If one says ‘-HX’, index entries will be made for all include files. This can generate many entries, since system header files may be complicated and may include other files as well.
This command is implemented as follows. When FWEAVE reads an
#include statement, it issues a system command to run the
C preprocessor on the included file. Output from the preprocessor is
written to a temporary file, which FWEAVE scans.
By default, the C preprocessor will look in certain default paths for
the included files. To add to those defaults, use one or more ‘-I’
options after the ‘-H’. These colon-delimited lists are
concatenated to the contents of the environment variable
FWEB_HDR_INCLUDES, if that is defined. The entire list is then
passed as multiple ‘-I’ options to the preprocessor.
This command, new with version 1.53, is highly experimental and
incomplete. The installation script attempts to determine what command
to use to run the preprocessor, but that is not guaranteed to work in
general. ‘-H’ has been tested only with gcc.
To send arguments to the C preprocessor, see -WH_.
The ‘-H’ mechanism uses temporary files to do its work. By default, those are deleted after use. However, for debugging purposes, one can force those to be retained by saying ‘-Hr’. That option also has the side effect of displaying the actual command line that was sent to the preprocessor.