Home

The FWEB user manual

1. If a command is used by neither processor its description will be replaced by a question mark 4 2 5 A Turn on ASCII translations This option is used primarily for debugging FWEB works internally with the ASCII character set If FWEB is run on a non ASCII machine notably IBM mainframes transla tions to and from the internal ASCII are done automatically on an ASCII machine these translations are unnecessary and are not performed unless the A option is used 4 2 6 B Turn off audible beeps F WEB sometimes beeps the terminal when it encounters certain errors The B option turns off the beeps replacing them by a printed exclamation point This option is sometimes called the marriage saver after the situation that prompted a user s request for this feature 4 2 7 b Number blocks FWEAVE Number do and if blocks in woven FORTRAN and RATFOR output This feature is particularly useful in FORTRAN 77 to help correlate the beginnings and ends of long blocks but note that appropriate use of literate programming techniques can keep all of one s blocks short Output something like the following is produced where the comments are inserted automatically by the b option do i 1 10 Block 1 do j 1 10 Block 2 if i j then Block 3 call subi i else Block 3 call sub2 i j endif Block 3 end do Block 2 end do Block 1 The precise form of the block comme
2. 113 12 3 1 1 index aaa 113 12 3 1 2 delim EE EE Ge Ge ee ee 113 12 3 1 3 group skip sesse esse eks ee kk ee 114 12 3 1 4 item OO EE nens 114 12 3 1 5 language PP e eee eee 114 12 3 1 6 lethead Ee eee ee 114 12 3 1 7 underline esses ss 114 12 3 2 Customizing the module list 114 12 3 3 Customizing the Table of Contents 114 12 3 4 Customizing cross reference subscripts 114 12 3 5 Customizing the behavior of fwebmac sty macros teh hehehe hh hehehe hh ehe 115 12 3 5 1 format esee sess 115 12 8 5 2 indent lesse essen 116 12 3 5 3 LaTeX eese eee 116 12 3 6 Remapping control codes ss EE see 116 12 3 7 Color output iss EE EE EG eee eee eee 117 12 3 8 Miscellaneous style file parameters 118 12 3 8 1 ASCII_LFen ce eee eee ee eee 118 12 3 8 2 cchar cee eee 118 12 3 8 3 cdir start esses 118 12 3 8 4 line char l FTANGLE 119 12 8 8 5 line length l FTANGLE 119 12 3 8 6 meta 77 7 meta 7 hdr FTANGLE MEE 119 12 3 8 7 outer eee 119 12 3 8 8 protect esses ee 119 12 3 8 9 suffix sese esses 119 12 3 8 10 macros s esses ene 119 12 3 8 11 limbo begin limbo end 120 12 3 8 12 meta FWEAVE 120 12 3 8 13 preamble eee
3. 68 7 2 3 9 DATE TIME Value of RCS global keyword Date cc centres 68 vii 7 2 3 10 DAY Theday 68 7 2 8 11 DECR Decrement a macro 69 7 2 8 12 DEFINE Deferred macro definition 69 7 2 8 13 D0 Macro do loop 69 7 23 14 DUMPDEF Dump macro definitions to the terminal 70 7 2 3 15 E Base of the natural logarithms 70 7 2 3 16 ERROR Send error message to output MEME 70 7 2 8 17 EVAL Evaluate a macro expression 70 7 2 3 18 EXP Exponential function 71 7 2 8 19 GETENV Get value of environment Variable 71 7 2 3 20 HEADER Value of RCS global keyword Header eee ke ge ke ke ke ke ee 71 7 2 8 21 HOME The user s home directory 71 7 2 3 22 ID Value of RCS global keyword Id 71 7 2 8 23 IF Two way conditional 71 7 23 24 SIFCASE n way conditional 71 7 2 8 25 IFDEF Two way conditional 72 7 2 8 26 IFNDEF Two way conditional 72 7 2 8 27 IFELSE Two way conditional 72 7 2 3 28 SINCR Increment a macro 72 7 2 3 29 SINPUT LINE Line number that begins current section aan T2 72 330 KEYWORD Value of global RCS like keyword 72 72 331 L Change to lower case 73 7 23 32 L KEYWORD Value of local RCS like keyword 73 72 333 SLANGUAGE Identifier for current language DNE T4 7 2 8 34 SLANGUAGE NUM Number of current language
4. 39 Suggesti0Ns cece eee eee 122 Support ehh 131 Syntax command lme ees ss ee de 15 Syntax free form ees Es cece ss sk 26 88 T Table of Contents aaa 96 Table of contents entries OP 39 Tags ENUM 1 teen hn 84 Tags structure 84 TEX hints ee ee SG RA I 88 Text control 0 00 cece ne 55 TIME sssssssse hn 68 77 Tokens upper case ssssssssss nne 32 Transliteration is ee SS eee eee eee 78 Typesetting ie naaa 91 U Unnamed module 0 0 eee eee 8 Upper case oon 78 User packages anan aaa 93 V Variable arguments sis aaa 64 Variables environment 0000 107 Version number aaa 32 Version of FWEB 0 eee 78 Vertical bar 39 56 Vertical bars 0 SG ge ee ed ge ee es se 7 W Warning level for modules 32 Web structure 5 Words reserved a 18 Option and command index 137 Option and command index line cette 79 AE nennen 76 EE sehen 76 RR aba nrnna abaka nrnna 76 BALEA EEEIEE g ROSFile esse ne ee nene 76 ABS sis 68 REVISION 0 0 0 0 ccc cece eee ene e ete e nee 76 SASSERT sss 68 SROUTINE 222220000 77 AUTHOR 22222020 b ee ee ee Ge ee Ge eg ee es ee 68 SSECTION NUM eese ene enne nnns di COMMENT esl 68 SECTIONS c cece cece cence en 77 DATE ess 68 SOURCE ee ee ha 77 DATE TIME sss 68 ET essen 77 DAY ce sss 68 STATE 2223
5. ee ee ee ee ee 129 Features version 1 50 ee ee ee ee ee ee 128 Features version 1 52 ee ee ee ee ee ee ee 127 Features version 1 58 ee Ge ccc ee ee ee 126 Features version 1 61 ee ee ee ee ee ee 125 File including web SE ge ee ei 43 44 File initialization 0 aa 108 File opening output 47 File RES EG cece eg ee eee 76 File style ee ee ccc ccc ee ee ee ee ee ee 112 File name completion eee ee 12 Files Imm 12 Files change EG SG GE eee eens 13 Files EE cece enn ees 12 Files output 13 ao hen 92 Formatting hne 91 FORTRAN hints 2 ee ee Ee ee ee eese 85 FORTRAN Rational iss ss ee ee ee ee esee 89 Functions built in 66 Functions intrinsic 00 cece eee eee eee ee 18 FWEB output inserting into LaTeX document DE 99 FWEB customizing 00 en 107 FWEB initializing ds se eee eee ae 108 H EER cence n 71 Header comments printing 31 Headers eee n 98 Hexadecimal notation seeeee essere 85 Hints Co aaa 84 Hints C oo ee se an 85 Hints FORTRAN 2 2220 85 Hints TEX 88 I I O keywords 0 0 ccc cece Ge ene ee 18 Identification 71 Identifier formatting a 42 Identifiers overloading 50 102 Identifiers single character 04 33 Identifiers truncating 00 eee ee 32 134 Include file
6. 90 9 3 Caveats about RATFOR aaaa eee hn 90 10 DOCUMENTATION 91 10 1 Typesetting cece Hmmm 91 10 1 1 FwEAVE s OUTPUT 22220 00 91 10 1 2 The macro package fwebmac sty 92 10 1 2 1 User Macros EE ee e ee ee eee 92 10 1 2 2 Fonts ee eee 92 10 1 3 La TEX support EE a 93 10 1 3 1 LaT X s document class 93 10 1 3 2 Using REVTEX 94 10 1 3 3 La TpX packages related to FWEB 95 10 1 3 4 Sections in La TEX 95 10 1 3 5 LaT X s index ss Ee Ge ee ee 96 10 1 3 6 LaT X s Table of Contents 96 10 1 3 7 Customizing La TEX s output 97 10 1 4 Page references 0 aaa 98 10 1 5 Page headers eee ee ee en 98 10 1 6 Section numbering schemes 98 10 1 6 1 Package fwebinsert Inserting FWEAVE s output into a La TEX document 99 10 2 Pretty printing EG SE Ge mmm 100 10 2 1 Pseudo operators iss ss EE SG ee kk ee eee 101 10 2 2 Alternatives for various input tokens 101 10 2 3 Overloading operators and identifiers 101 10 2 3 1 Overloading operators 101 10 2 3 2 Overloading identifiers 102 11 FWEB s INDEX osse sees se see eee 103 11 1 FWEB s self generated index ses a 103 11 2 Creating a stand alone index with makeindex 103 11 2 1 Creating a stand alone index
7. However in RATFOR the denotes concatenation by default To make it denote a short comment use the r option For concatenation use For an example see Section 4 2 40 n page 27 4 2 56 r Make denote short comment RATFOR See the corresponding discussion of in Section 4 2 81 page 37 and Section 4 2 41 n page 27 In FORTRAN 77 to include the exclamation point inside a string escape it with a back slash as in s A inside a string 4 2 57 r Reverse array indices RATFOR FTANGLE See the corresponding discussion of n in Section 4 2 42 n page 27 4 2 58 s Print statistics s prints statistics about memory usage at the end of the run sm prints statistics about memory usage at the end of the run just as does s it also prints information about dynamic memory allocations as they occur smnnn displays allocations of nnn bytes or more if nnn is missing 10000 is assumed Chapter 4 RUNNING FWEB 31 4 2 59 T Flag setting options for FTANGLE This is a family of options that set miscellaneous flags appropriate only for FTANGLE 4 2 59 1 TD Permit processing of deferred macro definitions Deferred macro definitions are m or equivalently define commands that appear in the code part rather than the usual definition part These definitions are evaluated during the output
8. as in m PI 3 14159 That is called protecting the macro FWEB s built in functions and macros beginning with are protected by default see Section 7 2 3 2 Protection page 67 To override that protection use the command line options Tb Section 4 2 59 2 Tb page 31 for built in functions or Tm Section 4 2 59 3 Tm page 31 for macros 7 2 2 Special tokens The following special tokens may be used in the text of FWEB macro definitions 7 2 2 1 ANSI C compatible tokens Paste tokens on either side to form a new identifier parameter Convert parameter to string without expansion For example m FORTRAN type name type _ name m TRACE where puts At where a FORTRAN int fcalc Expands to inty_fcalc TRACE predictor Expands to puts Aty predictor 7 2 2 2 Extensions to ANSI C macro syntax The most frequently used extensions are the following ones associated with variable arguments 0 n and FORTRAN 77 users should also employ 0 to allow sym bolic rather than numeric statement labels Try not to use the other extensions they are experimental complicated and unlikely to work in all situations In the following list the forms n and n may not work correctly in complicated situations This is a design deficiency that may be corrected someday param Like parameter but pass a quoted
9. atb cd a 4 Hot and amp amp AD 3 These same conventions are allowed in RATFOR mode Note that in FORTRAN and RATFOR is interpreted by default as the concatenation symbol not the start of a short comment To override that default use one of the command line options n r or or use a language changing command of the form n 10 2 3 Overloading operators and identifiers For special effects in the woven output there are commands to help one change the appearance of operators and identifiers 10 2 3 1 Overloading operators A feature common to both C and FORTRAN 90 is operator overloading the ability to extend or redefine the definition of an operator such as FALSE or FORTRAN 90 even allows one to define new dot operators for example one might define the operator IN to test for inclusion in a set In a nontrivial extension of the original design FWEAVE allows one to define how overloaded operators should appear on output For example in the opinion of the author it is much more readable to read if z set than if x IN set Indeed this feature can be used even when the compiler language itself does not permit overloading in order to customize the appearance of the woven output The v control code is used to change the appearance of an operator The format is Chapter 10 DOCUMENTATION 102 v new operator symbol or name T
10. f option see Section 4 2 16 f page 20 Discussion to be completed 12 3 5 Customizing the behavior of fwebmac sty macros To some extent the behavior of FWEB s macro package fwebmac sty can be changed by means of the following parameters Please try not to actually edit fwebmac sty itself it is produced automatically from fwebmac web And please don t edit that file either 12 3 5 1 format The format parameters are strings that specify the macro to be used to pretty print var ious kinds of identifiers These macro names are usually written automatically by FWEAVE but they may also be used directly by the user in the TEX documentation One can see their default values by typing ftangle Zformat For example the default value for format typewriter is The macro names defined by the format fields are not defined in fwebmac sty They are dummy names and can be changed to any other name not already in use without affecting the operation of FWEB This ability is necessary because other packages might usurp macros like for their own purposes Thus FWEAVE normally writes out the macro N to typeset a string Suppose however that some user package uses for something else One might realize this when LATEX crashes when it encounteres a V that was written automatically by FWEAVE To fix this problem put into fweb sty the lines format KEYWORD WTT format ke
11. means of the H command which tells FWEAVE to scan include files automatically See Section 4 2 17 H_ page 20 The old_identifier may be one of the following special names which insert extra spaces according to the positions of the underscores and behave as the part of speech indicated by the base names Chapter 5 FwEB COMMANDS 43 _BINOP_ _COMMA_ _EXPR _EXPR_ EXPR_ UNOP _ These are useful for dealing with certain macro constructions For example f PLUS _BINOP_ m PLUS m ADD x y x PLUS y Without the format command the ADD macro will pretty print without spaces before and after the PLUS When the current language is TEX the format command can be used to change a category code according to the format 0f TeXchar new cat code Difficulties may ensue if one try to change the category code of in this way a fully operational WEB for TEX is quite difficult and has been neither accomplished nor attempted 5 5 9 i Include file unconditional If one says Qi test hweb the file test hweb is inserted at the present point of the web file By default the current directory is searched Files can be included from other directories by means of the FWEB_ INCLUDES environment variable and or the I command line option See Section 12 1 Environment variables page 107 and Section 4 2 19 L page 21 In principle the included file may contain any fragment of sou
12. should become a thing of the past Since sections can be combined into modules there is no need for sections that must be physically contiguous in the output file to be contiguous in the source file This allows for great flexibility in structuring the documentation of the code 2 2 0 1 A simple example A simple example of an FWEB source file consisting of three sections is as follows n 4 Set FWEB language to Fortran and recognize short comments Titlefexample web Title is an FWEB TeX macro author J A Krommes author is a LaTeX macro Q INTRODUCTION This code is intended to illustrate the use of the write statement It also provides a simple example of the FWEB macro preprocessor m A_CONSTANT 1 2345 FWEB preprocessor macro definition Qa program main call compute end The computational routine is pretty boring Qa subroutine compute write Macro value A CONSTANT end INDEX Commands to FWEB are begun by the symbol see Chapter 5 AT commands page 38 In this example the first command n sets the global language to FORTRAN 77 One should always begin one s code with a language setting command In this example the language command is invoked with an optional argument That is necessary in FORTRAN in order to tell FWEB to use the short single line comment form beginning with which otherwise conflicts with the concatenation operator Se
13. test ch In addition to x y and z the only commands allowed in a change file are language changing commands such as c and the special commands and The command is used for column oriented languages such as FORTRAN 77 and means switch into code mode Similarly means switch out of code mode All commands in a change file must begin in column 1 Lines not beginning with are ignored so may be used as comments Comments may also be included on the x y and or z lines Chapter 4 RUNNING FWEB 15 4 RUNNING FWEB FWEB has a UNIX style command line syntax There are many command line options but few or none of these are necessary for standard appplications Proceed in blissful ignorance until you need to do something tricky then scan the list of options to see if they can help Commonly used command line options can be placed into the initialization file fweb see Section 4 2 Options page 15 that resides in one s home directory A style file patterned after the utility makeindex see Section 12 3 Style page 112 can be associated with each manuscript or collection of related manuscripts in order to customize their appearance This file is read after the command line options are processed except that the p option gets special treatment see Section 4 2 46 p page 28 4 1 Command line syntax The comma
14. where the level may be 0 least verbose through 4 most verbose the default as described in the following table 0 Like level 1 but the start up banner is not printed If FWEB runs to completion with no errors nothing at all will be printed 1 Print only error messages Print error and warning messages Print errors warnings and short information messages excluding starred section numbers and line numbers 4 Print everything The start up banner which includes the version number is printed for all message levels except 0 For level 0 one can use the V option to request the start up banner See Section 4 2 63 V_ page 32 This option is very recent and may not be fully debugged for obscure combinations of command line options Please report any annoyances Another way of discriminating message types is via color output See Section 12 3 7 Color page 117 4 2 27 m Define FwEB macro FTANGLE The command line construction mA x x defines the FWEB macro A as though the definition m A x x had appeared in the first definition part of the web file One can also say m A x x where the quotes are removed by the shell That is an appearing immediately after the macro name or argument list if there is one plays the role of the space in the conventional definition Thus carefully distinguish the forms m A x x A x expands to x m A x x A x expands to x m A
15. Chapter 10 DOCUMENTATION 92 10 1 2 The macro package fwebmac sty FWEAVE works in conjunction with the macro package fwebmac sty which is always read into the tex file by default This file is overly complicated so one should not mess with it unless in dire emergency Most of its commands are intended for behind the scenes processing However some features may be of general interest these are described in the items below For the most part macros used internally by fwebmac sty begin with an uppercase W If you are worried about macro conflicts a complete list of the macros appearing in fwebmac sty can be found in the Index produced by weaving fwebmac web 10 1 2 1 User macros For the user s convenience fwebmac sty defines a variety of macros such as FWEB Fortran etc Refer to fwebmac web for a complete list FWEAVE usurps various common single character macros such as for its own pur poses So the user can still access their original definitions those are let equal to alternative commands such as period For example commands such as the following are executed in fwebmac sty let amp amp let at oe let bslash let caret let dollar let dstar let equals let leftbrace let period let rightbrace let vertbar let PM Met NPOV Some of the more inscrutable synonyms are for historical reasons For
16. For more discussion of such keywords see Section 5 5 31 ATz page 50 The command is treated differently by FTANGLE and FWEAVE depending on its location in the source file FWEAVE will expand the construction in the limbo section and TEX parts only The value is not surrounded by quotes For example Oz Id test Ox Qc def ID Id K Id gt ID This is a K Id gt will expand into c ID This is a test and when LaTEX is run the macro MID will expand to Id Test The quotes are not necessary in the macro definition they are included only to emphasize that in this limbo context the K construction can effectively be put inside a string This is possible because the routine that copies the limbo section simply copies characters it does not tokenize anything FWEAVE does not expand K constructions in the definition or code parts it merely gives them a symbolic representation F TANGLE on the other hand expands K constructions in the definition or code parts during input The values are surrounded by quotes As usual FTANGLE ignores material in the limbo section and TEX parts For FTANGLE the built in function KEYWORD see Section 7 2 3 30 SKEYWORD page 72 behaves essentially as does K except that it is expanded during output not input FWEAVE does not expand KEYWORD The command k behaves as does K except that it accesses local ke
17. as an int from the point of the class Type construction to the end of the source code Thus one should use such dummy variables as Type only as formal template parameters never as ordinary variables 8 2 3 Special considerations for FORTRAN 8 2 3 1 Items for both FORTRAN 77 and FORTRAN 90 e FTANGLE will translate into unsigned decimal numbers the binary notation Ob the octal notation O and the hexadecimal notation Ox Thus Ob101 expands to 5 0101 expands to 65 and Ox101 expands to 257 e Don t use the column 1 C commenting convention Use or e For compiler directives use see Section 5 8 4 AT page 53 not a C in column 1 e If you are going to use the recommended convention for short comments you must say n see Section 4 2 40 n page 27 or n9 n as your language command Otherwise FWEB will treat the as FORTRAN S standard token for concatenation You may always use for concatenation bj Chapter 8 LANGUAGES 86 e If you want to completely comment out a whole block of code use the preprocessor construction if O endif see Section 7 3 Preprocessing page 80 Don t put a comment character at the beginning of each line that prevents FWEAVE from formatting the code sensibly and can be annoying to undo With the preprocessor form one can also impl
18. c ch 4 SP 3 4 This option is controlled by the three style file parameters paren len paren num and paren nest See Section 12 3 Style page 112 paren len is the default number of bytes to be allocated for each index if an index is longer than this number the current length is increased by this number and storage is automatically reallocated paren num is the maximum number of allowed indices for example when processing a i j k paren num is 3 paren nest is the maximum parenthesis nesting level In the example x a i Cj C paren nest is 2 If either of the last two parameters is exceeded a message will be issued asking you to increase the appropriate value 4 2 43 o Don t overload operators This option inhibits the operator overloading feature invoked by the command v see Section 10 2 3 Overloading page 101 4 2 44 q Don t translate RATFOR This option is obsolete 4 2 45 P Select TEX processor Say PT or PL to inform FWEAVE that its output will be processed by TEX or La TEX respectively Beginning with Version 1 50 the default processor is LaTeX PL If you always use TEX it s easiest to put PT into the fweb initialization file Please note that PT is no longer supported FWEB development is now based exclu sively on La TEX 4 2 46 p Buffer up a style file entry Th
19. ss EE SG EE RE ee eee eee 57 5 13 Pseudo invisible operators 57 5 18 1 e Pseudo expression EE EE Ee es 57 5 13 2 Pseudo semicolon EE EE Ee ke ee 58 5 18 3 Pseudo colon 000 e eee eee 59 5 14 Miscellaneous commands 0 EE EE eee ee eee ee 59 5 14 1 Inhibit macro expansion 59 6 COMMENTING STYLES 60 6 1 Invisible comments 60 6 2 Visible comments 0 00 cece cece ee eet ek eee 60 6 3 Temporary comments 0 ese nnn 61 7 MACROS and PREPROCESSING 62 7 1 Outer macros 00 eee cece eee teen eee 62 7 2 FWEB MmacroS 0 0 eee ee hh hte 63 7 2 1 Various features of FWEB macros 64 7 2 1 1 FWEB macros with variable arguments 64 7 9 1 2 Recursion 0 2 eee eee eee 64 7 2 1 3 Protecting macros against redefinition 64 7 2 2 Special tokens a 65 722 1 ANSI C compatible tokens 65 7 2 2 2 Extensions to ANSI C macro syntax 65 7 2 8 Built in functions 66 7 2 3 1 Strings and quotes 67 7 2 3 2 Redefining built in functions 67 7 2 8 3 A Convert to ASCIL 68 7 2 3 4 ABS Absolute value 68 7 2 3 5 ASSERT Assert a condition 68 7 2 3 6 SAUTHOR Value of RCS global keyword AUTHOL een 68 7 2 8 7 COMMENT Generate a comment 68 7 2 8 8 DATE Today s date
20. Eliminate or reduce cross reference information FWEAVE 34 4 2 68 X Print selected cross reference information do EE ee hh 34 4 2 69 y Allocate dynamic memory 35 4 2 70 Z Display default style file parameters 35 4 2 71 z Change name of style file 35 4 2 72 Don t recognize dot constants 35 4 2 73 V Explicitly escape continued strings 35 4 2 74 Continue parenthesized strings with backslashes 0 00 eee eee cece e 36 4 2 75 Set starting automatic statement number 36 4 2 76 gt Redirect output FTANGLE 36 4 2 77 Redirect output FTANGLE 36 4 2 78 Turn off comments about line and section numbers FTANGLE 36 4 2 79 Don t interpret compound assignment eN N ehh nhe ehh 37 4 2 80 Recognize short comments FORTRAN amp RATFOR 22o ana 37 4 2 81 Make denote short comment FORTRAN amp RATFOR 22o ana 37 4 2 82 Information options aaa 37 5 FWEB COMMANDS 38 5 1 Debugging commands EE EE eee ee ee eee eee 38 5 1 1 00 Turn off debugging 0 5 38 5 1 2 1 Display irreducible scraps 38 5 1 8 2 Display detailed reductions of the scraps 38 5 2 Literal control characters
21. End module name gt ends a module name of the form lt TEX text gt Technically gt is not a command rather it is a delimiter that terminates lt An unmatched gt is simply ignored after a warning message is issued 5 4 3 A Begin code part of unnamed section A begins the code part of an unnamed section For example In an unnamed section the code part begins with a or A A main For more discussion of the distinction between A and a see Section 5 4 4 ATa page 40 5 4 4 a Begin code part of unnamed section and mark a begins the code part of an unnamed section just as does A and in addition marks the next unreserved identifier it finds as defined in this section Precisely Chapter 5 FwEB COMMANDS 41 a A Originally FWEB did not contain the A command so when the functionality of auto matically marking the next unreserved identifier see Section 5 7 AT page 51 was added it was natural to add it to a A reasonable style of coding is to always use a if you don t know any better if you sometime run into trouble you can then change selected a s to A s For example it is appropriate to use a if one codes one function per section E g c Q Qa int subrtn Here the a marks subrtn as defined in this section i
22. Make denote short comment RATFOR ME 30 4 2 57 r Reverse array indices RATFOR FTANGLE ME 30 4 2 58 s Print statistics EE GE Gee ee ee 30 4 2 59 T Flag setting options for FTANGLE 31 4 2 59 1 TD Permit processing of deferred macro definitions 31 4 2 59 2 Tb Permit built functions to be redefined aaa 31 4 2 59 3 Tm Permit user macros to be redefined Ed 31 4 2 59 4 Tw Don t print header info 31 4 2 59 5 TW Don t retain trailing comments TEX N 31 4 2 59 6 T Don t insert line command after TA A 31 4 2 60 t Truncate identifiers EE EE ei 32 4 2 61 U Convert reserved output tokens to lower case FTANGLE iessesse enhn 32 4 2 62 u Undefine FWEB macro FTANGLE 32 4 2 63 V Print FWEB version number 32 4 2 64 v Make all comments verbatim FTANGLE 32 4 2 65 W Flag setting options for FWEAVE 32 4 2 65 1 W Set module warning flag 32 4 2 65 2 W1 Cross reference single character identifiers is eee Ee een 33 4 2 65 3 W Process bracketed array indices 33 4 2 65 4 WH Send additional arguments to the C PTEPTOCESSOL eee eee eee eee hh 33 4 2 65 5 WdfFlmvw Don t print various things in woven output aaa 34 4 2 66 w Change name of macro package FWEAVE iv 4 2 67 x
23. Note that that option buffers up style file entries i e one may use more than one p option p options placed in fweb are treated as residing in a temporary file that is read just before the local style file thus those behave as global style file entries that will be overridden by a matching entry in the local style file p options on the command line will be processed after the local style file thus override corresponding options in either fweb or the local style file To summarize the previous discussion the local style file is intended to contain settings that are common to a particular source file Settings common to all source files can be put into fweb by means of the p option To override a setting for a single run use a p option on the command line Style file entries have the form keyword value The equals sign is always optional The value is usually a double quoted string but may sometimes be an integer or a single quoted character For example LaTeX class options twoside LaTeX package indentfirst multicol mark_defined fcn_name 0 line char N C color error red Color red e 01 31m Chapter 12 CUSTOMIZATION 113 The syntax is completely free form Periods within keywords are precisely eguivalent to underscores but are useful heuristically for associating a structure like hierarchy to some of the commands Non printable characters in st
24. Summary 103 11 2 2 Creating a stand alone index Details 104 11 3 Using the idxmerge utility to merge indexes 105 11 3 1 Using idxmerge Summary 105 11 3 2 Using idxmerge Details 106 12 CUSTOMIZATION nes 107 12 1 Environment variables essere 107 12 2 Initialization EE EE EE SG Ee RR SG Ee eee eee ee 108 12 2 1 The initialization file 108 12 2 2 Memory allocation 0 108 12 2 2 1 yb Maximum bytes for identifiers index entries and module names 108 12 2 2 2 ybs Size of the change buffer in bytes MEE 109 12 2 2 3 ycb Size of line buffer for C output in bytes 109 12 224 ycf Size of a Ratfor buffer in bytes MEE 109 12 2 2 5 ycg Size of another Ratfor buffer in bytes 109 12 2 2 6 yd Increment for expanding the dots table EE ee ee cece eee eee 109 12 2 2 7 ydt Maximum number of deferred macro tokens 0 002 Ge eee ee 109 12 2 2 8 ydx Maximum number of deferred macro texts ss ec ee nnn 109 12 2 2 9 yid Maximum depth of file inclusion MEE 109 12 2 2 10 yif Maximum number of unique include file names iii EE RE EE esses 110 12 2 2 11 ykt Stack size for FTANGLE 110 12 2 2 12 ykw Stack size for FWEAVE 110 12 2 2 13 y11 Line length for FWEAVE s output in
25. all the other unary operators have the next highest and equal precedence then come the binary operators When the operator exists in C the action taken by FWEB is precisely that that the C compiler would take Arithmetic is done in either long or double variables as implemented by the C compiler that compiled FTANGLE This was the easy choice not necessarily the most desirable one The operators listed from highest precedence to lowest are as follows Chapter 7 MACROS and PREPROCESSING 82 Unary operators defined defined is a unary operator that acts on identifier tokens defined id or equivalently defined id evaluates to 1 true if the identifier is defined as an FWEB macro to 0 false other wise The construction if defined A works the same way as ifdef A but one can use defined in expressions as in if defined A defined B The parentheses around the macro names are optional With the advent of defined the FWEB preprocessor statements ifdef and ifndef become redundant but are often useful shorthands Unary minus Logical NOT ezpr evaluates to 0 if expr is nonzero and evaluates to 1 if expr is 0 One s complement of an integer For example 0 1 Binary operators Exponentiation all languages 2 3 8 kk Exponentiation FORTRAN or RATFOR A Multiplication division and modulus a 4 b m
26. as the index or module list from being printed 2 Now latex test until all of the section numbering is up to date This step is necessary because information in the aux file is used in processing the section headings Now test tex is ready to be inserted in a code like the following documentclass article usepackage fwebinsert begin document section Body The body of the document appendix FWEBinput test end document Note that the commands in test web are converted into LaTEX sectioning com mands such as section The above example works correctly because the first in test web is equivalent to a section level 0 command which should indeed immediately Chapter 10 DOCUMENTATION 100 follow an appendix command Suppose however that you wanted to input test web as part of the body of the above example and wanted the s to be treated as subsections level 1 rather than sections To tell fwebinsert what level number to assign to the s provide that number as an optional argument to FWEBinput as in the following example documentclassfarticle usepackage fwebinsert begin document section Body The body of the document FWEBinput 1 test end document Alternatively say FWEBlevel 1 before the FWEBinput The optional argument con struction merely calls FWEBlevel Here are some caveats about fwebinsert e Implementing
27. for example by a statement such as interface operator BETA in FORTRAN 90 one should also use an v in the definition part for example Qv BETA beta For a detailed discussion of overloading the output appearance of operators see Sec tion 10 2 3 Overloading page 101 Chapter 5 FwEB COMMANDS 50 5 5 28 OW Overload identifier This command begins the definition part For a detailed discussion of overloading the output appearance of identifiers see Sec tion 10 2 3 Overloading page 101 5 5 29 x Terminate ignorable material or begin material to be changed In a change file this command begins material to be changes see Section 3 3 Change files page 13 In web source files this command has a different use see the discussion of the z command see Section 5 5 31 ATz page 50 5 5 30 y Begin change material The y command is permitted only in change files See Section 3 3 Change files page 13 5 5 31 z Begin ignorable material or terminate change FWEB files may begin with the construction z x where the z occupies the very first two characters of the file and where the z and x must begin in column 1 Material between the z and x is pure commentary and is ignored by both processors with one exception The exception is that an RCS like line RCS stands for revision control system with syntax K
28. line 20 test web y tz C 1 line 5 test web Chapter 5 FwEB COMMANDS 49 Unfortunately the information comments have created invalid code that will not compile The q command solves this problem by turning off or on the information comments locally q0 turns them off q1 turns them on Thus if one rewrites the above example as Q Qa q0 x lt Some action gt q1 it will tangle to x ytaz as one desires For another use of the q command see Section 5 5 21 ATo page 47 5 5 23 R Treat next identifier as integer like reserved word F WEAVE For formatting purposes treat the next identifier as an integer like reserved word This command is useful in pretty printing certain kinds of macro constructions Further discussion is given in undefined Macros and formatting page undefined 5 5 24 r Set language to RATFOR 77 See Section 5 5 13 ATL page 45 and Chapter 8 Languages page 83 5 5 25 r9 Set language to RaTror 90 See Section 5 5 13 ATL page 45 and Chapter 8 Languages page 83 5 5 26 u Undefine outer macro This command begins the definition part u is the inverse of d For example in C the command u A tangles to undef A 5 5 27 v Overload operator This command begins the definition part v is used to change the woven appearance of an operator If one defines a new operator
29. or RATFOR FORTRAN and RATFOR can expand expressions such as x i dx into their FORTRAN counterparts such as x i x i dx It does so in a very straightforward way by copying the expression to the left of the equals sign ylx controls the maximum size of that expression 12 2 2 17 ym Maximum number of sections ym limits the maximum number of sections both named and unnamed Each un named section is counted separately The absolute maximum number of sections is 10239 probably one of the most stringent restrictions in FWEB s design This number is a bit less than 1 5 of 64K 12 2 2 18 yma Maximum number of arguments to FWEB macros The maximum number of arguments to FWEB macros defined by m is limited by 4 yma Chapter 12 CUSTOMIZATION 111 12 2 2 19 ymb Size of the buffer for expanding FwEB macros The expansion of each FWEB macro is done in a buffer whose size is controlled by ymb In some situations particularly in RATFOR more than onesuch buffer can be open at once 12 2 2 20 yn Maximum number of identifiers and module names A structure is associated with each unique identifier and module name The maximum number of such structures is controlled by yn See also Section 12 2 2 1 yb page 108 12 2 2 21 ynf Maximum number of open output files In addition to FTANGLE s usual output file e g test c additional files
30. phase 2 and can cause confusion when used with the preprocessor commands which are evaluated during the input phase 1 Because of this confusion deferred macro definitions are prohibited by default To permit them use the TD option then be prepared to make some obscure programming errors 4 2 59 2 Tb Permit built functions to be redefined By default built in functions such as IF see Section 7 2 3 Built in functions page 66 may not be redefined by an m command To allow this extremely dangerous operation use the Tb option 4 2 59 3 Tm Permit user macros to be redefined By default user macros may not be redefined by an m command To permit this use the Tm option Note that many functions described under Section 7 2 3 Built in functions page 66 such as PI are in fact implemented as macros 4 2 59 4 Tv Don t print header info By default FTANGLE attempts to be helpful and writes some information about the command line input and change files etc at the beginning of the output file This infor mation can be deleted by means of the Tv flag This is done automatically when the F flag see Section 4 2 15 F page 19 is in effect since the header information includes a time stamp that would defeat a successful file comparison 4 2 59 5 TY Don t retain trailing comments TEX Unless the v option is used comments are generally deleted by FTANGL
31. ss EE EE EE EE SG eese 38 5 2 1 The character EE EE Ee es 38 5 2 2 Literal vertical bar or optional line break 39 5 3 Beginning of section EE EE nh 39 5 3 1 Begin minor section Ee 39 5 3 2 n Begin major section 39 5 4 Beginning of code part 0 e eee ee ee ee nee 40 5 4 1 lt Begin module name 40 5 4 2 gt End module name 40 5 4 3 A Begin code part of unnamed section 40 5 4 4 a Begin code part of unnamed section and mark MU 40 5 5 Control codes b zZ 0 EE SG EE RE SG Ee es 41 5 5 1 B Suppress insertion of breakpoint command 41 5 5 2 b Insert a breakpoint command 41 5 5 3 Oc Set language to CO EE EE EE Ge 41 5 5 4 ct Set language to CF Ee Ee 42 5 5 5 D Define outer macro 2 5 42 5 5 6 d Define outer macro and mark 42 5 6 5 7 5 8 5 9 5 10 5 5 7 E Treat next identifier as ordinary expression FWEAVE SE n Hmmm mme 42 5 5 8 f Format identifier or module name 42 5 5 9 i Include file unconditional 43 5 5 10 I Include file conditional Ad 5 5 11 K Extract global RCS like keyword AA 5 5 12 k Access local RCS like keyword 44 5 5 13 L Set lang
32. such as the arguments of ifelse commands in m4 4 2 75 Set starting automatic statement number This option is useful for FORTRAN and RATFOR Symbolic statement labels that are defined with the 0 macro command Section 7 2 2 Tokens page 65 Section 8 2 3 For tran page 85 as in m EXIT 0 are incremented starting with the default of 90000 To change this to e g 789 say 789 4 2 76 gt Redirect output FTANGLE This changes the name of FTANGLE s output file If no name is given output is redirected to the terminal This command has no effect for FWEAVE Although the appearance of this command is highly intuitive it may be hard to type quickly An equivalent command is see Section 4 2 77 page 36 4 2 77 Redirect output FTANGLE Equivalent to gt see Section 4 2 76 5 page 36 and faster to type on many key boards 4 2 78 Turn off comments about line and section numbers FTANGLE By default tangled output includes comments about the line and section numbers cor responding to the current piece of code To eliminate this clutter say But note that the line number information is very useful for debugging in C and C as it enables the debugger to display the source line in the web file In some cases bugs in tangled output particularly from FORTRAN can be eliminated by using But please report the bu
33. twoside To specify user packages i e to obtain the effect of Nusepackagelpkgoptions pkgname j use the style file parameters LaTeX package and LaTeX package options as in LaTeX package pkgname LaTeX package options pkgoptions For example to indent the first line of every section and to permit the use of the multicol package the latter is a useful way of substantially cutting down on white space say Chapter 10 DOCUMENTATION 94 LaTeX package indentfirst multicol Note that specifying LaTeX package and LaTeX package options results in the execu tion by the Wbegin macro of precisely one line of the form usepackage myoptions mypackages Sometimes one instead needs to have multiple usepackage lines such as usepackage Loption1 package1 usepackage Loption2 package2 To get this effect one can put these commands explicitly into the style file parameter doc preamble see discussion two paragraphs below as in doc preamble usepackageLoption1 package1 usepackage Loption2 package2 TEX commands in the user s limbo section of the web source file will be processed after the begin document command Limbo commands from the style file can be inserted before and or after those in the limbo section with the aid of the style file parameters limbo begin and limbo end see Section 12 3 8 11 S limbo page 120 If there is a compelling reason to insert one s own LalEX commands between th
34. 0 5 The limbo section 8 2 3 Modules 00 SS EG RE cee cece hh hh 8 2 3 1 The unnamed module 00 5 8 2 3 2 Named modules 0200 e eee eee eee 9 2 4 Phases of processing 0 cree cece nen 10 2 4 1 The phases of FTANGLE esses eene 10 2 4 2 The phases of FWEAVE 0 00 cence cece anes 11 3 FILES ss cee ss ss ee ee es se 12 3 1 Input files sies EG EE RE SG eee mm 12 3 1 1 Automatic filename completion 12 3 2 Output files EE SG EE Ge RR SG cece eee eee 13 3 3 Change files EE EE mmm 13 4 RUNNING EWEB ss ss sees sesse eee eee 15 4 1 Command line syntax 15 4 2 Command line options EE EE SG GE EG eee eee eee 15 4 2 1 Negating options 16 4 2 2 1 Turn on brief debugging mode FWEAVE 16 4 2 3 2 Turn on verbose debugging mode FWEAVE AA 16 4 2 4 Display the control code mappings 16 4 2 5 A Turn on ASCII translations 17 4 2 6 B Turn off audible beeps 17 4 2 7 b Number blocks FWEAVE 17 4 2 8 C Set the color mode cece eee eens 18 ii 4 2 9 c Set global language to C 18 4 210 ct Set global language to C t 18 4 2 11 D Display reserved words iss ss es 18 4 212 d Convert do end
35. 2 ATdquote page 51 Note the extra parentheses required by the built in A first expands its argument in case it is a macro defined as a string 7 2 3 4 ABS Absolute value ABS expression returns the absolute value of the macro expression It is a macro implemented in terms of IF and EVAL 7 2 3 5 ASSERT Assert a condition SASSERT expression evaluates the macro expression If the expression is false an error message is printed and the run aborts This built in is useful for ensuring that FWEB macros required by the code are properly initialized Because it is expanded during the output phase it must appear in the code part not in the definition part 7 2 3 6 AUTHOR Value of RCS global keyword Author Equivalent to KEYWORD Author See Section 7 2 3 30 JKEYWORD page 72 7 2 3 7 COMMENT Generate a comment COMMENT string generates a comment in the output file This function is sometimes useful in conjunction with the processing of FWEB macros since ordinary comments are removed when macros are processed For example if one says c m M abc COMMENT Test a m M the tangled output will be m abc Test 7 2 3 8 DATE Today s date DATE generates a string consisting of the date in the form August 16 2001 It is implemented as a macro that calls other macros and primitive functions 7 2 3 9 DATE_TIME Value of RCS global keyword Date Equivalent to
36. 3 43 MODULES Total number of independent modules MODULES gives the total number of independent modules that is the number of in dependent module names plus 1 for the unnamed module 7 2 3 44 NAME Value of RCS global keyword Name Equivalent to KEYWORD Name See Section 7 2 3 30 SKEYWORLD page 72 Chapter 7 MACROS and PREPROCESSING 76 7 2 3 45 OUTPUT LINE Current line number of tangled output This returns the current line number of the tangled output Contrast this with INPUT_ LINE Section 7 2 3 29 SINPUT_LINE page 72 7 2 3 46 P The C preprocessor symbol P is essentially a synonym for UNQUOTE see Section 7 2 3 64 JUNQUOTE page 78 It is useful for constructing FWEB macro definitions that expand to C preprocessor statements For example m CHECK flag SP if flag special code P endif Another version of the preprocessor symbol is PP see Section 7 2 3 49 PP page 76 For most purposes P and PP will behave in exactly the same way The difference between them is that P is treated as a string without surrounding quotes whereas PP is treated as a character The character nature of PP is used by FORTRAN to reset the column number to 1 so C like preprocessor commands appear there rather than in column 7 For further discussion of strings and the differences between P and PP see Sec tion 7 2 3 1 Strings and quotes page 67 7 2 3 47 PI Pi The expression
37. 35 nb Number ifs and dos FORTRAN F WEAVE MU 25 4 2 36 nC Ignore single line comments FORTRAN 25 4 2 37 np Print semicolons FORTRAN FWEAVE 26 4 2 38 n Free form syntax continued by backslash 26 4 2 39 n amp Free form syntax continued by ampersand N hehehe 26 4 240 n Recognize short comments FoRTRAN 27 4 2 41 n Make denote short comment FORTRAN N hehehe 27 4 2 42 n Reverse array indices FORTRAN FTANGLE N hehehe 27 4 2 43 o Don t overload operators 28 4 2 44 q Don t translate RATFOR 50 5 28 4 2 45 P Select TEX processor seeseesss 28 iii 4 2 46 p Buffer up a style file entry 28 4 2 47 r Set global language to RATFOR 77 29 4 2 48 r9 Set global language to RATFOR 90 29 4 2 49 rg Set goto parameters isses 29 4 2 50 rk Suppress comments about RATFOR translation FTANGLE ssse esee nn 29 4 2 5 rK Write comments about RATFOR translation FTANGLE 2 oe ese ee enhn 30 4 2 52 r Turn on auto semi mode using pseudo semis RATFOR SE cece cette ek ke ee ee 30 4 2 53 r Turn on auto semi mode using actual semis RATFOR SE Ee nnne 30 4 2 54 rb Number ifs and dos RATFOR 30 4 2 55 r Recognize short comments RATFOR 30 4 2 56 r
38. 77 7 2 3 60 TIME The time 77 7 2 8 61 TRANSLIT Transliteration 78 7 2 8 62 SU Change to upper case 78 7 2 8 63 UNDEF Undefine a macro 78 7 2 3 64 UNQUOTE Remove quotes from string MEME 78 7 2 3 65 UNSTRING Convert string into characters MEME 78 7 2 3 66 VERBATIM Obsolete 78 7 23 67 VERSION Present FWEB version number MEME 78 7 2 4 Debugging with macros 79 7 3 Preprocessing cece eee EG ee hh 80 8 LANGUAGES eee ee eee ss ss ss eee 83 8 1 Setting the language aan 83 8 2 Special hints and considerations for each language 84 8 2 1 Special considerations for C 84 8 2 2 Special considerations for C 85 8 2 8 Special considerations for FORTRAN 85 8 2 3 1 Items for both FORTRAN 77 and FORTRAN 90 occ cee nnne 85 8 2 3 2 Items specific to FORTRAN 77 and fixed form FORTRAN 90 Lee se ee ese 87 8 2 3 3 Items specific to FORTRAN 90 87 8 2 4 Special considerations for RATFOR 88 8 2 5 Special considerations for TeX 88 8 2 6 Special considerations for the VERBATIM language Aa 88 9 RATFOR 0 0 89 9 1 RATFOR syntax 0000000 000000 89 9 2 RATFOR commands 0 89 9 2 1 RATFOR 77 commands aaa 89 9 2 2 Additional RATFOR 90 commands
39. E g use IF not IF This change was warned about in the last release Single character identifiers can now be completely cross referenced via the W1 option See Section 4 2 65 2 W1 page 33 Some module warning messages can be eliminated with the W option See Section 4 2 65 1 WAT page 32 The q command still experimental has been added to locally turn on or off the the line and module comments in the tangled output See Sec tion 5 5 22 ATq page 48 The level of verbosity of FWEB s informational messages can be controlled with the M option See Section 4 2 26 M_ page 23 C C programmers may find the command useful See Section 5 9 ATIb page 53 The nC option has been added for FORTRAN users it kills commented lines at a very early stage in the processing This can be useful when converting existing codes to FWEB See Section 4 2 36 nC page 25 FORTRAN 90 see Section 4 2 31 n9 page 24 now defaults to free form syntax As of the non beta Version 1 61 free form FORTRAN 90 now inserts semi colons automatically in the code part Thus textbook FORTRAN 90 exam ples will weave correctly without the annoyance of explicitly terminating Chapter 14 NEW FEATURES 15 16 17 each statement with a semicolon If you prefer to put in the semicolons explicitly use n to turn off the auto insertion See Section 4 2 33 n page 24 The defau
40. EE nh 74 72 335 LEN Length of string 74 7 2 3 36 LOCKER Value of RCS global keyword LOCKED eee N N 75 7 2 3 37 LOG Natural logarithm 75 7 2 3 38 S LOG10 Logarithm to the base 10 75 7 2 3 39 M Define a deferred macro 75 7 2 3 40 MAX Maximum of a list 75 72341 SMIN Minimum 75 7 23 42 MODULE NAME Name of present web module 75 7 23 43 MODULES Total number of independent modules 75 7 2 3 44 NAME Value of RCS global keyword Name CE 15 viii 7 2 3 45 SOUTPUT LINE Current line number of tangled output esee 16 7 2 3 46 P The C preprocessor symbol 16 72 8A7 PI Pi EE EE SG Ge EE ee eee 76 7 2 3 48 POW Exponentiation 76 7 2 3 49 PP The C preprocessor symbol 16 7 2 3 50 RCSFILE Value of RCS global keyword RCSfile ee EE EE EE EE Ee eee 76 7 2 3 51 REVISION Value of RCS global keyword Revision eee eee eee 76 7 2 8 52 ROUTINE Current function RATFOR ONLY eee nnm TT 7 2 8 53 SECTION NUM Number of current FWEB SATO EE hh hr TI 7 23 54 SECTIONS Maximum section number MEME 77 7 2 3 55 SOURCE Value of RCS global keyword SOUFCO leen eee nhe TI 7 23 56 SQRT Square root 77 7 2 3 57 STATE Value of RCS global keyword State ke ke Ee Ee ehh TI 7 23 58 STRING Expand then stringize 77 7 2 3 59 STUB Trap for missing module
41. EG eens 101 Overloading identifiers a 102 Overloading operators a aaa 101 P Package fwebnum aan 98 Package multicol a 96 Packages USET aaa eee eens 93 Page headers aaa aaa 98 Page numbers iii aaa 98 Part code 5 7 Part definition se aaa 5 7 Part TEX SE N ees 5 7 EE btn e enn ne 5 Phases of FTANGLE 0c eee ee Ge ge ee 10 Phases of FWEAVE ees aaa se ee ee ee ee ee 11 OE hh hh 76 Pound sign 76 PreprocessiNg is SS nn 80 Preprocessor symbol 76 Preprocessor m4 ee se eene 24 Preprocessor sending additional arguments to 33 Pretty printing iis cece eee 100 Printing two sided 0 0 eee eee eee 93 Processor La TEX eee ee 28 Processor TEX aaa 28 Concept index Processors FWEB ees ee ee se eel 5 Program UNIE se ee aaa 77 Programming tips 122 Pseudo colon aaa 59 Pseudo expression asaan 57 Pseudo operators aaa 57 101 Pseudo semicolon aaa 58 Pseudo semicolons automatic 24 58 88 R RATFOR 1 00 ee ed nn 89 RATFOR commands 89 RATFOR caveats about 90 Rational FORTRAN 22 24o eee ee eens 89 RES file 76 RCS like keyword 0000eeeee 50 72 73 Recursion aan 64 Redefined commands version 1 61 124 References forward ccc sss 51 Reserved words 00 0 0 sce eee seen nee 18 RevislOn ee SG SG nn
42. KEYWORD Date See Section 7 2 3 30 SKEYWORD page 72 7 2 3 10 DAY The day DAY generates a string consisting of the day of the week such as Monday It is implemented as a macro that calls other macros and primitive functions Chapter 7 MACROS and PREPROCESSING 69 7 2 3 11 DECR Decrement a macro SDECR N redefines the numeric macro N to be one less than its previous value If N does not simplify to a number an error results In other words in the language of C the effect is to say N The two argument form SDECRCN m executes the equivalent of N m 7 2 3 12 DEFINE Deferred macro definition DEFINE behaves like the FWEB macro command m but it is intended to appear in the code part not the definition part so it is processed during output not input Thus the code fragment a DEFINE A 1 07 a tangles to a A a 1 Notice how the 0 command was used to kill an unwanted newline analogous to the dnl macro in m4 In the above example one could also say DEFINE A 1 To define a macro with arguments say something like DEFINE A x x x Do not say DEFINE A x x x as in this case the equals sign will be included in the macro expansion One must use the equals sign as a means of preventing parentheses from being interpreted as an argument in examples like DEFINE A x This expands to x A completely equivalent sh
43. LANGUAGE_NUM C 0 C 1 Fortran 2 Fortran 90 3 Ratfor 4 Ratfor 90 5 TeX 6 VERBATIM 7 This built in is useful in conjunction with an IFCASE construction see Section 7 2 3 24 SIFCASE page 71 7 2 3 35 LEN Length of string LEN string returns the length of string in bytes If string is not surrounded by quotes it is interpreted as if it were quoted so it is not expanded if it is a macro Thus in the example Chapter 7 MACROS and PREPROCESSING 75 m SS string LEN SS the value returned is 2 not 5 To expand the argument before taking the length one can say something like m XLEN s LEN s 7 2 3 36 LOCKER Value of RCS global keyword Locker Equivalent to KEYWORD Locker See Section 7 2 3 30 SKEYWORD page 72 7 2 3 37 LOG Natural logarithm LOG x returns In z 7 2 3 38 L0G10 Logarithm to the base 10 L0G10 x returns log a 7 2 3 39 M Define a deferred macro M is equivalent to DEFINE See Section 7 2 3 12 SDEFINE page 69 7 2 3 40 MAX Maximum of a list SMAX x1 x2 returns the maximum of the list of arguments There must be at least one argument 7 2 3 41 MIN Minimum MIN x1 x2 returns the minimum of the list of arguments There must be at least one argument 7 2 3 42 MODULE NAME Name of present web module SMODULE NAME returns the name of the present web module If the present module is unnamed it returns the string unnamed 7 2
44. Number of current FWEB section SECTION_NUM returns an integer greater than 0 that is the integer number of the current web section This is not the La TEX section number such as 3 4 7 2 3 54 SECTIONS Maximum section number SECTIONS is the maximum section number as understood by FWEAVE 7 2 3 55 SOURCE Value of RCS global keyword Source Equivalent to KEYWORD Source See Section 7 2 3 30 SKEYWORD page 72 7 2 3 56 SQRT Square root SQRT x returns Ya It is a convenience macro defined in terms of POW See Sec tion 7 2 3 48 SPOW page 76 7 2 3 57 STATE Value of RCS global keyword State Equivalent to KEYWORD State See Section 7 2 3 30 SKEYWORD page 72 7 2 3 58 STRING Expand then stringize STRING s expands its argument if it is a macro then makes the expansion into a quoted string If the argument is already a quoted string it is returned unchanged 7 2 3 59 STUB Trap for missing module When a missing module is detected FTANGLE inserts the command SSTUB module name into the output code The built in STUB expands to a function call appropriate to the current language For example in C it expands to missing_mod in FORTRAN it expands to call nomod 7 2 3 60 TIME The time TIME returns a string consisting of the local time in the form 19 59 Chapter 7 MACROS and PREPROCESSING 78 7 2 3 61 TRANSLIT Transliteration The macro T
45. PI returns m to the default machine precision The expression PI Ciprec returns 7 to the decimal precision iprec which must be less than 50 7 2 3 48 POW Exponentiation POW x y generates z It is a macro defined in terms of EVAL see Section 7 2 3 17 SEVAL page 70 and the exponentiation operator 7 2 3 49 PP The C preprocessor symbol PP is shorthand for UNSTRING P see Section 7 2 3 46 SP page 76 or essen tially a synonym for UNSTRING see Section 7 2 3 65 SUNSTRING page 78 It is useful particularly in FORTRAN for constructing FWEB macro definitions that expand to C preprocessor statements For an example see Section 7 2 3 46 P page 76 For a detailed discussion of the difference between P and PP see Section 7 2 3 1 Strings and quotes page 67 7 2 3 50 RCSFILE Value of RCS global keyword RCSfile Equivalent to KEYWORD RCSfile See Section 7 2 3 30 SKEYWORD page 72 7 2 3 51 REVISION Value of RCS global keyword Revision Equivalent to KEYWORD Revision See Section 7 2 3 30 JKEYWORD page 72 Chapter 7 MACROS and PREPROCESSING 77 7 2 3 52 ROUTINE Current function RATFOR only When RATFOR is the current language ROUTINE expands to a string built of the name of the current program function or subroutine This function is not useful for other languages for which it expands to the null string 7 2 3 53 SECTION_NUM
46. SG Ge SG eee 93 Vi m 96 Vidxname cette ete 106 NINDEX SE eee n 7 96 113 maketitle ccc ee ee ee ee ee ee 97 numbercode ee Ge ee ee eg ee ee ee 98 Vnumberdef8 cece ccc ccc cet ee ee 98 Nnumberline cee ccc ccc ees 97 numberTeX 0 ccc cece n 97 Option and command index Npagerefs EG Se eee 97 98 VON 105 NSection isses 95 startindex ii Ge GE Ee ee ee ee ee ee ee 96 subsection cette ee 95 subsubsection eee eee ee eee es 95 title lawakan 97 Title 2 97 topofcontents 0 0 EG ene 97 topofindex 0 ieee eens 106 twocolumn eee cece cet eees 96 Nusepackage EE es 93 TE ccc m n 33 TEL enn 94 WDLOCK o 0 e 17 NLANG 96 UC MD 115 WID s Im en 115 VEE EE e ne 116 AE mne 116 WidM D 116 WIDM N 116 VA mn 43 Vas ER e eee 43 Wintrinsic cece nn 116 Mkeyword is SS Ee mh 116 NWKEYWORD ee eie ee de ede ge ee de ee 116 Il ene 25 87 VWreserved a 116 NWRESERVED Lee dee Ge ede ee 116 ETE areen 116 Wtypewriter 0 eee eee 116 NIKA eee eee 33 140 EA 0 ccc ccc ccc ccc ccc cen nnn 51 CONTENTS tex ccc nene 13 fweb sty AE eee eee 12 112 FWEB HDR INCLUDES se ees es ee ee ees ee 107 FWEB INCLUDES ees ee ss ee se ee ss ee ees ee 108 FWEB d EE ccc e 108 FWEB STYLE DIR soes ee ss se ee ee n 108 fwebinsert sty cece eee 99 fwebmac sty se ee Ee se eee 91 92 fwebmac web see
47. UNSTRING see Section 7 2 3 65 SUNSTRING page 78 In understanding the operation of those functions it is important to understand just what a string means in the FWEB context As usual it is a vector of characters However those need not be delimited by quotes although they may be Internally a string is represented by the construction sqc cqs where s is a special string delimiter never seen by the user q is an optional quote character either single or double quote depending on the language and c is an ordinary character Whether or not the quotes are present the string delimiters inhibit macro expansion The difference between UNQUOTE and UNSTRING can now be stated as follows Given a quoted string such as abc in C e UNQUOTE removes the quote characters q leaving sabcs still a string e UNSTRING removes both the quote characters q and the string delimiters s leaving abc a collection of three characters This collection is not tokenized it does not represent the single identifier name abc and therefore is not very useful UNSTRING is primarily used internally The built ins P see Section 7 2 3 46 P page 76 and PP see Section 7 2 3 49 PP page 76 which both generate the preprocessor character provide a good illustration of the differences between UNQUOTE and UNSTRING Consider FORTRAN as an example Essentially SP is defined as UNQUOTE which is internally sis When
48. a separate set of parameters is provided such as meta top hdr meta top lspecifies text that precedes material enclosed by Here l is one of the standard language subscripts see Section 12 3 Style page 112 such as N90 meta prefix begins each line of the meta comment meta bottom specifies text that follows the meta comment 12 3 8 7 outer F TANGLE converts d see Section 5 5 6 ATd page 42 to outer def and u see Section 5 5 26 ATu page 49 to outer undef 12 3 8 8 protect The strings protect l specify the protection character s to end a continued line 12 3 8 9 suffix The extension for the files output by FTANGLE is specified by suffix l 12 3 8 10 macros The default name of the macro package to be read in This is usually fwebmac sty see Section 10 1 2 fwebmac sty page 92 but can be overridden by the command line option w see Section 4 2 66 w page 34 Chapter 12 CUSTOMIZATION 120 12 3 8 11 limbo begin limbo end limbo begin is TEX material to be printed at the beginning of the limbo section just before the text from 1 commands See Section 5 5 14 ATI page 45 This command was previous called just limbo and that still works Similarly limbo end is printed at the end of the limbo section Thus the beginning of the file output by FWEAVE looks like this input fwebmac sty Wbegin contains documentc
49. and PREPROCESSING 71 7 2 3 18 EXP Exponential function SEXP x returns e 7 2 3 19 GETENV Get value of environment variable GETENV name returns a string consisting of the current value of the environment variable name Under VMS logical names behave like environment variables The argument to GETENV need not be a string double quoted but it may be if necessary to avoid the expansion of a macro 7 2 3 20 HEADER Value of RCS global keyword Header Equivalent to KEYWORD Header See Section 7 2 3 30 JKEYWORD page 72 7 2 3 21 HOME The user s home directory HOME is a convenience macro equivalent to GETENV HOME 7 2 3 22 ID Value of RCS global keyword Id Equivalent to KEYWORD Id See Section 7 2 3 30 SKEYWORD page 72 7 2 3 23 IF Two way conditional IF is a primitive function not a macro that is the code part version of if The syntax is IF expr action if true action if false The expr is an FWEB macro expression that must reduce to 0 false or 1 true First that argument is expanded If it is true action if true is expanded otherwise action if false is expanded There may be peculiarities with this and the other built in IF function having to do with the order of expansion when the actions contain macros whose arguments themselves are macros Therefore do not use them unless absolutely necessary Do not redefine IF or any other built in co
50. and command index ak 19 id ehh hes 19 FF ehh hh hh 20 FE ehh hes 19 EE araa rran rrenaren 21 UJ DUE 20 EE rrna rrr 20 i sb 20 ui CODD 20 DM 21 JUI 21 P QUE 21 ne hh he en 22 FR aasan arenaer ranra naeran 22 87 EE hh hh hes 23 RE ehh hh hh 22 i GG rnrn rrr 23 d MUI 23 EE NG 24 TMA ehh hh hne 24 p ODE 24 Dn hh han 27 88 TG hh hh hh hehe 26 EE anaran rrara 27 VAR AA KN AA 27 TIDE ehh hh hh hne 25 EE hn 24 58 TEE hh hh 24 58 EE AA 26 EE hh hh hh hen 24 RE EO hh he 25 TIG hh hh hh hen 25 NP 0 hee 26 TO AA AG hh hh ehh 28 Aa 28 SP ehh hes 28 is 29 a Ee hh hen 30 DE PAA 30 me sea 30 a sese aaa aa aaa 30 EE hehehe ara 30 a AA 29 TIED ehh hh hen 30 i ehh e e ehh e e eee 29 ui qM 29 SE hh hh hen 30 IH DE 30 ISM errre rreren arrar ent e nen 30 138 TH ccc E 31 N 31 HTD ccc he e hehe hee 31 STD iie he ehe hee 31 mi ME AA 31 i A e e n 31 UW CC 32 EE he e ehe 32 ns 0 re 32 EE he ehe ee een 32 n 00000 34 uu E 32 34 ae 32 IE mh 33 i EE 33 ul N 33 p cC 34 p COMME 34 pU C n nn neees 104 a hh eee 35 nip 108 TYDS hehehe 109 Ee 109 mi Aa 109 iS hh 109 nr AA rnrn rrara 109 HVE ehh hehe hee 109 mi qM 109 EG hen 109 mo PEDI 110 N 110 EE DEI 110 al hehe hee 110 AE e hehe hen 110 SYIN eh ehh hen 110 mat eh hh hee 110 m pM 110 EE ee 110 Ee 111 SYN easunrarenrrrrnrrrrrrrrrrrrrrrrrrr rrr 111 EA cece eee 111 DYOP ehh hee 111 m MEME 111 m oM 111 a ehh 111 YEE La 111
51. are no longer ac knowledged individually See Chapter 15 Support page 131 e The next major release FWEB Version 2 00 is planned for no earlier than January 1 2000 This documentation is now accessible on the World Wide Web from http w3 pppl gov krommes fweb_toc html Other sources of information about FWEB are the archival files of the fweb users and fweb installers mailing lists To learn how to obtain those see Chapter 15 Support page 131 If you are learning FWEB for the first time you will probably find that this unfinished manual is not sufficiently pedagogical For background please refer to Knuth s book cited in Chapter 1 Intro page 3 You should also browse through Chapter 2 Concepts page 5 in particular Section 2 2 Structure page 5 FWEB Copying Permissions 2 FWEB Copying Permissions FWEB is free This means that everyone is free to use them and free to redistribute them on a free basis FWEB operates under the terms of the GNU General Public License see for example section Distribution in The GNU Emacs Manual Although it is hoped that FwEB will be useful there is ABSOLUTELY NO WAR RANTY Chapter 1 INTRODUCTION to FWEB 3 1 INTRODUCTION to FWEB FWEB is a system for literate programming It enables one to maintain both documen tation and source code in a single place the web file and to explain the code in terms of a web of very small fragments Because FWEB is intimately i
52. bar would signal a shift into code mode which is probably not what one wants For an example see Section 5 12 4 AT page 56 In a code part inserts an optional line break in an expression e g f a b 0 c d This helps TEX to break the line at an appropriate place If the line does not need to be broken the command does nothing Compare with V see Section 5 12 3 AT bs page 56 and see Section 5 12 2 AT page 55 which always break the line 5 3 Beginning of section Sections are begun by either or 5 3 1 Begin minor section begins a new minor unstarred or unnamed section that is not entered into the Table of Contents For example This is an example of a minor unnamed section No entry is made in the Table of Contents Qa main o 5 3 2 0 n Begin major section begins a new major starred section of level 0 The command must be followed by the name of the section entry in the Table of Contents followed by a period If a period appears in the name itself it must be protected by braces The section name is also used as a running head on the output pages To deal with the possibility that the full name may be too long the section name may be preceded by an optional argument enclosed in brackets If it is present the optional argument is used as the running head If a period appears as part of the opti
53. begin new parts say ftangle See Section 4 2 4 AT page 16 5 1 Debugging commands Several commands provide localized versions of the 1 and 2 options related to debugging of pretty printing 5 1 1 0 Turn off debugging This cancels the effect of a previous 1 or 2 see Section 5 1 2 ATI page 38 and Section 5 1 3 AT2 page 38 The 0 command should appear in a different section from the 1 or 2 commands 5 1 2 1 Display irreducible scraps This is a local version of the command line option 1 see Section 4 2 2 1 page 16 refer to that discussion for more information 5 1 3 2 Display detailed reductions of the scraps This is a local version of the command line option 2 see Section 4 2 3 2 page 16 refer to that discussion for more information 5 2 Literal control characters Several commands insert specific characters 5 2 1 The character inserts the single character Don t forget to double the even inside strings For example the FWEB source line puts 00 is represented by 0 will be tangled to puts is represented by Chapter 5 FwEB COMMANDS 39 5 2 2 Literal vertical bar or optional line break In the TEX documentation part of a section inserts a vertical bar This is useful inside LaTEX verbatim environments A simple
54. begins with an upper case E formerly it was lower case The behavior of the optional argument of the Title macro has been slightly redefined The new more symmetrical form is Title Short title Long title where Long title is printed on the title page and Short title is used for the running header within the document See Section 10 1 3 6 Table of Contents page 96 The line break commands and formerly identical now behave slightly differently breaks the line just as it would if the line had been too long and been spontaneously broken See Section 5 12 2 AT page 55 V backspaces one unit of indentation after breaking the line See Section 5 12 3 AT bs page 56 Usually one should use sorry I was previously recommending For an example in which it is natural to use see Section 5 12 3 ATbs page 56 The names of some of the code typesetting macros in fwebmac sty have been changed to conform to the convention that they should all start with W This change will be invisible to you unless you happen to have user macros of your own that start that way or perish the thought you have redefined low level and obscure code in fwebmac sty Chapter 14 NEW FEATURES 14 1 3 New features v1 61 This release adds some features for managing large projects including i the idxmerge utility that merges indexes produced by several FWEB files ii a mechanism for acce
55. earlier uses The second form shows how to handle embedded blanks in a UNIX shell Then if one were programming in C use of H would issue the system command Chapter 4 RUNNING FWEB 34 gcc E P Dtesti 1 Dtest2 2 4 2 65 5 WdfFlmvw Don t print various things in woven output The printing of selected definition part commands can be suppressed as follows Wd outer definitions d or D Wf format statements f WF format statements F W1 limbo text definitions 1 Wm FWEB macro definitions m or M Wv operator overloads v Ww identifier overloads w or W When these options used associated cross referencing is suppressed as well 4 2 66 w Change name of macro package FWEAVE The option w means Don t print input fwebmac sty as the first line of the tex output file The option wfname means Print input fname as the first line For example when working with REVTEX see Section 10 1 3 2 REV TeX page 94 one needs to say wrwebmac sty This option can be used for special effects when one is trying to obtain behavior differ ent from that defined by FWEB s macro package fwebmac sty see Section 10 1 2 fweb mac sty page 92 However try to not do that Please submit requests for such behavior modifications to the developer see Chapter 15 Support pa
56. eee 120 12 3 8 14 dot constant 120 12 3 8 15 null file ee see 120 xii 12 3 9 Automatic file name completion 120 13 USAGE TIPS and SUGGESTIONS 121 13 1 Converting an existing code to FWEB 121 13 2 Programming tips and other suggestions 122 13 3 Features for scientific programming 123 14 NEW FEATURES ese 124 14 1 Version 1 61 m 124 14 1 1 Updates to documentation v1 61 124 14 1 2 Redefined commands v1 61 124 14 1 3 New features V1 61 125 14 1 4 Significant bugs v1 61 126 14 2 Version 1 58 EE EE EG EE cette ee 126 14 3 Version 1 59 EE EE EG EE cee tenes 127 14 4 Version 1 50 EE EE ES EE eee ene 128 14 5 Version 1 40 EE EE EE eee een ee 129 15 SUPPORT nnn 131 Appendix A Installing FWEB 132 Concept index ss ss ss een 133 Option and command index 137 Parameter mdex eee enn 141 xiii
57. file as for example ndx index preamble are TEX commands that begin the Index index postamble are TEX commands that end the Index index collate specifies the collating sequence for the Index 12 3 1 2 delim delim O is the string to insert after the identifier in an index entry delim n is the string to insert between two section numbers in an index entry Chapter 12 CUSTOMIZATION 114 12 3 1 3 group skip group skip is a string of TEX commands to insert between letter groups 12 3 1 4 item O item O is the TEX command to begin an index entry 12 3 1 5 language language prefix begins a language entry language suffix ends one 12 3 1 6 lethead lethead prefix begins a letter group lethead suffix ends one The flag lethead flagl controls the format of the letter group if it is zero nothing is inserted if it is positive an upper case letter is inserted if it is negative a lower case letter is inserted 12 3 1 7 underline underline prefix is the TEX command to begin an underlined index entry underline suffix is the TEX command to end an underlined index entry 12 3 2 Customizing the module list modules tex is the name of the file into which the module names are written modules preamble is a string of TEX commands to begin the list of modules modules postamble is a string of TEX commands to end the list of modules modules info is the name of the TEX macro that formats the command
58. formatting name of 43 Include file printing name of 43 Include files finding SE Ge 21 Include files indexing ee Se 21 Include files inhibiting ee aan 22 Include files scanning Ee ee Ee 20 Include files skipping aaa 21 Index EG Ge nn 7 96 Index entries deleting Ai ES Ge 54 Index entries forcing aaa 54 Index entries Roman tYDe EE Ee ee 54 Index entries typewriter type 54 Index entries underlining 54 Index entries user format 00 54 Index name of 113 Index stand alone 0 cece aaa 103 Indexes merging aaa 105 Indexing commands iis SE ge ee eee 54 Information options 37 Initialization file 10 0 ee eee eee 108 Input line number of 72 Installing FWEB ee oa aaa 132 Intrinsic functions aa 18 Items joining 57 J Joining items hn 57 K Keyword RCS EE EE cece 72 73 Keyword RCS like 0 0 ee eee 50 Keywords 1 O 0 cece cece cece eee 18 87 L Language number esses 74 Language determining aa 74 Language determining the 74 Language global aaa 83 Language setting a 18 45 83 Languages aaa 83 La TEX ee SG EG aaa 93 LaTEX section 95 LaTEX2e occ enn ee 93 Left brace inserting iis aaa 41 Length of string 0
59. is printed saying where further help is available It refers one to the various information options see Section 4 2 82 Info options page 37 and the on line documentation see Chapter 15 Support page 131 If the stand alone info program the GNU hypertext browser is installed one can enter info FWEB at this time by typing or a space separated list of FWEB menu items such as Macros FWEB built in PI In fact since PI appears in the detailed node listing one can simply type PI More generally one can type anything that info accepts on its command line the option f FWEB is implicit One can bypass the printed message and directly enter info by specifying the info arguments as arguments to h For example on a UNIX system one could type h PI Here the dollar sign must be escaped because it has special significance to the shell and the quotes are necessary in order to preserve that escape character as the argument is supplied to info To get to the top level FWEB info directory type h or h 4 2 19 I Append to search list for include files The fundamental search list for include files read in via i or I is defined by the environment variable FWEB INCLUDES which is a colon delimited list such as setenv FWEB INCLUDES usr fweb other stuff The I option appends to this list For information about include files see Section 5 5 9 ATi p
60. limbo end ec eee 120 line char ccc ss es ee se hen 119 line length sesse se Es se ee ee nne 119 M MACLOS ec cette tees 119 mark defined exp type 115 mark defined fcn name esses 115 mark defined generic name 115 mark defined outer macro 115 Parameter index mark_defined typedef_name 115 mark defined WEB macro esses 115 MCCA ES ehh hh hen 120 meta bottom seeessee en 119 meta bottom hdr 0 eee eres 119 Meta prefix ccc cece en 119 meta prefix hdr eee eee 119 meta tOP eee cece ehh 119 meta top hdr sess ene 119 modules info nh 114 modules postamble Es es se ee eee 114 modules preamble ss ss se EE ke ee ee 114 modules teX is SE eens 114 N null file ss SS ES SE Se nn 120 142 O outer def cette eee 119 outer under cee ccc eee nnn 119 preamble named ce ieee eee eee ee 120 preamble unnamed 0 EE Se ee Ee 120 protect ss ss ee een 119 SUFFIX eens 119 underline prefix ccc cece eee eee eee 114 underline suffix a 114 Short Contents FWEB oo ss see ees sesse ees ss ee Hh hh 1 F WEB Copying Permissions 2 1 INTRODUCTION to FWEB 3 2 WEB CONCEPTS ss sesse esse esse esse mn 5 3 FILES sesse esse sesse ss see ns 12 4
61. macro construction output by FWEAVE is Mpgi HH possible action macro page number Here the name pg is the value of makeindex page The action macro is something like underline which would be used by FWEAVE to underline the page number to indicate where a variable is defined A default definition of pg is given is fwebmac sty It is a three argument macro def pg 1 2 3 where the arguments are as follows 1 Integer file identification number 2 Action macro 3 Page number The definition should contain the construction 2 3 e the page number must be the argument of the action macro The first argument is left empty in the idx file written by FWEAVE This can be filled in later by the utility idxmerge see Section 11 3 Merging indexes page 105 that merges the indices from several web files For example in a master index one might ultimately print page numbers like II 5 where II refers to a file such as test2 web To aid this merging process the root name of the web file is written as a comment at the top of the idx file output by FWEAVE 11 3 Using the idxmerge utility to merge indexes In a large project one may maintain and work with several FWEB files It may be useful to produce a global index that spans all of those files To this end the utility idxmerge and associated La TEX package idxmerge are supplied with the FWEB distribution 11
62. may be opened by means of the 0 see Section 5 5 20 ATO page 47 or o see Section 5 5 21 ATo page 47 commands Depending on the situation some of these files may remain open simultaneously The maximum number of such files is controlled by ynf 12 2 2 22 yop Maximum number of entries in the table for operator overloading In FWEAVE the appearance of an operator can be changed overloaded by means of the v command see Section 5 5 27 ATv page 49 Each such operator is entered into a table the maximum size of which is controlled by yop 12 2 2 23 yr Maximum number of cross references The Index cross reference information in which sections each identifier is used or defined is maintained in a large array of structures one structure for each cross reference The maximum number of cross references is controlled by yr 12 2 2 24 ys Maximum number of scraps The maximum number of scraps is controlled by ys For a discussion of scraps see Section 4 2 2 1 page 16 12 2 2 25 ysb Size of style file input line buffer The maximum length of each input line of the style file fweb sty by default is con trolled by ysb 12 2 2 26 ytt Maximum number of tokens that FTANGLE can process A token is an identifier numerical constant operator etc FTANGLE must read in and store all tokens in the entire source file because they can be out
63. next time the web source is tangled In an attempt to discourage messing with FTANGLE s output file all unnecessary spaces are deliberately removed A common way of integrating FWEB into ones program development is to do all com pilations through a make file into which one puts an extra dependency line that explains how to produce the compilable output file from the web source For example test c test web ftangle test test o test c gcc c test test c With this approach one is not so tempted to edit test c FWEB development is now based on LaTgX Plain TEX is no longer supported For detailed descriptions of the La TEX support see Section 10 1 3 LaTeX page 93 2 2 The structure of a web An FWEB source file is structured into sections which correspond to logical subunits of the code either a function or a fragment of a function Each section consists of three parts each of which is optional the 1 TEX part 2 definition part and 3 code part When FTANGLE outputs code it can combine the code parts of possibly noncontiguous sections into larger units called modules as explained in Section 2 3 Modules page 8 With the aid of sections one s possibly huge and logically complex code can be broken down into bite sized pieces each one easily comprehensible Since sections may correspond Chapter 2 WEB CONCEPTS 6 to only a small part of a function or subroutine 1000 line main programs they still exist
64. or optional line break In the TEX documentation part of a section inserts a vertical bar Here s a LaTEX example begin verbatim The constructions x and x are very different end verbatim You might wish to try this out to see what FWEAVE produces In a code part inserts an optional line break in an expression 5 12 5 Blank line forces a line break with some extra vertical white space However note that blank lines in the source are significant so this command should seldom if ever be necessary if is immediately followed by a letter e g if it is assumed that a preprocessor command is beginning See Section 7 3 Preprocessing page 80 Chapter 5 FwEB COMMANDS 57 5 12 6 Cancel line break is analogous to TEX s tie it prevents a line break which FWEAVE usually inserts after each complete statement it recognizes For example printf Working 0 fflush stdout x y break 5 12 7 amp Join items During FWEAVE s output amp joins the items to either side with no spaces or line breaks inbetween This command must be distinguished from the preprocessor construction paste to kens together In a macro definition a bc creates the single identifier abc If one said a kbc two identifiers would be output with no spaces separating them In simple cases the results may look identica
65. or vice versa 2 Bilevel This is for terminals that don t support true color but do support a double bright mode and reverse video Colors are mapped onto various combinations of those two display attributes according to an internally defined scheme For example red is mapped onto the pair of escape sequences md mr double bright mode in reverse video 3 Trilevel As above but adds underlining capability 4 User defined colors This implements a minimal set of defaults It is intended that the user add definitions in the style file to override those defaults Chapter 12 CUSTOMIZATION 118 The mechanism is intended to work with systems that support the termcap library The terminal is controlled by writing appropriate escape sequences to it The style file parameters that store the escape sequences are the color name preceded by Color note the upper case C e g Color red For cases like reverse video standard termcap abbreviation mr the escape sequences are determined by querying the termcap database usually etc termcap through the termcap library functions For ANSI color color mode 1 ANSI escape sequences are hard coded into FWEB One can see the escape sequences F WEB assigns to colors by saying ftangle ZColor For any non zero color mode one can override FWEB s default choices for color map pings and escape sequences by redefining one or more of the Color parame
66. print the keyword name itself surrounded by double angle brackets If the keyword was local k the brackets will carry the subscript 0 e FTANGLE treats the global command K Keyword gt essentially like it does Keyword except that the construction is expanded on input rather than output e FTANGLE expands the command k keyword gt on input generating a quoted string containing the value of the local keyword The command z is also used in change files to end a change See Section 3 3 Change files page 13 5 6 Conversion to ASCII Several commands are useful for generating machine independent code For example FWEB works internally with the ASCII character set so uses these commands heavily to convert from the possibly non ASCII native character set of the machine on which FWEB is running 5 6 1 Convert character to ASCII The construction c converts c to its ASCII value In C and C it is converted to octal for example A is output as 0101 In FORTRAN and RATFOR it is converted to decimal the previous example would be output as 65 If the native character set of one s machine is ASCII the conversion will not be done unless the A command line option is used See Section 4 2 5 A_ page 17 5 6 2 Convert string to ASCII The construction G abc converts the enclosed string to its ASCII representation For ex
67. reference information including in C and C the scan ning of include files for typedef and or class declarations see Sec tion 4 2 17 H_ page 20 stores limbo text definitions made with 1 see Section 5 5 14 ATI page 45 collects information about overloaded operators v and identifiers W See Section 5 5 27 AT v page 49 and Section 5 5 28 ATW_ page 50 2 outputs limbo text outputs special TEX macros for overloaded operators copies TEX material directly to output treats material between vertical bars as code to be typeset tokenizes and stores contents of each code section analyzes code syntax and converts it to appropriate TEX macros 3 writes out cross reference information To eliminate some of that see Sec tion 4 2 67 x page 34 Specifically it writes out the Index INDEX tex by default but see Section 3 2 Output files page 13 and Section 12 3 1 Index params page 113 writes out a list of named modules MODULES tex by default but see Section 3 2 Output files page 13 and Section 12 3 2 Module params page 114 writes out macros to generate the Table of Contents Table of Contents information is actually processed by La TEX not FWEAVE The information is written to the aux file Chapter 3 FILES 12 3 FILES FWEB works with a variety of files File names have the form path rootL ext where t
68. some preprocessing of the FORTRAN source before it feeds it to the cores of the processors 4 2 42 n Reverse array indices ForTRAN FTANGLE This somewhat experimental flag permits FORTRAN programmers to use C style array indices Conversions such as the following are made during the output phase of FTANGLE a k i gt a i k a k i j gt ali j k a k j i gt ali j k No spaces may intervene between and C effectively C is treated as one token for the purposes of n This feature permits convenient definitions of macros that deal with multi dimensional vectors Chapter 4 RUNNING FWEB 28 Unfortunately FTANGLE doesn t fully understand the syntax of the source code and never will unless it is fully integrated with a compiler It will therefore be confused by situations like the following FORTRAN example dimension x 0 4 1 2 OK character 90 ch 4 OK write 6 x i j i 1 2 j 3 4 Will reverse incorrectly c ch 4 3 4 Shouldn t reverse but will One solution due to Charles Karney is to insert a space to prevent C from being rec ognized as a single token However since ordinary white space is eaten on input one must resort to something like the following UNQUOTE is a built in FWEB function see Section 7 2 3 64 SUNQUOTE page 78 m SP UNQUOTE a dimension x 0 4 1 2 character 90 ch 4 write 6 SP x i j i 1 2 j 3 4
69. string through unchanged param Don t expand argument param Convert parameter to a single quoted string no expansion param Convert parameter to a double quoted string no expansion 0 Number of variable arguments n n th variable argument counting from 1 0 Like 0 but the argument may be a macro expression known at run time itn Like n but the argument may be a macro expression Chapter 7 MACROS and PREPROCESSING 66 LO The total number of arguments fixed variable The argument inside the brackets may be a macro expression n The nth argument including the fixed ones counting from 1 The argument inside the brackets may be a macro expressions Comma separated list of all variable arguments 0 Unique statement number expanded in phase 1 nnn Unique statement number for each invocation of this macro ex panded in phase 2 lt Begin a module name Internal comma doesn t delimit macro argument A few examples of the more important of these tokens are as follows c m FPRINTF fmt fprintf fp fmt Use the whole list of variable args m BC printf There were hi arguments n 0 Use the number of var args n m DONE 0 Symbolic statement label in FORTRAN a goto DONE DONE call endup 7 2 3 Built in functions Built in functions behave in most ways like macros In some cases they actually are macros but other times they impl
70. the fwebmac sty macro WARRAY This macro takes one argument which is just the array index or indices In C indexing like a i j k generates the argument i j k By default WARRAY just surrounds its argument with brackets However the user may change its definition to get special effects such as superscripted or subscripted indices A simple example macro WSUB is provided in fwebmac sty one can say let WARRAY WSUB in the limbo section to have bracketed indices print as subscripts This feature may not work when the contents of the brackets are too complicated so that F WEAVE tries to typeset them by going in and out of math mode For more information experts can see fwebmac web command WXA 4 2 65 4 WH Send additional arguments to the C preprocessor When the H option see Section 4 2 17 H_ page 20 is used the C preprocessor is invoked to scan include header files for typedef s and class declarations That is called with a standard set of options Presently gcc is actually called to invoke the preprocessor it is sent the options E P and I Occasionally it may be necessary to send additional options Those can be specified as the string argument to WH Thus to define two macros to the preprocessor one could say either of WH Dtesti 1 WH Dtest2 2 WH Dtesti 1 Dtest2 2 The first form shows that WH accretes to
71. the style file parameter index name see Section 12 3 1 1 S index page 113 For more discussion of FWEB s indexing facilities see Chapter 11 Index page 103 Minor unnamed sections are begun by at space these have no associated names and are not entered into the Table of Contents A newline counts as a space 2 2 0 2 The TEX part All sections begin with optional TEX commentary That can just be straight text to input that no knowledge of TEX is required It can also include mathematical exposition or any of the other advanced features offered by TEX Whenever FWEB is in TEX mode one can temporarily shift into code mode by enclosing the code within vertical bars That code is typeset just like code in the code part see below except that newlines are replaced by spaces Thus one can say things like Consider the C code fragment c for i 0 i lt 10 i which If the global language were C instead of FORTRAN the c inside the vertical bars would not be necessary The ability to switch back and forth between text mode and code mode at will allows for a very convenient and flexible style of exposition 2 2 0 3 The definition part The TEX part is followed by an optional definition part The beginning of the definition part is signaled by the appearance of any one of the commands d f m v or OW explained later In the previous example the first sectio
72. they are present and treats the result as a collection of characters No tokenization is done so macro expansion does not operate on those characters For a more detailed discussion and a comparison with UNQUOTE see Section 7 2 3 64 SUNQUOTE page 78 see Section 7 2 3 1 Strings and quotes page 67 7 2 3 66 VERBATIM Obsolete This was an old name for UNQUOTE see Section 7 2 3 64 SUNQUOTE page 78 Please remove all references to this macro from existing codes 7 2 3 67 VERSION Present FWEB version number VERSION returns a string built out of the FWEB version number such as 1 61 Chapter 7 MACROS and PREPROCESSING 79 7 2 4 Debugging with macros If an FWEB macro expands to more than one output line debugging can be a bit confus ing if the debugger e g gdb displays lines in the web source file instead of the output file as it normally does for C and C While single stepping through the code the debugger will incorrectly step the screen display for each output line even if the macro call occu pies just one line in the source file To localize the debugger s confusion insert a line command after the macro call For example c Example of a macro that expands to several output lines m UPDATE i delta_i i delta_i store i a main 1 UPDATE j 5 line More code The debugger will be in sync from here on An alternative for highly confusing situations is to us
73. this package was tricky It may work in simple circumstances but it is not fully debugged e The FWEBinput command surrounds the included TEX code with begingroup endgroup J in an attempt to prevent various macro conflicts As it stands the command fwebinput is let equal to FWEBinput If necessary one could redefine fwebinput to not include the enclosing begingroup endgroup e For anything except level 0 inclusions one should have just one FWEBinput command following each sectioning command This is a bug e One is supposed to be able to use the package fwebnum see Section 10 1 6 Numbering page 98 in conjunction with fwebinsert One can apply that to either the included file via a LaTeX package entry in fweb sty the including file via a usepackage command or both Try out these various combinations to see what emerges 10 2 Pretty printing Pretty printing refers to FWEAVE s attempt to typeset and highlight the code in a read able way This is usually done automatically for all of the compiler like languages such as C However it can be inhibited by turning on the N mode with N or by using the VERBATIM language selected with Lv Pretty printing is one of those topics that can arouse strong passions your idea of what s esthetic may not be mine Unfortunately FWEB s formatting rules are mostly hard coded so if for example you don t like the way braces are arranged in typeset C cod
74. this single character string is sent to the output it is treated like any other expression and therefore would appear in column 7 or greater even if the construction appeared at the very beginning of the line On the other hand PP is essentially defined as UNSTRING which is internally the single character amp Because this character is not a string the FORTRAN output driver treats it as a special control character defined in this case to force the character into the first column 7 2 3 2 Redefining built in functions By default built in functions are protected that is they may not be redefined by an m command To do so cavalierly invites many kinds of weird disasters If it is absolutely necessary to redefine a built in function use the command line option Tb see Section 4 2 59 2 Tb page 31 Many of FWEB s built in functions are in fact ordinary macros that are implemented in terms of lower level built ins An example is POW see Section 7 2 3 48 SPOW page 76 which is constructed from the built in function EVAL see Section 7 2 3 17 SEVAL page 70 By default such macros are also protected against redefinition to override use the option Tm see Section 4 2 59 3 Tm page 31 Chapter 7 MACROS and PREPROCESSING 68 7 2 3 3 A Convert to ASCII A string is the built in equivalent of or See Section 5 6 AT quote page 51 and Section 5 6
75. to be complete statement may not be formatted as one might expect Thus the construction 15 continue doesn t format quite properly the colon disappears this problem is solved by putting a semicolon after the continue Also if one is talking about multiple statements for example with a shift into code mode during TEX documenta tion there s no choice but to insert the semicolon between statements For example la b c d l 8 2 3 3 Items specific to FORTRAN 90 Chapter 8 LANGUAGES 88 e If FORTRAN 90 is selected see Section 4 2 31 n9 page 24 the default is free form syntax lines are continued by a trailing ampersand However automatic line breaking is done in a way compatible with fixed form syntax as well e With free form syntax comment lines in the tangled output file begin with But such lines are not recognized on input unless n is used See Section 4 2 41 n page 27 e Beginning with Version 1 61 by default pseudo semicolons are automatically inserted in free form Fortran 90 code as one would expect For more discussion see Sec tion 4 2 32 nAT page 24 and Section 4 2 33 n page 24 To be completed 8 2 4 Special considerations for RATFOR For some warnings about RATFOR see Section 9 3 Caveats page 90 8 2 5 Special considerations for TeX Lx is supported only to the extent that fwebmac sty can be generated correctly from fwebmac web You are welcom
76. with nested comments and FWEAVE will continue to format the code as code so the documentation will make sense For FORTRAN programmers converting an existing code to FWEB the nC option see Section 4 2 36 nC page 25 may be helpful Chapter 7 MACROS and PREPROCESSING 62 7 MACROS and PREPROCESSING FWEB offers a built in preprocessor facility especially useful for FORTRAN programmers It is closely patterned after the C C preprocessor but with some extensions such as variable numbers of arguments In addition there are some built in functions that provide functionality that cannot be emulated by user defined macros When working with a language such as C that has its own preprocessor the question arises when to use that and when to use FWEB s facilities The answer generally comes with experience Remember that FWEB s macros have been expanded by the time the tangled output file is produced whereas language specific preprocessor commands are just passed through to that file If you re a FORTRAN programmer strongly consider the use of FWEB s macro facilities they will simplify your present and future life by creating more legible codes and reducing programming errors by eliminating redundant pieces of code C C programmers may also appreciate the preprocessor extensions In addition to conventional macro processing FWEB also offers the convenience of cer tain built in functions that behave in many ways like macro
77. writing various messages to the ter minal in color e g serious error messages might appear in red This feature was motivated by the color 1s of Linux It is installed automatically if the termcap library is present Messages output from FWEB are ranked according to an internal message type table each type can be associated with a color that can be changed in the style file Presently the message types hopefully self explanatory are ordinary program_name mod_name info warning error fatal mod_num line num in file include file out file timing The associated style file parameters are the above names prefaced by color e g color warning Each of those has a default value such as color error red Those defaults can be displayed by saying ftangle Zcolor What the color actually means in practice depends on the color mode set by the C option see Section 4 2 8 C_ page 18 That selects one of several primitive palettes as follows 0 No color ordinary black and white output This is the default and the mode used when the termcap library is not present 1 ANSI color With a color terminal that supports ANSI color es cape sequences one has available the following colors black red green yellow blue magenta cyan white and default These are displayed with bold attribute that is bright not dim default stands for the usual black on white background
78. x x Precisely equivalent to the previous example The equals sign is permitted only with command line macro definitions not with m commands see Section 5 5 16 ATm page 45 in the definition parts of the web file Chapter 4 RUNNING FWEB 24 4 2 28 m4 Understand m4 built in commands This tells FWEAVE to properly format the reserved words of the m4 preprocessor The use of that preprocessor is not recommended in conjunction with FWEB use FWEB s built in C like preprocessor instead 4 2 29 m Append pseudo semicolons When m is in effect the construction is appended automatically to all FWEB macro definitions This option is not recommended Please insert the by hand when necessary as in m SET x y x 1 y 20 m TEST x if x y else z 4 2 30 n Set global language to FORTRAN 77 This is FWEB s default so it generally does not need to be used explicitly See also the discussion of Section 4 2 24 L_ page 22 However variants of this option as described below may be useful See also Chapter 8 Languages page 83 and Section 8 2 3 Fortran page 85 4 2 31 n9 Set global language to FORTRAN 90 See Chapter 8 Languages page 83 and Section 8 2 3 Fortran page 85 see also the discussion of L in Section 4 2 24 L page 22 4 2 32 n Supply automatic pseudo semicolons FORTRAN Don t forget that a semicolon has special me
79. 0 Brackets active 0 0 0 0 cece cece aaa 33 Breakpoints inserting a 41 Breakpoints suppressing a 41 Bugs hh hn 131 Bugs version 1 61 ee aaa 126 built in functions redefining 31 Bullet aa 114 Bullet subscript 0 cece eee eee es 115 C C hints 0 ee ence ene 84 C hints hh 85 Case changing cece eee ee eee ee 73 78 Class OptionS 0 0 cece cence eee eens 93 Code mode cece EE SG Ge eens 7 Code part beginning unnamed 40 Code converting to FWEB 4 121 Code temporarily commenting out 61 86 Code typesetting aaa 7 Colon pseudo EE EE EE GE es 59 COlOT EE a 117 Color mode ANSI AE aaa 117 Color mode bilevel esee 117 Color mode trilevel 000 000 eee eee 117 Color mode user defined suuuuu 117 133 Color and message types 00005 117 Color ANSI 0 0 117 Color setting is Eg e 18 Columns multiple 96 Commands redefined ie 124 Commentary optional 7 Commenting styles ii SS ge ee ne 60 Comments AE eee nee 52 60 Comments FORTRAN ss se ee ee ee 27 Comments generating 0 sees eae 68 Comments ignorable 00 eee eee 52 Comments ignore single line Fortran 25 Comments invisible 00c cece eee 60 Comments short aaa 37 86 Comments
80. 000 ee ee een 77 DECR oo SS 69 STRING nannaa naaraana narre teen eens 77 SDEPINE sss 69 STUB 3o 77 BDO LL sese essa ess sanas g9 EE e di DUMPDEF ees 70 TRANSLIT ssssssssssss n 78 SE 70 PU 0 ehh 78 SERROR ooo sss 70 UNDEF ee ccc cee en 78 EVAL sss 70 SUNQUOTE 2 2220 en 78 EXP ie ebb bb bebe beer 71 SUNROLL 2222020 cence m e 70 SGETENY ess 71 UNSTRING ee n 78 HEADER ess 71 VERBATIM Ge ccc cee n 78 HOME ooo esu 71 VERSION noana e cece cece en 78 SID ee ehh 71 IE eee haha 71 7 SIFCASE 2 22 71 DENM 15 SIFDEF 22 se a 72 AA 37 SIFELSE oma 72 IMEEM 36 87 SIFNDEF 222 5200 0 en 72 A SE Se ee Se Se ee Se See ee ee ee 36 SINGR AE EG Ee Ge en ee ent ee ee ee 72 Ta 35 SINPUT LINE ee ee ee ee e 72 EE EEEa 37 KEYWORD ee ee ee n 50 72 EM 36 EE nnana anaana raaraa 73 EE EEE 36 L_KEYWORD ee ee n 50 73 EE 16 SLANGUAGE 22 74 EE EEEE EEEE EEEE 37 87 LANGUAGE NUM 74 AA 36 SLEN een 74 DAMEN 35 LOCKER ssssssssssss een 75 SEMEN 16 LOG M 75 HQ nec n tenet ented een enns 16 L0G10 EE EG Ee Ge Ge ee ee ee ee 75 AL EOE 17 J AA 75 Sh e ee aea 17 MAX ccc ccc cect ete Ge ee ee ee ee 75 EE a arare aaaraaaraarn 17 SMIN ee ee Ge Ee Ge ee Ge ee ee ee ee 75 TG nannaa EAEE AAEE EEEE EEEE 18 MODULE NAME ee ee Gee ee n 75 HG EEEE 17 117 SMODULES onnon cc ccc ee ee ee ee 75 SL SEMEN 18 TE e eee tent te nates 75 a AA 19 Option
81. 1 This can be done by specifying the package fwebnum as in Chapter 10 DOCUMENTATION 99 LaTeX package fwebnum This package is supplied with the FWEB distribution it is still somewhat experimental By default fwebnum numbers all sections including unnamed ones To prohibit num bering of unnamed sections use the package option dontnumberunnamed as in LaTeX package options dontnumberunnamed This option will eventually make numberTeX obsolete do not use numberTeX in conjunc tion with fwebnum 10 1 6 1 Package fwebinsert Inserting FWEAVE s output into a La TEX document Beginning with version 1 61 it is barely possible to insert the TEX output woven by FWEAVE into a La TEX document For example a code listing could be an appendix to a dissertation or a handbook on numerical methods could insert fragments of code formatted by FWEAVE Suppose one has the file test web and used FWEAVE to create test tex Unfortu nately it does not work to simply Vinput test tex into a La TEX document because by default test tex operates in a stand alone mode and tries to issue a begin document command Instead one must use the package fwebinsert and the special input command FWEBinput Jj as in the following example There are two important steps 1 Use FWEAVE to create test tex You may wish to use the x flag see Section 4 2 67 x page 34 to prevent some of the lists at the end such
82. 3 1 Using idxmerge Summary As quick reference for those who have already plowed through the following details here is a summary of the procedure To print a stand alone index by merging the indexes from several web sources do the following First create if necessary a file index tex that inputs index ind Then Chapter 11 FWEB s INDEX 106 fweave XI testi web fweave XI test2 web fweave XI test3 web idxmerge oindex testi idx test2 idx test3 idx 4 Creates index ind and index names tex makeindex s testi sty index latex index Note the use of the XI option For further background see the previous section Section 11 2 Using makeindex page 103 11 3 2 Using idxmerge Details Suppose one has three files test1 web test2 web and test3 web To use idxmerge weave each of the files separately using the XI option to create test idx and test sty Then say idxmerge oindex testi idx test2 idx test3 idx This creates two output files index idx and index names tex idxmerge first sorts the list of file names It then writes one entry into index names tex for each file of the form idxname n file_namen This file can be input by the topofindex command for an example see the La TEX2e package idxmerge supplied with the FWEB distribution and used to create a list of the merged files Then it merges the indexentry commands from each of the input files int
83. 5 8 1 Begin long verbatim comment 52 5 8 2 Begin short verbatim comment 52 5 8 3 0 Ignorable comment 0 6 52 5 8 4 Begin compiler directive 53 5 8 5 Begin meta comment 065 53 5 8 6 End meta comment 53 Special left brace EE SS EE ce eee ee ee 53 Index entries 0 eee cece ee eee aee 54 5 10 1 _ Force index entry to be underlined 54 5 10 2 Delete index entry 54 5 10 3 Force index entry a 54 5 10 4 Make index entry Roman type 54 5 10 5 Make index entry typewriter type 54 vi 5 10 6 9 Make index entry user defined format 54 5 11 Control text EE SS EE ehh 55 5 11 1 t Put control text into a TEX hbox FWEAVE EE ee nee tenn hehehe 55 5 11 2 Pass control text verbatim to the output 55 5 12 Spacing ee ce cee hh hh 55 5 12 1 Insert a thin space 55 5 12 2 Force a line break preserving indentation Mesh hne hehehe hh terete tenes 55 5 12 3 V Force a line break then indent 56 5 12 4 Literal vertical bar or optional line break 56 5 12 5 Blank line a 56 5 12 6 Cancel line break 0 57 5 12 7 amp Join items
84. DOCUMENTATION 95 journals It modifies the sectioning commands of documentclass article and provides various other useful macros Unfortunately as of August 1998 REV TEX is not fully compatible with LaTpx2e it must be invoked with documentstyle revtex not documentclass This is annoying because FWEB s macros in fwebmac sty default to documentclass if they recognize that LaTEX 2e is loaded To use REV TEX uncomment the line in fwebmac sty that says useREVTeXtrue One cannot say useREVTeXtrue in the limbo section of one s web source because the document class has already been selected by that time You may wish to rename the resulting file say to rwebmac sty so it can be loaded in place of the standard fwebmac sty To do that one would use the command line option wrwebmac sty see Section 4 2 66 w page 34 Saying useREVTeXtrue selects documentstyle rather than documentclass To im plement a standard command such as documentstyleLaps my_macros revtex use the style file fweb sty parameters LaTeX style and LaTeX options as in LaTeX style revtex LaTeX options aps my macros Here my macros sty would be a user s macro package loaded in addition to those of REVTEX and FWEB REVTEX support is extremely recent There may be glitches please report those In a pinch if La TEX stops while processing a REV TEX file produced by FWEAVE try typing s scroll mode t
85. E as it writes the output file However in the TEX language such deletions can change the behavior of the output by introducing extra spaces Therefore TEX comments that do not begin a line are always retained unless the T option is used This option has no effect for languages other than TEX 4 2 59 6 T Don t insert line command after 0 If the f command see Section 5 8 3 AT page 52 is used to comment out a line it eats the trailing newline An undesirable consequence of this is that if nothing is done the subsequent line numbering will be misunderstood by a debugger at least until FWEB inserts a line command for some reason To prevent this FWEB inserts by default an implicit line command see Section 7 3 Preprocessing page 80 after each that Chapter 4 RUNNING FWEB 32 begins a line To prevent this from happening possibly because the feature doesn t work correctly in which case you should report it see Chapter 15 Support page 131 use the T option 4 2 60 t Truncate identifiers The truncation option enables one to use a wider character set for identifiers than the language compiler will accept The standard example is vanilla flavored FORTRAN 77 which doesn t allow the underscore If one says tn6 _ underscores will be removed from all identifiers then the result will be truncated to length 6 If the truncation procedure results in no
86. EG eee eee eee 74 Level message SG Ee aaa 23 Limbo section 00 eee en 8 Limbo texts eg e 45 Line break canceling aaa 57 Line break forcing 0 cece eee eee 55 Concept index Line break forcing with indent 56 Line break optional 0000 eee 39 56 Line number iis eee eee eee 76 Line numbering turning off 48 Literate programming 0c eee ee eee 3 LOCK oo an 75 Logarithms base 10 aaa 75 Logarithms natural aa 70 75 Lower case aaa 73 EG GER hh hh 62 Macros absolute value of ss ss ss se 68 Macros debugging aaa 70 Macros debugging with aan 79 Macros decrementing aaa 69 Macros deferred iiie 31 Macros defining iii ee se 69 75 Macros evaluating iis ee aaa 70 Macros formatting aaa 79 Macros FWEB ss se ee ee es se se ee ee ee ee 63 Macros incrementing ie aaa 72 Macros inhibiting expansion of 59 Macros outer 0 cece ete 62 Macros preprocessing 0 00s eee eee 80 macros redefining ee e esse ee ee eee 31 Macros redefinition of 0 eee eee ee 64 Macros repetitively defining 69 Macros special tokens for aaa 65 Macros undefining 0s eee ee ss 78 Macros with variable arguments 64 Majo
87. EX text Within any TEX text including comments constructions delimited by signify a temporary shift into code mode In the present design one cannot enclose a comment within the vertical bars 2 3 1 The unnamed module The unnamed code module is introduced by the command a Subsequent uses of a accrete code to the unnamed module To repeat the fundamental operation of FTANGLE is that F TANGLE outputs the unnamed module Thus there must be at least one a in the source file or FTANGLE will output nothing Why is the command called a Historically it was the first letter of the alphabet as befits its prominent status However one can also think of it as accrete Chapter 2 WEB CONCEPTS 9 2 3 2 Named modules Named modules represent logically connected fragments of code A module name is specified by the construction lt Arbitrary TEX text 0 Leading and trailing white space around the name text is ignored The name text can include the construction which tells FWEAVE to typeset a code fragment Thus module names can be highly explicit for example lt Check that x gt 0 0 labort if not To define a named module replace the a that begins the unnamed code part of a section by lt module name gt If one uses this construction with the same name in a later section the effect is to accrete to the contents of the module Thus a named modu
88. EYWORD Keyword extracts as a character string the text of an RCS like key word defined in the ignorable commentary between z and x at the beginning of a file included via i SL KEYWORD local keyword is expanded during input and the results are known only during the time the include file is being read Chapter 7 MACROS and PREPROCESSING 74 Note that the argument of SL KEYWORD must be a quoted string For more discussion of the distinction between local and global keywords please see Section 5 5 31 ATz page 50 and Section 7 2 3 30 SKEYWORD page 72 It is expected that local keywords will rarely be used as fundamental revision control information should presumably be extracted from the top of the master web file 7 2 3 33 LANGUAGE Identifier for current language This expands to an identifier that denotes the current language as follows Language LANGUAGE C C CPP Fortran N Fortran 90 N90 Ratfor R Ratfor 90 R90 TeX X VERBATIM V Note that this outputs identifiers not FWEB macros They are intended to be used in IF or IFELSE statements such as IF LANGUAGE C C text other text For multiway switches the LANGUAGE_NUM built in is more useful see Section 7 2 3 34 SLANGUAGE NUM page 74 7 2 3 34 LANGUAGE NUM Number of current language LANGUAGE_NUM expands to an integer that uniquely defines the current language as follows Language
89. FWEB A WEB system of structured documentation for multiple languages By John A Krommes Copyright 1993 1998 John A Krommes Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies Permission is granted to copy and distribute modified versions of this manual under the con ditions for verbatim copying provided also that the section entitled Copying is included exactly as in the original and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one Permission is granted to copy and distribute translations of this manual into another lan guage under the above conditions for modified versions except that this permission notice may be stated in a translation approved by the author FWEB 1 FWEB This Texinfo documentation describes FWEB Version 1 61 e To learn about new features of this version see Section 14 1 V1 61 page 124 e For a quick introduction to and review of the structure of an FWEB source file see Section 2 2 Structure page 5 e If you used to receive e mail information about FWEB but don t any longer it s probably because you need to update your e mail address in the fweb users mailing list Subscription instructions can be found in Chapter 15 Support page 131 e Bug reports and suggestions are much appreciated but
90. NG 80 Other types of troublesome situations involve spaces When FWEB understands the syntax it inserts spaces automatically to make the output pleasing Consider however the somewhat contrived example c d A x y x y 0d B s1 d C s2 a AB C 0 Here FWEAVE will consider x and y to be ordinary identifiers simple expressions and will abut them with no intervening spaces which is confusing to read The solution is to insert a space manually with d A x y x OG y Whether one should write macros like this at all is a separate issue For a related example see the discussion of Section 5 12 ATcomma page 55 7 3 Preprocessing Generally the FWEB preprocessor commands follow a syntax identical to their C C counterparts The one exception is the line command Whereas the C command takes a line number and file name as arguments the FWEB command takes no arguments its expansion automatically inserts the current line number and file name This command should be necessary only in rare circumstances One of those involves situations in which an FWEB macro expands to more than one output line see Section 7 2 4 Debugging with macros page 79 The FWEB preprocessor commands may appear in either the definition or the code parts But BEWARE No matter where they appear they are expanded during INPUT not output This is probably a design flaw For more discussion see Section 7 2 FWEB macr
91. RANSLIT s from to interprets each of its arguments as strings without expanding anything Then s is modified by replacing any of the characters found in from by the corresponding characters in to If to is shorter than from then the excess characters in from are deleted from s As a limiting case if to is empty then all the characters in from are deleted from s For example TRANSLIT s aeiou 12345 replaces the vowels in s by the corresponding digits and TRANSLIT s aeiou deletes all the vowels The backslash may be used to escape a character as in ANSI C For example TRANSLITC a d a Na D A translates into A D Here one had to explicitly enclose strings involving AN in double quotes in order to avoid a complaint about an unterminated string 7 2 3 62 U Change to upper case U string changes string to upper case 7 2 3 63 UNDEF Undefine a macro SUNDEF macro undefines an FWEB macro 7 2 3 64 UNQUOTE Remove quotes from string UNQUOTE string returns string without its surrounding quotes However the result ing construction is still treated as a string no macro expansion is done For a more detailed discussion and a comparison with UNSTRING see Section 7 2 3 65 SUNSTRING page 78 see Section 7 2 3 1 Strings and quotes page 67 7 2 3 65 UNSTRING Convert string into characters SUNSTRING string removes quotes from the string if
92. RUNNINGEWEB ee ss see ee es see ee ss see ese 15 5 FWEB COMMANDS 38 6 COMMENTING STYLES esse sesse sesse ee 60 7 MACROS and PREPROCESSING 0000 62 8 LANGUAGES sees ses sees ss se ht 83 9 RATFOR ce cece cee sees ss see hh 89 10 DOGUMENTATION sees ee ees esse sesse see A n9 91 11 FWEB s INDEX ss see ees sesse ees hh ee 103 12 CUSTOMIZATION ss see ee ees ss esse m n8 107 13 USAGE TIPS and SUGGESTIONS ss ee see ese ees 121 14 NEW FEATURES sesse sees sesse sesse ese ee ee 124 15 SUPPORT sesse es sesse sesse sesse ss es ee se ee 131 Appendix A Installing FWEB esse sesse ss 132 Concept Index sees esse ss ss ss se hts 133 Option and command index sesse ese esse sesse ss se ee 137 Parameter index esse eee sesse ss esse ss ese 141 Table of Contents EFWEB esse ees esse ees ss see Hh e 1 FWEB Copying Permissions ss sees ss see ee 2 1 INTRODUCTION to FWEB 3 1 1 History of WEB and literate programming 3 1 2 Features of FWEB ees ss cee eee eee eee eee 3 2 WEB CONCEPTS see ee 5 2 1 The FWEB processors FWEAVE and FTANGLE 5 2 2 The structure of a web ss 0 EE RE EG cece ee eee ee 5 2 2 0 1 A simple example 6 2 2 0 2 The TEX part 7 2 2 0 3 The definition part 7 2 2 0 4 The code part a 7 2 2
93. TION 96 be warned in such cases If not you will recognize difficulties by noting that the Table of Contents or section numbering is incomplete The aux file is also used by both processors to generate appropriate error messages that refer to the La TEX section number instead of the internal one A discussion of alternative section numbering schemes is given in Section 10 1 6 Num bering page 98 10 1 3 5 LaTEX s index The Index should be the last section of the code and should be begun by the command INDEX For more information see Section 12 3 1 1 S index page 113 The challenge of typesetting the Index is to get it into two column mode in the best possible way In the original Plain T X FWEB special code was provided for this With La TEX however one wants to use standard features The best solution is to use the user package multicol If that is loaded by means of the style file statement LaTeX package multicol then any text typed by the user following the VINDEX command will be typeset in single column mode after which two column mode is entered If it is not loaded a twocolumn command is issued before the index section is begun in order to get the Index started on a new page More precisely what happens is the following When the INDEX command is rec ognized essentially the following operations are performed where the results are bracketed in the form multic
94. TRAN code output 12 3 8 3 cdir start This parameter has the form cdir start l where is one of C Cpp N N90 R R90 X or V The contents of this parameter is written immediately after the that begins a compiler directive Chapter 12 CUSTOMIZATION 119 12 3 8 4 line char l FTANGLE By default FTANGLE outputs comments indicating line numbers in the web file from which the tangled output comes This information can be used by debuggers especially those for C and C to correlate error messages to the web source The line_char parameter sets the comment character that begins the line comment 12 3 8 5 line length l FTANGLE This parameter is used by the FORTRAN like languages to control the length of the output line in the f file produced by FTANGLE For FORTRAN 77 its default value is the venerable 72 For FORTRAN 90 its default is 73 Using that value makes it possible to generate code that is compatible with both fixed and free form format by continuing lines with an trailing ampersand in column 73 and another ampersand in column 6 of the next line These parameters customize the treatment of meta comments Fundamentally meta comments consist of material enclosed by The header information usually written at the top of the file output by FTANGLE see Section 4 2 59 4 Tv page 31 is also treated as a meta comment For that header material
95. You may be relieved to know that to the best of my knowledge FwEB does not suffer from the Y2K bug This info documentation is now accessible on the World Wide Web from http w3 pppl gov krommes fweb toc html You can subscribe to one or both of two FWEB mailing lists fweb users and fweb installers To subscribe send e mail to majordomo pppl gov In the body of the mes sage say e g subscribe fweb users You will receive introductory information describing how these lists are intended to be used To unsubscribe at any time substitute unsubscribe for subscribe in the above instructions Archive files containing the messages sent to the FWEB mailing lists are kept in ftp ppp1l gov pub fweb archive fweb users installers archive In addition to anonymous ftp these files may be obtained by sending a message to majordomo pppl gov of the form get fweb users fweb users archive Appendix A Installing FWEB 132 Appendix A Installing FWEB Here is the bare bones installation procedure for UNIX users 1 Download the zgip compressed tar file from ftp pppl gov pub fweb The name of the file contains the version number e g fweb 1 61 tar gz ftp ftp pppl gov bin get fweb 1 61 tar gz quit 2 Uncompress and unpack the tar file gunzip fweb 1 61 tar gz tar xf fweb 1 61 tar If the GNU tar is installed these two steps can be combined into gtar xzf fweb 1 61 tar gz Unpacking creates the directory fweb 1 61 with at
96. a 76 Root square EE nn 77 Scientific programming 123 Scrap irreducible EE Ge ee 16 Section names lONB ee Ee SE esse ee eee 39 Section names short aaa 39 Section number current 0000e eee 77 Section number maximum sess 77 Section beginning Major 39 Section beginning minor 445 39 Section limbo 0 0 0 e eens 8 Sections aa 5 Sections named ccc eee aaa 6 Sections numbering aaa 98 Sections unnamed 0 cece eee eens 6 Semicolon pseudo cc cece e cece een ee 58 Semicolons automatic 000 24 87 Semicolons printing aaa 26 Sharp sign aaa 76 Spacing commands ce cece eee ee 55 Spacing thin space SE Ee s 55 Square TOO eee 77 State eee hh 77 Statement numbers automatic 36 Statistics printing SG n 30 String length ee GE ee de u 74 136 String definition of 67 String quoted a aaa 67 String quoting a aaa 77 String unquoted 0 cece ds s 67 Strings continuing 35 Strings long aaa aaa 35 Strings parenthesized Ee ee ei 36 Strings unquoting aaa 78 Style file 0 0 cee ene 112 Style file changing name of 35 Style file for makeindeX ii ee ee kk see 104 Subscript bullet EE aa 114 Subsection beginning major
97. age 35 is intended to provide more local customization perhaps differing for each source file and group of source files The style file does not contain command line options rather it contains parameter settings that override FWEB s defaults The p option see Section 4 2 46 p page 28 may be used to specify a style file entry in fweb i e a global value for all source files or on the command line i e a value used for a single run The order of processing is 1 Evaluate environment variables See Section 12 1 Environment variables page 107 2 Read fweb and remember its contents sort those into three groups options beginning with beginning with amp and beginning with a letter file names See Section 12 2 Initialization page 108 3 Process fweb options beginning with or for backward compati bility except for p 4 Read and process command line options except for p See Section 4 2 Options page 15 5 Process remaining fweb options either file names or options beginning with amp 6 Process any p options from fweb See Section 4 2 46 p page 28 7 Process the style file See Section 12 3 Style page 112 8 Process any p options from the command line Unfortunately because not all options are processed immediately when they are read errors may not show up when one expects Fo
98. age 43 4 2 20 i Don t print I include files FWEAVE If a web file is included via I see Section 5 5 10 ATI page 44 for example I formats hweb then the i option means to read and process the web file but don t print its contents This option is often used for large files of macro definitions formats or typedef statements that must be included at the beginning of even very short web files it clutters things up to print such header files all of the time C and C programmers will find that the H option substantially reduces the need to include such header files see Section 4 2 17 H page 20 Chapter 4 RUNNING FWEB 22 Note that files included via i lower case do not respond to i or i By default identifiers that are referenced in non printed include files are not cross referenced or indexed in any way To force them to be cross referenced say ix instead of i In the present implementation the cross reference information for such non printed files is presented in the form n where n is the integer section number The LaTEX section label is undefined for sections in non printed files The option i means skip the include files completely This is usually not very useful 4 2 21 i Don t read I include files If a web file is included via 1 for example I formats hweb then the i option means to ig
99. ample in C and C abc will be output as 141 142 143 In FORTRAN and RATFOR no such simple mechanism exists in the language so a func tion call is issued For example the previous example would be output as ASCIIstr abc fj The user is responsible for defining the function ASCIIstr The name of this function can be changed by the style file entry ASCII_fcn See Section 12 3 8 1 ASCIL fcn page 118 If the native character set of one s machine is ASCII the conversion will not be done unless the A command line option is used See Section 4 2 5 A_ page 17 5 7 Forward referencing Chapter 5 FwEB COMMANDS 52 5 7 1 Mark as defined This command marks the next non reserved identifier that appears after the as being defined in the current section It is usually issued automatically for example a is equivalent to A d is equivalent to D L and m is equivalent to M If the appropriate style file parameter mark defined 7 is 1 this command causes any appearance of the identifier to be subscripted with a section number For more information see Section 12 3 4 Subscript params page 114 The utility of this command can be seen from the characteristic construction This is section 5 Ga Issues an implicit which marks test as defined in section 5 subroutine test end This is section 6 Qa program main
100. and or the I option see Section 4 2 19 I_ page 21 If that path is empty then the current directory is searched name hch Optional change file for include file 3 1 1 Automatic file name completion Automatic completion of input file names is turned on by the e command line option see Section 4 2 14 e page 19 When this option is in effect input file names that include no period have no extension are completed automatically according to the contents of the following style file entries Type of file Style file entry Default WEB file ext web web Change file ext ch ch Include file ext hweb hweb Change file for ext hch hch include file More than one extension may be specified as a space delimited list e g ext web web wb the first one that matches is used Chapter 3 FILES 13 3 2 Output files F WEAVE writes a variety of output files name tex Woven output to be processed with LaTeX CONTENTS tex Temporary file that accumulates Table of Contents infor mation For LaTEX the aux file is used instead INDEX tex Temporary file that stores indexing information MODULES tex Temporary files that stores module list The names of the three temporary files can be changed with style file parameters see Section 12 3 Style page 112 Commonly one may put into the style file fweb sty commands such as index tex ndx modules te
101. aning to UNIX shells so you ll probably have to quote this command n This is the default mode of operation for free form FORTRAN 90 the input driver auto matically appends a pseudo semicolon invisible to each logical line of source code Since it is the default one doesn t have to use it unless one wishes to negate it see Section 4 2 1 Negating options page 16 In that case it is best to place the n command in the source file as n9 n If one places it on the command line be sure to set the language first n9 n6 For free format FORTRAN 90 when n is in effect the default np is also turned on See Section 4 2 37 np page 26 For further discussion see the companion command Section 4 2 33 n page 24 4 2 33 n Supply automatic semicolons FORTRAN Don t forget that a semicolon has special meaning to UNIX shells so you ll probably have to quote this command n This command functions the same as n see Section 4 2 32 n AT page 24 except that actual visible semicolons rather than pseudo semicolons are appended This is the Chapter 4 RUNNING FWEB 25 default mode of operation for FORTRAN 77 and for that language it cannot be turned off by negation The distinction between n and n has to do with what is visible on output In FORTRAN 77 semicolons are not printed by default since that seemed to annoy many us
102. any style file Normally the style file is read from the same directory in which the web source file resides or from the path defined by the environment variable FWEB STYLE DIR To force fweb sty to be read from the current directory say z 4 2 72 Don t recognize dot constants If this command is used the processors will not understand that constructions such as LT are operators in FORTRAN or RATFOR This command is useful if one is trying to modernize the source code to use FWEB conventions such as lt instead of LT 4 2 73 Explicitly escape continued strings In Fwes long strings are continued with the backslash Normally the continuation of the string must start in the first column of the next line otherwise spurious blanks will be introduced However when the option is in effect FWEB expects that the continuation will also begin with the backslash and it will ignore leading white space and the backslash This feature was inspired by FoRTRAN 90 Thus in the example Chapter 4 RUNNING FWEB 36 This is continued the effective string is This is continued when is in effect Note that this option affects all strings in the source file one cannot mix and match 4 2 74 Continue parenthesized strings with backslashes This option is like see Section 4 2 73 page 35 but it refers to certain strings that are not normally quoted
103. are first defined see Section 12 3 4 Subscript params page 114 Sometimes these result in output that is too cluttered and confusing The f option turns off the subscripting operations 4 2 17 H Scan C C include files FWEAVE For C or C the H option tells FWEAVE to do a phase 1 scan of include files for typedef and or class declarations This removes the necessity of including many redundant f format statements see Section 5 5 8 AT page 42 which would otherwise be necessary in order that the code be pretty printed correctly For example if one uses the H option with the code ctt include lt Complex h gt Complex Zz the identifier Complex will be properly formatted as a reserved word in boldface as though one had said f Complex int In addition to the basic H there are several more detailed options Hx Make index entries only for double quoted include files HX Make index entries for all include files Hr Retain temporary files generated by the preprocessor By default index entries are not made for variables that are read during such scans If one says Hx index entries will be made only for include files whose names are enclosed in double quotes rather than angle brackets such as include myheader h usually these are defined by the user and reside in the local directory If one says HX index entries will be made for all inc
104. as a valid expression Chapter 5 FwEB COMMANDS 58 5 13 2 Pseudo semicolon is an invisible semicolon These are often used in C programming to terminate a module name that expands to a compound statement Carefully compare the uses of and in the following example Qc Qa if flag lt Compound statementO gt else lt Simple statement This compound statement ends with a brace but is used as an expression above lt Com gt 1 X y 3 This fragment does not end with a semicolon so one must be supplied above lt Sim gt Zz Here is a case for which the pseudo semicolon is not necessary Consider c The code fragment x yl If the 1 is turned on one might think that FWEAVE would report an irreducible scrap sequence because x y is an expression but not a complete statement Turning on 2 demonstrates this However it is not necessary to say x y because the warning message is not issued if the parsing reduces to just one unresolved scrap On the other hand goto done does not reduce to just one unresolved scrap so say goto done in cases such as this See Section 10 2 1 Pseudo operators page 101 In some situations pseudo semicolons are inserted automatically An important case is free format FORTRAN 90 There the language syntax says that newlines terminate state ments except when there s a traili
105. automatic file name completion When the e option is in effect FWEB attempts to be helpful in figuring out what file name one intends For any input file name that has no extension no embedded period FWEB completes the name by adding the extension contained in the style file parameter listed in the following table Type of file Style file entry Default WEB file ext web web Change file ext ch ch Include file ext hweb hweb Change file for include file ext hch hch More than one extension may be specified as a space delimited list e g ext web web wb the first one that matches is used 4 2 15 F Compare output files with old versions FTANGLE When the F option is in effect FTANGLE writes its output to a temporary file or files instead of to its ultimate destination such as test c and or test f After all output is written the temporary files are compared with the old version of the files if they exist If the files are identical the appropriate temporary file is deleted otherwise the temporary file is renamed effectively overwriting the old version This feature avoids updating the time stamp on the file unnecessarily so a make file won t recompile the output unless it really has to Note that with this option in effect if one uses the UNIX utility touch to force processing of a group of files but the web sources are never changed the make file will continue to tangle the sources
106. bseguently one can accrete to the above named sections as often as desired and in any order This way definitions of global variables can be introduced anywhere in the web source file as logical and pedagogical exposition dictates but will be guaranteed to appear at the top of the code Function prototypes could be handled this way as well alternatively they could all be collected into one section perhaps at the end of the source file The above organization still guarantees that they will appear at the beginning of the output Functions could be introduced one at a time in subsequent unnamed sections Very rarely one might try the following construction a lt Left side gt lt Right side gt Here the intent is to construct an assignment statement However this will be flagged as an error because FWEB thinks one is trying to define the named module lt Left side gt which one shouldn t be doing while in code mode To make it work just put the invisible expression e see Section 5 13 ATe page 57 before the equals sign 2 4 Phases of processing The FWEB processors perform their work in several distinct phases The following is somewhat technical Scan it then use it for reference later if necessary 2 4 1 The phases of FTANGLE F TANGLE has two phases In phase 1 the source file is read in phase 2 compilable code is written out in the order specified by the web More specifically phase 1 e
107. bytes 110 12 22 14 yln Maximum length of module names or strings in bytes 110 12 2 2 15 ylb Maximum number of nested loops in RATFOR 2 cece cece eee ee ee nes 110 12 2 2 16 ylx Maximum length of expressions that can be expanded with the post increment operators of FORTRAN or RATFOR 110 12 2 2 17 ym Maximum number of sections MEE 110 12 2 2 18 yma Maximum number of arguments to FWEB MacroS 00 eee ee eee 110 12 2 2 19 ymb Size of the buffer for expanding FWEB macros esses eee 111 12 2 2 20 yn Maximum number of identifiers and module names 111 12 2 2 21 ynf Maximum number of open output I ME 111 12 2 2 22 yop Maximum number of entries in the table for operator overloading 111 12 2 2 23 yr Maximum number of cross references EE eee eee eee 111 12 2 2 24 ys Maximum number of scraps 111 12 2 2 25 ysb Size of style file input line buffer MEE 111 12 2 2 26 ytt Maximum number of tokens that F TANGLE can process 0 e ee esee 111 12 2 2 27 ytw Maximum tokens in the current section being processed by FWEAVE 112 12 2 2 28 yx Maximum number of texts 112 12 2 2 29 yxb Size of line buffer for TEX and verbatim output ss cece eee eee ee 112 12 3 The Style fille 0 00 ee eee eee ee 112 12 3 1 Customizing FWEAVE s index
108. call test This will print as test 5 end The command should be distinguished from _ see Section 5 10 AT page 54 The latter causes the index entry for the identifier to be underlined the former possibly causes the identifier to be subscripted by a section number One may wish to turn off the subscripts because they become too cluttered however the underlined index entries remain useful and unobtrusive 5 8 Comments FWEB supports a variety of commenting styles borrowed from C C and TEX For more discussion see Chapter 6 Comments page 60 5 8 1 Begin long verbatim comment The following comment is copied to the tangled output By default comments are not copied If you desire all comments to be so copied use v See Section 4 2 64 v page 32 5 8 2 Begin short verbatim comment See the discussion of in Section 5 8 2 AT page 52 5 8 3 0 Ignorable comment If any line in a web source code contains the command 0 all remaining material on that line to and including the newline character is ignored by the input driver and never processed at all Chapter 5 FwEB COMMANDS 53 A stronger form of this command is This deletes the current line as well any empty lines that immediately follow This command is particularly useful when the N mode is in effect See Section 5 5 17 ATN page 46 Line numbering problems can arise when these
109. commands are used For a discussion see Section 4 2 59 6 T 72 page 31 5 8 4 Begin compiler directive The remainder of the line is processed as a compiler directive Optional material may be inserted automatically at the beginning of the tangled output line by means of the style file option cdir start See Section 12 3 8 Miscellaneous params page 118 5 8 5 C Begin meta comment Material between and is treated in the N mode For example ec Comment 1 Comment 2 e Style file parameters allow optional material to be insert at the beginning and end of the meta comment and at the beginning of each line of output For more information see the style file parameters beginning with meta see Section 12 3 8 Miscellaneous params page 118 5 8 6 End meta comment See the discussion of Section 5 8 5 ATIp page 53 5 9 Special left brace The command is useful in C C programming to beautify some of the pretty printing It translates into a left brace but also suppresses the automatic insertion of newlines into the subsequent function body or block This is desirable for very short func tions such as simple constructors in C For example class C 1 private int i public C int i0 fi i0 Here the function will be typeset as C int i0 i i0 rather than the default Chapter 5 FwEB COMMANDS 54 C int i0 1 i i0 5 10 Index entr
110. comments for documentation should be converted to the standard FWEB commenting style e If one has a block of code prefaced by an extremely long comment replace that by a named module and put the comment into the TEX part of that section 4 2 37 np Print semicolons FORTRAN FWEAVE Although the FORTRAN input driver automatically terminates logical lines with semi colons FORTRAN 77 see Section 4 2 33 n page 24 or pseudo semicolons FORTRAN 90 see Section 4 2 32 nAT page 24 so that the innards of FWEAVE can process them cor rectly the semicolons are not printed by default To make actual semicolons be printed use the np option np is turned on automatically for free format FORTRAN 90 when n is in effect the default For more discussion see Section 4 2 33 n page 24 4 2 38 n Free form syntax continued by backslash In FORTRAN 90 this turns on free form syntax and sets the continuation character to be the backslash as it would be in C For example n9 n Q Qa program main x y end In the tangled output the backslash is converted into FORTRAN 90 s standard continuation character the ampersand See also Section 4 2 39 n amp page 26 4 2 39 n amp Free form syntax continued by ampersand In FORTRAN 90 this turns on free form syntax and sets the continuation character to be the ampersand For example Chapter 4 RUNNING FWEB 27 n9 n a
111. countered If that occurs the previously open file is closed This command is expanded during output so it must appear in the code part For an example of using the 0 command to produce both C header files h and source files c see the discussion in Section 7 1 Outer macros page 62 To change the name of the output file locally for just the present section see Sec tion 5 5 21 ATo page 47 5 5 21 Co Open output file local scope This behaves like 0 except that the new file name is in effect only for the current section A subsequent o issued in a different section but for the same file name accretes material to the file An annoying problem arises in C programming when o s are used to create multiple source files that are subsequently compiled under the control of a Makefile Remember that by default line number information is written into the C files This means that a change in the web file code for one source file can affect all of the others because the line numbering in the web file changes Therefore a trivial change to the code for just one source file can cause all of the others to be recompiled Chapter 5 FwEB COMMANDS 48 As long as one desires debugging information relative to the original web file there is really no solution to this problem one needs the proper line information in each file in order to work with the debugger so if line numbers change the sources mu
112. de for generalizing these rules by the user To force an identifier to be placed into the Index precede it by 4 A module name must be within the scope of an N the first time the name is seen if it is ever to be within such scope Thus the following does not work properly Consider the module lt Test gt Not yet within scope of N Chapter 5 FwEB COMMANDS 4T eN Qa X lt Test gt 0 y What happens is that the N mode is not restored after the code part use of lt Test gt This is a bug There are very tricky design issues to be dealt with here 5 5 18 n Set language to FORTRAN 77 FORTRAN 77 is FWEB s default language so this command is usually not strictly nec essary However it is good practice to include it so a user looking at the web file can tell immediately what language it is supposed to process For more discussion of languages see Section 5 5 13 ATL page 45 and Chapter 8 Languages page 83 5 5 19 n9 Set language to FORTRAN 90 For more discussion of languages see Section 5 5 13 ATL page 45 and Chapter 8 Languages page 83 For hints about FWEB programming in FORTRAN see Section 8 2 3 Fortran page 85 5 5 20 0 Open output file global scope A statement of the form 0 new output file name changes the name of FTANGLE s output file This change remains in effect for the duration of the file or until another 0 is en
113. discards TEX documentation e tokenizes the source e expands FWEB preprocessor commands such as if see Section 7 3 Preprocessing page 80 e expands see Section 5 6 ATquote page 51 see Sec tion 5 6 2 ATdquote page 51 and the binary notation Ob see Sec tion 8 2 1 C page 84 in FORTRAN also the octal notation O and the hexadecimal notation Ox e stores code text in appropriate modules e memorizes macro definitions d and m see Section 5 5 6 ATd page 42 and Section 5 5 16 ATm page 45 Phase 2 e outputs outer macro definitions d e outputs the unnamed module a e expands FWEB macros m e expands built in macros such as IF or PI see Section 7 2 3 Built in functions page 66 e translates RATFOR statements see Chapter 9 Ratfor page 89 Chapter 2 WEB CONCEPTS 11 2 4 2 The phases of FWEAVE FWEAVE has three phases In phase 1 the source file is read and cross reference infor mation is collected In phase 2 the source file is read again then pretty printed with some cross reference information For discussion of pretty printing see Section 10 2 Pretty printing page 100 In phase 3 an automatically generated Index List of Modules and Table of Contents are written More specifically phase 1 Phase tokenizes and stores identifiers and module names collects cross
114. do ss EE EE esee 19 4 213 E Change the delimiter of a filename extension MU 19 4 2 14 e Turn on automatic filename completion 19 4 2 15 F Compare output files with old versions FTANGLE iessesse enhn 19 4 216 f Turn off module references for identifiers do EE ee hh 20 4 2 17 H Scan C C include files FWEAVE 20 4 2 18 h Get help EE eee eee eee eee 21 4 2 19 I Append to search list for include files 21 4 2 00 i Don t print I include files FWEAVE 21 4 2 21 i Don t read T include files 22 4 2 22 j Inhibit multiple includes 22 4 2 23 k Don t recognize lower case forms of keywords AA 22 4 224 L Select global language 22 4 2 25 1 Echo input line 23 4 2 26 M Set output message level 23 4 2 27 m Define FWEB macro FTANGLE 23 4 2 28 m4 Understand m4 built in commands 24 4 2 29 m Append pseudo semicolons 24 4 2 30 n Set global language to FORTRAN TT 24 4 2 3 n9 Set global language to FORTRAN 90 24 4 2 32 n Supply automatic pseudo semicolons FORTRAN cece cece ee etter eee hn 24 4 2 33 n Supply automatic semicolons FORTRAN 4 2 34 n Put statement label on separate line FORTRAN eee see SE ee cere mnn 25 4 2
115. dot constant begih ees ee ee ee ee ee ee 120 dot_constant end 0 ccc eee 120 E ext Ch eee nee 120 ext hch a rrer 120 ext hweb a 120 ext web ee eens 120 F format id ele eee 115 141 format ID ce eee 115 format intrinsic 0 eee eee 115 format keyword s cece eee 115 format KEYWORD 0 00 115 format outer MaCFO cece eee 115 format reserved iis 0 eee ee eee 115 format RESERVED 00 ee ee 115 format short id ccc ccc eee 115 format typewriter aa 115 format WEB_macro cc ccc cece nen 115 G group skip 114 I indent code eee ee eee 116 indent TeX ee ee eee 116 index collate ss eel eee 113 index name 0 ee eee eee 113 index postamble eee cee 113 index preamble 0 ei ieee 113 index tex n 113 UDeM_O SEE EE se ee hh hen 114 L language prefiX sis ss ee ee ee eee 114 language suffix ee ee ee ee ER Ee ee 114 LaTeX class eee eee 116 LaTeX class options ss ss se ee 116 LaTeX options ses ccc eee eens 116 LaTeX package sesse ss ee EE ee 116 LaTeX package option8 se EE ee ee 116 LaTeX style iss ee EE se es ee ene 116 lethead flag 0 cnet 114 lethead prefiX ss ss EE Ee ee ee 114 lethead suffiX EE eee eee 114 limbo begin sesse se eee ee ee 120
116. e usepackage and begin fdocument commands one may use the style file parameter doc preamble whose value is a string consisting of LaTEX commands empty by de fault Those commands are processed immediately before begin document One use of doc preamble is to inhibit FWEB s tendency to keep a section together on one page To make it break more readily in the middle of sections particularly useful for multicolumn output say doc preamble secpenalty 0 In summary the beginning of the file output by FWEAVE looks like the following where lt parameter gt means the contents of the style file string called parameter input fwebmac sty Wbegin many obscure arguments lt limbo begin gt Optional TeX commands copied from user s limbo section lt limbo end gt The AWbegin command essentially does the following documentclass lt LaTeX class options gt lt LaTeX class gt usepackage lt LaTeX package options gt lt LaTeX package gt lt doc preamble gt begin document For precise information about how Wbegin works see fwebmac web If you feel that macro absolutely needs to be changed please inform the developer see Chapter 15 Support page 131 10 1 3 2 Using REV TEX REV TEX is the standard macro package used for formatting scientific papers submitted to the American Physical Society the American Institute of Physics and some European Chapter 10
117. e true reserved words such as int they also include the names of intrinsic functions such as sin and for FORTRAN and RATFOR I O keywords such as IOSTAT Thus to see the reserved words for RATFOR 90 say ftangle Lr9 D For this option one must set the language on the command line because the D option is processed before the limbo section of the web file is read If one says Dabc one will get just the reserved words that begin with abc If one says D one will get all reserved words for all languages The D may be followed by a list of one or more optional letters enclosed in square brackets For UNIX systems don t forget to quote the brackets as they mean something special to the shell The letters represent which kind of reserved word to display they may be i intrinsic kK keyword or r reserved Thus to see a list of the FORTRAN keywords say D k To see a list of the intrinsic functions for C that begin with s say Lc D i s Chapter 4 RUNNING FWEB 19 4 2 12 d Convert do enddo This option is obsolete 4 2 13 E Change the delimiter of a file name extension The standard delimiter for filename extensions is a period as in test web To change this character to a comma for example say E This feature is required by at least one perverse system 4 2 14 e Turn on
118. e Section 4 2 40 n page 27 For more information about languages see Chapter 8 Languages page 83 For a fuller discussion of optional arguments see Section 8 1 Setting the language page 83 The command begins a major or named section corresponding to LaTPX s section command this command is followed by the section name terminated by a period The period is essential if it is omitted weird errors may result Major sections are entered in an automatically generated Table of Contents They are also printed at the top of each output page If the full section name is too long to so print one can shorten it with an optional argument as in Chapter 2 WEB CONCEPTS 7 INTRO INTRODUCTION The command n not illustrated in the above example begins a major sub section of level n where 0 is equivalent to the simple 1 indicates a subsection and x2 indicates a subsubsection The highest permissible major level is 2 a subsubsection Such subsections are also entered in the Table of Contents For more information see Section 10 1 3 4 Sections page 95 As the example demonstrates the name of the very last section which should be starred should be INDEX Note the backslash INDEX is a TEX macro This command tells FWEAVE to write out the index in a special two column format By default INDEX ex pands to INDEX but this name can be overridden by
119. e was changed See Section 4 2 15 F_ page 19 7 Converting output tokens to lower case See Section 4 2 61 U page 32 8 The built in functions E and PI See Section 7 2 3 15 SE page 70 Section 7 2 3 47 SPI page 76 9 The built in functions EXP LOG and LOG10 See Section 7 2 3 18 SEXP page 71 Section 7 2 3 37 SLOG page 75 and Section 7 2 3 38 SLOG10 page 75 Chapter 14 NEW FEATURES 130 MAX and MIN generalized to take arbitrary list of arguments See Sec tion 7 2 3 40 SMAX page 75 Section 7 2 3 41 SMIN page 75 11 The marriage saver option In response to a serious user request see Sec tion 4 2 6 B_ page 17 10 Chapter 15 SUPPORT 131 15 SUPPORT FWEB is supported by John Krommes krommes princeton edu This project is a definitively spare time activity Bug reports submitted with very short test files will be verified although not necessarily in real time For very simple fixes a change file may be provided Generally however bugs are not fixed until the next release Releases occur intermittently depending on my many other professional obligations Suggestions are very welcome Many of FWEB s current features were incorporated in response to users requests However the queue for future improvements is long nothing may happen immediately The next major release of FWEB Version 2 00 is planned for ap proximately the year 2000
120. e you re mostly stuck Most directly this possibly undesirable choice comes from design decisions made by previous authors It also makes FWEAVE very fast and enables certain complicated tricks that seem difficult or impossible to accomplish with a completely customizable approach The latter seems quite formidable and has not been attempted a good thesis project for the 21st century Chapter 10 DOCUMENTATION 101 10 2 1 Pseudo operators Pseudo operators behave like a particular part of speech for the purposes of FWEAVE s formatting but are invisible on output they are ignored by FTANGLE The pseudo operators are e pseudo expression See Section 5 13 ATe page 57 pseudo semicolon See Section 5 13 2 AT page 58 pseudo colon See Section 5 13 3 ATcolon page 59 10 2 2 Alternatives for various input tokens FWEAVE translates various input constructions into allegedly more readable symbols for example in FORTRAN it translates LT into lt Here is a table of what one can type on input and what FWEAVE will typeset The first entry is standard FORTRAN the parenthesized material is an allowable input alternative In most cases the pretty input alternatives follow C s convention It lt gt lt or I1 3 V le lt gt lt neqv gt eq gt Xor gt ne lt gt 3 eqv gt gt gt gt gt not gt ge C gt gt
121. e broken across lines must begin in column 1 as in n Q Qa lt This is a module name broken across lines gt Q Failure to do this results in a spurious semicolon being inserted in the middle of the name This happens because the FORTRAN 77 input driver does various low level manipulations of the source before it presents it to the innards of FWEB it s not tokenizing the source at that time and doesn t understand all of the FWEB syntax such as module names e Define symbolic statement labels with 0 see Section 7 2 2 Tokens page 65 Such names should be followed by a colon Thus 6n Q 6m EXIT 0 6m ABORT 0 Qa ABORT continue Chapter 8 LANGUAGES 87 EXIT continue e By default statement labels are llap d from the body of the statement With this con vention long labels can extend too far into the left margin Instead try the command line option n see Section 4 2 34 ncolon page 25 which puts them on a separate line Alternatively one can redefine the macro W1b1 found with some discussion in fwebmac sty e As a suggestion use upper case for I O keywords such as IOSTAT However by default the lower case forms are also recognized To permit only upper case use k see Section 4 2 23 k page 22 Note that although there is a command nk it is unfortunately not related to k GA e One may use as an alternative for the exponentiation opera
122. e length for TEX and the verbatim mode See Section 12 2 2 29 yxb page 112 12 2 2 4 ycf Size of a Ratfor buffer in bytes The sizes of buffers used by RATFOR for constructing messages about the commands it is expanding are controlled by ycf and ycg 12 2 2 5 ycg Size of another Ratfor buffer in bytes The sizes of buffers used by RATFOR for constructing messages about the commands it is expanding are controlled by ycf and ycg 12 2 2 6 yd Increment for expanding the dots table The dots table is used for FORTRAN to hold information relating to dot operators such as NE In FORTRAN 90 additional such operators can be added by the program so the table can grow dynamically The yd option controls how many additional entries are made available each time the table size needs to be reallocated 12 2 2 7 ydt Maximum number of deferred macro tokens Deferred FWEB macros are ones defined in the code part rather in the definition part Their use is normally prohibited see Section 4 2 59 1 TD page 31 ydt controls how many bytes are set aside for the storage of these replacement text of those macros See also Section 12 2 2 8 ydx page 109 12 2 2 8 ydx Maximum number of deferred macro texts ydx controls how many deferred macros are permitted See also Section 12 2 2 7 ydt page 109 12 2 2 9 yid Maximum depth o
123. e made by page num bers rather than module numbers or La TEX section numbers If there is more than one section per page they are identified by a b c etc such as section 17b Presently this will not work correctly when multicol is used for the body of the document The information necessary to process page references in this way is written into the aux file As is usual with La TEX several runs may be required for the references to be fully consistent with the source file 10 1 5 Page headers The very top header line on each page of FWEAVE s output contains several pieces of information e the current section name or document title e the page number e the range of La TEX section numbers on the page these are preceded by the 3 symbol and e the range of integer section numbers as understood internally by FWEAVE those are in square brackets and preceded by the sign 10 1 6 Section numbering schemes The FWEB commands and are translated by complicated magic into La TEX com mands such as section subsection etc By default use of documentclass article then produces Dewey decimal section numbers such as 2 13 4 subsubsection 4 of subsec tion 13 of section 2 When the section tree is very deep these numbers can look somewhat obtrusive An alternative scheme that of the original WEB is to merely number each section in ascending integer order beginning with
124. e 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 4 2 27 m page 23 Use the preprocessor construction if O endif to comment out unwanted code See Section 7 3 Preprocessing page 80 For logical operations with the preprocessor use not It s conventional to identify the ends of long preprocessor constructions as follows if A Chapter 13 USAGE TIPS and SUGGESTIONS 193 endif lAl 16 To debug an errant FWEB macro use the built in function DUMPDEF See Sec tion 7 2 3 14 SDUMPDEF page 70 17 Use for compiler directives See Section 5 8 4 AT page 53 Use the style file parameters cdir start to specify information that will be written out at the beginning of the line See Section 12 3 8 3 cdir start page 118 18 Stick to the standard FWEB commenting style or Don t use alter natives such as FORTRAN s column 1 convention these may not work or may not be supported someday See Chapter 6 Comments page 60 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 La TEX alternatives 20 In FORTRAN use 0 to declare readable alphabetic statement labels S
125. e the option see Section 4 2 78 page 36 Another potentially confusing situation occurs when is used to comment out a line FWEB deals with the line number problem that arises here automatically see Sec tion 4 2 59 6 T page 31 FwEAVE makes a valiant attempt to pretty print see Section 10 2 Pretty printing page 100 the definitions of both outer macros and FWEB macros in a reasonable way However this can be a formidable task because macro syntax can be essentially arbitrary Consider for example the following definition c d GET type type get_ type a GET int Expands into intyget_int The problem is that the identifier type is used in two different ways as the type of a reserved word the second type and as an ordinary expression the third type The first type has both meanings simultaneously Unfortunately within any particular language FWEAVE associates one unique type or ilk with each identifier One solution to this problem is to use the R command see Section 5 5 23 ATR page 49 which changes the ilk of the very next identifier to integer like Thus d GET type OR type get typeO will format correctly An alternative solution uses the related command E which changes the ilk of the very next identifier to an ordinary expression Thus f type int d GET type type get EtypeO Chapter 7 MACROS and PREPROCESSI
126. e to experiment but you may encounter difficulties which you should report see Chapter 15 Support page 131 To be completed 8 2 6 Special considerations for the vERBATIM language Unfortunately the VERBATIM language is not fully debugged Therefore it is not recommended for general use To be completed Chapter 9 RATFOR 89 9 RATFOR RATFOR stands for RATIONAL FORTRAN It endows FORTRAN with a C like syn tax Certain loop and other constructions such as switch or i that are not allowed in FORTRAN are allowed in RATFOR FWEB translates those into proper FORTRAN Although RATFOR is a definite improvement over FORTRAN it certainly does not have the power of C e g elegant pointer notation or C e g classes Many advantages accrue by taking the time to learn C RATFOR offers a gentle transition It is not supported very actively any more 9 1 RATFOR syntax A sample RATFOR program is Qr Q Qa program main 1 integer k real fcn x for k 0 k lt 10 k x fcn k if x lt 0 0 x 0 0 break The concluding brace of a function is translated into an END statement Note the use of semicolons to terminate statements braces to delimit compound statements lt instead of LT the C like for construction and the k expression Constructions like k or k 1 1 must be used with great care They translate to statements i
127. e use of the XI option and the use of a different root name index here for the output file Chapter 11 FWEB s INDEX 104 11 2 2 Creating a stand alone index Details To create an index file in a form suitable for later stand alone processing by makeindex use the XI option to FWEAVE If the web file is test web the default name of the makeindex output file is test idx This name can be overridden by the style file param eter makeindex out Run makeindex on test idx to create the LaTEX file index ind see following discussion for details A stand alone index can then be produced by saying latex index where a skeleton version of index tex would be 4 index tex skeleton for printing a stand alone index documentclass article usepackage fwebmac begin document input jobname ind end document In practice a more involved procedure will probably be followed see below Usually makeindex works in conjunction with a style file In fact the syntax of FWEB s style file see Section 12 3 Style page 112 was motivated by that of makeindex When the XI option see Section 4 2 68 X_ page 34 is used FWEAVE will create an appropriate style file for makeindex The default name of test sty can be overridden by the style file parameter makeindex sty To run makeindex on the index data for test web and create the output file index ind
128. eX material old operator This means Display the new operator according to the TEX material but treat it like the old operator e g unary or binary for formatting purposes The quoted TEX material is treated just like a C string so if one wants to include a backslash one must escape it with another backslash For example one can make an equals sign display on output as a large left arrow by saying Qv Leftarrow Two FORTRAN examples are v FALSE FALSE FALSE Qv IN in This feature can go a long way toward enhancing readability of the woven output partic ularly when operators are actually being overloaded It can also lead to arbitrarily bizarre output that no one else will understand As usual restraint is advised 10 2 3 2 Overloading identifiers Although operator overloading is quite useful it does not allow one to change the ap pearance of identifiers In its most general form such a facility becomes quite complicated one must endow F WEAVE with a macro processing facility analogous to that of FTANGLE This has not been done yet maybe it will be someday In the meantime one has the command W which provides a restricted form of such a facility This command is experi mental and not firmly established Changes in usage and or syntax may be made in future versions The most general form of the W command is W identifier replacement text This means Replace any references to iden
129. eans a mod b for example 5 4 3 2 The usual plus and minus lt lt a lt lt b means shift integer a left b bits 1 3 8 gt gt As above but right shift 7 gt 2 1 lt lt gt gt Evaluates to 1 if the inequality holds to O otherwise E g 2 0 lt 3 0 evaluates to 1 a b a b evaluates to 1 0 if a equals b evaluates to 0 1 otherwise amp Bitwise AND The truth table is 0b1100 amp 0b1010 0b1000 Bitwise EXCLUSIVE OR C For FORTRAN use xor The truth table is 0b1100 xor 0b1010 0b0110 Bitwise OR The truth table is 0b1100 0b1010 0b1110 amp amp Logical AND a amp amp b evaluates to 1 if both a and b are true nonzero Logical OR a b evaluates to 1 if either a or b are true Note in particular the use of the single caret which is language dependent it is an expo nentiation operator for FORTRAN just as in TEX but is the exclusive or operator for C Also note that the bitwise operators should almost never be used For logic almost always one will be using z amp amp and Chapter 8 LANGUAGES 83 8 LANGUAGES FWEB has the ability to work with more than one source language during a single run The language in effect at the beginning of the first section defines the global language Further language changes within a section have scope local
130. ebnum see Section 10 1 6 Num bering page 98 10 1 1 Fweave s OUTPUT When one says fweave test the file test tex is created Some TEX commands contained in this file are created automatically others are copied from the web source file They are organized into several sequential groups as follows 1 input command to read in FWEAVE s macro package By default the initial input command is input fwebmac sty see Sec tion 10 1 2 fwebmac sty page 92 The name of the macro package can be changed with the w command line option but that is dangerous and useful only for very special effects See Section 4 2 66 w page 34 2 Mibegin command The Wbegin macro sets up certain defaults which can be overridden in the limbo section In La TEX it also issues the documentclass article and begin document commands 3 Limbo text from the style file parameter limbo begin See Section 12 3 8 11 S limbo page 120 4 Limbo text from 1 commands See Section 5 5 14 ATI page 45 5 User s limbo section 6 Limbo text from the style file parameter 1imbo end See Section 12 3 8 11 Simbo page 120 7 TEX commands for individual WEB sections 8 Vinput command to read in the index data file 9 Vinput command to read in the module list data file 10 Winfo command summarizes some status information 11 Wcon command generates the Table of Contents and ends the run
131. ee Sec tion 7 2 2 Tokens page 65 and Section 4 2 75 colon page 36 21 When mixing languages define the language of a module at the highest possible level e g in the unamed module not after lt gt 22 Use LaTeX Plain TEX is no longer supported Upgrade to LaTEX 2e See Section 10 1 3 LaTeX page 93 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 Chapter 15 Support page 131 13 3 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 7 2 3 47 SPI page 76 and SE Section 7 2 3 15 SE page 70 2 Several built in functions perform mathematical manipulations See EXP Sec tion 7 2 3 18 SEXP page 71 POW Section 7 2 3 48 SPOW page 76 SQRT Section 7 2 3 56 SSQRT page 77 LOG Section 7 2 3 37 SLOG page 75 L0G10 Section 7 2 3 38 SLOGI0 page 75 MAX Section 7 2 3 40 SMAX page 75 and SMIN Section 7 2 3 41 S MIN page 75 3 The do loop macro DO may be useful See Section 7 2 3 13 DO page 69 4 C style array indices can be used by means of the n option See Sec
132. ement conditional comments by using FWEB preprocessor macros e g if DEBUG endif Pre FWEB codes may have such blocks commented out with a C in column 1 Those should be converted to the preprocessor construction However if you re in a real hurry temporarily use the nC option see Section 4 2 36 nC page 25 to kill those lines very early in the processing before they can give you all kinds of trouble e An unfortunate byproduct of using for short comments is that in general for mat constructions like format won t work It will work if one uses nC see Section 4 2 36 nC page 25 Alternatively one can say format e Consecutive lines commented out with a C c or in column 1 are converted into a single comment before processing by FWEB Large blocks of such lines common in pre F WEB code may overflow FWEB s tables To avoid that insert blank lines between some of the comments Better however is to move most such blocks out of the code part to the TEX part of the section It s most readable to have only a few very short comments interspersed in the code To help with conversion of existing codes the command line option nC can be used to completely ignore comment lines e commands should by and large start in column 1 That s not necessary for short module names that fit on one line However a long module name that must b
133. ement functions that a user could not define They all begin with a dollar sign and are in upper case In using these built ins confusion may arise regarding the order of expansion of various arguments When they are implemented as macros they are subject to the same ANSI C preprocessor rules as other FWEB macros which is that all arguments are fully expanded before generating the replacement text of the macro When they are directly implemented as a primitive function however that rule may not apply For example IF expands only its first argument during its first pass of processing depending on the results of that expansion it then expands either its second or third argument but not both The built in function DUMPDEF can be used to understand and debug the action of the built in functions See Section 7 2 3 14 SDUMPDEF page 70 In the original FWEB design built in functions began with an underscore This usage conflicts with the conventions for reserved words in ANSI C and has been eliminated All FWEB built ins now begin with a dollar sign No user defined macro should begin with a dollar sign It might interfere with the functioning of some internal built in function Chapter 7 MACROS and PREPROCESSING 67 7 2 3 1 Strings and quotes Several of the built in functions expect or return a string argument Examples include STRING see Section 7 2 3 58 SSTRING page 77 UNQUOTE see Section 7 2 3 64 SUN QUOTE page 78 and
134. ents are produced by the La TEX macro numberline Jj La TEX s default definition is inadequate when section numbers are very large they extend to the right and can overwrite the section name The macro is redefined more appropriately when the package fwebnum see Section 10 1 6 Numbering page 98 is used 10 1 3 7 Customizing LaTpgX s output Several TEX flags are provided to change the appearance of the final La TEX document This appearance is a bit experimental and it is fair to say that not everything may be fully debugged please report problems These are means either true or false e pagerefs index references by pages or section numbers e numberTeX number the beginning of unnamed TeX parts Chapter 10 DOCUMENTATION 98 e numberdefs number the beginning of the definition part e numbercode number the beginning of the code part The defaults for these flags are pagerefsfalse numberTeXfalse numberdefstrue numbercodetrue If desired one may override these in the limbo section They are defined using Plain TEX s newif rather than the equivalent La TEX command because they may also be used when La TEX is not present numberTeX is on the verge of obsolescence Try to not use it never use it in conjunction with the package fwebnum See Section 10 1 6 Numbering page 98 10 1 4 Page references When one says pagerefstrue LaTEX only index references ar
135. er abbreviation such as op For example the option yop200 allocates 200 units for the op buffer To query the default allocations just say y When FWEB runs out of space it usually but not always issues a message telling one which y command to use in order to increase the allocations Someday it will reallocate automatically One may wish to add some such options to the fweb file For a more detailed discussion of memory allocation and a menu of the various dynamic arrays see Section 12 2 2 Memory allocation page 108 4 2 70 Z Display default style file parameters The information option Zabc prints to the screen the default contents of the style file parameters beginning with abc Just Z prints everything After printing the defaults the p options see Section 4 2 46 p page 28 and the style file fweb sty are processed If that processing has overridden any of the defaults the parameters are printed again preceded by an asterisk To see only the parameters that have been modified from the defaults say Z The Z option behaves slightly differently for color escape sequences than for other parameters see Section 12 3 7 Color page 117 4 2 71 z Change name of style file The command znew sty changes the default style file name fweb sty to new sty The command z with no argument means Don t read
136. ere the colon is the value of makeindex actual it separates the sort key before the colon from the actual expression to be printed The macros such as gt typeset the identifiers in the appropriate way depending on their use in the code Note that the backslashes are quoted with the value of makeindex quote which is by default the double quote Although one might guess that the typesetting macros such as gt would be defined in fwebmac sty that is not true Rather for various technical reasons they are equated to macros in fwebmac sty as one of the operations of the NWbegin macro that is executed at the beginning of every tex file output by FWEAVE For example AWbegin does the equivalent of let gt Wid Unfortunately without further action that equating would be forgotten by a La TEX run made on the output index ind of makeindex For that reason FWEAVE appends the appropriate Wequate macro to the end of makeindex preamble This is one specific instance that necessitates that FWEAVE write the makeindex style file Each of the indexentry s contains the encapsulation character the value of makeindex encap By the conventions of makeindex everything between the encapsula tion character and the closing right brace defines a macro expression that acts on the page number E g the general form above generates the command macro page number The specific
137. ers However that causes trouble with FORTRAN 90 code containing multiple statements per line as in a b c d If np is not used then the semicolon in the above example is not printed hindering legibility Thus the default mode of operation for free format FORTRAN 90 is n and np This turns the above example into a b c d and displays it correctly When n is used semicolons will not be printed by default To force them to be printed use the np option see Section 4 2 37 np page 26 Do not insert semicolons by hand in FORTRAN 77 they are always inserted automatically If you have terminated FORTRAN 90 statements by hand turn off auto semis by n and use np at your discretion The following table summarizes the defaults for auto semi insertion and semicolon print ing in FORTRAN both fixed and free formats N A means not applicable Fixed Free F77 n N A F90 n n np 4 2 34 n Put statement label on separate line FORTRAN By default in FORTRAN statement labels are placed on the same line and backspaced from the command that is being labeled as in EXIT continue This can look ugly if the label is very long The command n places the label on a separate line as is done automatically for RATFOR e g EXIT continue If neither of these options appeals to you you could try redefining the macro NW1b1 found wi
138. es ec Meta comments provide a poor person s alignment feature i counter X data value Chapter 6 COMMENTING STYLES 61 x 2 0 call exec i x end The use of meta comments is not recommended they are only marginally supported Use ordinary long comments instead Inside of them use the various powerful features of TeX or La TEX such as halign or begin verbatim end verbatim to format your comment appropriately 6 3 Temporary comments During development one frequently desires to temporarily comment out a section of code C programmers sometimes try to do this by enclosing the code in but this is not good style for several reasons First it is impossible if the code itself includes comments since comments do not nest in C Second FWEAVE will treat the commented code as TEX rather than C code and will at best format it very poorly In fact LaTEX will frequently complain because the commented code might contain characters such as underscores that TEX expects to be in math mode Those are dealt with automatically when F WEAVE is in code mode The trivial example a_b is sufficient to illustrate this point The proper way of commenting out sections of code is to use preprocessor constructions tif O endif in C or more generally if 0 endif usable in all languages The FWEB preprocessor is described in Section 7 3 Preprocessing page 80 With this method there is no trouble
139. es so that FWEAVE understands them properly or you may need to insert some pseudo semicolons pseudo expressions e or pseudo colons see Section 10 2 1 Pseudo operators page 101 Consider using FWEB s built in macro preprocessor see Chapter 7 Macros page 62 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 7 2 3 Built in functions page 66 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 Chapter 13 USAGE TIPS and SUGGESTIONS 192 C q C j VN VV NV AV TINA tab OJRET MAN C a C j NANA NANANA FRET Get rid of the keywords such as then or end if in favor of braces Change singly guoted character strings to doubly quoted ones The nC option see Section 4 2 36 nC page 25 may be helpful 13 2 Programming tips and other suggestions 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 Chapter 14 New feat
140. expected or unreadable way it s because FWEAVE wasn t able to parse the relevant block of code perhaps because it didn t understand that some variable in an include file has a special meaning In such cases trying to fix things with is the wrong solution Either use f see Section 5 5 8 ATf page 42 or H see Section 4 2 17 H_ page 20 Distinguish the command from see Section 5 2 2 AT page 39 which inserts an optional breakpoint into an expression 5 12 3 Force a line break then indent The command behaves like see Section 5 12 2 AT page 55 except that it backspaces one notch after the line break This usually has the effect of undoing the natural indentation that would have been inserted had a long line been spontaneously broken One common case where the command might be used would be to put the return type of a C function on a separate line int main It would be nice to have FWEAVE do that automatically Unfortunately the syntax of a function isn t recognized until the opening braces are sensed by that time the declaration part of the statement has already been processed This is one example of the fact that the FWEB processors are much less intelligent and sophisticated than language compilers A clever and simple idea for getting around this kind of problem is lacking at this point 5 12 4 Literal vertical bar
141. ext Sometimes however the 1 command is useful for pedagogical purposes as the limbo material can then be defined at the point where the logical discussion is made 5 5 15 M Define FWEB macro This command begins the definition part For a detailed discussion of FWEB macros see Chapter 7 Macros page 62 5 5 16 m Define FwEB macro and mark This command begins the definition part m defines an FWEB macro and also marks the next identifier as defined here It is equivalent to m MOL see Section 5 7 ATI page 51 For a detailed discussion of FWEB macros see Chapter 7 Macros page 62 The distinction between m and M is analagous to the distinction between a and A See Section 5 4 4 ATa page 40 Chapter 5 FwEB COMMANDS 46 5 5 17 N Turn on N mode This command must appear before the code part Generally this means immediately before a Do not use this command in limbo use Lv instead The N mode invokes language independent behavior within the scope of a particular language The scoping rules are the same as for language changes i e using N within a given section produces language independent behavior for that section and for any modules first referenced in that section Fundamentally language independent behavior essentially means a literal transcription of the input to the output For example it inhibits blank com
142. eyword Text of Keyword at least one blank after the colon and at least one before the last dollar sign UNIX users see man ident is parsed and the text of the Keyword is made available to the control codes K see Section 5 5 11 ATK_ page 44 and k see Section 5 5 12 ATK page 44 as well as to FTANGLE s built in function KEYWORD see Section 7 2 3 30 SKEYWORD page 72 A distinction is made between keywords that are found in the ignorable commentary at the beginning of the master web file which are called global keywords and ones that are found at the beginning of files included via i which are called local keywords The commands that access RCS like keywords function as follows e KEYWORD Keyword accesses a global keyword It is a built in function that is expanded by FTANGLE during output into the quoted character string Text of Keyword e K and k are expanded during input K accesses a global keyword whereas k accesses a local keyword Chapter 5 FwEB COMMANDS 51 e In the limbo section or a TEX part FWEAVE will expand K Keyword gt into Text of Keyword without the surrounding quotes and similarly for k The intention is that the expanded text can be used as bodies of TEX macros F WEAVE will also print the values of global keywords at the end of its output whether or not they are referenced by K e Elsewhere FWEAVE will just
143. f file inclusion Files included by i can themselves contain i commands to a nesting level controlled by yid Chapter 12 CUSTOMIZATION 110 12 2 2 10 yif Maximum number of unique include file names The number of unique file names appearing in i commands is controlled by yif 12 2 2 11 ykt Stack size for FTANGLE F TANGLE uses a stack to deal with the web of module names i e a named section can refer to another module name The size of this stack is controlled by ykt 12 2 2 12 ykw Stack size for FWEAVE FWEAVE s stack handles the possibilities that code mode can be embedded in a module name or vice versa The maximum nesting level for such mode changes is controlled by ykw 12 2 2 13 y11 Line length for FwEAvE s output in bytes y11 controls the length of each line in the tex file output by FWEAVE 12 2 2 14 yln Maximum length of module names or strings in bytes When each module name or string is parsed it is stored temporarily in a buffer whose length is controlled by yln 12 2 2 15 ylb Maximum number of nested loops in RATFOR In RATFOR various loops such as while are translated into their FORTRAN equivalents ylb controls the maximum nesting level of such expandable constructions 12 2 2 16 ylx Maximum length of expressions that can be expanded with the post increment operators of FORTRAN
144. f that identifier is used elsewhere it will be subscripted with the section number To turn this feature off use f see Section 4 2 16 f page 20 However if a section contains an arbitrary code fragment the code part should probably begin with A E g c Q QA x y If one had used a here the x would have been marked as defined here which is not what one wants 5 5 Control codes b z 5 5 1 B Suppress insertion of breakpoint command This is for detailed debugging of FWEB codes It inserts a left brace and suppresses the insertion of a breakpoint command See the discussion of b in Section 5 5 2 ATb page 41 5 5 2 b Insert a breakpoint command Discussion to be finished Useful only for very intimate debugging of FwEB codes In these days of safe sex such intimacy may not be desirable See also Section 5 5 ATB page 41 5 5 3 c Set language to C The command c is a shorthand for Lc For a discussion of language commands in limbo see Section 5 5 13 ATL page 45 See Chapter 8 Languages page 83 and Section 8 2 1 C page 84 Chapter 5 FwEB COMMANDS 42 5 5 4 ct Set language to C The command c is a shorthand for Lc For a discussion of language commands in limbo see Section 5 5 13 ATL page 45 See Chapter 8 Languages page 83 and Section 8 2 2 Cpp page 85 5 5 5 D Define outer macro T
145. font 6 1 Invisible comments z x fa source or include file begins with z in the very first two characters of the file then all material is skipped until and including a line beginning in column 1 with x except that lines of the form Keyword text of keyword are processed see Section 7 2 3 30 SKEY WORD page 72 Section 5 5 11 ATK page 44 source files or Section 5 5 12 ATk page 44 include files pA All material until and including the next newline is completely ignored Q7 As but also skip blank lines that immediately follow the current line For example z Author J A Krommes x c 0 4 This sets the global language to C EXAMPLE 6 2 Visible comments is a long comment it may extend over several lines is a short comment terminated by the next newline 0 0 is a meta comment Meta comments are a localized form of the N mode see Chapter 8 Languages page 83 Tangled meta comments are begun by the con tents of the style file entry meta top and terminated by meta bottom Each line of the meta comment is begun by meta prefix Woven meta comments are begun by meta_code begin and ended by meta_code end See Section 12 3 8 Miscellaneous params page 118 n a program main Get input call get_input Read the parameter file Process information Comments like this can be split over several lin
146. g anyway Chapter 15 Support page 131 In some cases it is useful to turn off the line and section number information locally This can be done with the q command See Section 5 5 22 ATq page 48 Chapter 4 RUNNING FWEB 37 4 2 79 Don t interpret compound assignment operators Both RATFOR and FORTRAN attempt to translate the commands ks and into code that behaves as their C C counterparts To turn this feature off use Notice that in FORTRAN 90 is a token for not equal so if you want to use that you must turn off the compound assignment operators with use However a better solution is to leave them turned on and use FWEB s standard token for not equal See also Section 12 2 2 16 ylx page 110 4 2 80 Recognize short comments FORTRAN amp RATFOR If this command is not used with the FoRTRAN like languages the construction will be interpreted as concatenation rather than as the beginning of a short comment Concatenation can be signified with FWEB s token so no penalty is incurred for using ep One way of invoking this option is with the global language command such as n Another is to put the command into the initialization file fweb See also Section 4 2 40 n page 27 and Section 4 2 55 r page 30 4 2 81 Make denote short comme
147. ge 131 4 2 67 x Eliminate or reduce cross reference information FWEAVE Cross reference information for FWEAVE includes the Table of Contents c the Index 1 and the Module List m The option x eliminates all of that information The option xletters eliminates the piece of information corresponding to each letter in the list For example xim eliminates the Index and the Module List Another possibility is to say xu which prevents cross references from unnamed sections begun with a or A from appearing in the Index 4 2 68 X Print selected cross reference information FWEAVE When used with any of the arguments cim this option is the opposite of x See Section 4 2 67 x page 34 The option XI tells FWEAVE to write its index cross references to a file formatted for input by the makeindex utility This feature facilitates creation of a master index that spans several individual web files For more discussion see Section 11 2 Using makeindex page 103 The construction XI stands alone one may not mix the I with the list cim Also this option is overridden by xi which suppresses output of all index information Chapter 4 RUNNING FWEB 35 4 2 69 y Allocate dynamic memory This option changes the default size for a dynamically allocated memory buffer The buffers are indicated by a one or two charact
148. gt 5 10 6 9 Make index entry user defined format The construction 9Text gt is used to create an index entry in a format defined by the user It is associated with the macro 9 which will be called during TEX s processing of the Index as 9 Text The user must define 9 according to the format NdefN9 11 3 where argument 1 is the text between 9 and gt For example to print that text in a sans serif font say def 9 1 sf 1 Note the extra level of braces to prevent the font command from propagating Chapter 5 FwEB COMMANDS 55 5 11 Control text Control text is material terminated by gt it must be all on one line and must not contain any s 5 11 1 Ct Put control text into a TEX hbox FWEAVE When FWEAVE sees the command tcontrol text gt it packages the control text into an hbox and ships it to the output This command is ignored by FTANGLE 5 11 2 Pass control text verbatim to the output For FTANGLE the command control text gt sends the control text to the output exactly as input FWEAVE highlights the control text by drawing a box around it 5 12 Spacing The spacing commands are used to refine FWEAVE s pretty printed output Generally it s not necessary to bother with these until one is putting the final touches on a code 5 12 1 Insert a thin space Extra spacings are sometimes necessary when working with u
149. he brackets denote optional Here the slash is called the prefix end character Since this character differs for various operating systems it can be changed by system installers in custom h see Chapter 12 Customization page 107 The character that initiates the filename extension normally a period can be changed with the E command line option see Section 4 2 13 E_ page 19 3 1 Input files FWEB reads files with a variety of default extensions fweb Initialization file optional for setting up default options used for all runs This file is always in the user s home directory See Section 12 2 Initialization page 108 fweb sty Style file optional for customizing the behavior of a particular web file or group of files See Section 12 3 Style page 112 This file is always in the directory of the web file that is being tangled unless that is changed by environment variable FWEB_STYLE_DIR The basic name can be changed by the z option see Section 4 2 71 z page 35 A sample fweb sty file is provided with the FWEB distribution name web Source file name ch Change file optional for making incremental changes to a web source file See Section 3 3 Change files page 13 name hweb Code included into web file with i see Section 5 5 9 ATi page 43 Include files are searched for in the path set by the environment vari able FWEB INCLUDES
150. his command begins the definition part D defines an outer macro For more discussion see Section 7 1 Outer macros page 62 For example in C D Al will be tangled to the beginning of the output file as define A 1 5 5 6 d Define outer macro and mark This command begins the definition part d defines an outer macro just as D does and also marks the next identifier as defined in the present section It is equivalent to d epe see Section 5 7 ATI page 51 The distinction between d and D is analagous to the distinction between a and A See Section 5 4 4 ATa page 40 5 5 7 E Treat next identifier as ordinary expression FWEAVE For formatting purposes treat the next identifier as an ordinary expression his command is useful in pretty printing certain kinds of macro constructions Further discussion is given in undefined Macros and formatting page undefined 5 5 8 f Format identifier or module name This command begins the definition part The construction f identifier old identifier makes FWEAVE treat identifier like old identifier For example f mytype int says to treat the variable mytype just as int is treated e g as a reserved word in C or C Traditionally C programmers needed to use this command to format identifiers that were defined in include files This annoying redundancy has now been eliminated by
151. hree special identifiers just mentioned so one shouldn t use those as regular variables To cause only the upper case forms to be recognized use the k option 4 2 24 L Select global language To select a global language from the command line say LI where is one of c ct n n9 r r9 v x See Chapter 8 Languages page 83 Usually the global language is set via an command in limbo not on the command line However one may need to use a command line option such as L_ if a subsequent command line option is language dependent See for example the discussion of the option D in Section 4 2 11 D page 18 Chapter 4 RUNNING FWEB 23 4 2 25 1 Echo input line The option 1 mmmf nnn echoes the input lines constructed by the input driver be tween lines mmm and nnn Missing nnn means echo to the end of file Missing mmm means echo from the beginning This option is useful as a debugging tool usually by the system developer It is often used to verify that the input driver is inserting semicolons correctly For FORTRAN 77 it is also useful to verify that comments are being processed correctly 4 2 26 M Set output message level By default FWEB is relatively verbose as it proceeds it prints messages about what files it is reading and writing numbers of the starred sections line numbers etc However different levels of verbosity can be set by the command Mlevel
152. iable arguments page 64 and some additional preprocessing tokens see Section 7 2 2 Tokens page 65 e Adjacent strings in macro text are automatically concatenated 7 2 1 1 FwEB macros with variable arguments An important extension to the ANSI C syntax is to allow macros with variable optional arguments FWEB macros with a variable number of arguments are indicated by an ellipsis as in Om VAR x y z text The tokens 0 number of variable arguments n value of the nth optional argument and comma delimited list of the optional arguments are useful in this context 7 2 1 2 Recursion ANSI C does not permit recursive macros for good reason Thus in the example 6m recurse recurse the identifier recurse simply expands as recurse not as an infinite loop However in FWEB recursion may be useful in conjunction with some of the built in functions see Section 7 2 3 Built in functions page 66 To permit a macro to be recursive say m No formal support is provided for recursive macros If they don t work or suddenly stop working in a new release you re on your own 7 2 1 3 Protecting macros against redefinition Normally an FWEB macro can be redefined at will The example Chapter 7 MACROS and PREPROCESSING 65 m PI 3 14159 m PI 3 is permissible but probably not a good idea If you want to ensure that a crucial macro definition is never redefined inadvertently say m
153. ies Although most information for the Index is gathered automatically in some situations it must be done by hand 5 10 1 _ Force index entry to be underlined This command applies to the next identifier that appears after the _ The index entry for that identifier will be underlined By convention this means defined or declared This command is usually issued automatically For example the index entries for the variables i and j in the C statement int i j will be underlined since FWEAVE un derstands enough of the syntax to know that variables are being defined Macro definitions begun by D or M will also be underlined automatically 5 10 2 Delete index entry This command applies to the next identifier that appears after the it prevents an index entry associated with that identifier from being made This might be useful when the N mode is in effect 5 10 3 Force index entry This command applies to the next identifier that appears after the it forces an index entry for that identifier It is particularly useful when the language is VERBATIM since cross referencing is turned off in that case 5 10 4 O Make index entry Roman type To insert one s own index entry in Roman type say 6 My entry gt 5 10 5 Make index entry typewriter type To insert one s own index entry in typewriter type say My entry
154. in boldface underlined in the index etc That is if one says Chapter 8 LANGUAGES 85 struct S one can t say S s one must say struct S s This is a good reason for using C where such tags do define a new type To be completed 8 2 2 Special considerations for C e All of the items in the previous section see Section 8 2 1 C page 84 still apply e The command is very useful for beautifying very short definitions of member functions such as constructors See Section 5 9 ATIb page 53 e Essentially FWEAVE has only one name space global to the entire code those names do not obey any concept of scope In various situations in C and C however multiple namespaces are used or the interpretation of a name changes according to its scope Thus the design of FWEAVE imposes a few restrictions on one s programming style Remember FWEAVE doesn t know nearly as much as a language compiler One example in C has to do with formal types in templates Consider the following example template lt class Type gt class A private Type p In order that the class definition be typeset correctly Type must be understood to be a reserved word like int and that is correctly figured out by the first class command However according to C the scope of Type is local to the class definition unfor tunately FWEAVE does not respect that locality and will always treat Type
155. ion 12 3 8 Miscellaneous params page 118 bj Outer macros can be undefined by u The translation is controlled by the style file parameter outer undef See Section 12 3 8 Miscellaneous params page 118 The default behavior in which the outer macro definitions are just copied to the top of the output file is fine for simple applications However often C programmers prefer to maintain their macro definitions in a header file such as test h One way of accom plishing this is to redirect FTANGLE s output from the command line as in ftangle test test h then use an 0 command immediately after the first a in the web file to open up test c A more complicated variant of this allows additional information to be placed into the header file as in the following example c INTRO We assume command line redirection into test h test h d A 1 This will go into test h a lt Header material gt Also goes into test h D test c Remaining unnamed sections go into test c Header material may be defined as needed throughout the code but with this design it will all go into test h lt Header material gt lt IncludesO gt Q lt Typedefs gt 0 lt Global variables gt 7 2 FWEB macros FWEB macros sometimes called inner macros are defined by m see Section 5 5 16 ATm page 45 or M see Section 5 5 15 ATM_
156. ion helps one usually the system developer to figure out why This feature can be turned on more locally by means of the 2 command See Sec tion 5 1 3 AT2 page 38 4 2 4 Display the control code mappings This option supplies information about the control codes see Chapter 5 AT com mands page 38 It shows the associated style file parameters that can be used to remap the codes but don t do that and it displays the precedence Some codes such as may be used anywhere others such as begin a new section or part of section Codes that Chapter 4 RUNNING FWEB 17 begin the definition part are labelled by D codes that begin the code part are labelled by C codes that begin a new section are labelled by S The option produces two columns of output the first is sorted numerically the second alphabetically The notation USED BY OTHER means that this command is ignored by whatever processor F TANGLE or FWEAVE is currently being run but may be used by the other processor For technical reasons a very few commands such as i do not show up in this output at present If one says just information about all control codes is produced Selected con trol codes may be queried by listing them after the For example to learn about the commands and a say a Remember to quote certain characters on UNIX systems e g
157. is option specifies a style file entry see Section 12 3 Style page 112 Its argument is exactly the same as a line that one may put into the local FWEB style file Thus Chapter 4 RUNNING FWEB 29 if in fweb sty one would say entry value the form of the p option would be pentry value The single quotes are required on a UNIX system because the double quotes have special significance to the shell This option can be used either in the fweb initialization file see Section 12 2 Initializa tion page 108 to record style file entries that are common to all runs or on the command line to override a local style file entry for a single run This behavior is a consequence of the following order of processing style parameters 1 p options in fweb 2 entries in the local style file fweb sty 3 p options on the command line 4 2 47 r Set global language to RATFOR 77 See Chapter 8 Languages page 83 and Chapter 9 Ratfor page 89 See also Sec tion 4 2 24 L page 22 4 2 48 r9 Set global language to RATFOR 90 See Chapter 8 Languages page 83 and Chapter 9 Ratfor page 89 See also Sec tion 4 2 24 L_ page 22 4 2 49 rg Set goto parameters This obscure option is used for configuring RATFOR and really should be a style file parameter Discussion not finished 4 2 50 rk Suppress comments about RATFOR t
158. it automatically generates an Index of all variable usage One can also insert one s own index entries by using the commands e entry in Roman type see Section 5 10 4 AT page 54 e O entry in typewriter type see Section 5 10 5 ATdot page 54 and e 9 user defined format see Section 5 10 6 AT9 page 54 More discussion to be completed 11 2 Creating a stand alone index with makeindex In addition to the internal index described in the previous section see Section 11 1 Internal index page 103 FWEAVE can write the index data to a file formatted for later stand alone processing by the makeindex utility Several such indexes can be merged together see Section 11 3 Merging indexes page 105 The procedure is simple although the following discussion goes into some rather arcane details 11 2 1 Creating a stand alone index Summary As a quick reference for those who have already read the details in the next subsection the procedure to print a stand alone index with makeindex is as follows First create if necessary a file index tex that Vinputs index ind A skeleton is illustrated in the next subsection Then fweave XI test web Creates test idx and test sty makeindex s test sty o index ind test idx Creates index ind latex index If you re not happy with the pg macro supplied in fwebmac sty define it yourself in index tex In this procedure note th
159. l but consider how things would differ if abc were itself an FWEB macro that should itself be expanded 5 13 Pseudo invisible operators Pseudo or invisible operators are ignored by FTANGLE and not printed by FWEAVE however they retain grammatical significance that helps out FWEAVE in its attempts to understand the syntax 5 13 1 e Pseudo expression e is an invisible expression pseudo expression see Section 10 2 1 Pseudo operators i page 101 It is sometimes useful in situations where FWEAVE s pretty printing has broken down because it didn t properly understand the language syntax If for example FWEAVE failed to properly parse the C statement p int q one might get things to work properly by saying p int e q In this particular case one is patching up a deficiency all right a bug in FWEAVE s production rules This particular bug may no longer exist However there are other situations in which the use of e might be necessary Consider for example the C macro definition define A x x Here the replacement text of the macro is x which by itself is not a valid construction in C When the 1 or 2 options are used FWEAVE will report an irreducible scrap sequence in this situation although it may typeset it correctly anyway To eliminate the warning message say instead define A x e x Now the fragment e x is interpreted
160. l text is converted into the option text and options have the same syntax as on the command line The language symbols must be in lower case they are C c C c Fortran 77 n Fortran 90 n9 Ratfor 77 r Ratfor 90 r9 TeX x VERBATIM v An example of a command with the optional text field is n By definition this is equivalent to n n Thus it both sets the language and invokes a command line option As another example n9 really means n n9 Thus the language is first set to FORTRAN then reset to FORTRAN 90 One doesn t need to worry about this detail n9 n amp means set the language to FORTRAN 90 and use free form syntax with the ampersand as the continuation character This construction is now FWEB s default Chapter 8 LANGUAGES 84 The brackets may contain more than one space delimited option A language command should appear somewhere in limbo before the start of the first section The language in effect at the beginning of the first section defines the global language For historical reasons the default language is FORTRAN 77 but do not rely on this always include a language command Language commands may be used within sections but the new language remains in force only for that section The language of a named module is inherited from the language in effect at the time the name is first used Thus in the following example the global language is FORTRAN 77 but an arbitrar
161. lass usepackage lt doc preamble gt begin document j lt limbo begin gt contents of any 1 commands user s TeX commands from the limbo section lt limbo end gt The limbo end command is useful for printing the entire document in two column format For more discussion see Section 10 1 3 5 LIndex page 96 12 3 8 12 meta FWEAVE To be finished 12 3 8 13 preamble Additional TEX material can be inserted at the beginning of a named section with preamble named and at the beginning of an unnamed one with preamble unnamed 12 3 8 14 dot constant In FORTRAN dot constants such as LT are begun and ended by periods In special circumstances the beginning and ending characters may be modified by dot constant begin l and dot constant end l 12 3 8 15 null file The name of the null file or device For more discussion see Section 3 3 Change files page 13 12 3 9 Automatic file name completion For more information see Section 4 2 14 e page 19 Chapter 13 USAGE TIPS and SUGGESTIONS 121 13 USAGE TIPS and SUGGESTIONS In this section are collected various tips and suggestions to help one make full use of Fwes Additional hints broken down by each supported source language can be found in Chapter 8 Languages page 83 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 pu
162. le might ultimately consist of the code from sections 2 5 and 9 for example To use a named module simply use the name anywhere in a code part FTANGLE will insert the contents of the module at the point where the name is used For example c Here s how to use a named module a for i 1 i lt n i lt Inner loop Here s how to define a named module Definitions may occur after use lt Inner gt ali i There are several details to notice about the above example First FWEAVE considers module names to be simple expressions such as the single identifier x In C expressions are made into complete statements as is required in the body of a for statement by appending a semicolon In this case a pseudo semicolon is appropriate for more discussion of that see Section 5 13 2 AT page 58 Second after a name has appeared once in full it may be abbreviated by a unique prefix followed by three periods as demonstrated in the above example By convention a complete module name cannot be a subset of another For example lt Test gt and lt Test of graphics gt will elicit an error message Commonly the first unnamed section in the code indicates its modular structure For example a C code might begin with c Q DEMO Qa lt Include files gt lt Typedefs gt 0 lt Function prototypes gt 0 lt Global variables gt Chapter 2 WEB CONCEPTS 10 Su
163. least the two subdirectories Web and Manual 3 Change to the new Web subdirectory and run the configuration script cd fweb 1 61 Web configure configure is an sh script It attempts to figure out various local system fea tures automatically then generates the three files defaults mk config h and custom h those are used in the make For further information about the operation of configure see fweb 1 61 READ_ME FWEB 4 Make and install the release make CFLAGS special compiler flags make install If gcc is available it will be used in the make in that case the default CFLAGS should be sufficient If another compiler is used ensure that it is run in ANSI compatible mode not the old style Kernighan and Ritchie FWEB compiles on my system without any warnings with gcc ansi pedantic Please report any compiler warnings from an allegedly ANSI C environment Concept index Concept index EIE cece ete 87 ETUE N 87 literal tenes 7 A Absolute value cece eee eee 68 Allocation memory aaa 35 108 ASCII converting to aan 51 68 Asserting a condition 68 Assignment operators compound 37 87 Author a hh hh 68 Automatic pseudo semicolons 24 58 88 Automatic semicolons aaa 24 87 B Bar vertical 39 56 Binary notation eese 84 85 Blocks numbering 4 17 25 3
164. line and related information 12 3 3 Customizing the Table of Contents contents tex is the name of the file into which the Table of Contents is written contents preamble is the TEX string that begins printing the Table of Contents contents postamble is the TEX string that ends the Table of Contents 12 3 4 Customizing cross reference subscripts When FWEAVE pretty prints code it can attach cross reference subscripts to various kinds of identifiers such as function or macro names A bullet e for a subscript indicates that the name was defined in the current section The actual marking of the cross reference is done by the command see Section 5 7 AT page 51 This is usually done implicitly for example the commands a d and m issue an implicit See the discussion of a in Section 5 4 4 ATa page 40 In C various declarations of variables also result in such an implicit mark Chapter 12 CUSTOMIZATION 115 Various nuances in the type possibly underlined used for the subscript give a hint about what kind of identifier FWEAVE thinks it s working with For more information about the typesetting conventions see the definition of the primitive macro W IN in fwebmac web The following flags select which identifiers are so subscripted To see the default values of these parameters say ftangle Zmark_defined To turn off the subscripting operations completely use the
165. lt meaning of the k option was changed now both lower and upper case forms of FORTRAN I O keywords are recognized See Sec tion 4 2 23 k page 22 Various changes were made to internal code in fwebmac sty This should not affect anyone unless you have redefined fwebmac macros If so you ll have to compare your versions with the present ones For example colons as argument delimiters in defs have been removed It is now barely possible to use documentstyle revtex instead of the default documentclass article See Section 10 1 3 2 REVTeX page 94 14 1 4 Significant bugs v1 61 1 Perhaps the most significant bug is that some high order gt 128 char acters in strings may not typeset or be processed correctly This may be an issue for some users of foreign language packages The difficulty arises from a design decision made by a previous author This has at least partly been fixed but I eschewed a substantial overhaul for fear of breaking other things 14 2 Version 1 53 126 This release fixes a relatively small number of obscure bugs in fweb 1 52 beta A few minor enhancements were also made They include 1 Sections can be numbered by consecutive integers rather than LaTeX s default Dewey decimal form by saying LaTeX package fwebnum See Section 10 1 3 4 Sections page 95 The H option experimental and incomplete was added For C and C this option tells FWEAVE to scan i
166. lude files This can generate many entries since system header files may be complicated and may include other files as well This command is implemented as follows When FWEAVE reads an include statement it issues a system command to run the C preprocessor on the included file Output from the preprocessor is written to a temporary file which FWEAVE scans By default the C preprocessor will look in certain default paths for the included files To add to those defaults use one or more I options after the H These colon delimited Chapter 4 RUNNING FWEB 21 lists are concatenated to the contents of the environment variable FWEB HDR INCLUDES if that is defined The entire list is then passed as multiple I options to the preprocessor This command new with version 1 53 is highly experimental and incomplete The installation script attempts to determine what command to use to run the preprocessor but that is not guaranteed to work in general H has been tested only with gcc To send arguments to the C preprocessor see Section 4 2 65 4 WH page 33 The H mechanism uses temporary files to do its work By default those are deleted after use However for debugging purposes one can force those to be retained by saying Hr That option also has the side effect of displaying the actual command line that was sent to the preprocessor 4 2 18 h Get help If just h is typed a message
167. lude optional arguments that limit the information that will be listed See Section 4 2 11 D page 18 14 3 Version 1 52 This release was issued only as a beta version It consists mostly of bug fixes However there are a few other interesting points 1 fwebmac sty was enhanced to warn the user to run La TEX again when the section numbering hasn t yet been brought up to date I m not sure I ve covered all the bases but before it didn t complain at all 2 C classes are now formatted identified as reserved words on the first pass so forward references such as The class Cl Qa class C will now work Note that typedef has done this for a while although there are still a few glitches 3 For two years the documentation has described two control codes as fol lows Q inhibit line break force an index entry Apparently the code had these definitions inverted it has now been brought up to date with the documentation Fortunately these commands are evi dently not heavily used since no one complained 4 fwebmac sty was further reworked to interact properly with the user pack age multicol If in fweb sty one says LaTeX package multicol then the two column index is done with multicol this gives various improve ments over the twocolumn format that was used previously Furthermore it s possible to use multicol to do one s entire document in two column format This turned out t
168. ly upper case keywords format KEYWORD Wtypewriter character strings format typewriter 12 3 5 2 indent indent TeX specifies paragraph indentation for the TEX part indent code specifies similar indentation for the code part 12 3 5 3 LaTeX 7 For LaTEX2e the default document class can be overridden by LaTeX class The default class is article and FWEB has not been tested with other document classes except minimally with revtex see Section 10 1 3 2 REVTeX page 94 Options to the document class can be specified by LaTeX class options User packages can be given by LaTeX package Options to user packages can be specified by LaTeX package options There may be just one LaTeX package command and just one LaTeX package options command If it is necessary to issue multiple such commands then put them into doc preamble See the discussion in Section 10 1 3 1 Document class page 93 When running under La TEX prior to La TEX2e or with REVTeX see Section 10 1 3 2 REV TeX page 94 the document is effectively begun by the command documentstyle options style The options field can be specified by LaTeX options the style field by LaTeX style 12 3 6 Remapping control codes Control code remappings are sophisticated and unwise They are mostly intended for the developer so are not explained here Chapter 12 CUSTOMIZATION 117 12 3 7 Color output In the design of FWEB provision has been made for
169. mal ED 112 p qM 112 LE hehe 112 AE e hne 35 Option and command index DE 35 fweb Ee hn 12 108 Ql cece hh hes 39 1 ccc nett tenn eee 59 CE DUE 56 O define ee cee 80 elif aaau ereraa erre 80 endif eee 80 ER eens 80 ifdef eee 80 O ifndef eee 80 O line eee 80 undef eee 80 ME 52 Qiii IR rh hh s 52 CE 57 CEE 51 TE 53 EE annarrar nen ar annen 53 CE ME 6 39 C 55 EE cette hrs 54 MEDI 54 JA 55 TEE araea rrara rarere 52 YE hh 52 EE hh hes 59 EE ehh hh 58 ER ccc nnn tet tenn eee 55 DEDE 53 TEE ehh hers 38 OL ccc mmn 14 52 hn 14 ll 54 QU tne hrs 51 IE hn 39 56 EE hh hh hers 57 MUI 54 EE hh hes 40 ER hh hrs 54 TE 56 QS cece teen nnn eee 40 0 hh hh hh hes 38 EE ehh hh heres 38 EE hehehe 38 ER ehh hrs 54 139 0 EE hh hen 40 A 40 EE N rh ahhh an Al MM Al EE ehh hh hh eren 41 QCH DUI 42 MM 42 MM 42 ER ehh hh 57 EE N 42 OE N et beeen nents 42 ENE ehh hh 43 EE EE N hahaha AA SE EE N 50 SE N rea araara reana 50 CUE 45 JM 45 OM EE n ete 45 J N N 45 6 ehh hh hh 47 C0 N 46 OS he ehh hh 47 EE hh hne 47 Co N N N hh hmm hh hn 47 Q hh e 48 OL EE hh hen 49 JE 49 EE EO 49 QE M 55 QU EE hh eren 49 C0 DUEE 49 C0 EE N 50 AE cee tenet nents 50 D MEE 50 ESE ehh hh hh hen 50 OY EEEE 27 VbeforeindeX EE nn 96 botofcontents EE EE EE Ge ee 97 documentclass EE eee ee ee 93 documentstyle is
170. module warning flag FWEAVE can check module names for the possible anomalous conditions of never used or multiple uses These correspond to a module warning level as in the following num bered list Chapter 4 RUNNING FWEB 33 1 Never used 2 Multiple uses The module warning flag is the bitwise OR of the desired warning levels warning messages are printed only when the relevant bits are turned on By default it is 1 so only messages about never used modules are printed The W flag overrides the default For example to get messages only about multiple uses say W 2 to get no messages say W 0 One can put such an option into the fweb initialization file see Section 12 2 Initialization page 108 FWEAVE will always complain about module names that are never defined 4 2 65 2 W1 Cross reference single character identifiers By default FWEB does not index uses of single character identifiers following Knuth s original design It does index their definitions To get complete cross reference informa tion for single character identifiers use the W1 option 4 2 65 3 W Process bracketed array indices This experimental option makes square brackets behave like parentheses in the context of array indices In FORTRAN FTANGLE will just replace the brackets by parentheses In C the brackets will be left alone FWEAVE however will typeset the indices according to
171. mp Q Qa program main x amp y end For FoRTRAN 90 free form syntax continued by the ampersand is FWEB s default so one probably will not need to use n amp explicitly See also Section 4 2 38 n page 26 4 2 40 n Recognize short comments FORTRAN The standard FWEB notation for a short comment one terminated by the next newline is However in FORTRAN the denotes concatenation by default To make it denote a short comment use the n option One can do this in the fweb file see Chapter 12 Customization page 107 or with the language setting command in limbo as in n In FWEB one may always use for concatenation so there s no penalty for using n 4 2 41 n Make denote short comment FORTRAN In FoRTRAN 90 V starts a short comment However by default FWEB usurps for the logical not as in if x y To force it to recognize as a comment use n However the recommended style is to use FWEB s standard convention that denotes the start of a short comment see Section 4 2 40 n page 27 See also Section 4 2 81 page 37 and Section 4 2 56 r page 30 In FORTRAN 77 to include the exclamation point inside a string escape it with a back slash as in s A inside a string This possibly annoying restriction arises because the unduly complicated FORTRAN input driver does
172. n has a definition part consisting of one FWEB macro definition m the second section has no definition part For more information see Chapter 7 Macros page 62 Failure to appreciate how easy it is to shift from part to part can get one into trouble For example don t write documentation such as Consider the m command because the m will inadvertently terminate the documentation part and begin the definition part What one needs to do here is to use the literal as in m 2 2 0 4 The code part An unnamed code part is begun by a A named code part is begun by the appear ance of a module name such as lt Global variables gt followed by an equals sign see Section 2 3 Modules page 8 Within the code part one can place any sequence of code Chapter 2 WEB CONCEPTS 8 or code fragments they need not be complete subroutines that are valid for the current language Setting the language is described in Chapter 8 Languages page 83 The code part is terminated by the next appearance of or which signal the beginning of a new section or by the end of file 2 2 0 5 The limbo section The portion of the source file before the first section i e before the first or is called in limbo or the limbo section The only commands that are allowed in limbo in addition to which stands for the character and is allowed anywhere are
173. n unique identifiers these are listed 4 2 61 U Convert reserved output tokens to lower case FTANGLE Particularly during RATFOR expansion certain tokens such as DO are output by FTAN GLE in upper case The U option forces such tokens to be produced in lower case 4 2 62 u Undefine FwrEB macro FTANGLE uA undefines the FWEB macro fweb via m CAUTION This option can also undefine built in functions such as IF Don t do that since built ins can use other built ins behind the scenes undefining one can cause very strange behavior A previously defined on the command line or in 4 2 63 V Print FWEB version number This flag requests the startup banner which includes the FWEB version number to be printed This is usually done anyway so it is only relevant when the message level is 0 see Section 4 2 26 M_ page 23 4 2 64 v Make all comments verbatim FTANGLE By default comments are not passed to the tangled output With v all comments are included verbatim in the tangled output Since there s generally no harm in this one might want to put this option into fweb see Section 12 2 Initialization page 108 4 2 65 W Flag setting options for FWEAVE This is a family of options that set miscellaneous flags appropriate only for FWEAVE Options such as W and Wf can be combined as W 4 2 65 1 W Set
174. nclude files for typedef and or class definitions See Section 4 2 17 H_ page 20 The k option was added This tells FORTRAN and RATFOR to understand the lower case forms of I O keywords such as iostat with the exception of read write and end See Section 4 2 23 k page 22 The n option was added This tells FORTRAN to place statement labels on a separate line which is useful when the labels are relatively long By default FORTRAN labels are placed on the same line as the thing they are labeling which looks good for short labels See Section 4 2 34 ncolon page 25 The preprocessor command line was added For C code this adds an explicit line command to the tangled output file This helps to keep the line numbers between debugger and source file in syne when an FWEB preprocessor statement expands to several lines See Section 7 2 4 Debugging with macros page 79 Chapter 14 NEW FEATURES 127 An implicit line command is added after each see Section 5 8 3 AT page 52 that begins a line this keeps line numbering correct To override this use the option T See Section 4 2 59 6 T page 31 6 p style file options see Section 4 2 46 p page 28 on the command line are now processed after the local style file See Section 12 3 Style page 112 7 The functionality of the D command was enhanced to inc
175. nd line syntax is ftangle fweave option webfile web changefile ch A file name is anything that doesn t begin with a except that a lone hyphen stands for the special file name stdin which means read from the standard input This should not be used except for very special effects Command line options begin with a File names and options can be intermixed or the options may appear after the file names The first file name encountered is the web source file the second if it exists is the change file see Section 3 3 Change files page 13 When no change file is specified FWEB attempts to read from the null file dev null on UNIX systems This name should be specified when FWEB is installed see Chapter 12 Customization page 107 or can be set in the style file fweb sty See Section 12 3 8 15 null_file page 120 The web file is shown as required since one is normally processing a source However some of the information options see Section 4 2 82 Info options page 37 will work without specifying any file name For example one can obtain a list of all of the style file parameters and their default values by saying ftangle Z 4 2 Command line options Command line options may be put one per line into the initialization file fweb which is always in the user s home directory In that file options beginning with a hyphen are processed before the command line
176. nd yourself in fweb sty you should include FWEBtoc at the end of that initialization if you want the Table of Contents to appear in the beginning Otherwise it will appear at the end In essence the Table of Contents is produced by the La TEX commands pagenumbering roman maketitle topofcontents tableofcontents botofcontents newpage By default the FWEB hooks topofcontents and botofcontents are empty but they may be used in special circumstances to override the usual behavior One can set the parameters for maketitle in the limbo section in the usual La TEX way except that it is better to use FWEB s Title macro instead of title Title MYCODE WEB author My name date January 1 2001 By default the argument of the Title macro is printed both on the title page and as a running headline in the document The default font for the title is ttitlefont that for the running headline is large tt However Title has one optional argument that allows one to override the running headline perhaps by specifying a shorter form Say Title Short title Long title to make the running headline be large tt Short title and the title page title be ttitlefont Long title The F wes Title macro calls LaTEX s title macro with the long title as its argu ment By default F WEAVE uses in the Wbegin macro titled author 4 date today 3pt Time Section numbers in the Table of Cont
177. nditionals as they are used internally to FwEB 7 2 3 24 IFCASE n way conditional This primitive built in behaves like TEX s Nifcase command The syntax is IFCASE expr case 0 case l case n 1 default If expr reduces to an integer between 0 and n 1 inclusively the appropriate case is selected otherwise the default case is selected As examples IFCASE 2 zero one two default gt two IFCASE 2 zero one three gt three IFCASE 2 zero one gt one Chapter 7 MACROS and PREPROCESSING 72 7 2 3 25 IFDEF Two way conditional This built in primitive is the code part version of ifdef The syntax is IFDEF macro action if defined action if not defined 7 2 3 26 IFNDEF Two way conditional This built in primitive is the code part version of ifndef The syntax is IFNDEF macro action if not defined action if defined 7 2 3 27 IFELSE Two way conditional The syntax of this built in primitive is IFELSE exprl expr2 action if equal action if not equal The expansions of expri and expr2 are compared on a byte by byte basis If they are equal the first action is taken otherwise the second action is taken For example M S abc IFELSE abc S yes no evaluates to yes 7 2 3 28 INCR Increment a macro INCRCN redefines the numeric macro N to be one greater than its previous value If N does not simplify to a number an err
178. ne beginning with and replace that with amp 2 The La TEX processor PL is now the default 3 The experimental fwebmacL sty macro package supplied with version 1 40 has been substantially reworked and is now the default fwebmac sty Remove any reference to fwebmacL sty from your fweb file 4 Support for La TEX2e is now provided See Section 10 1 3 LaTeX page 93 5 The style file parameter index name was added This is the section name to be given to the Index see Chapter 11 Index page 103 which should be the last major starred section It becomes the contents of the macro VINDEX Therefore one can end one s source file by saying Q XINDEX 6 The IF class of built in functions was reworked They should now be more robust recursive and intuitive Simple uses of these functions should work as before However complicated uses that depended on tricky things about the order of expansion of arguments may require revision Carefully compare the descriptions of these functions in the documentation e g see Section 7 2 3 23 SIF page 71 with your usage of them in any pre existing code In some cases if a previous constructions using IF no longer works it might work if you say m IF a b c IF a b c and then use IF in your code This forces an extra level of macro expansion The same remark goes for DEFINE The old forms _IF etc no longer work conver
179. ng ampersand However newlines are thrown away before tokenized text is seen by FWEAVE s parser and in any event would just be in terpreted as white space Therefore by default newlines that terminate statements are replaced by pseudo semicolons so the parsing proceeds correctly In the FORTRAN 90 case one could also insert pseudo semicolons or actual semicolons by hand and some users prefer that The possibilities are controlled by the options n see Section 4 2 32 nAT page 24 and n see Section 4 2 33 n page 24 Chapter 5 FwEB COMMANDS 59 5 13 3 Pseudo colon is an invisible colon see Section 10 2 1 Pseudo operators page 101 It can be helpful in formatting certain C constructions correctly For example if one has a named module defined as lt CasesQ gt case 1 case 2 case 3 then one can use it as a case construction followed by the usual colon as in switch c lt CasesQ gt stuff break 5 14 Miscellaneous commands 5 14 1 Inhibit macro expansion FWEB macros and built in functions are always expanded by default This may not be desirable particularly in the N mode To inhibit expansion of an individual identifier preface it by Chapter 6 COMMENTING STYLES 60 6 COMMENTING STYLES FWEB allows a variety of commenting styles The visible comments are in the font cmntfont which defaults to mainfont a ten point Roman
180. no matter how many times it is run since FTANGLE will never update the time stamp on the files This is harmless but annoying To get things back in sync do a run without the F The location of the temporary file as well as details of the renaming procedure are determined by the automatic configuration script configure during installation of the processors The script first looks for the non ANSI function tempnam If it finds it it uses it to place the temporary file in the directory that FWEB would normally use for output in the absence of the F option That is usually the current directory If tempnam is not available the ANSI routine tmpnam is used That places the temporary file in a directory determined by the system Chapter 4 RUNNING FWEB 20 To implement the renaming the rename function is used That may fail if tmpnam placed the temporary file on a different device If so an attempt is made to force the rename by using the system routine to issue a mv command Terminal output indicates the progress of the renaming An asterisk following an output file name indicates that rename did not succeed but the mv command did Some of the above mentioned file names and system commands are system dependent see Chapter 12 Customization page 107 4 2 16 f Turn off module references for identifiers FWEAVE In an attempt to be helpful FWEAVE appends subscripts to many identifiers indicating in which section they
181. nore such files completely This option is seldom useful the i option see Section 4 2 20 i page 21 is more often used 4 2 22 j Inhibit multiple includes File inclusion via FWEB s i command suffers from a design deficiency they cannot be inhibited by means of FWEB s preprocessor commands The reason is that i is processed very early in the input stage before tokenization This design decision was inherited from CWEB and is very difficult to change A particularly annoying situation arises when the same file is included multiple times various array space may be eaten up unnecessarily The j option inhibits such multiple includes 4 2 23 k Don t recognize lower case forms of keywords By definition in FORTRAN and RATFOR a keyword is one of the parameters such as IOSTAT used in the parameter list of an I O statement For example open 21 FILE file_name STATUS old IOSTAT io_flag Such keywords are typeset in typewriter type to better highlight them In FORTRAN these keywords are case insensitive However note that certain of the lower case forms in particular end read and write have other special meanings and one can in principle use any of these keywords as ordinary variables in other parts of the code however FWEB identifiers can have just one meaning throughout the code By default the lower case forms are also recognized as keywords except for the t
182. nt FORTRAN amp RATFOR This option is not recommended use FWEB s standard to begin short comments To include the exclamation point inside a string escape it with a backslash as in S A V inside a string 4 2 82 Information options Several of the command line options can be used to elicit information about the initial state of FWEB displays information about the control codes See Section 4 2 4 AT page 16 D displays information about reserved words See Section 4 2 11 D page 18 y displays default dynamic memory allocations See Section 4 2 69 y page 35 Z displays default values of style file parameters See Section 4 2 70 Z page 35 The h option reminds one about these information options it also provides convenient access to the GNU info browser See Section 4 2 18 h page 21 Chapter 5 FwEB COMMANDS 38 5 FwEB COMMANDS All FWEB commands begin with the character It is recommended that these begin in column 1 if possible This is required in some cases e g the x y and z in change files see Section 3 3 Change files page 13 or column oriented FORTRAN 77 processing Some of these control codes may be used anywhere others begin a new part of the current section For a discussion of sections and parts see Section 2 2 Structure page 5 For a quick summary of the control code mappings and to see which codes
183. nt that is emitted can be changed by redefining the macro Wblock in fwebmac sty Chapter 4 RUNNING FWEB 18 4 2 8 C Set the color mode The option Cn sets the color mode to n where the color modes are briefly 0 No color 1 ANSI color 2 Bilevel 3 Trilevel 4 User defined These modes and color output in general are described more thoroughly in Section 12 3 7 Color page 117 For obscure technical reasons this command is processed differently than all other command line options In the present incomplete implementation the color mode must be set on the command line not in fweb To work around this annoyance UNIX users could alias commands such as ftangle C1 4 2 9 c Set global language to C Usually the global language Chapter 8 Languages page 83 is set to C by means of the command c in limbo rather than using c on the command line However one may need to use the command line option c if a subsequent command line option is language dependent See for example the discussion of the option D in Section 4 2 11 D page 18 4 2 10 ct Set global language to C For more information see the discussion of c in Section 4 2 9 c page 18 4 2 11 D Display reserved words This information option displays the list of reserved words for the language currently in force For the purposes of this option reserved words includ
184. ntegrated with TEX one gains many advantages such as book quality typesetting and extensive cross referencing facilities A simple example program is described in Section 2 2 Structure page 5 FWEB was originally intended for scientific programming the F stands for FORTRAN and is in wide use in that arena however it has much broader applicability It is an extension of Knuth s WEB system that handles the specific languages C C Fortran both F77 and F90 RATFOR and in a limited fashion TEX itself It also attempts to implement a WYSIWYG language independent mode as well as a closely related but not identical verbatim language The language independent features are highly experimental and are not recommended The origins and philosophy of literate programming are described in the very enjoy able book by D E Knuth Literate Programming Center for the Study of Language and Information Leland Stanford Junior University 1992 Knuth s original WEB was written in Pascal and it formatted Pascal code Silvio Levy introduced CwEB a WEB system written in C for C FWEB is a by now substantial modification of version 0 5 of CWEB that was graciously supplied by Levy It also borrows various ideas from the works of Ramsey and Briggs on language independent webs The original WEB s worked with Plain TEX More recently many users have turned to Lamport s La TEX because of its ease of use and higher level features Excellen
185. nusual macro constructions inserts a thin space analogous to TEX s An example where explicit spacing would be necessary is as follows Qc Q Om OP m A x y x OP y a z Ala b Without the s the body of the A macro will weave as the unappealing xOPy This occurs because although OP is defined to be a binary operator FWEAVE thinks of it as just a mere expression and one of its fundamental production rules is to concatenate expressions with no intervening expressions This demonstrates that situations arise in which one needs to override FWEAVE s default processing But for the above example there is actually a better solution Instead of using the s include the format command f OP BINOP See Section 5 5 8 ATf page 42 5 12 2 Force a line break preserving indentation This command is used to override FWEAVE s natural inclinations For example if one wants each piece of a declaration to appear on a separate line one can say int i j e Chapter 5 FwEB COMMANDS 56 k This command preserves the natural indentation that would have happened if FWEAVE or LaTEX had broken a long line spontaneously Thus the declared variables are indented in the above example To remove that indent use V instead See Section 5 12 3 ATbs page 56 Try to use the line break commands sparingly i e let FWEAVE do the work Often if lines run together in an un
186. nvolving signs so they can be used only where simple statements are allowed not essentially anywhere as in C for example they cannot be used as function arguments 9 2 RATFOR commands 9 2 1 RATFOR 77 commands Chapter 9 RATFOR break Used with case or to break out of loops as in C case i Used with switch default Used with case as in C 90 do Note the semicolon unnecessary if followed by a compound stmt else Used after if as in C for a b c Asin C if condition 1 next Equivalent to C s continuel statement go to bottom of loop repeat 1 until condition Equivalent to C s doul Fuwhile return expression Asin C switch expression Asin C while condition 1 Like C s while 9 2 2 Additional RATFoR 90 commands contains interface name 1 interface operator op interface assignment assgnmnt 1 module name 1 private sequence type name where expression 9 3 Caveats about RATFOR The version of RATFOR built into FWEB differs slightly from its UNIX counterpart 1 Numeric statement labels must be followed by a colon they should be first on their line Use symbolic statement labels instead see the discussion of 0 in Section 7 2 2 Tokens page 65 2 The quoting convention for characters and strings follows that of C Single quote single characters double quote st
187. o index idx filling in the integer file identifier n the position of the file in the sorted list into the first argument of the pg macro One can now say makeindex s testi sty index This creates index ind which can be processed by for example a simple modification of the simple La TEX template given above in Section 11 2 Using makeindex page 103 The only difference is that the package idxmerge was used in that file the macros topofindex and idxname are appropriately defined to print out a numbered list of the merged files to cross reference into the numerical file and page number entries in the body of the index Here is an example provided in the FWEB distribution 4 index tex skeleton for printing a stand alone index documentclassf article usepackage fwebmac idxmerge begin document input jobname ind end document Chapter 12 CUSTOMIZATION 107 12 CUSTOMIZATION The default behavior of FWEB can be changed in a variety of ways 1 UNIX environment variables logical variables in VMS affect path or file names 2 An initialization file resides in the home directory 3 A style file resides in the current directory The initialization file usually called fweb is intended to contain command line op tions one per line that are to be used in every run See Section 12 2 Initialization page 108 The style file called fweb sty by default see Section 4 2 71 z p
188. o be relatively simple but one needs to get the commands in the proper order See Section 10 1 3 5 LIndex page 96 for more details Two column format substantially cuts down the white space I saved about 5096 on a 200 page code One known glitch with FWEB multicol is that if one selects page number cross references instead of La TEX section numbers page references such as 98c don t get the c correct This is presumably not a big deal At this point assume that the use of multicol is highly experimental 5 Further bugs in the C and C production rules were fixed Chapter 14 NEW FEATURES 128 14 4 Version 1 50 1 The syntax for entries in the initialization file fweb see Section 12 2 Initialization page 108 has been modified in a way that is as backward compatible as possible Previously meant process the option before the command line options meant process it after This convention was somewhat hard to remember given the statement that any command line option could be put into fweb furthermore just about everything in fweb should in fact be processed before the command line options So now both and mean the same thing namely process before and the notation should fade away as time goes on If you explicitly want something to be processed after all command line options for some tricky reason begin it with amp Le scan your fweb file for any li
189. o force it to continue you might get usable output 10 1 3 3 LaTpX packages related to FWEB The following packages are supplied with the FWEB distribution and can be used to achieve special effects Packages are invoked by giving their names as arguments to the LaTeX package command see Section 12 3 5 3 S La TeX page 116 e fwebinsert Enables insertion of woven code into a LaTEX document See Sec tion 10 1 6 1 Inserting woven code page 99 e fwebnum Number each section in ascending integer order See Section 10 1 6 Num bering page 98 e idxmerge Merge several stand alone indexes See Section 11 3 Merging indexes page 105 10 1 3 4 Sections in La TEX FWEB s sectioning commands and n are converted into La TEX s section com mands such as section n 0 subsection n 1 and subsubsection n 2 During La TEX s processing of the tex file it keeps track of the maximum depth achieved by n This number is written as the last item in the aux file During the next La TEX run that number is used to map the untitled commands to the next most insignificant sectioning command That level of sectioning command is slightly redefined from La TEX s default so don t try to redefine it The previous scheme means that it may be necessary to run LaTEX as many as three times in order to resolve all sectioning and cross reference information correctly You should Chapter 10 DOCUMENTA
190. ol nomulticol beforeindex newpage twocolumn print INDEX section heading startindex begin multicols 2 medskip Wfin Nend multicols relax Use of the asymmetrical name Wfin is for historical reasons The positioning of beforeindex suggests a way of printing the entire document in two column mode If one enters multi column mode in the limbo section then beforeindex can be used to terminate it It is best to do this at the end of the limbo section otherwise user macro definitions in the limbo section must be made global in order that they remain defined in the Index The relevant commands can be placed in the style file LaTeX package multicol doc preamble secpenalty 0 limbo end def beforeindex end multicols newpage n begin multicols 2 n raggedcolumns Just to repeat use only the first command to get just the Index printed in two column format use the second and third ones to make the entire document two column 10 1 3 6 LaTEX s Table of Contents LaT X uses the aux file to accumulate the information for the Table of Contents Chapter 10 DOCUMENTATION 97 When LaT X is used the Table of Contents appears at the front of the document by default beginning with version 1 61 This is accomplished by setting the default value of the style file parameter limbo end to FWEBtoc where FWEBtoc is defined in fwebmac sty If you initialize 1imbo e
191. onal argument it must be protected by braces If is followed by a digit n it begins a new major sub section of level n This is also entered into the Table of Contents Thus the complete syntax to begin a major section is n Short name Full name For example MAIN PROGRAM This begins a major section of level 0 Qa main Chapter 5 FwEB COMMANDS 40 0 1 Input routines dots A very long section name that essentially means input routines Now follow some subroutines a get input For La TEX the highest permissible major level is 2 a subsubsection Section names can contain reasonably arbitrary TEX text including font changing com mands and other macros However it is necessary to understand that fragile commands in the sense of La TEX may not work because the section name is used in various contexts e g as a page header If a macro in a section name doesn t work properly try preceding it with protect FWEAVE converts commands to section numbers For a discussion of section num bering see Section 10 1 6 Numbering page 98 5 4 Beginning of code part The code part is begun by the appearance of either a or 4 Module name 5 5 4 1 lt Begin module name lt begins a module name which has the form lt TEX text gt Module names inside FWEB macro definitions begin with not lt 5 4 2 gt
192. one would thus say makeindex s test sty o index ind test idx It s important to use the o option with a name different than the original file name because it simplifies the construction of the skeleton file index tex that prints the stand alone index FWEAVE writes test sty because the contents of that file may depend on parameter settings in FWEB s style file fweb sty FWEB s style vocabulary includes all parameters understood by makeindex If a makeindex parameter is called param one references it in fweb sty by makeindex param Thus to change the headings flag of makeindex one would put into fweb sty a line like makeindex headings flag 1 To see a list of all makeindex related parameters say fweave Zmakeindex see Section 4 2 70 Z_ page 35 Remember do all makeindex customizations in fweb sty the actual style file test sty that will be read by makeindex is written automatically by FWEAVE The idx file will contain a list of entries that begin with indexentry more precisely the value of the parameter makeindex keyword The general form is indexentry sort key identifier expression macro page number Typical entries are indexentry istream gt istream pg 1 indexentry main gt main pg underline 1 indexentry pow pow pg 2 indexentry z lzlpg underline 2 Chapter 11 FWEB s INDEX 105 H
193. options so command line options can override the defaults To force an option to be processed after the command line options preface it with an ampersand rather than a hyphen this is rarely necessary To make sense of the plethora of options it helps to know that options beginning with n are related to FORTRAN those beginning with r are related to RATFOR Some flags that can be set separately for those two languages also have a global option that sets the flags for both languages simultaneously cf n r and Some options take arguments For example an FWEB macro can be defined from the command line by saying something like mIBMPC 1 Unlike many UNIX utilities no spaces Chapter 4 RUNNING FWEB 16 are allowed between any option and its argument For example if one says m IBMPC FWEB will think that IBMPC is a file name 4 2 1 Negating options To negate a command line option use an extra hyphen For example v means Don t make all comments verbatim This kind of construction isn t used very often but it is useful if an option such as v is turned on in the fweb initialization file and one wishes to turn it off for just one run 4 2 2 1 Turn on brief debugging mode FWEAVE This option tells FWEAVE to display irreducible scrap sequences A scrap is a part of speech The expression x y consists of three scraps x an expre
194. or results In other words in the language of C the effect is to say N The two argument form INCRCN m executes the equivalent of N m 7 2 3 29 INPUT_LINE Line number that begins current section INPUT_LINE is the number of the line in the web source file that begins the cur rent section not the source line in which the INPUT_LINE command appears Compare OUTPUT LINE Section 7 2 3 45 SOUTPUT LINE page 76 7 2 3 30 KEYWORD Value of global RCS like keyword KEYWORD provides a built in function alternative to the use of K in a code part see Section 5 5 11 ATK page 44 KEYWORD Keyword extracts as a character string the text of an RCS like keyword defined in the ignorable commentary between z and x at the beginning of the web source file see Section 5 5 31 ATz page 50 RCS stands for revision control system The general syntax is UNIX users see man ident Keyword text of keyword For example z Author krommes Ox Chapter 7 MACROS and PREPROCESSING 73 c a char author KEYWORD Author This tangles to char author krommes In this example Author is one of the standard RCS keywords However any keyword that fits the syntax keyword contents can be accessed by KEYWORD At least one blank is necessary before and after contents The argument of KEYWORD need not be quoted bu
195. orthand notation for DEFINE is M 7 2 3 13 D0 Macro do loop SDO macro imin imax di t Y repetitively defines macro as would the FORTRAN statement do macro imin imax di For example D0 I 0 2 1 all I generates the three statements a 0 0 a 1 1 a 2 2 In general the macro name used as loop counter should not be explicitly defined as a macro prior to the DO If it is not it will remain undefined after the end of the iteration Instead of the delimiting braces parentheses may be used These may be useful to help FWEAVE format certain constructions correctly Chapter 7 MACROS and PREPROCESSING 70 Nested delimiters are handled correctly The delimiters are required even if only a single statement is to expanded DO is implemented in terms of a command UNROLL However if one says something like SDUMPDEF UNROLL 0 5 1 FWEB will respond that UNROLL is not an FWEB macro Rather UNROLL is processed like expandable commands in RATFOR such as while This implies that it cannot be redefined as ordinary macros or built in functions can be 7 2 3 14 DUMPDEF Dump macro definitions to the terminal In the call DUMPDEF m1 m2 ml m2 and so on are macro calls with arguments if appropriate Two lines of output are generated for each argument Line 1 is the macro definition line 2 is its expansion using the provided arguments One can use this built in to debug one s own macro
196. os page 63 The syntax of each command is as follows line Insert a line command define identifier Define an FWEB macro equivalent to m Qitundef identifier Undefine an FWEB macro Qitifdef identifier Is FWEB macro defined Equivalent to if defined identifier Qitifndef identifier Is FWEB macro not defined Equivalent to if defined identifier if expression elif expression else Chapter 7 MACROS and PREPROCESSING 81 endif In the if statement the expression may contain FWEB macros but must ultimately evaluate to a number If that number is zero the expression is false otherwise it is true The expression following constructions such as if is evaluated by a built in expression evaluator that can also be used for other purposes such as in macro expansion Its behavior is again motivated by expression evaluation in ANSI C it is not quite as general but should be more than adequate One design flaw that will be fixed someday is that the order of expression evaluation is not necessarily left to right as it is in C It supports both integer and floating point arithmetic with type promotion from integer to floating point if necessary and the ANSI defined operator Operators with the highest precedence see table below are evaluated first as usual parentheses override the natural order of evaluation The unary operator defined has the highest precedence
197. ow begin with not _ The underscore prefix was a bad design decision it introduces conflicts with ANSI C in certain cir cumstances To ease conversion the old forms are still understood Thus one can use EVAL and _EVAL interchangably However do not use the underscore forms they will be deleted in future releases 3 Full La TEX support FWEB no longer usurps LaTEX s output routine and La TEX s sectioning commands Table of Contents commands etc are used T he appearance of the woven output is changed to be more book like This is an experiment 4 Verbatim language Lv selects a language independent format See Sec tion 8 2 6 Verbatim page 88 5 Language independent mode The N mode inhibits pretty printing blank compression etc source code is essentially copied literally from input to output This mode is turned on automatically by the VERBATIM language but it can also be used with the other languages It is turned on by the command line option N or the local command N See Section 5 5 17 ATN_ page 46 6 Writing of temporary files When the F command line option is in effect tangled output is written to temporary files instead of the final target files and the temporary files are compared to the last version of the target files on disk If there is no change the target files are not updated This avoid unnecessary recompilation if only the documentation not the cod
198. page 45 These should normally be placed in the definition part as in n Documentation m CUBE x x 3 a z3 CUBE x CUBE y Chapter 7 MACROS and PREPROCESSING 64 the appearance of an m in the documentation part begins the definition part They are collected during FTANGLE s phase 1 and effectively placed at the top of the unnamed section so they are all known during the output in phase 2 In unusual situations when macros are being conditionally defined and or undefined the order of processing a macro definition becomes significant If the command line option TD is used then FWEB macros may be used in the code part as well they are then called deferred macros These definitions will be processed during phase 2 in the order that the code sections are processed which may not be the same as the physical order in the source file The use of deferred macros is highly discouraged for the following reason FWEB macros are often used in conjunction with the FWEB preprocessor commands Preprocessor com mands are always processed during phase 1 so they do not interact properly with deferred macros It is for this reason that deferred macros are normally prohibited from appearing in the code part 7 2 1 Various features of FWEB macros e Fundamentally FWEB macros follow the syntax for ANSI C There are also a few extensions notably the possibility of variable optional arguments see Section 7 2 1 1 Var
199. pression by FTANGLE and tells FWEAVE to turn off pretty printing instead the output is printed in typewriter type within a begin verbatim end verbatim environment There are some subtleties with this mode not to mention the likelihood of bugs 1 FWEB macros and built in functions will normally be expanded even in the N mode To inhibit expansion of a particular identifier place before the identifier For example Om A 1 ON a A A expands to A 1 2 Blank lines are significant The N mode is ended by the appearance of the or denoting the start of the next section If that were preceded by one or more blank lines those would show up in both the tangled and woven output They might or might not be significant in the tangled output but they almost certainly will look ugly in the woven output To avoid this use the command which deletes the remainder of the current line and all immediately following empty lines For example ON a X hh Next section 3 If the N mode is invoked from a compiler like language such as FORTRAN cross referencing of variables is done as usual However if the language is VERBATIM which turns on the N mode automatically no cross referencing is done Identifiers are still recognized according to FWEB s rules Those rules as currently implemented may be essentially meaningless for some languages in the future provision may be ma
200. put in a different order than they are input The maximum number of tokens is controlled by ytt Chapter 12 CUSTOMIZATION 112 12 2 2 27 ytw Maximum tokens in the current section being processed by FWEAVE Unlike FTANGLE FWEAVE need only read in one section at a time The maximum number of tokens in any section is controlled by ytw 12 2 2 28 yx Maximum number of texts For FTANGLE a text is either the replacement text of a macro or the contents of a named section The maximum number of such texts is controlled by yx For FWEAVE a text is a phrase that arises from combining primitive scraps during the translation stage of phase 2 For both processors the absolute maximum number of texts is 10239 12 2 2 29 yxb Size of line buffer for TEX and verbatim output This option is like ycb see Section 12 2 2 3 ycb page 109 but controls the size of the output line for the TEX Lx and verbatim Lv languages 12 3 The Style file A style file default name fweb sty may reside in the user s current directory or the directory specified by the environment variable FWEB_STYLE_DIR The default name can be changed by the command line option z see Section 4 2 71 z page 35 The style file is processed after all command line options have been processed except that the command line option p see Section 4 2 46 p page 28 gets special treatment
201. r example nothing is actually processed while fweb is being read its contents are just being stored It could therefore happen that a syntax error in entering a p option in fweb may not be reported until after the style file has been read possibly confusing the user as to the source of the error 12 1 Environment variables FWEB_HDR_INCLUDES Colon delimited list of directories for the C preprocessor in the form of gcc to search for include header files This is used in conjunction with the H option see Section 4 2 17 H page 20 One can append to this list by means of the I option provided that option comes after the H see Section 4 2 19 L page 21 Chapter 12 CUSTOMIZATION 108 FWEB INCLUDES Colon delimited list of directories to search for i include files One can append to this list by means of the I option provided that option comes before any use of H see Section 4 2 19 L page 21 FWEB_INI Name of the initialization file If not defined either fweb or fweb ini is chosen depending on the machine The initialization file always resides in HOME FWEB_STYLE_DIR Directory in which the style file resides If not defined the current directory is used 12 2 Initialization Although some aspects of FWEB s behavior are hard coded many can be changed and or initialized by the user 12 2 1 The initialization file On s
202. r section beginning 0 39 Major section optional argument for 39 Major subsection 0 cece EE ek ee ee 39 Makefiles USE EG SG ge ee ee eee 5 Makeindex using aaa 103 Marriage hh 17 Maximum ssssssssee hen 75 Memory allocation 35 108 Message level ie cece eee es 23 Message tYDES is aaa 117 Mininum ees a 75 Module name beginning 40 Module name ending 00084 40 Module name of 75 Module named Ee eee 9 Module unnamed 0000s cece ee eee eee eee 8 Modules ccc aaa 8 Modules missing 77 Modules number of 75 135 Modules warning level for 0 32 multicol using ie SG nn 96 N Named module ie aaa 9 Not equal 37 87 Notation binary 84 85 Notation hexadecimal ie 85 Notation octal a 85 Numbering blocks aan 17 25 30 O Octal notation aaa 85 Operators overloading 28 49 101 Operators pseudo aaa aaa 57 Options class aaa 93 Options information 16 18 35 37 Options negating e nne 16 Ouput redirecting is aaa 36 Outer macro defining anan 42 Outer macros undefining 49 Output files changing names of 13 Output line 76 Output changing appearance of 16 Overloading
203. ranslation FTANGLE By default the RATFOR translator writes comments about what command it is trans lating The rk option suppresses those comments Arguments to this option allows one to suppress comments about only particular commands according to the following list b break C case t default d do f for i if n next p repeat until r return S switch h where w while For example one can say rkrb to suppress comments about the return and break state ments Chapter 4 RUNNING FWEB 30 4 2 51 rK Write comments about RATFOR translation FTANGLE This is the negative of rk see Section 4 2 50 rk page 29 it forces comments about particular RATFOR commands 4 2 52 r Turn on auto semi mode using pseudo semis RATFOR Please don t use this option it may not work Insert semicolons by hand in your RATFOR code just as one does in C 4 2 53 r Turn on auto semi mode using actual semis RATFOR Please don t use this option it may not work Insert semicolons by hand in your RATFOR code just as one does in C 4 2 54 rb Number ifs and dos RATFOR In the woven output extra comments are added to help one correlate the block structure of the code For more discussion see Section 4 2 7 b page 17 4 2 55 r Recognize short comments RATFOR The standard FWEB notation for a short comment is
204. rce text However it is best to make it a complete section begun by or if at all possible Unfortunately the i command cannot be commented out or conditionally included by use of an FWEB preprocessor command That is because i is processed very early in the parsing process Consider i could include TEX text but the preprocessor is only active in the definition and code parts Include commands may be nested to a depth set by the option yid See Section 12 2 2 9 yid page 109 In the woven output if a section comes from an include file the name of the include file is printed in square brackets as the first text of the TEX part To inhibit printing of that name say Vdef WIF 1 in the limbo section To change the way that name is formatted redefine the macro WIFfmt whose single argument is the name of the include file It is not called when there is no current include file The default definition is def WIFfmt 1 tt 1 Chapter 5 FwEB COMMANDS AA 5 5 10 I Include file conditional This command behaves like i if the command line option 1 is not used If it is used then the contents of the included file is not printed in the woven output See Section 4 2 20 i page 21 and Section 4 2 21 i page 22 5 5 11 K Extract global RCS like keyword The construction K Keyword gt accesses the value of a global RCS like keyword
205. rings 3 In a switch cases fall through to the next case unless terminated by break just as in C 4 The do statement must be terminated by a semicolon if followed by a simple statement It s unnecessary if followed by a left brace that begins a compound statement 5 Use amp and for the logical AND and OR 6 Do not use an end statement at the very end of a RATFOR program unit it is added automatically by FWEB when the closing brace is sensed Chapter 10 DOCUMENTATION 91 10 DOCUMENTATION FWEB uses La TEX to produce its documentation Plain TEX is no longer supported It is not necessary to be very familiar with La TEX in order to use FWEB effectively FWEB does complicated things behind the scenes relieving the programmer of many burdens If you don t need complicated mathematics one needs to know virtually no LaTEX at all in order to document a section of code And if you do need to typeset math consider that LaTEX makes this daunting task about as simple as one could hope If you re an FWEB beginner don t bother diving into the details of this section until you really need to 10 1 Typesetting FwEB s new look beginning with version 1 40 is designed to work only with LaTEX The new look is more book like following ideas from Briggs nuweb By default it uses default La TEX section numbers such as 1 5 32 however sections may be numbered with consecutive integers by specifying the LaTgX2e package fw
206. rings can be specified as octal constants e g 033 hexadecimal constants e g x1B or one of the ANSI escape sequences a AD NP AD Ar Aw and Aw The non ANSI escape sequence Ve escape is also supported that is particularly useful for color processing see Section 12 3 7 Color page 117 Various of the style file parameters take a language subscript Those are C C Cpp C N FORTRAN 77 N90 FORTRAN 90 R RATFOR 77 R90 RATFOR 90 V Verbatim X TEX Thus line_char N is the comment character for FTANGLE s line commands see Sec tion 12 3 8 4 line char page 119 for FORTRAN 77 code Unfortunately the descriptions of the parameters aren t all completed yet To query the default values say ftangle Z see Section 4 2 70 Z_ page 35 12 3 1 Customizing FWEAVE s index In the following 7 denotes the name of various subparameters 12 3 1 1 index index name is the name of the index section This string is used in Wbegin to initialize the TEX macro INDEX The index section is recognized by matching for a starred section the actual section name against the contents of NINDEX When they match a new page and two column mode are begun These rules imply that the last section of one s source file can be titled INDEX as in INDEX index tex is the name of the file into which the Index is written The character is translated into the root name of the web
207. s As a trivial example the value of 7 is available through the built in function PI Built in functions are described in Section 7 2 3 Built in functions page 66 They can be useful to programmers in all languages FWEB recognizes two kinds of macros outer macros and WEB macros inner macros Control codes associated with either of these kinds normally begin the definition part However FWEB macros are sometimes allowed in the code part as well see Section 7 2 F WEB macros page 63 Macros are expanded by FTANGLE only FWEAVE merely prints them as they occur in the source file 7 1 Outer macros Outer macros provide a shorthand way of invoking macro definitions in the source lan guage they are not expanded by FWEB Outer macros are defined by d see Section 5 5 6 ATd page 42 or D see Section 5 5 5 ATD page 42 They may be placed in any defi nition part FTANGLE collects them during phase 1 during phase 2 they are simply copied in order of their appearance to the beginning of the output file This is most useful for C or C codes it s a quick way of typing define when the positioning of the define is unimportant As an example c d YES 1 d NO O a main Chapter 7 MACROS and PREPROCESSING 63 d BUF_LEN 100 a The keyword into which the d is translated is language dependent it is controlled by the style file parameter outer_def See Sect
208. s or to find out the secrets of FWEB s built ins As an example if one says DUMPDEF EVAL 2 4 it responds with the two lines EVAL O EVAL 0 EVAL 2 4 16 The n notation indicates the n th argument of the macro If one replaces EVAL with EVAL in the above DUMPDEF it will respond EVAL 0 built in EVAL 2 4 16 The purpose of code such as EVAL 0 EVAL 0 is to ensure that the argument of EVAL is expanded if it contains macros the primitive function EVAL does not do that expansion automatically Names indicated as lt built in gt by DUMPDEF may be redefined as ordinary macros but this is in general a very bad idea other parts of FWEB may mysteriously stop working 7 2 3 15 E Base of the natural logarithms The expression E returns e the base of the natural logarithms to the default machine precision The expression E iprec returns e to the decimal precision iprec which must be less than 50 7 2 3 16 ERROR Send error message to output SERROR string prints an error message in FWEB s standard form 7 2 3 17 EVAL Evaluate a macro expression EVAL expression uses FWEB s macro expression evaluator see Section 7 3 Prepro cessing page 80 to reduce the macro expression to its simplest form An attempt to per form arithmetic on combinations of non macro identifiers and numbers generates a warning message Chapter 7 MACROS
209. s of arguments make the FWEB preprocessor sometimes useful even for C and C See Chapter 7 Macros page 62 and Section 7 3 Preprocessing page 80 e Many aspects of FWEB s behavior default strings etc can be customized by means of setting parameters in a makeindex like style file by default fweb sty See Section 12 3 Style page 112 Chapter 2 WEB CONCEPTS 5 2 WEB CONCEPTS The principle concepts of WEB programming are laid out in Knuth s book the reference to which was given in Chapter 1 Intro page 3 FWEB follows most conventions introduced by WEB and CWEB except that the names of some commands have been changed for consistency symmetry and or clarity 2 1 The FWEB processors FWEAVE and FTANGLE Following Knuth s original design FWEB consists of two processors FTANGLE and FWEAVE Both operate on a single source file say test web FTANGLE produces com pilable code say test c whereas FWEAVE produces a TEX file test tex that can in principle be processed with either TEX or LaTEX If a file test tex already exists FWEAVE will ask for confirmation before overwriting it if it does not think that the file was created by a previous run of FWEAVE The output file produced by FTANGLE is not intended for human eyes or for editors it is for compiling only All changes to the code should be made to the web file since changes made directly to the output file would be overwritten the
210. s sectioning commands with minor changes Table of Contents facilities etc The following discussion is based on La TEX2e If La TEX2e is not installed FWEAVE rec ognizes that fact and issues the documentstyle command instead of documentclass Users are strongly encouraged to upgrade to LaTEX2e A useful book that describes the present state of La TEX is Goossens Mittelbach and Samarin The La TEX Companion Addison Wesley Reading MA 1994 10 1 3 1 LaTgX s document class An FwEB LaTEX document is set up with the Wbegin command issued automatically by FWEAVE See the summary at the end of this section for the essence of what the Wbegin command accomplishes FWEAVE uses Ndocumentclass article by default In principle the document class can be changed by the FWEB style file option LaTeX class see Section 12 3 5 Fweb mac params page 115 However FWEAVE has not been tested with most other document classes It will probably not work with most document classes that redefine the section ing commands from those of documentclass article However it may work with the revtex scientific macro package See Section 10 1 3 2 REV TeX page 94 To incorporate class options i e to obtain the effect of documentclass myoptions article use the style file parameter LaTeX class options as in LaTeX class options myoptions To get two sided printing for example one would say LaTeX class options
211. s see ee ee ccc ccc ccc ee 115 fwebnum sbY esse es ee EE ee ee ee eee 98 100 idxmerge sty cece ee ee 105 INDEX tEeX ees ee se ccc ee ee ee ee ee 13 MODULES tEX cece es se ee ee en 13 multicol stY es EE ee ee ccc ete ene 96 tempNam cee cette nes 19 termcap esse se EE ehh 118 termcapO aa 118 EMPNAM SE eee 19 Parameter index Parameter index A ASCII FEN eee hn 118 C CCHAY oo a tenes 118 cdir start ccc se ee hen 118 Color black iss ES aaa 118 Color blu is eee 118 Color cYan i a 118 Color default esses sees 118 COlOFr FFOF le cette ee 117 color fatal cee eee 117 Color green ee ee eee ee ee 118 color in file ss ccc cece ee 117 color include file eese 117 Color info eee 117 color line_num es es se es ee nn 117 Color magenta ccc eee eee eee ee 118 color mod name ss cece ee nn 117 color mod NUM cece cece cence eens 117 color ordinary sse ee 117 color out file e n 117 color program name eene 117 Color TEed n 118 COLOK CAUMING 0 se ee es se enne 117 color warning iese ee es se enne 117 Color white eee ks Ge eee 118 Color yelloW is ee EE ee ee ee eee eee 118 contents postamble a 114 contents preamble ses se EE ee ee 114 contents teX iss SE SG eee eee 114 D delim OO SS EE SS es ee ee hrs 113 GelLiM_N hrs 113
212. ssing RCS like information in the ignorable commentary at the beginning of the file and iii the ability to include FWEAVE formatted code into a standard La TEX document It also fixes a variety of miscellaneous bugs 1 10 11 12 13 14 A stand alone index file suitable for processing by makeindex can be pro duced by the XI option See Section 11 2 Using makeindex page 103 Stand alone indexes produced by XI can be merged with the idxmerge utility See Section 11 3 Merging indexes page 105 FWEAVE formatted code can be included in a standard La TEX2e document by means of the fwebinsert package See Section 10 1 6 1 Inserting woven code page 99 Revision control system RCS information that appears in the ignor able commentary between the optional z and x that begin an FWEB file see Section 5 5 31 ATz page 50 is accessible in the body of the file through the built in function KEYWORD see Section 7 2 3 30 SKEY WORD page 72 and the new commands K see Section 5 5 11 ATK_ page 44 and k see Section 5 5 12 ATk page 44 These features can access RCS like keywords that are not known to RCS itself as long as they fit the proper syntax see Section 5 5 31 ATz page 50 The h option now permits easy access to the GNU info browser if it is installed See Section 4 2 18 h page 21 Underscored versions of built in functions have been removed
213. ssion a binary operator and y an expression FWEAVE contains production rules such as replace the combination expr binop expr with expr If all goes well the result of FWEAVE s reduction process is ultimately just one scrap such as function If FWEAVE is left with more than one scrap at the end of a section this is called an irreducible scrap sequence 1 displays them Irreducible scrap sequences can arise either because the programmer made a mistake or because FWEAVE has not been taught the proper grammar While FWEAVE is reducing the scraps it appends TEX macros that ultimately produce the pretty printed output Frequently people ask how to change the appearance of that output Fundamentally this is not possible at present the grammar rules and the associated TEX are hard coded A completely general user customizable scheme is very complex and daunting it has not been attempted This brief debugging mode can be turned on more locally by means of the 1 command See Section 5 1 2 AT1 page 38 4 2 3 2 Turn on verbose debugging mode FWEAVE This option tells FWEAVE to display detailed reductions of the scraps as it does the pretty printing For a discussion of scraps see Section 4 2 2 1 page 16 Sometimes FWEAVE fails spectacularly at pretty printing a section either because of a syntax error on the part of the user or because of a bug in FWEAVE s logic This opt
214. st be recompiled One can of course turn off the line numbering with the command line option see Section 4 2 78 page 36 but then debugger statements will refer to the tangled C code which is undesirable A better partial solution is to use q see Section 5 5 22 ATq page 48 to turn off the line numbering for output code that is currently stable In the following example the code for each file is put into a module then the modules are output in the unnamed section it is assumed that the programmer is currently making changes to the code for file2 c a q0 o filel c lt File 1 q1 o file2 c lt File 20 0 q0 o file3 c Q File 3 For very large projects another solution is to maintain multiple web source files To avoid losing the substantial benefits of the automatic index refer to the discussion in Section 11 3 Merging indexes page 105 to learn how to create a master index that contains information about several web files 5 5 22 q Turn off module and line info locally The command line option see Section 4 2 78 page 36 turns off comments about module and line numbers globally for the entire code However in some cases one wants to turn that off in just a small block of code One important example arises in FORTRAN Consider a x lt Some actione lt Some action gt y z This example will tangle to something like x C 1
215. t and exten sive development of La TEX has been accomplished as described by Goossens Mittelbach and Samarin The La TEX Companion Addison Wesley Reading MA 1994 The present version of FWEB is intended to be used with La TEX LaTgX2e in particular Plain TEX is no longer supported 1 1 History of WEB and literate programming To be completed see Knuth s book cited in Chapter 1 Intro page 3 1 2 Features of FWEB FWEB is distinguished from its relatives in several respects e FWEB introduces the concept of a current language see Chapter 8 Lan guages page 83 so more than one compiler language can be processed in a single FWEB run For example mixtures of C and FORTRAN are common in modern scientific programming e FWEB understands the syntaxes of several of the more important compiler languages C C FORTRAN both F77 and F90 RATFOR and TEX For other languages FWEB can work in a language independent mode that essentially weaves and tangles the source code verbatim but still provides the user with the powerful WEB features related to TEX documentation module names macro processing etc Chapter 1 INTRODUCTION to FWEB e FWEB contains a built in RATFOR RATIONAL FORTRAN translator See Chapter 9 Ratfor page 89 e FWEB has a built in C like macro preprocessor This is especially useful for FORTRAN and RATFOR which have no predefined preprocessor However certain extensions such as variable number
216. t it may be In either event the output is a quoted string Keywords extracted from ignorable commentary at the beginning of a web file are called global and are known throughout the code Distinguish these from local keywords extracted from ignorable commentary at the beginning of an include i file Such keywords are known only during the time that file is being read and are accessible via k see Sec tion 5 5 12 ATk page 44 For convenience built ins are defined for some standard RCS global keywords These are AUTHOR gt KEYWORD Author DATE TIME gt KEYWORD Date HEADER gt KEYWORD Header SID gt SKEYWORD Id LOCKER gt KEYWORD Locker NAME gt SKEYWORD Name RCSFILE gt KEYWORD RCSfile REVISION gt KEYWORD Revision SOURCE gt KEYWORD Source STATE gt KEYWORD State There are no such abbreviations for local keywords because such abbreviations would be expanded during output whereas it is necessary to recognize and expand the local keywords during input Presumably such local keywords will be used rarely if at all 7 2 3 31 L Change to lower case SL string changes string to lower case The argument is first expanded in case it is a macro 7 2 3 32 L_KEYWORD Value of local RCS like keyword For most purposes SL KEYWORD behaves as k see Section 5 5 12 ATk page 44 It is still under development and should not be used yet L_K
217. t to IF 7 The option j was added This inhibits multiple inclusions via i of the same include file See Section 4 2 22 j page 22 8 One now has the ability to change the comment character that begins FTANGLE s line command In the style file say e g line char N to change the default line output by FTANGLE in FORTRAN mode to line This could be useful if one runs the C preprocessor on the tangled FORTRAN output 9 FWEAVE s processing of typedef statements in C and C was improved Chapter 14 NEW FEATURES 129 10 FwEB should now be able to process C templates and exception han dling at least in simple situations The typesetting of C references e g int amp was also improved Please report any difficulties 11 There were various miscellaneous obscure bug fixes 14 5 Version 1 40 1 The meaning of has changed SORRY Formerly this inhibited a line break that function is now performed by The new meaning of is to force an index entry the opposite of which inhibits an index entry If you have large codes using the old that you do not wish to convert you can recover the old mappings by placing the following commands into fweb sty yes_index 7 no_line_break However please try to make the conversion the new codes are intended to be more symmetrical and easier to remember 2 Built in functions n
218. tartup FWEB attempts to read an initialization file This always resides in the user s home directory It is usually called fweb fweb ini on personal computers The default file name can be overridden by the environment variable FWEB INI One may put into fweb any option that might be used as a command line option Presently there must be just one entry per line If the option begins with a or a for backward compatibility it is processed before the actual command line options if it begins with amp or is a file name it is processed after Generally fweb options should begin with so that one may override them from the command line The W sign begins a comment terminated by the end of line 12 2 2 Memory allocation The command line option y see Section 4 2 69 y page 35 is used to change the default allocation for a dynamic array The arrays have a one or two character abbreviation denoted by aa Some error messages will use this abbreviation when suggesting that one increase a default allocation To query the present allocations of variable aa just say yaa To query everything say y This whole scheme is somewhat annoying In most cases dynamic arrays should be reallocated automatically That can be done without too much difficulty but I was reluctant to try it for Version 1 61 in fear of breaking something Please wait for the year 2000 If one
219. temporary aaa 61 Comments TEX 31 Comments verbatim aaa 32 Comments visible 0 cece cece aaa 60 Compiler directives lisse 53 Completion automatic file name 12 Concatenation EG n 27 Condition asserting ee ee een 68 Conditional n way 0 c cece eee eee 71 Conditional two way eeeeee 71 72 Contents table of aaa 96 Control text EG SG rne 55 Converting an existing code to FWEB 121 Cross references eliminating 34 Cross references suppressing 34 Customization ee eee nee 107 Customizing FWEB 00 cece eee ee 107 D Date cite Ge han 68 Date generating the 2c eee eee 68 Day generating the iss 0 eee eee eee 68 Debugging 1 0 eee eee ee eee 16 38 Debugging MAcTOS aaa ne 70 Documentation format aaa 91 Dot constants recognizing a 35 E Environment variables 00005 71 107 Environment obtaining the 71 Error messages printing isses 70 Escape sequences ANSI a 118 Example of FWEB file ee ee ee ee 6 Concept index Exponentiaflon ss es ee es Ge ee ee 71 76 87 Expression evaluation 81 Expression pseudo naana aenaran 57 Expressions evaluating 0005 70 F Features new sss 124 Features version 1 40
220. ters in the style file The escape sequences can either be specified in raw form e g for color mode 1 a default is Color red Xe 01 31m or in the form of a sequence of two character ab breviations that are defined in the termcap documentation e g for modes 2 and 3 the default is Color red mdmr When one displays that with the Z option FWEB will display the actual escape sequences that it determines from the termcap database not the abbreviations For both input and output note that one may use the non ANSI escape sequence e to represent the escape character 033 When one says ZColor for color modes 1 3 all of the parameters are listed as modified even if the user redefines none That occurs because the defaults are overwritten internally when the color mode is set FWEB s configuration script attempts to determine whether the termcap library is present if not they link in dummy termcap routines termcap0 web To override this behavior change the appropriate lines in defaults mk produced by the command configure Color message output is not fully debugged it s a frill after all so some messages that should reasonably be colored may not be so in the present release 12 3 8 Miscellaneous style file parameters There are a variety of miscellaneous parameters 12 3 8 1 ASCII Fcn See Section 5 6 2 ATdquote page 51 12 3 8 2 cchar Continuation character for FOR
221. th some discussion in fwebmac web That macro is emitted only when not used n is 4 2 35 nb Number ifs and dos FORTRAN FWEAVE In the woven output extra comments are added to help one correlate the block structure of the code For more discussion see Section 4 2 7 b page 17 4 2 36 nc Ignore single line comments FORTRAN Ignore at the input driver stage comment lines beginning with C c or Interpretation In the usual mode of operation the FORTRAN 77 input driver makes a heroic attempt to mix the original single line column 1 commenting style with the F WEB Chapter 4 RUNNING FWEB 26 style and It converts single line comments to the style and passes them along to the innards of the processors Problems sometimes arise when converting an existing FORTRAN code to FWEB Such codes may have very large blocks of code or documentation commented out with a C in column 1 Special TEX characters in those comments can cause problems for FWEAVE sometimes FTANGLE gets confused as well The nC option short circuits these problems by simply throwing all such lines away at the input driver stage This option is not a recommended long term solution Instead consider the following e In FWEB blocks of code should be commented out with the preproces sor commands if 0 endif see Section 6 3 Temporary comments page 61 e Textual
222. the language changing commands and one of those such as c should appear Other text in limbo is ignored by FTANGLE and is copied by FWEAVE to the tex output file Thus one can make or issue TEX macro definitions in limbo that override the defaults in FWEB s macro package fwebmac sty In the above example see the Title command This is defined in fwebmac sty and basically issues La TEX s title command Another way of getting TEX text into the limbo section is by means of the 1 command see Section 5 5 14 ATI page 45 LaTEX users may need to know that TEX commands in limbo are executed after the begin document command which is issued automatically in fwebmac sty For more information see Section 10 1 3 LaTeX page 93 2 3 Modules The code parts of possibly noncontiguous sections can be combined into modules For FWEAVE this is a logical combination for purposes of cross referencing different pieces of the code But for FTANGLE the combination is physical FTANGLE s output proceeds module by module Modules can be named or unnamed There is exactly one unnamed module The fundamental operation of FTANGLE is that FTANGLE outputs the unnamed module That output goes to a compilable file with an extension appropriate to the current language The contents of a module either unnamed or named consists of a mixture of code and comments FTANGLE ignores the comments FWEAVE treats them as T
223. the most up to date and detailed information refer to fwebmac web 10 1 2 2 Fonts Several fonts have been declared Those include e titlefont large sans serif e ttitlefont large typewriter e SC small caps e Csc Caps small caps and e tentex TEX s extended character set For illustrations and further details see fwebmac web Chapter 10 DOCUMENTATION 93 To typeset a string of characters in typewriter type one may use the N macro More precisely the name of this macro is the value of the style file parameter format typewriter For more information see Section 12 3 5 1 S format page 115 When using this one must escape the special characters 4 _ 7 amp as in alpha FWEAVE does that escaping automatically when typesetting strings in code mode You may wish to surround with an hbox that is not done by default because FWEAVE uses special trickery to break long strings in code mode automatically and that breaking would be inhibited by an hbox 10 1 3 LaTEX support Original LaTEX support through version 1 30 was substantially incomplete in that LaTEX s output routine was usurped by the relatively simple one used for FWEB s TEX support However beginning with version 1 40 full LaTEX support is provided and Plain TEX is not supported version 1 50 supports La TgX2e LaTEX s output routine is used as are it
224. tifier in the woven output with the replacement text A more restrictive form is W identifier newmacro which replaces references to identifier with a call to newmacro Note that there are no quotes in this form The shortest form is W identifier which replaces references to identifier with a call to identifier For example the iden tifier x normally appears in woven output as Wshort x If one says W x one will instead get the macro reference Xx which could be defined to give a variety of special effects However one may need some rather intimate understanding of FWEAVE s output in order to ensure that things always work correctly One of the important uses of this facility is to expedite special formatting of array references This subject is discussed separately below in the section on Special array formatting sorry that isn t here yet where an example is given Chapter 11 FWEB s INDEX 103 11 FWEB s INDEX FWEB has several powerful indexing facilities 1 It sorts and writes its own self contained internal index including cross references to all the variables as well as items inserted by the user 2 It can write its cross reference information to a file formatted for use by the makeindex utility This feature facilitates creation of a master index that contains information about several web files 11 1 FWEB s self generated index One of the most useful features of FWEB is that
225. tion 4 2 42 n page 27 5 An active bracket feature helps improve the appearance of woven code that uses sub scripts and or superscripts heavily See Section 4 2 65 3 W page 33 Chapter 14 NEW FEATURES 14 NEW FEATURES This info documentation is now accessible on the World Wide Web see Chapter 15 Support page 131 124 Some things that have been added or changed in recent releases are described in the following 14 1 Version 1 61 14 1 1 Updates to documentation v1 61 1 FWEB supports color modes in which messages to the terminal can appear in colors chosen by the user see Section 12 3 7 Color page 117 The color mode is set by the new command line option C see Section 4 2 8 C_ page 18 A previously undocumented feature is that for the C like and Fortran like languages FTANGLE expands the binary notation Ob to an unsigned decimal number See Section 2 4 Phases page 10 14 1 2 Redefined commands v1 61 A few obscure commands have been slightly redefined Sorry about that but it makes for more symmetry and ease of recall and or solves some technical problems 1 Although it was never documented previous versions permitted either lower or upper case for the commands that set the language e g both c and C worked Now only the lower case forms work The upper case forms may have other meanings The style file parameter Ext_delimiter now
226. to that section Usually language means a compiler language like FORTRAN or C These languages will be pretty printed by FWEAVE Pretty printing can be inhibited by turning on the N mode globally with the command line option N locally with N or by selecting the VERBATIM language in both of these cases the input text is echoed literally to the output of both FTANGLE and FWEAVE Language is a stronger concept than mode For example when a language is se lected the extension of the tangled output file is changed appropriately for example if test web contains C code that is contains the command c test web tangles into test c compressing blanks and otherwise deliberately making the tangled output rela tively unreadable and FWEAVE pretty prints using the C syntax Turning on the N mode does not affect the language FTANGLE copies the source code literally into test c no blank compression or other modifications and FWEAVE typesets the source code within a verbatim environment no pretty printing When the VERBATIM language is selected the N mode is turned on automatically but FTANGLE writes its output to a file with a special default extension that can be customized in the style file See Section 12 3 8 Miscellaneous params page 118 8 1 Setting the language The most general form of a language command is e L Itext options where 1 is a language symbo
227. tor e FWEB attempts to be helpful and tries to expand the operators x and in a way compatible with the usage in C and C For example it expands x y into x x y This feature can be a great time saver and also makes the code substantially more legible it is strongly recommended To turn off this feature use the option See Section 4 2 79 plus page 37 Notice that in FORTRAN 90 is a token for not equal so if you want to use that you must use the option However a better solution is to use FWEB s preferred operator for not equal e By default the operators true and false will weave as caligraphic T and F That appearance be changed by redefining the macros WTRUE and WFALSE in fwebmac sty or in the limbo section of your source file e If FTANGLE messes up and outputs incorrect FORTRAN code try tangling with the command line option see Section 4 2 78 page 36 and then report the prob lem 8 2 3 2 Items specific to FORTRAN 77 and fixed form FORTRAN 90 e By default when processing the code part the FORTRAN driver inserts semicolons au tomatically at the end of each logical statement Thus the core of FWEB is presented with a uniform syntax However when one escapes into code mode by using vertical bars those semicolons aren t inserted so something that appears a first glance
228. ts 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 10 11 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 gt in place of the fragment you re replacing then put that fragment somewhere else prefaced by and Name of module gt 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 identi fiers or section nam
229. uage sss 45 5 5 14 1 Specify limbo text EE EG Es 45 5 5 15 M Define FWEB macro 45 5 5 16 m Define FWEB macro and mark 45 5 5 17 N Turn on N mode EG EE Ek se 46 5 5 18 n Set language to FORTRAN 77 4T 5 5 19 n9 Set language to FORTRAN 90 4T 5 5 20 0 Open output file global scope 47 5 5 21 o Open output file local scope 47 5 5 22 q Turn off module and line info locally 48 5 5 23 OR Treat next identifier as integer like reserved AA 49 5 5 24 r Set language to RATFOR 77 49 5 5 25 r9 Set language to RATFOR 90 49 5 5 26 u Undefine outer macro 49 5 5 27 v Overload operator 49 5 5 28 W Overload identifier 50 5 5 29 x Terminate ignorable material or begin material to be changed 0 0 00 0 cere ee eee 50 5 5 30 y Begin change material 50 5 5 31 z Begin ignorable material or terminate change MU 50 Conversion to ASCII ss EE ee eese 51 5 6 1 Convert character to ASCIL 51 5 6 2 Q Convert string to ASCI 51 Forward referencing 0 0 0 ke EE Ee eee e 51 5 7 1 Mark as defined 0 52 Comments 0 00 eee cee hh hh 52
230. ures page 124 Periodically check ftp pppl gov pub fweb READ ME for bug reports and other news Make bug reports See Chapter 15 Support page 131 If you have a color terminal try the option C1 see Section 4 2 8 C page 18 see Section 12 3 7 Color page 117 Any option in fweb that is intended to be processed after the command line options should begin with amp rather than This is rarely necessary See Section 12 2 Initialization page 108 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 12 3 Style page 112 8 Use the info options 10 11 12 13 14 15 D y and Z to find out about various internal FWEB tables control codes reserved words memory allocations and style file parameters See Section 4 2 82 Info options page 37 Begin all FWEB sources with invisible commentary bracketed by z x See Sec tion 5 5 31 ATz page 50 Always include an explicit language setting command in the limbo section Under normal circumstances do not set the language from the command line See Chapter 8 Languages page 83 Keep sections quite short Knuth suggests a dozen lines That s quite hard to achieve sometimes but almost never should a section be mor
231. uses y to examine the maximum permitted values of these parameters one will note the magic number 10239 appearing occasionally This number is a bit less than 64K 5 it is a signature of an inherently 32 bit design that goes back to Knuth Unfortunately this number can t be increased without some radical redesign Wait for the year 2100 12 2 2 1 yb Maximum bytes for identifiers index entries and module names Unique identifiers index entries and module names are stored contiguously in a large memory area the size of which is controlled by yb The default may need to be increased for very large source files or decreased to squeeze things into a personal computer See also Section 12 2 2 20 yn page 111 Chapter 12 CUSTOMIZATION 109 12 2 2 2 ybs Size of the change buffer in bytes Information from change files is read into the change buffer whose size is controlled by ybs It should not be necessary to change this unless an error message specifically tells one to do so 12 2 2 3 ycb Size of line buffer for C output in bytes FTANGLE outputs lines of a fixed maximum length It attempts to split them in a reasonable way dependent on the language When it absolutely can t figure out how to split the line it will issue a warning message and split it anyway The ycb option controls the maximum output line length for C and C The analogous command yxb controls the output lin
232. x mds contents tex cts The is replaced by the root name of the web file FTANGLE writes files of the form name ext Compilable output file The extensions for the compilable output file s have certain defaults but can be changed by style file parameters according to the following table Language Style file entry UNIX default non UNIX default C suffix C c c C suffix Cpp C C Fortran 77 suffix N f for Fortran 90 suffix N90 90 for90 Ratfor 77 suffix R r rat Ratfor 90 suffix R90 r90 rat90 TeX suffix X sty sty VERBATIM suffix V mk mk For example to change the default extension for a C file from C to c put into fweb sty the line suffix C c 3 3 Change files The primary input to the FWEB processors is the test web source file However a change file test ch can also be specified A change file consists of instances of the following structure x One or more lines of text EXACTLY as in the web file Copy these lines with an editor don t type them from scratch ey Replacement text z The change file mechanism allows one to insert local changes or test new code without physically modifying the original web file Chapter 3 FILES 14 To specify a change file use its name as the second file name on the command line The extension ch is assumed by default For example ftangle test test processes test web with the change file
233. y number of C functions can be placed into a C language module with just one c language changing command n Q Qa program main end Qc e ceo Q Q Q ce z int fcn F TANGLE will write two output files for this example e g test f and test c Partic ularly note that one did not need an c command in the last section because the language was C when lt C gt was first encountered 8 2 Special hints and considerations for each language One important thing to keep in mind is that in FWEB an identifier may have for each language precisely one meaning throughout the document This restriction is not neces sarily in accord with the syntaxes of the various source languages See for example the discussions in Section 8 2 2 Cpp page 85 and Section 8 2 3 Fortran page 85 8 2 1 Special considerations for C e FTANGLE treats the construction Ob as a binary notation that it expands to an unsigned decimal number Thus 0b101 expands to 5 and 0b1111111111111111 expands to 65535 e FWEAVE processes typedef statements during phase one so they will format properly even if they are used in a documentation part before they are defined in a code part e The H option helps one to deal with identifiers defined in header files See Sec tion 4 2 17 H_ page 20 e Note that in C structure and enum tags do not define a new type so the tag name does not get highlighted
234. yword WIT format typewriter AWIT Here WIT can be any name not already in use you need not and should not give a definition for WTT Macros like V or WIT are given their values during the execution of the Wbegin macro that begins the output from FWEAVE The style file values are written as arguments to that macro and essentially a command like let Wtypewriter is executed where the internal macro Wtypewriter is defined in fwebmac sty If you want to change the way FWEB typesets a particular kind of identifier you must redefine the internal macro name not the one used in the format parameters Here are the internal macros used by fwebmac sty to typeset the various kinds of identifiers The associated style file parameters are shown in parentheses Wid ordinary identifiers format id WID completely upper case ordinary identifiers format ID Chapter 12 CUSTOMIZATION 116 Wshort single character ordinary identifiers format short_id WidD outer macros format outer_macro WIDD completely upper case outer macros format outer macro WidM FWEB macros format WEB_macro WIDM completely upper case FWEB macros format WEB macro Wreserved reserved words format reserved WRESERVED completely upper case reserved words format RESERVED Wintrinsic library intrinsic function names format intrinsic Wkeyword certain Fortran keywords format keyword WKEYWORD complete
235. ywords not global ones See Section 5 5 12 ATk page 44 5 5 12 k Access local RCS like keyword The construction k keyword behaves as K does see Section 5 5 11 ATK page 44 except it accesses local keywords defined at the top of include files Chapter 5 FwEB COMMANDS 45 5 5 13 L Set language L1 sets the language to I where is one of c c n n9 r r9 v x See Chapter 8 Languages page 83 There are shorthand forms of this command for some languages see c Section 5 5 3 ATc page 41 c Section 5 5 4 ATcpp page 42 n Section 5 5 18 ATn page 47 n9 Section 5 5 19 ATn9 page 47 r Section 5 5 24 ATr page 49 and r9 Sec tion 5 5 25 ATr9 page 49 Generally the global language should be set in the limbo section by means of L c etc rather on the command line by options such as L or c 5 5 14 1 Specify limbo text This command begins the definition part Limbo text is material that FWEAVE should output before the start of the first section For example 1 def Atabc Note that AV stands for a backslash In general characters must be escaped just as in C so that one can include things like n newline in the definitions Limbo text may also be typed directly into the limbo section in that case no escapes are necessary since one is typing ordinary TEX t

The FWEB user manual

Contents

Download Pdf Manuals

Related Search

Related Contents