Go to the first, previous, next, last section, table of contents.


USAGE TIPS and SUGGESTIONS

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.

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 @ASP{} 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 @ASP{} 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 section Pseudo-operators).
  9. 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.
  10. Scientific programmers may benefit from built-in macro-like functions like $PI; see section 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 section `-nC': Ignore single-line comments [FORTRAN]) may be helpful.

Programming tips and other suggestions

  1. Learn how to use the GNU info browser to access the on-line documentation.
  2. Read the list of new features and changes for the last several releases. See section NEW FEATURES.
  3. Periodically check ftp.pppl.gov:/pub/fweb/READ_ME for bug reports and other news. Make bug reports! See section SUPPORT.
  4. If you have a color terminal, try the option `-C1' (see section `-C': Set the color mode, see section Color output).
  5. 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
  6. Put standard command-line options into `.fweb'. Also put there standard style parameters--e.g.,
    -pindex.tex "#.ndx"
    -pmodules.tex "#.mds"
    -pcontents.tex "#.cts"
    
  7. Learn how to use the style file. See section The Style file.
  8. 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.
  9. Begin all @FWEB{} sources with invisible commentary bracketed by `@z...@x'. See section `@z': Begin ignorable material, or terminate change.
  10. 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.
  11. 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.
  12. It's easy to define macros from the command line to expedite conditional preprocessing. See section `-m': Define @FWEB{} macro (@FTANGLE{}).
  13. Use the preprocessor construction `@#if 0...@#endif' to comment out unwanted code. See section Preprocessing.
  14. For logical operations with the preprocessor, use `||', not `|'.
  15. It's conventional to identify the ends of long preprocessor constructions as follows:
    @#if A
    .
    .
    @#endif // |A|
    
  16. To debug an errant @FWEB{} macro, use the built-in function `$DUMPDEF'. See section $DUMPDEF: Dump macro definitions to the terminal.
  17. 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.
  18. 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.
  19. 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.
  20. In FORTRAN, use `#:0' to declare readable alphabetic statement labels. See section Special tokens and section `-:': Set starting automatic statement number.
  21. When mixing languages, define the language of a module at the highest possible level--e.g., in the unamed module, not after `@<...@>='.
  22. Use LaTeX. Plain TeX is no longer supported. Upgrade to LaTeX2e. See section LaTeX support.
  23. 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.

Features for scientific programming

@FWEB{} contains a few features particularly intended for scientific programming.

  1. Several built-in functions generate numerical constants. See `$PI' (section $PI: Pi) and `$E' (section $E: Base of the natural logarithms).
  2. 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).
  3. The do-loop macro `$DO' may be useful. See section $DO: Macro do loop.
  4. C-style array indices can be used by means of the `-n)' option. See section `-n)': Reverse array indices [FORTRAN] (@FTANGLE{}).
  5. 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.