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.)
- 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.
- Next, set the language by including a command such as
@n
or
@c++
.
- Place an
@a
command (switch into unnamed code) before each
program unit (e.g., main program, subroutine, or function).
- Before each
@a
, place an @*
or command,
followed by TeX documentation about that particular section of code.
- 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@>=
.
- 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.)
- Beautify and clarify your documentation by using code mode
(enclosing stuff between vertical bars) liberally within your TeX.
- 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).
- 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.
- Scientific programmers may benefit from built-in macro-like functions
like
$PI
; see Built-in functions.
- 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.