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{}. Additional hints broken down by each supported
source language can be found in section LANGUAGES.
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 @ASP{} 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
@ASP{} 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. The `-nC' option (see section `-nC': Ignore single-line comments [FORTRAN]) may be helpful.
-
Learn how to use the GNU
info
browser to access the on-line
documentation.
-
Read the list of new features and changes for the last several
releases. See section NEW FEATURES.
-
Periodically check
ftp.pppl.gov:/pub/fweb/READ_ME
for bug
reports and other news. Make bug reports! See section SUPPORT.
-
If you have a color terminal, try the option `-C1' (see section `-C': Set the color mode,
see section Color output).
-
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.
-
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-person'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. 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 the 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.