@FWEB{} has the ability to work with more than one source language during a single run. The language in effect at the beginning of the first section defines the global language. Further language changes within a section have scope local to that section.
Usually, `language' means a compiler language like FORTRAN or C. These languages will be "pretty-printed" by @FWEAVE{}. Pretty-printing can be inhibited by turning on the N mode (globally, with the command-line option `-N'; locally, with `@N') or by selecting the VERBATIM `language'; in both of these cases, the input text is echoed literally to the output of both @FTANGLE{} and @FWEAVE{}.
`Language' is a stronger concept than `mode'. For example, when a language is selected, the extension of the tangled output file is changed appropriately--for example, if `test.web' contains C code (that is, contains the command `@c'), `test.web' tangles into `test.c' (compressing blanks and otherwise (deliberately) making the tangled output relatively unreadable) and @FWEAVE{} pretty-prints using the C syntax. Turning on the N mode does not affect the language; @FTANGLE{} copies the source code literally into `test.c' (no blank compression or other modifications), and @FWEAVE{} typesets the source code within a verbatim environment (no pretty-printing). When the VERBATIM language is selected, the N mode is turned on automatically, but @FTANGLE{} writes its output to a file with a special default extension that can be customized in the style file. See section Miscellaneous style-file parameters.
The most general form of a language command is
@[L]ltext[options]
where l is a language symbol, text is converted into the option `-ltext', and options have the same syntax as on the command line.
The language symbols must be in lower case; they are
C c
C++ c++
Fortran-77 n
Fortran-90 n9
Ratfor-77 r
Ratfor-90 r9
TeX x
VERBATIM v
An example of a command with the optional text field is `@n/'. By definition, this is equivalent to `@n[-n/]'. Thus, it both sets the language and invokes a command-line option.
As another example, `@n9' really means `@n[-n9]'. Thus the language is first set to FORTRAN, then reset to FORTRAN-90. One doesn't need to worry about this detail.
@n9[-n&]means set the language to FORTRAN--90 and use free-form syntax with the ampersand as the continuation character. (This construction is now @FWEB{}'s default.)
The brackets may contain more than one space-delimited option.
A language command should appear somewhere in limbo, before the start of the first section. The language in effect at the beginning of the first section defines the global language. For historical reasons, the default language is FORTRAN-77, but do not rely on this; always include a language command.
Language commands may be used within sections, but the new language remains in force only for that section. The language of a named module is inherited from the language in effect at the time the name is first used. Thus, in the following example, the global language is FORTRAN--77, but an arbitrary number of C functions can be placed into a C-language module with just one `@c' language-changing command.
@n @ @a program main end @c @<C@>@; @ @<C@>= int fcn() {}@FTANGLE{} will write two output files for this example--e.g., `test.f' and `test.c'. Particularly note that one did not need an `@c' command in the last section because the language was C when `@<C@>' was first encountered.
Special hints and considerations for each language
One important thing to keep in mind is that in @FWEB{} an identifier may have, for each language, precisely one meaning throughout the document. This restriction is not necessarily in accord with the syntaxes of the various source languages. See, for example, the discussions in section Special considerations for C++ and section Special considerations for FORTRAN.
Special considerations for C
- @FTANGLE{} treats the construction `0b...' as a binary notation that it expands to an unsigned decimal number. Thus, `0b101' expands to 5 and `0b1111111111111111' expands to 65535.
- @FWEAVE{} processes typedef statements during phase one, so they will format properly even if they are used in a documentation part before they are defined in a code part.
- The `-H' option helps one to deal with identifiers defined in header files. See section `-H': Scan C/C++ include files (@FWEAVE{}).
- Note that in C structure and enum tags do not define a new type, so the tag name does not get highlighted in boldface, underlined in the index, etc. (That is, if one says `struct S {...};', one can't say `S s;', one must say `struct S s;'.) This is a good reason for using C++, where such tags do define a new type.
(To be completed.)
Special considerations for C++
- All of the items in the previous section (see section Special considerations for C) still apply.
- The `@{' command is very useful for beautifying very short definitions of member functions such as constructors. See section Special left brace
- Essentially, @FWEAVE{} has only one name space, global to the entire code; those names do not obey any concept of scope. In various situations in C and C++, however, multiple namespaces are used, or the interpretation of a name changes according to its scope. Thus, the design of @FWEAVE{} imposes a few restrictions on one's programming style. (Remember, @FWEAVE{} doesn't know nearly as much as a language compiler.) One example in C++ has to do with formal types in templates. Consider the following example:
template <class Type> class A { private: Type *p; }In order that the class definition be typeset correctly, `Type' must be understood to be a reserved word like int, and that is correctly figured out by the first class command. However, according to C++, the scope of `Type' is local to the class definition; unfortunately, @FWEAVE{} does not respect that locality and will always treat `Type' as an int from the point of the `class Type' construction to the end of the source code. Thus, one should use such dummy variables as `Type' only as formal template parameters, never as ordinary variables.Special considerations for FORTRAN
Items for both FORTRAN-77 and FORTRAN-90
- @FTANGLE{} will translate into unsigned decimal numbers the binary notation `0b...', the octal notation `0...', and the hexadecimal notation `0x...'. Thus, `0b101' expands to 5, `0101' expands to 65, and `0x101' expands to 257.
- Don't use the column 1 `C' commenting convention. Use `/* ... */' or `// ...'.
- For compiler directives, use `@?' (see section `@?': Begin compiler directive), not a `C' in column 1.
- If you are going to use the recommended `// ...' convention for short comments, you must say `@n/' (see section `-n/': Recognize short comments [FORTRAN]) or `@n9[-n/]' as your language command. Otherwise, \FWEB\ will treat the `//' as \FORTRAN'S standard token for concatenation. (You may always use `\/' for concatenation.)
- If you want to completely comment out a whole block of code, use the preprocessor construction `@#if 0...@#endif' (see section Preprocessing). Don't put a comment character at the beginning of each line; that prevents @FWEAVE{} from formatting the code sensibly and can be annoying to undo. With the preprocessor form, one can also implement conditional comments by using @FWEB{} preprocessor macros: e.g., `@#if(DEBUG)...@#endif'. Pre-@FWEB{} codes may have such blocks commented out with a `C' in column 1. Those should be converted to the preprocessor construction. However, if you're in a real hurry, temporarily use the `-nC' option (see section `-nC': Ignore single-line comments [FORTRAN]) to kill those lines very early in the processing, before they can give you all kinds of trouble.
- An unfortunate byproduct of using `//' for short comments is that, in general, format constructions like
format(//)
won't work. (It will work if one uses `-nC'; see section `-nC': Ignore single-line comments [FORTRAN].) Alternatively, one can sayformat(/ /)
.- Consecutive lines commented out with a `C', `c', `*', or `!' in column 1 are converted into a single comment before processing by @FWEB{}. Large blocks of such lines (common in pre-@FWEB{} code) may overflow @FWEB{}'s tables. To avoid that, insert blank lines between some of the comments. Better, however, is to move most such blocks out of the code part to the TeX part of the section. It's most readable to have only a few very short comments interspersed in the code. To help with conversion of existing codes, the command-line option `-nC' can be used to completely ignore comment lines.
- `@' commands should, by and large, start in column 1. That's not necessary for short module names that fit on one line. However, a long module name that must be broken across lines must begin in column 1, as in
@n @ @a @<This is a module name broken across lines@>@;Failure to do this results in a spurious semicolon being inserted in the middle of the name. This happens because the FORTRAN-77 input driver does various low-level manipulations of the source before it presents it to the innards of @FWEB{}; it's not tokenizing the source at that time and doesn't understand all of the @FWEB{} syntax such as module names.- Define symbolic statement labels with `#:0' (see section Special tokens). Such names should be followed by a colon. Thus,
@n @ @m EXIT #:0 @m ABORT #:0 @a . . ABORT: continue . . EXIT: continue . .- By default, statement labels are
\llap
'd from the body of the statement. With this convention, long labels can extend too far into the left margin. Instead, try the command-line option `-n:' (see section `-n:': Put statement label on separate line [FORTRAN]), which puts them on a separate line. Alternatively, one can redefine the macro\Wlbl
, found with some discussion in `fwebmac.sty'.- As a suggestion, use upper case for I/O keywords such as
IOSTAT
. However, by default the lower-case forms are also recognized. To permit only upper case, use `-k' (see section `-k': Don't recognize lower-case forms of keywords). Note that although there is a command `-nk', it is unfortunately not related to `-k'.- One may use `^' as an alternative for the exponentiation operator `**'.
- @FWEB{} attempts to be helpful and tries to expand the operators `++', `--', `+=', `-=', `*=', and `/=' in a way compatible with the usage in C and C++. For example, it expands `x += y' into `x = x + (y)'. This feature can be a great time-saver and also makes the code substantially more legible; it is strongly recommended. To turn off this feature, use the option `-+'. See section `-+': Don't interpret compound assignment operators. Notice that in FORTRAN-90 `/=' is a token for "not equal," so if you want to use that you must use the `-+' option. However, a better solution is to use `!=', @FWEB{}'s preferred operator for "not equal."
- By default, the operators
.true.
and.false.
will weave as caligraphic T and F. That appearance be changed by redefining the macros\WTRUE
and\WFALSE
in `fwebmac.sty' or in the limbo section of your source file.- If @FTANGLE{} messes up and outputs incorrect FORTRAN code, try tangling with the command-line option `-#' (see section `-#': Turn off comments about line and section numbers (@FTANGLE{})) (and then report the problem.)
Items specific to FORTRAN-77 and fixed-form FORTRAN-90
- By default, when processing the code part the FORTRAN driver inserts semicolons automatically at the end of each logical statement. Thus, the core of @FWEB{} is presented with a uniform syntax. However, when one escapes into code mode by using vertical bars, those semicolons aren't inserted, so something that appears a first glance to be complete statement may not be formatted as one might expect. Thus, the construction `|5: continue|' doesn't format quite properly (the colon disappears); this problem is solved by putting a semicolon after the `continue'. Also, if one is talking about multiple statements (for example, with a shift into code mode during TeX documentation), there's no choice but to insert the semicolon between statements. For example, `|a = b; c = d;|'.
Items specific to FORTRAN-90
- If FORTRAN-90 is selected (see section `-n9': Set global language to FORTRAN--90), the default is free-form syntax (lines are continued by a trailing ampersand). However, automatic line breaking is done in a way compatible with fixed-form syntax as well.
- With free-form syntax, comment lines in the tangled output file begin with `!'. But such lines are not recognized on input unless `-n!' is used. See section `-n!': Make `!' denote short comment [FORTRAN].
- Beginning with Version 1.61, by default (pseudo-)semicolons are automatically inserted in free-form \Fortran-90 code, as one would expect. For more discussion, see section `-n@;': Supply automatic pseudo-semicolons [FORTRAN] and section `-n;': Supply automatic semicolons [FORTRAN].
(To be completed.)
Special considerations for RATFOR
For some warnings about RATFOR, see section Caveats about RATFOR.
Special considerations for TeX
`@Lx' is supported only to the extent that
fwebmac.sty
can be generated correctly fromfwebmac.web
. You are welcome to experiment, but you may encounter difficulties (which you should report; see section SUPPORT).(To be completed.)
Special considerations for the VERBATIM language
Unfortunately, the VERBATIM language is not fully debugged. Therefore, it is not recommended for general use. (To be completed.)
Go to the first, previous, next, last section, table of contents.