Go to the first, previous, next, last section, table of contents.
In this section are collected various tips and suggestions to help one make
full use of 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 section Pseudo-operators).
-
Consider using FWEB's built-in macro preprocessor (see section MACROS and PREPROCESSING)
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 section 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.
This section will be enlarged in the future! Meanwhile, please feel
free to contact `krommes@princeton.edu' for help and advice, and to
suggest items to include here.
-
Read the list of new features and changes for the last several
releases. See section NEW FEATURES.
-
Read the FWEB FAQ, available on the World-Wide Web from
http://www.arsc.sunyit.edu/fwebdocs/fweb.html
(This may be out of date relative to the current release.)
-
Periodically check
ftp.pppl.gov:/pub/fweb/READ_ME
for bug
reports and other news. Make bug reports! See section SUPPORT.
-
Any option in `.fweb' that is intended to be processed after
the command-line options should begin with `&' rather than
`-'. (This is rarely necessary.)
See section Initialization
-
Put standard command-line options into `.fweb'. Also put there
standard style parameters--e.g.,
-pindex.tex "#.ndx"
-pmodules.tex "#.mds"
-pcontents.tex "#.cts"
-
Learn how to use the style file. See section The Style file.
-
Use the info options `-@', `-D', `-y', and `-Z'
to find out about various internal FWEB tables (control codes,
reserved words, memory allocations, and style-file parameters).
See section Information options.
-
Learn how to use the GNU info browser to access the on-line
documentation.
-
Begin all FWEB sources with invisible commentary
bracketed by `@z...@x'.
See section `@z': Begin ignorable material, or terminate change.
-
Always include an explicit language-setting command in the limbo
section. Under normal circumstances, do not set the language from the
command line.
See section LANGUAGES.
-
Keep sections quite short.
Knuth suggests a dozen lines. That's
quite hard to achieve sometimes, but almost never should a section be more
than a page long. If a block of code is longer than that, split it up
using named modules.
-
It's easy to define macros from the command line to expedite
conditional preprocessing.
See section `-m': Define FWEB macro (FTANGLE).
-
Use the preprocessor construction `@#if 0...@#endif' to
comment out unwanted code.
See section Preprocessing.
-
For logical operations with the preprocessor, use `||', not `|'.
-
It's conventional to identify the ends of long preprocessor
constructions as follows:
@#if A
.
.
@#endif // |A|
-
To debug an errant FWEB macro, use the built-in function
`$DUMPDEF'.
See section
$DUMPDEF
: Dump macro definitions to the terminal.
-
Use `@?' for compiler directives. See section `@?': Begin compiler directive.
Use the style-file parameters `cdir_start' to specify
information that will be written out at the beginning of the line.
See section
cdir_start
.
-
Stick to the standard FWEB commenting style `/*...*/' or
`//...'. Don't use alternatives such as FORTRAN's column 1
convention; these may not work or may not be supported someday.
See section COMMENTING STYLES.
-
The meta-comment feature `@(...@)' provides a poor-man's
alignment feature. But it doesn't work very well, and it's not in the
spirit of TeX; learn to use `\halign' or the LaTeX alternatives.
-
In FORTRAN, use `#:0' to declare readable alphabetic statement
labels. See section Special tokens and section `-:': Set starting automatic statement number.
-
When mixing languages, define the language of a module at the highest
possible level--e.g., in the unamed module, not after `@<...@>='.
-
Use LaTeX. Plain TeX is no longer supported. Upgrade to
LaTeX2e as soon as possible. See section LaTeX support.
-
If you are reading this documentation from printed pages, make sure it's
also installed as an Info package on your system so it can be read
interactively with
emacs
. You can also read it through a
World-Wide Web browser such as Netscape. For the address, see
section SUPPORT.
FWEB contains a few features particularly intended for scientific
programming.
-
Several built-in functions generate numerical constants. See `$PI'
(section
$PI
: Pi) and `$E' (section $E
: Base of natural logarithms).
-
Several built-in functions perform mathematical manipulations. See
`$EXP' (section
$EXP
: Exponential function), `$POW' (section $POW
: Exponentiation), `$SQRT'
(section $SQRT
: Square root), `$LOG' (section $LOG
: Natural logarithm), `$LOG10' (section $LOG10
: Logarithm to the base 10),
`$MAX' (section $MAX
: Maximum of a list), and `$MIN' (section $MIN
: Minimum).
-
The do-loop macro `$DO' may be useful. See section
$DO
: Macro do loop.
-
C-style array indices can be used by means of the `-n)' option.
See section `-n)': Reverse array indices [FORTRAN] (FTANGLE).
-
An active bracket feature helps improve the appearance of
woven code that uses subscripts and/or superscripts heavily. See section `-W[': Process bracketed array indices.
Go to the first, previous, next, last section, table of contents.