13.1 Converting an existing code to FWEB

To convert an existing code to FWEB, one should do the following. (The following simple procedure assumes that one puts all the subroutines into the unnamed module. However, other more elaborate schemes are possible.)

1. Place invisible commentary about the author, version, etc. at the beginning of the source file by bracketing it with ‘@z...@x’. The ‘@z’ must be the first two characters of the file.
2. Next, set the language by including a command such as ‘@n’ or ‘@c++’.
3. Place an ‘@a’ command (switch into unnamed code) before each program unit (e.g., main program, subroutine, or function).
4. Before each ‘@a’, place an ‘@*’ or ‘@ ’ command, followed by TeX documentation about that particular section of code.
5. If you have program units longer than about twelve lines, either make them function calls, if you can afford the overhead and can impart sufficient information via the function name, or break them up into shorter fragments by using named modules. Insert the command ‘@<Name of module@>’ in place of the fragment you’re replacing, then put that fragment somewhere else, prefaced by ‘@ ’ and ‘@<Name of module@>=’.
6. Make sure your comments are valid TeX. (One can’t have things like raw underscores or dollar signs in comments, since those cause TeX to take special actions.)
7. Beautify and clarify your documentation by using code mode (enclosing stuff between vertical bars) liberally within your TeX.
8. After you’ve seen the woven output, you may need to go back and format a few identifiers or section names so that FWEAVE understands them properly, or you may need to insert some pseudo-semicolons (‘@;’), pseudo-expressions (‘@e’), or pseudo-colons (‘@:’) (see Pseudo-operators).
9. Consider using FWEB’s built-in macro preprocessor (see Macros) to make your code more readable—for example, replace raw numerical constants by symbolic names.
10. Scientific programmers may benefit from built-in macro-like functions like $PI; see Built-in functions.
11. If you are a FORTRAN user, for ultimate readability consider converting to RATFOR. The initial annoyance is getting rid of column-6 continuations. With the aid of a good editor, this can be done simply. For example, in emacs one can replace the regular expression [carriage return, five spaces, something not equal to space, tab, or 0] with [backslash, carriage return, six spaces]:

    M-x replace-regexp RET
    C-q C-j \.{\ \ \ \ \ }[\^\.\ tab 0]RET
    \\\\ C-q C-j \.{\ \ \ \ \ \ }RET
    

    Get rid of the keywords such as then or end if in favor of braces. Change singly-quoted character strings to doubly-quoted ones. The ‘-nC’ option (see -nC) may be helpful.