« back to all changes in this revision
Viewing changes to Manual/fweb.texi
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Yann Dirson
- Date: 2002-01-04 23:20:22 UTC
- Revision ID: james.westby@ubuntu.com-20020104232022-330ad4iyzpvb5bm4
Tags: upstream-1.62
Import upstream version 1.62
- files added:
- Boot
- Boot/amiga
- Boot/ibm
- Boot/ibm/mvs
- Boot/ibm/pc
- Boot/ibm/pc/gnu
- Boot/ibm/pc/microsoft
- Boot/misc
- Boot/unix
- Boot/unix/ansi
- Boot/unix/dsu
- Boot/unix/sgi
- Boot/unix/sun
- Boot/unix/sun/cc
- Boot/unix/sun/gcc
- Boot/vax
- Demos
- Manual
- Web
added
removed
Manual/fweb.texi
1
\input texinfo @c -*-texinfo-*-
2
@def@ifhtml{@doignore{ifhtml}}
3
@setfilename fweb.info
4
@settitle FWEB
5
6
@macro Fprog{name}
7
@sc{\name\}
8
@end macro
9
10
@macro FWEB
11
@Fprog{Fweb}
12
@end macro
13
14
@macro FWEAVE
15
@Fprog{Fweave}
16
@end macro
17
18
@macro FTANGLE
19
@Fprog{Ftangle}
20
@end macro
21
22
@macro ASP
23
@iftex
24
@tex`\hbox{\tt@@\char`\ }'@end tex
25
@end iftex
26
@ifinfo
27
@w{@samp{@@ }}@c
28
@end ifinfo
29
@end macro
30
31
@macro PI
32
@tex
33
$\pi$
34
@end tex
35
@ifinfo
36
@var{pi}@c
37
@end ifinfo
38
@end macro
39
40
@macro EQUIV
41
@tex
42
$\equiv$
43
@end tex
44
@ifinfo
45
==@c
46
@end ifinfo
47
@end macro
48
49
50
@
51
@ifinfo
52
This file documents FWEB...
53
54
Copyright 1993--1998 John A. Krommes
55
56
Permission is granted to make and distribute verbatim
57
copies of this manual provided the copyright notice and
58
this permission notice are preserved on all copies.
59
60
@c @ignore
61
Permission is granted to process this file through TeX
62
and print the results, provided the printed document
63
carries a copying permission notice identical to this
64
one except for the removal of this paragraph (this
65
paragraph not being relevant to the printed manual).
66
67
@c @end ignore
68
Permission is granted to copy and distribute modified
69
versions of this manual under the conditions for
70
verbatim copying, provided also that the section
71
entitled ``Copying'' is included exactly as in the original, and provided
72
that the entire resulting derived work is distributed
73
under the terms of a permission notice identical to this
74
one.
75
76
Permission is granted to copy and distribute
77
translations of this manual into another language,
78
under the above conditions for modified versions,
79
except that this permission notice may be stated in a
80
translation approved by the author.
81
@end ifinfo
82
83
@titlepage
84
@title FWEB
85
@subtitle A WEB system of structured documentation
86
@subtitle for multiple languages
87
@author By John A. Krommes
88
@page
89
@vskip 0pt plus 1filll
90
Copyright @copyright{} 1993--1998 John A. Krommes
91
92
Permission is granted to make and distribute verbatim
93
copies of this manual provided the copyright notice and
94
this permission notice are preserved on all copies.
95
96
Permission is granted to copy and distribute modified
97
versions of this manual under the conditions for
98
verbatim copying, provided also that the section
99
entitled ``Copying'' is included exactly as in the original, and provided
100
that the entire resulting derived work is distributed
101
under the terms of a permission notice identical to this
102
one.
103
104
Permission is granted to copy and distribute
105
translations of this manual into another language,
106
under the above conditions for modified versions,
107
except that this permission notice may be stated in a
108
translation approved by the author.
109
@end titlepage
110
111
112
@node Top,Copying,(dir),(dir)
113
114
@ifhtml
115
NOTE: Because of last-minute translation problems with texi2html
116
operating on the macro-expanded version of fweb.texi, user-defined macro
117
expansion has temporarily been turned off in this html version.
118
Multitable is also giving trouble, as is @samp in section names. These
119
are probably problems with texi2html; sorry for the inconvenience.
120
@end ifhtml
121
122
@unnumbered @FWEB{}
123
124
This Texinfo documentation describes @FWEB{} Version 1.61.
125
126
127
@quotation
128
129
@itemize @bullet
130
@item
131
To learn about new features of this version, see @ref{V1.61}.
132
133
@item
134
For a quick introduction to, and review of the structure of an @FWEB{}
135
source file, see @ref{Structure}.
136
137
@item
138
If you used to receive e-mail information about @FWEB{} but don't any
139
longer, it's probably because you need to update your e-mail address in
140
the @code{fweb-users} mailing list. Subscription instructions can be
141
found in @ref{Support}.
142
143
@item
144
Bug reports and suggestions are much appreciated, but are no longer
145
acknowledged individually. See @ref{Support}.
146
147
@item
148
The next major release, @FWEB{} Version 2.00, is planned for
149
no earlier than January 1, 2000.
150
151
@end itemize
152
@end quotation
153
154
@ifinfo
155
If you're perusing this documentation for the first time, try first
156
reading the discussion at just the top-level nodes in order to get a
157
general sense of what's here. Lower-level nodes have many details, but
158
most of them are unnecessary for the casual user.
159
160
One can obtained a TeX'd copy of the present documention by saying
161
@samp{texi2dvi fweb.texi}, assuming that the relevant @code{texinfo}
162
macros have been installed on one's system. (@file{texinfo.tex} and the
163
script @code{texi2dvi} are included in the standard GNU distributions.)
164
@end ifinfo
165
166
This documentation is now accessible on the World-Wide Web from
167
168
@quotation
169
@url{http://w3.pppl.gov/~krommes/fweb_toc.html}.
170
@end quotation
171
172
Other sources of information about @FWEB{} are the archival files of
173
the @code{fweb-users} and @code{fweb-installers} mailing lists. To
174
learn how to obtain those, see @ref{Support}.
175
176
If you are learning @FWEB{} for the first time, you will probably find
177
that this (unfinished) manual is not sufficiently pedagogical. For
178
background, please refer to Knuth's book cited in @ref{Intro}. You
179
should also browse through @ref{Concepts}, in particular
180
@ref{Structure}.
181
182
@ifinfo
183
The first part of this master menu lists the major nodes in this Info
184
document. The rest of the menu lists all of the lower-level nodes in
185
the document.
186
@end ifinfo
187
188
@menu
189
* Copying:: Your rights; NO WARRANTY.
190
* Intro:: An introduction to @FWEB{}.
191
* Concepts:: General concepts of WEB programming.
192
* Files:: Files used by @FWEB{}.
193
* Starting:: Command-line syntax and options
194
* @@ commands: AT commands. @FWEB{} commands.
195
* Comments:: Commenting styles.
196
* Languages:: Languages.
197
* Macros:: Macro definitions and preprocessing.
198
* Ratfor:: RATional FORtran.
199
* Documentation:: Features and hints about working with @FWEAVE{}.
200
* Index:: The index produced by @FWEB{}.
201
* Customization:: Customizing @FWEB{}, learning about parameters, etc.
202
* Hints:: Various usage tips, etc.
203
* New features:: New features/changes in the current version.
204
* Support:: Help, bug reports, etc.
205
* Installing:: Installing @FWEB{}.
206
* Concept index:: Significant concepts.
207
* Option and command index:: Command-line options, @@ commands, etc.
208
* Parameter index:: Style-file parameters.
209
210
--- The Detailed Node Listing ---
211
212
INTRODUCTION to @FWEB{}
213
214
* History:: History of literate programming.
215
* Features:: Special features of @FWEB{}.
216
217
WEB CONCEPTS
218
219
* Processors:: @FTANGLE{} and @FWEAVE{}.
220
* Phases:: Phases of operation of the @FWEB{} processors.
221
* Structure:: The structure of a web.
222
* Modules:: Use of named and unnamed modules.
223
224
FILES
225
226
* Input files:: Input files.
227
* Output files:: Output files.
228
* Change files:: Change files.
229
230
Input files
231
232
* Completion:: Automatic file-name completion.
233
234
RUNNING @FWEB{}
235
236
* Syntax:: Command-line syntax.
237
* Options:: Command-line options.
238
239
Command-line options
240
241
* Negating options:: How to invert the meaning of an option.
242
* -1:: Brief debugging mode.
243
* -2:: Verbose debugging mode.
244
* -@@: -AT. Display information about control codes.
245
* -A: -A_. Turn on ASCII translations.
246
* -B: -B_. Turn off audible beeps.
247
* -b:: Number blocks.
248
* -C: -C_. Set the color mode.
249
* -c:: Set global language to C.
250
* -c++: -cpp. Set global language to C++.
251
* -D: -D_. Display information about @FWEB{}'s reserved words.
252
* -d:: Convert unnumbered `do...enddo's to Fortran--77.
253
* -E: -E_. Change the delimiter of a file-name extension.
254
* -e:: Turn on automatic file-name completion.
255
* -F: -F_. Compare output files with old versions.
256
* -f:: Turn off module references for identifiers.
257
* -H: -H_. Scan #include files to format typedef and/or class commands.
258
* -h:: Where to get help.
259
* -I: -I_. Append a directory to search list for include files.
260
* -i:: Don't print contents of @@I include files.
261
* -i!:: Don't even read @@I include files.
262
* -j:: Inhibit multiple includes of the same file.
263
* -k:: Don't recognize lower-case forms of Fortran I/O keywords.
264
* -L: -L_. Select global language.
265
* -l:: Echo the input line.
266
* -M: -M_. Set output message level.
267
* -m:: Define an @FWEB{} macro.
268
* -m4:: Understand the m4 built-in commands.
269
* -m;:: Append pseudo-semicolons to @FWEB{} macro definitions.
270
* -n:: Set global language to Fortran--77.
271
* -n9:: Set global language to Fortran--90.
272
* -n@@;: -nAT;. For Fortran, supply pseudo-semicolons automatically (default).
273
* -n;:: For Fortran, supply actual semicolons automatically.
274
* -ncolon:: In Fortran, place statement labels on separate lines.
275
* -nb:: In Fortran, number the ifs and dos.
276
* -nC:: In Fortran, ignore single-line comments ('C', 'c', or '*').
277
* -np:: Print semicolons in woven Fortran output.
278
* -n\:: In Fortran--90, free-form syntax continued with '\\'.
279
* -n&:: In Fortran--90, free-form syntax continued with '&'.
280
* -n/:: In Fortran, recognize '//' as the start of a short comment.
281
* -n!:: In Fortran, make '!' denote the start of a short comment.
282
* -n):: In Fortran, reverse array indices.
283
* -o:: Turn off @FWEAVE{}'s mechanisms for overloading operators.
284
* -q:: Don't translate Ratfor.
285
* -P: -P_. Select TeX processor.
286
* -p:: Set style parameter.
287
* -r:: Set the global language to Ratfor--77.
288
* -r9:: Set the global language to Ratfor--90.
289
* -rb:: In Ratfor, number the ifs and dos.
290
* -rg:: Set |goto| parameters.
291
* -rk:: Suppress comments about Ratfor statement translation.
292
* -rK: -rK_. Write out comments about Ratfor statement translation.
293
* -r@@;: -rAT;. Turn on Ratfor's auto-semi mode, using pseudo-semicolons.
294
* -r;:: Turn on Ratfor's auto-semi mode, using actual semicolons.
295
* -r/:: In Ratfor, recognize '//' as the start of a short comment.
296
* -r!:: In Ratfor, make '!' denote the start of a short comment.
297
* -r):: In Ratfor, reverse array indices.
298
* -s:: Print statistics about memory usage.
299
* -T: -T_. Flag-setting commands for @FTANGLE{}.
300
* -t:: Truncate identifiers.
301
* -U: -U_. Convert reserved output tokens to lower case.
302
* -u:: Undefined a predefined or command-line macro.
303
* -V: -V_. Print version number.
304
* -v:: Make all comments verbatim.
305
* -W: -W_. Flag-setting commands for @FWEAVE{}.
306
* -w:: Change name of @FWEB{}'s macro package.
307
* -X: -X_. Print selected cross-reference information.
308
* -x:: Reduce or eliminate cross-reference information.
309
* -y:: Allocate dynamic memory.
310
* -Z: -Z_. Display default values of style-file parameters.
311
* -z:: Change name of style file.
312
* -.:: Don't recognize dot constants.
313
* -\:: Explicitly escape continued strings.
314
* -(: -lp. Continue parenthesized strings with backslashes.
315
* -colon:: Set starting automatic statement number
316
* ->:: Redirect tangled output.
317
* -=:: Redirect tangled output.
318
* -#:: Don't print comments about line numbers and module names
319
in tangled output.
320
* -+: -plus. Don't interpret compound assignment operators.
321
* -/:: Recognize '//' as the start of a short comment.
322
* -!:: Make '!' denoted the start of a short comment.
323
324
* Info options:: Information options.
325
326
@samp{-T}: Flag-setting options for @FTANGLE{}
327
328
* -TD:: Permit processing of deferred macro definitions.
329
* -Tb:: Permit built-functions such as @code{$IF} to be redefined.
330
* -Tm:: Permib user-defined macros to be redefined.
331
* -Tv:: Don't print header info at top of output.
332
* -T%:: Don't retain trailing comments.
333
* -T#:: Don't insert @samp{#line} command after @samp{@@%}.
334
335
@samp{-W}: Flag-setting options for @FWEAVE{}
336
337
* -W@@: -WAT. Set module warning flag.
338
* -W1:: Completely cross-reference single-character identifiers.
339
* -W[:: Turn on processing of bracketed array indices.
340
* -WH: -WH_. Send extra arguments to the C preprocessor.
341
342
Commands that inhibit printing:
343
344
* -Wd: -Wnoprint. Don't print @@d or @@D in woven output.
345
* -Wf: -Wnoprint. Don't print @@f.
346
* -WF: -Wnoprint. Don't print @@F.
347
* -Wl: -Wnoprint. Don't print @@l.
348
* -Wm: -Wnoprint. Don't print @@m or @@M.
349
* -Wv: -Wnoprint. Don't print @@v.
350
* -Ww: -Wnoprint. Don't print @@w or @@W.
351
352
@FWEB{} COMMANDS
353
354
* @@0: AT0. Turn off debugging.
355
* @@1: AT1. Display irreducible scraps.
356
* @@2: AT2. Display detailed scrap reductions.
357
358
Literal control characters:
359
* @@@@: ATAT. Insert an '@@'.
360
* @@|: AT|. Vertical bar/optional line break.
361
362
Beginning of section:
363
* @@ : ATspace. Begin minor section.
364
* @@*: AT*. Begin major section.
365
366
Beginning of code part:
367
* @@<: AT<. Begin module name.
368
* @@>: AT>. End module name.
369
* @@A: ATA_. Begin code part.
370
* @@a: ATa. Begin code part and mark next identifier.
371
372
Control codes b--z:
373
* @@B: ATB_. Insert left brace; suppress default insertion of breakpoint command.
374
* @@b: ATb. Insert breakpoint command.
375
* @@c: ATc. Set language to C.
376
* @@c++: ATcpp. Set language to C++.
377
* @@D: ATD_. Define outer macro.
378
* @@d: ATd. Define outer macro and mark it.
379
* @@E: ATE_. Treat next identifier as ordinary expression.
380
* @@e: ATe. Invisible expression.
381
* @@f: ATf. Format identifier or module name.
382
* @@I: ATI_. Include a WEB file, but don't print it.
383
* @@i: ATi. Include a WEB file.
384
* @@K: ATK_. Expand global RCS-like keyword.
385
* @@k: ATk. Expand local RCS-like keyword.
386
* @@L: ATL_. Set language.
387
* @@l: ATl. Specify limbo text.
388
* @@M: ATM_. Define an @FWEB{} macro.
389
* @@m: ATm. Define a @FWEB{} macro and mark it.
390
* @@N: ATN_. Turn on language-independent mode.
391
* @@n: ATn. Set language to Fortran--77.
392
* @@n9:ATn9. Set language to Fortran--90.
393
* @@O: ATO_. Open new output file (global scope).
394
* @@o: ATo. Open new output file (local scope).
395
* @@q: ATq. Turn off or on module and line information locally.
396
* @@R: ATR_. Treat next identifier as integer-like reserved word.
397
* @@r: ATr. Set language to Ratfor--77.
398
* @@r9: ATr9. Set language to Ratfor--90.
399
* @@u: ATu. Undefine an outer macro.
400
* @@v: ATv. Overload an operator.
401
* @@W: ATW_. Overload an identifier.
402
* @@x: ATx. Terminate ignorable material.
403
* @@y: ATy. End first part of change.
404
* @@z: ATz. Begin ignorable material.
405
406
Conversion to ASCII:
407
* @@': ATquote. Convert single character to ASCII.
408
* @@": ATdquote. Convert string to ASCII.
409
410
Forward referencing:
411
* @@[: AT[. Mark next identifier as defined in this section.
412
413
Comments:
414
* @@/*: AT/*. Begin a long verbatim comment.
415
* @@//: AT//. Begin a short verbatim comment.
416
* @@%: AT%. Ignore everything to next newline.
417
* @@?: AT?. Begin a compiler directive.
418
* @@(: ATlp. Begin a meta-comment.
419
* @@): AT). End a meta-comment.
420
421
Special brace:
422
* @@@{: ATlb. Insert left brace; suppress newlines in pretty-printing.
423
424
Index entries:
425
* @@_: AT_. Force an index entry to be underlined (marked as defined).
426
* @@-: AT-. Delete index entry for following identifier.
427
* @@+: ATplus. Force index entry for following identifier.
428
* @@^: AT^. Make index entry in Roman type.
429
* @@.: ATdot. Make index entry in typewriter type.
430
* @@9: AT9. Make index entry in format controlled by `\9'.
431
432
Control text:
433
* @@t: ATt. Put control text into TeX \hbox.
434
* @@=: AT=. Pass control text verbatim to the output.
435
436
Spacing:
437
* @@comma: ATcomma. Insert a thin space.
438
* @@/: AT/. Insert a line break, preserving indentation.
439
* @@\: ATbs. Insert a line break and backspace.
440
* @@|: AT|_. Insert optional line break in an expression.
441
* @@#: AT#. Force line break with blank line.
442
* @@~: AT~. Cancel a line break (tie adjacent lines together).
443
* @@&: AT&. Join left and right items.
444
445
Pseudo (invisible) operators:
446
* @@e: ATe. Invisible expression.
447
* @@;: AT;. Invisible semicolon.
448
* @@colon: ATcolon. Invisible colon.
449
450
Miscellaneous:
451
* @@!: AT!. Inhibit expansion for next macro.
452
453
COMMENTING STYLES
454
455
* Invisible comments:: Skipping input material.
456
* Visible comments:: Comments in code mode.
457
* Temporary comments:: Temporarily commenting out code.
458
459
MACROS and PREPROCESSING
460
461
* Outer macros:: Macros copied to beginning of output file (@@d).
462
* FWEB macros:: Macros and built-in functions expanded by @FWEB{} (@@m).
463
* Macros and formatting:: How to format macros for pretty-printing.
464
* Preprocessing:: @FWEB{}'s preprocessing language (@@#if, etc.)
465
466
@FWEB{} macros
467
468
* Macro features:: Various points about @FWEB{} macros.
469
* Tokens:: Special tokens used in @FWEB{} macros.
470
* Built-in functions:: Macro-like functions built into @FWEB{}.
471
* Debugging with macros:: Debugging glitches, and their solutions.
472
473
Various features of @FWEB{} macros
474
475
* Variable arguments:: @FWEB{} macros with variable arguments.
476
* Recursion:: @FWEB{} macros may be recursive (proceed at your own risk).
477
* Macro protection:: Protecting @FWEB{} macros against redefinition.
478
479
480
Built-in functions
481
482
* Strings and quotes:: Quoted and non-quoted strings.
483
* Protection:: By default, built-in functions may not be redefined.
484
485
INDIVIDUAL BUILT-IN FUNCTIONS
486
487
* $A:: Convert to ASCII.
488
* $ABS:: Absolute value.
489
* $ASSERT:: Assert a condition.
490
* $AUTHOR:: RCS global keyword; see $KEYWORD.
491
* $COMMENT:: Generate a comment.
492
* $DATE:: Today's date.
493
* $DATE_TIME:: RCS global keyword; see $KEYWORD.
494
* $DAY:: Today.
495
* $DECR:: Decrement a macro.
496
* $DEFINE:: Define a (deferred) macro.
497
* $DO:: Macro @b{DO} loop.
498
* $DUMPDEF:: Dump macro definitions to the terminal.
499
* $E:: Base of the natural logarithms: 2.71828...
500
* $ERROR:: Send error message to output.
501
* $EVAL:: Evaluate an expression.
502
* $EXP:: Exponential function.
503
* $GETENV:: Get value of environment variable.
504
* $HEADER:: RCS global keyword; see $KEYWORD.
505
* $HOME:: The user's home directory.
506
* $ID:: RCS global keyword; see $KEYWORD.
507
* $IF:: Two-way conditional: ``If expression is true''
508
* $IFCASE:: n-way conditional.
509
* $IFDEF:: Two-way conditional: ``If macro is defined''
510
* $IFNDEF:: Two-way conditional: ``If macro is not defined''
511
* $IFELSE:: Two-way conditional: ``If macro1 equals macro2''
512
* $INCR:: Increment a macro.
513
* $INPUT_LINE:: Line number that begins current section.
514
* $KEYWORD:: Extract text of global RCS-like keyword.
515
* $L:: Change string to lower case.
516
* $L_KEYWORD:: Extract text of local RCS-like keyword.
517
* $LANGUAGE:: Identifier for current language.
518
* $LANGUAGE_NUM:: Number of current language.
519
* $LEN:: Length of string.
520
* $LOCKER:: RCS global keyword; see $KEYWORD.
521
* $LOG:: Natural logarithm.
522
* $LOG10:: Logarithm to the base 10.
523
* $M:: Define a (deferred) macro.
524
* $MAX:: Maximum of one or more elements.
525
* $MIN:: Minimum of one or more elements.
526
* $MODULE_NAME:: Name of present @code{web} module.
527
* $MODULES:: Total number of independent modules.
528
* $NAME:: RCS global keyword; see $KEYWORD.
529
* $OUTPUT_LINE:: Current line number of tangled output.
530
* $P:: The C preprocessor symbol @code{#} (an unquoted string).
531
* $PI:: 3.14159...
532
* $POW:: Raise to a power.
533
* $PP:: The C preprocessor symbol @code{#} (a character).
534
* $RCSFILE:: RCS global keyword; see $KEYWORD.
535
* $REVISION:: RCS global keyword; see $KEYWORD.
536
* $ROUTINE:: Current Ratfor program, function, or subroutine.
537
* $SECTION_NUM:: Number of current section.
538
* $SECTIONS:: Maximum number of sections.
539
* $SOURCE:: RCS global keyword; see $KEYWORD.
540
* $SQRT:: Square root.
541
* $STATE:: RCS global keyword; see $KEYWORD.
542
* $STRING:: Expand argument, then stringize.
543
* $STUB::
544
* $TIME:: The local time.
545
* $TRANSLIT:: Transliterate a string.
546
* $U:: Change string to upper case.
547
* $UNDEF:: Undefine an @FWEB{} macro.
548
* $UNQUOTE:: Remove quotes from string (leaving an unquoted string).
549
* $UNSTRING:: Remove quotes and string delimiters from string.
550
* $VERBATIM:: (Obsolete.)
551
* $VERSION:: @FWEB{} version number.
552
553
LANGUAGES
554
555
* Setting the language:: Setting the language.
556
557
Special hints and considerations for each language.
558
* C:: C
559
* C++: Cpp. C++.
560
* Fortran:: Fortran--77 and Fortran--90.
561
* Ratfor: Ratfor_. RATional FORtran.
562
* TeX:: @TeX{}.
563
* Verbatim:: Literal mode.
564
565
@sc{Ratfor}
566
567
* Syntax: RSyntax. Ratfor syntax.
568
* Commands:: Ratfor commands.
569
* Caveats:: Nuances about @FWEB{} Ratfor.
570
571
DOCUMENTATION
572
573
* Typesetting:: Woven output; TeX vs. LaTeX, etc.
574
* Pretty-printing:: Turning ugly input into beautiful output.
575
576
Typesetting
577
578
* Output:: Structure of the TeX output from @FWEAVE{}.
579
* fwebmac.sty:: The macro package used with @FWEAVE{}.
580
* LaTeX:: Specifics of the LaTeX support.
581
582
The macro package @file{fwebmac.sty}
583
584
* User macros:: Macros defined for user convenience.
585
* Fonts:: Useful font commands.
586
587
La@TeX{} support
588
589
* Document class:: LaTeX's document class, options, etc.
590
* REVTeX:: The REV@TeX{} scientific macro package.
591
* Packages:: Special FWEB-related La@TeX{}2e packages.
592
* Sections:: Section numbering, spacing, etc.
593
* Index:LIndex. Technical details about multi-columns and the Index.
594
* Table of Contents:: The Table of Contents.
595
* Customizing LaTeX:: Conditional flags, etc.
596
* Inserting woven code:: How to insert @FWEAVE{}'s output into a La@TeX{} document.
597
598
La@TeX{} packages related to @FWEB{}
599
600
* fwebinsert:Inserting woven code. Enable insertion of woven code into a La@TeX{} document.
601
* fwebnum:Numbering. Number each section in ascending order.
602
* idxmerge:Merging indexes. Merge several stand-alone indexes.
603
604
Customizing La@TeX{}'s output
605
606
* Page references:: Indexing by page numbers.
607
* Headers:: The content of page headers.
608
* Numbering:: Various section numbering schemes.
609
610
Pretty-printing
611
612
* Alternatives:: Alternatives for various input tokens.
613
* Pseudo-operators:: Invisible parts of speech.
614
* Overloading:: Changing the appearance of various quantities.
615
616
@FWEB{}'s INDEX.
617
618
* Internal index:: The self-contained index produced by @FWEB{}.
619
* Using makeindex:: Writing index data for use by @code{makeindex}.
620
* Merging indexes:: Using the @code{idxmerge} utility to merge indexes.
621
622
CUSTOMIZATION
623
624
* Environment variables:: Environment or logical variables.
625
* Initialization:: Initialization file.
626
* Memory allocation:: Dynamic memory allocation.
627
* Style:: Style file.
628
629
Memory allocation
630
631
* -yb:: Maximum bytes for identifiers, index entries, and module names.
632
* -ybs:: Size of the change buffer.
633
* -ycb:: Size of line buffer for C output.
634
* -ycf:: A Ratfor buffer.
635
* -ycg:: Another Ratfor buffer.
636
* -yd:: Increment for expanding the dots table.
637
* -ydt:: Maximum number of deferred macro tokens.
638
* -ydx:: Maximum number of deferred macro texts.
639
* -yid:: Maximum depth of file inclusion.
640
* -yif:: Maximum number of unique include-file names.
641
* -ykt:: Stack size for @FTANGLE{}.
642
* -ykw:: Stack size for @FWEAVE{}.
643
* -yll:: Line length for @FWEAVE{}'s output.
644
* -yln:: Maximum length of module names or strings.
645
* -ylb:: Maximum number of nested loops in Ratfor.
646
* -ylx:: Maximum length of expressions that can be expanded with
647
the post-increment operators of Fortran or Ratfor.
648
* -ym:: Maximum number of sections.
649
* -yma:: Maximum number of arguments to @FWEB{} macros.
650
* -ymb:: Size of the buffer for expanding @FWEB{} macros.
651
* -yn:: Maximum number of identifiers and module names.
652
* -ynf:: Maximum number of open output files.
653
* -yop:: Maximum number of entries in the table for operator
654
overloading.
655
* -yr:: Maximum number of cross-references.
656
* -ys:: Maximum number of scraps.
657
* -ysb:: Size of style-file input-line buffer.
658
* -ytt:: Maximum number of tokens that @FTANGLE{} can process.
659
* -ytw:: Maximum number of tokens in the current section being
660
processed by @FWEAVE{}.
661
* -yx:: Maximum number of texts.
662
* -yxb:: Size of line buffer for @TeX{} output.
663
664
The Style file
665
666
* Index params:: Customizing the Index.
667
* Module params:: Customizing the list of sections.
668
* Contents params:: Customizing the Table of Contents.
669
* Subscript params:: Customizing subscripting for cross-references.
670
* Fwebmac params:: Customizing behavior of @FWEB{}'s macros.
671
* Completion params:: Automatic selection of file extensions, etc.
672
* Control-code mappings:: Remapping @FWEB{}'s control codes (danger)!
673
* Color:: @FWEB{}'s color output.
674
* Miscellaneous params:: Other customizations.
675
676
Customizing @FWEAVE{}'s index
677
678
* delim_0: S_delim. Insert after identifier in index entry.
679
* delim_n: S_delim. Insert between section numbers in index entry.
680
681
* encap.infix: S_encap. Start the section number.
682
* encap.prefix: S_encap. @TeX{} macro to begin a section number.
683
* encap.suffix: S_encap. Ends the section number.
684
685
* group_skip::
686
687
* index.collate: S_index. Collating sequence for the Index.
688
* index.postamble: S_index. @TeX{} material to end the Index.
689
* index.preamble: S_index. @TeX{} material to begin the Index.
690
* index.tex: S_index. Name of file holding the Index.
691
692
* item_0:: @TeX{} command to begin an index entry.
693
694
* language.prefix: S_language. Begin a language entry in the Index.
695
* language.suffix: S_language. End a language entry in the Index.
696
697
* lethead.prefix: S_lethead. Begin a letter group.
698
* lethead.suffix: S_lethead. End a letter group.
699
* lethead.flag: S_lethead. Control beginning of letter group.
700
701
* name: S_index. Name of index.
702
703
* underline.prefix: S_underline. Begin an underlined index entry.
704
* underline.suffix: S_underline. End an underlined index entry.
705
706
Customizing the module list
707
708
* modules.info: S_modules.
709
* modules.postamble: S_modules. @TeX{} commands to end module list.
710
* modules.preamble: S_modules. @TeX{} commands to begin module list.
711
* modules.tex: S_modules. Name of file containing list of modules.
712
713
Customizing the Table of Contents
714
715
* contents.postamble: S_contents. @TeX{} commands to end Table of Contents.
716
* contents.preamble: S_contents. @TeX{} commands to begin Table of Contents.
717
* contents.tex: S_contents. Name of contents file.
718
719
Customizing cross-reference subscripts
720
721
* mark_defined.generic_name: S_mark_defined.
722
* mark_defined.fcn_name: S_mark_defined.
723
* mark_defined.WEB_macro: S_mark_defined.
724
* mark_defined.outer_macro: S_mark_defined.
725
* mark_defined.exp_type: S_mark_defined.
726
* mark_defined.typedef_name: S_mark_defined.
727
728
Customizing the behavior of @file{fwebmac.sty} macros
729
730
* doc.preamble: S_LaTeX. Preamble for entire document.
731
* doc.postamble: S_LaTeX. Postamble for entire document.
732
733
* format_IDENTIFIER: S_format. Macro name for typesetting upper-case identifiers.
734
* format.reserved: S_format. Macro for reserved words.
735
* format.short_identifier: S_format. Macro for single-character identifiers.
736
* format_OUTER_MACRO: S_format. Macro for upper-case @samp{@@d} identifiers.
737
* format.outer_macro: S_format. Macro for lower-case @samp{@@d} identifiers.
738
* format_WEB_MACRO: S_format. Macro for upper-case @samp{@@m} identifiers.
739
* format.WEB_macro: S_format. Macro for lower-case @samp{@@m} identifiers.
740
* format.intrinsic: S_format. Macro for intrinsic library functions.
741
* format_KEYWORD: S_format. Macro for upper-case keywords.
742
* format.keyword: S_format. Macro for lower-case keywords.
743
* format.typewriter: S_format. Macro for strings.
744
* format.wildcard: S_format. Macro for user-defined index entries.
745
746
* indent.TeX: S_indent. Paragraph indentation for @TeX{} part.
747
* indent.code: S_indent. Paragraph indentation for code part.
748
749
* LaTeX.class: S_LaTeX. Specify the document class.
750
* LaTeX.class.options: S_LaTeX. Specify options for document class.
751
* LaTeX.package: S_LaTeX. Specify user package(s)
752
* LATeX.package.options: S_LaTeX. Specify options for user package(s).
753
754
Miscellaneous style-file parameters
755
756
* ASCII_fcn:: Routine for converting strings to ASCII.
757
* cchar:: Continuation character for Fortran.
758
* cdir_start:: @samp{@?} translates to this.
759
* line_char:: Comment char. for @FTANGLE{}'s @code{line} cmds.
760
* line_length: S_line_length.
761
762
* paren.len: -n). Length of one parenthesized index for @samp{-n)}.
763
* paren.levels: -n). Number of nested parentheses for @samp{-n)}.
764
* paren.num: -n). Number of permitted indices for @samp{-n)}.
765
766
* meta.top: S_meta_t. Material to precede tangled meta-comment.
767
* meta.prefix: S_meta_t. Begins each line of meta-comment.
768
* meta.bottom: S_meta_t. Material that follows the meta-comment.
769
770
* meta.top.hdr: S_meta_t. Like meta.top, but for info at start of file.
771
* meta.prefix.hdr: S_meta_t. As above.
772
* meta.bottom.hdr: S_meta_t. As above.
773
774
* outer.def: S_outer. @FTANGLE{} converts @samp{@@d} to this.
775
* outer.undef: S_outer. @FTANGLE{} converts @samp{@@u} to this.
776
777
* protect:: Protection character to end a continued line.
778
* suffix:: Suffixes for output files.
779
780
For @FWEAVE{}:
781
782
* macros:: Default name of the macro package to be
783
read in by @FWEAVE{}.
784
* limbo.begin: S_limbo. Default material to begin the limbo section.
785
* limbo.end: S_limbo. Default material to end the limbo section.
786
787
* meta.code.begin: S_meta_w.
788
* meta.code.end: S_meta_w.
789
790
* meta.TeX.begin: S_meta_w. @TeX{} material to begin @FWEAVE{}'s
791
output of a meta-comment.
792
* meta.TeX.end: S_meta_w. As above, but end the meta-comment.
793
794
* preamble.named: S_preamble. @TeX{} material to begin named section.
795
* preamble.unnamed: S_preamble. @TeX{} material to begin unnamed section.
796
797
For both processors:
798
799
* dot_constant.begin: S_dot_constant. Beginning character for dot constant.
800
* dot_constant.end: S_dot_constant. Ending character for dot constant.
801
802
* null_file:: Name of the null file.
803
804
Automatic file name completion
805
806
* Ext.web: S_Ext. Extensions for the web file.
807
* Ext.ch: S_Ext. Extensions for the change file.
808
* Ext.hweb: S_Ext. Extensions for include files.
809
* Ext.hch: S_Ext. Extensions for change files associated with
810
include files.
811
812
USAGE TIPS and SUGGESTIONS
813
814
* Converting:: Converting an existing code to @FWEB{}.
815
* Tips:: Usage tips and suggestions.
816
* Science:: Useful features for scientific programming.
817
818
NEW FEATURES
819
820
* V1.61::
821
* V1.53::
822
* V1.52::
823
* V1.50::
824
* V1.40::
825
@end menu
826
827
@node Copying, Intro, Top, Top
828
@comment node-name, next, previous, up
829
830
@unnumbered @FWEB{} Copying Permissions
831
832
@FWEB{} is ``free.'' This means that everyone is free to use them and free to
833
redistribute them on a free basis. @FWEB{} operates under the terms
834
of the GNU General Public License; see, for example,
835
@ref{Distrib, , Distribution, emacs, The GNU Emacs Manual}.
836
837
Although it is hoped that @FWEB{} will be useful,
838
there is @emph{ABSOLUTELY NO WARRANTY}.
839
840
@node Intro, Concepts, Copying, Top
841
@comment node-name, next, previous, up
842
843
@chapter INTRODUCTION to @FWEB{}
844
845
@cindex Literate programming
846
@FWEB{} is a system for @dfn{literate programming}. It enables one to
847
maintain both documentation and source code in a single place (the
848
@code{web} file), and to explain the code in terms of a @dfn{web} of
849
very small fragments. Because @FWEB{} is intimately integrated with
850
@TeX{}, one gains many advantages such as book-quality typesetting and
851
extensive cross-referencing facilities. A simple example program is
852
described in @ref{Structure}.
853
854
855
@FWEB{} was originally intended for scientific programming (the 'F'
856
stands for @sc{Fortran}), and is in wide use in that arena; however, it
857
has much broader applicability. It is an extension of Knuth's WEB
858
system that handles the specific languages C, C++, Fortran (both F77 and
859
F90), @sc{Ratfor}, and (in a limited fashion) @TeX{} itself. It also
860
attempts to implement a WYSIWYG language-independent mode as well as a
861
(closely-related but not identical) verbatim `language'. @emph{The
862
language-independent features are highly experimental} and are not
863
recommended.
864
865
The origins and philosophy of literate programming are described in the
866
very enjoyable book by D. E. Knuth, @cite{Literate Programming} (Center for
867
the Study of Language and Information, Leland Stanford Junior
868
University, 1992).
869
870
Knuth's original WEB
871
@pindex WEB
872
was written in Pascal, and it formatted Pascal code.
873
Silvio Levy introduced @sc{Cweb},
874
@pindex CWEB
875
a WEB system written in C for C. @FWEB{}
876
@pindex FWEB
877
is a
878
(by now, substantial) modification of version 0.5 of @sc{Cweb} that was
879
graciously supplied by Levy. It also borrows various ideas from the
880
works of Ramsey and Briggs on language-independent webs.
881
882
The original WEB's worked with Plain @TeX{}. More recently, many users
883
have turned to Lamport's La@TeX{} because of its ease of use and
884
higher-level features. Excellent and extensive development of La@TeX{} has been
885
accomplished, as described by Goossens, Mittelbach, and Samarin, @cite{The
886
La@TeX{} Companion} (Addison--Wesley, Reading, MA, 1994).
887
The present version of @FWEB{} is intended to be used with
888
La@TeX{} (La@TeX{}2e, in particular); Plain @TeX{} is no longer supported.
889
890
@menu
891
* History:: History of literate programming.
892
* Features:: Special features of @FWEB{}.
893
@end menu
894
895
@node History, Features, Intro, Intro
896
@comment node-name, next, previous, up
897
898
@section History of WEB and literate programming
899
(To be completed; see Knuth's book, cited in @ref{Intro}.)
900
901
@node Features, , History, Intro
902
@comment node-name, next, previous, up
903
904
@section Features of @FWEB{}
905
906
@FWEB{} is distinguished from its relatives in several respects:
907
908
@quotation
909
@itemize @bullet
910
@item
911
@FWEB{} introduces the concept of a @emph{current language}
912
(@pxref{Languages}), so more than one compiler language can be processed
913
in a single @FWEB{} run. For example, mixtures of C++ and
914
@sc{Fortran} are common in modern scientific programming.
915
916
@item
917
@FWEB{} understands the syntaxes of several of the more important
918
compiler languages: C, C++, @sc{Fortran} (both F77 and F90),
919
@sc{Ratfor}, and @TeX{}. For other languages, @FWEB{} can work in a
920
language-independent mode that essentially weaves and tangles the source
921
code verbatim, but still provides the user with the powerful @sc{web}
922
features related to @sc{TeX} documentation, module names, macro
923
processing, etc.
924
925
@item
926
@FWEB{} contains a built-in @sc{Ratfor} (@sc{RATional} @sc{FORtran})
927
translator. @xref{Ratfor}.
928
929
@item
930
@FWEB{} has a built-in C-like @emph{macro preprocessor}. This is
931
especially useful for @sc{Fortran} and @sc{Ratfor}, which have no predefined
932
preprocessor. However, certain extensions such as variable numbers of arguments
933
make the @FWEB{} preprocessor sometimes useful even for C and C++.
934
@xref{Macros} and @ref{Preprocessing}.
935
936
@item
937
Many aspects of @FWEB{}'s behavior, default strings, etc. can be
938
customized by means of setting parameters in a @code{makeindex}-like
939
@emph{style file} (by default, @file{fweb.sty}). @xref{Style}.
940
941
@end itemize
942
@end quotation
943
944
@node Concepts, Files, Intro, Top
945
@comment node-name, next, previous, up
946
947
@chapter WEB CONCEPTS
948
949
The principle concepts of @sc{WEB} programming are laid out in Knuth's book,
950
the reference to which was given in @ref{Intro}. @FWEB{} follows most
951
conventions introduced by @sc{web} and @sc{Cweb}, except that the names
952
of some commands have been changed for consistency, symmetry, and/or
953
clarity.
954
955
@menu
956
* Processors:: @FTANGLE{} and @FWEAVE{}.
957
* Phases:: Phases of operation of the @FWEB{} processors.
958
* Structure:: The structure of a web.
959
* Modules:: Use of named and unnamed modules.
960
@end menu
961
962
@node Processors, Phases, Concepts, Concepts
963
@comment node-name, next, previous, up
964
965
@section The @FWEB{} processors: @FWEAVE{} and @FTANGLE{}
966
967
@cindex Processors, @FWEB{}
968
Following Knuth's original design, @FWEB{} consists of two processors,
969
@FTANGLE{} and @FWEAVE{}. Both operate on a single source file, say
970
@file{test.web}. @FTANGLE{} produces compilable code, say @file{test.c},
971
whereas @FWEAVE{} produces a @TeX{} file, @file{test.tex}, that can
972
(in principle) be processed with either @TeX{} or La@TeX{}. (If a file
973
@file{test.tex} already exists, @FWEAVE{} will ask for confirmation
974
before overwriting it if it does not think that the file was created by
975
a previous run of @FWEAVE{}.)
976
977
The output file produced by @FTANGLE{} is not intended for human eyes
978
(or for editors!); it is for compiling only. All changes to the code
979
should be made to the @code{web} file, since changes made directly to
980
the output file would be overwritten the next time the @code{web} source
981
is tangled. In an attempt to discourage messing with @FTANGLE{}'s
982
output file, all unnecessary spaces are deliberately removed.
983
984
@cindex Makefiles, using
985
A common way of integrating @FWEB{} into ones program development is to
986
do all compilations through a @code{make} file, into which one puts an
987
extra dependency line that explains how to produce the compilable output
988
file from the @code{web} source. For example,
989
990
@example
991
test.c: test.web
992
ftangle test
993
994
test.o: test.c
995
gcc -c test test.c
996
@end example
997
@noindent
998
With this approach, one is not so tempted to edit @file{test.c}.
999
1000
@FWEB{} development is now based on La@TeX{}; Plain @TeX{} is no longer
1001
supported. For detailed descriptions of the La@TeX{} support, see @ref{LaTeX}.
1002
1003
1004
@node Structure, Modules, Phases, Concepts
1005
@comment node-name, next, previous, up
1006
1007
@section The structure of a web
1008
1009
@cindex Web, structure
1010
An @FWEB{} source file is structured into @dfn{sections}, which
1011
correspond to logical subunits of the code (either a function or a
1012
fragment of a function).
1013
@cindex Sections
1014
Each section consists of three @dfn{parts}, each of which is optional:
1015
@cindex Parts
1016
@cindex Part, @TeX{}
1017
@cindex Part, definition
1018
@cindex Part, code
1019
the
1020
1021
@quotation
1022
@enumerate
1023
@item
1024
@TeX{} part;
1025
1026
@item
1027
definition part; and
1028
1029
@item
1030
code part.
1031
@end enumerate
1032
@end quotation
1033
@noindent
1034
When @FTANGLE{} outputs code, it can combine
1035
the code parts of (possibly noncontiguous) sections into
1036
larger units called @dfn{modules}, as explained in @ref{Modules}.
1037
1038
With the aid of sections, one's possibly huge and logically complex code
1039
can be broken down into bite-sized pieces, each one easily
1040
comprehensible. Since sections may correspond to only a small part of a
1041
function or subroutine, 1000-line main programs (they still exist!)
1042
should become a thing of the past.
1043
1044
Since sections can be combined into modules, there is no
1045
need for sections that must be physically contiguous in the output file
1046
to be contiguous in the source file. This allows for great flexibility
1047
in structuring the documentation of the code.
1048
1049
@subsubsection A simple example
1050
1051
@cindex Example, of @FWEB{} file
1052
A simple example of an @FWEB{} source file consisting of three sections is as
1053
follows:
1054
1055
@example
1056
@group
1057
@@n/ % Set FWEB language to Fortran, and recognize short // comments.
1058
1059
\Title@{example.web@} % \Title is an FWEB TeX macro.
1060
\author@{J. A. Krommes@} % \author is a LaTeX macro.
1061
1062
@@* INTRODUCTION.
1063
This code is intended to illustrate the use of the |write| statement.
1064
It also provides a simple example of the \FWEB\ macro preprocessor.
1065
1066
@@m A_CONSTANT 1.2345 // \FWEB\ preprocessor macro definition.
1067
1068
@@a
1069
program main
1070
call compute
1071
end
1072
1073
@@ The computational routine is pretty boring.
1074
@@a
1075
subroutine compute
1076
write(*,*) 'Macro value = ', A_CONSTANT
1077
end
1078
1079
@@* \INDEX.
1080
@end group
1081
@end example
1082
1083
Commands to @FWEB{} are begun by the @samp{@@} symbol (@pxref{AT
1084
commands}). In this example, the first command, @samp{@@n}, sets the
1085
global language to @sc{Fortran}-77. One should always begin one's code
1086
with a language-setting command.
1087
1088
In this example, the language command is invoked with an optional
1089
argument @samp{/}. That is necessary in @sc{Fortran} in order to tell
1090
@FWEB{} to use the short (single-line) comment form beginning with
1091
@samp{//}, which otherwise conflicts with the concatenation operator.
1092
@xref{-n/}.
1093
1094
For more information about languages, see @ref{Languages}. For a fuller
1095
discussion of optional arguments, see @ref{Setting the language}.
1096
1097
@findex @@*
1098
@cindex Sections, named
1099
@cindex Sections, unnamed
1100
The @samp{@@*} command begins a @dfn{major} or @dfn{named section}
1101
(corresponding to La@TeX{}'s @code{\section} command); this command is
1102
followed by the section name, terminated by a period. (The period is
1103
essential; if it is omitted, weird errors may result.) Major sections
1104
are entered in an automatically generated Table of Contents. They are
1105
also printed at the top of each output page. If the full section name
1106
is too long to so print, one can shorten it with an optional argument,
1107
as in
1108
1109
@example
1110
@@* [INTRO]INTRODUCTION.
1111
@end example
1112
1113
The command @samp{@@*@i{n}} (not illustrated in the above example)
1114
begins a major (sub)section of level @i{n}, where @samp{@@*0} is
1115
equivalent to the simple @samp{@@*}, @samp{@@*1} indicates a subsection,
1116
and @samp{@@*2} indicates a subsubsection. The highest
1117
permissible major level is 2 (a subsubsection). Such subsections are
1118
also entered in the Table of Contents. For more information, see
1119
@ref{Sections}.
1120
1121
@findex \INDEX
1122
@cindex Index
1123
As the example demonstrates, the name of the very last section, which
1124
should be starred, should be @samp{\INDEX}. Note the backslash;
1125
@samp{\INDEX} is a @TeX{} macro. This command tells @FWEAVE{} to
1126
write out the index in a special two-column format. By default,
1127
@samp{\INDEX} expands to @samp{INDEX}, but this name can be overridden
1128
by the style-file parameter @samp{index.name} (@pxref{S_index}). For
1129
more discussion of @FWEB{}'s indexing facilities, see @ref{Index}.
1130
1131
Minor (@dfn{unnamed}) sections are begun by @ASP{} (``at-space'');
1132
these have no associated names and are not entered into the Table of
1133
Contents. A newline counts as a space.
1134
1135
@subsubsection The @TeX{} part
1136
1137
@cindex Commentary, optional
1138
@cindex Part, @TeX{}
1139
All sections begin with (optional) @TeX{} commentary. That can just be
1140
straight text; to input that, no knowledge of @TeX{} is required. It
1141
can also include mathematical exposition or any of the other advanced
1142
features offered by @TeX{}.
1143
1144
Whenever @FWEB{} is in @TeX{} mode, one can temporarily shift into @dfn{code mode}
1145
@cindex Code mode
1146
@cindex Vertical bars
1147
@cindex Code, typesetting
1148
by enclosing the
1149
code within vertical bars. That code is typeset just like code in the
1150
code part (see below), except that newlines are replaced by spaces.
1151
Thus, one can say things like
1152
1153
@example
1154
Consider the C code fragment `|@@c for(i=0; i<10; i++)@{@}|', which ...
1155
@end example
1156
@noindent
1157
(If the global language were C instead of @sc{Fortran}, the @samp{@@c} inside
1158
the vertical bars would not be necessary.)
1159
The ability to switch back and forth between text mode and code mode at
1160
will allows for a very convenient and flexible style of exposition.
1161
1162
@subsubsection The definition part
1163
1164
@cindex Part, definition
1165
The @TeX{} part is followed by an
1166
optional @dfn{definition part}. The beginning of the definition part is
1167
signaled by the appearance of any one of the commands @samp{@@d}, @samp{@@f},
1168
@samp{@@m}, @samp{@@v}, or @samp{@@W} (explained later).
1169
In the previous example, the first section has a
1170
definition part consisting of one @FWEB{} macro definition (@samp{@@m}); the
1171
second section has no definition part. For more information, see @ref{Macros}.
1172
1173
(Failure to appreciate how easy it is to shift from part to part can get
1174
one into trouble. For example, don't write documentation such as
1175
@samp{Consider the @@m command}, because the @samp{@@m} will inadvertently
1176
terminate the documentation part and begin the definition part. What
1177
one needs to do here is to use the literal @samp{@@}, as in
1178
@samp{@@@@m}.)
1179
@cindex @@, literal
1180
1181
@subsubsection The code part
1182
1183
@cindex Part, code
1184
An unnamed @dfn{code part} is begun by @samp{@@a}. A named code part is begun
1185
by the appearance of a module name, such as @samp{@@<Global
1186
variables@@>}, followed by an equals sign; see @ref{Modules}. Within
1187
the code part, one can place any sequence of code or code fragments
1188
(they need not be complete subroutines) that are valid for the current
1189
language. (Setting the language is described in @ref{Languages}.) The
1190
code part is terminated by the next appearance of @samp{@@*} or @ASP{}
1191
(which signal the beginning of a new section), or by the end of file.
1192
1193
@subsubsection The limbo section
1194
1195
@cindex Section, limbo
1196
@cindex Limbo section
1197
The portion of the source file before the first section (i.e., before
1198
the first @samp{@@*} or @ASP{}) is called @dfn{in limbo} or
1199
@dfn{the limbo section}.
1200
@cindex Limbo section
1201
The only @samp{@@} commands that are allowed in limbo (in addition to
1202
@samp{@@@@}, which stands for the character @samp{@@} and is allowed
1203
anywhere) are the language-changing commands, and one of those, such as
1204
@samp{@@c}, should appear. Other text in limbo is ignored by @FTANGLE{}
1205
and is copied by @FWEAVE{} to the @code{tex} output file. Thus, one can make or
1206
issue @TeX{} macro definitions in limbo that override the defaults in
1207
@FWEB{}'s macro package @file{fwebmac.sty}. In the above example, see
1208
the @code{\Title} command. This is defined in @file{fwebmac.sty}, and
1209
basically issues La@TeX{}'s @code{\title} command.
1210
1211
(Another way of getting @TeX{} text into the limbo section is by means of
1212
the @samp{@@l} command; see @ref{ATl}.)
1213
1214
La@TeX{} users may need to know that @TeX{} commands in limbo are
1215
executed @emph{after} the @samp{\begin@{document@}} command (which is
1216
issued automatically in @file{fwebmac.sty}). For more information, see
1217
@ref{LaTeX}.
1218
1219
@node Modules, , Structure, Concepts
1220
@comment node-name, next, previous, up
1221
1222
@section Modules
1223
1224
@cindex Modules
1225
The code parts of (possibly noncontiguous) sections can be combined into
1226
@dfn{modules}. For @FWEAVE{}, this is a @emph{logical} combination, for
1227
purposes of cross-referencing different pieces of the code. But for
1228
@FTANGLE{}, the combination is physical; @FTANGLE{}'s output proceeds module
1229
by module.
1230
1231
Modules can be @dfn{named} or @dfn{unnamed}. There is exactly one
1232
unnamed module. The fundamental operation of @FTANGLE{} is that
1233
1234
@quotation
1235
@emph{@FTANGLE{} outputs the unnamed module}.
1236
@end quotation
1237
@noindent
1238
That output goes to a compilable file with an extension appropriate to
1239
the current language.
1240
1241
The contents of a module, either unnamed or named, consists of a mixture
1242
of code and comments. @FTANGLE{} ignores the comments; @FWEAVE{}
1243
treats them as @TeX{} text. Within any @TeX{} text, including comments,
1244
constructions delimited by @samp{|...|} signify a temporary shift into
1245
code mode. (In the present design, one cannot enclose a comment within
1246
the vertical bars.)
1247
1248
@subsection The unnamed module
1249
1250
The unnamed code module
1251
@cindex Unnamed module
1252
@cindex Module, unnamed
1253
is introduced by the command @samp{@@a}. Subsequent
1254
uses of @samp{@@a} accrete code to the unnamed module.
1255
To repeat, the fundamental operation of @FTANGLE{} is that
1256
1257
@quotation
1258
@emph{@FTANGLE{} outputs the unnamed module}.
1259
@end quotation
1260
1261
@noindent
1262
Thus, there must be at least one @samp{@@a} in the source file or
1263
@FTANGLE{} will output nothing.
1264
1265
(Why is the command called @samp{@@a}? Historically, it was the first
1266
letter of the alphabet, as befits its prominent status. However, one
1267
can also think of it as ``accrete.'')
1268
1269
@subsection Named modules
1270
1271
@cindex Named module
1272
@cindex Module, named
1273
Named modules represent logically-connected fragments of code.
1274
1275
A module name is specified by the construction
1276
1277
@example
1278
@@< @i{Arbitrary @TeX{} text} @@>
1279
@end example
1280
1281
@noindent
1282
Leading and trailing white space around the name text is ignored. The
1283
name text can include the @samp{|...|} construction, which tells
1284
@FWEAVE{} to typeset a code fragment. Thus, module names can be
1285
highly explicit---for example,
1286
1287
@example
1288
@@< Check that |x >= 0.0|; |abort| if not @@>
1289
@end example
1290
1291
To define a named module, replace the @samp{@@a} that begins the unnamed code
1292
part of a section by @samp{@@< @i{module name} @@>=}. If one uses this
1293
construction with the same name in a later section, the effect is to
1294
@emph{accrete} to the contents of the module. Thus, a named module
1295
might ultimately consist of the code from sections 2, 5, and 9, for
1296
example.
1297
1298
To use a named module, simply use the name anywhere in a code part;
1299
@FTANGLE{} will insert the contents of the module at the point where the
1300
name is used. For example,
1301
1302
@example
1303
@@c
1304
@@ Here's how to use a named module.
1305
@@a
1306
for(i=1; i<n; i++)
1307
@@< Inner loop @@>@@;
1308
1309
@@ Here's how to define a named module. Definitions may occur after use.
1310
@@< Inner...@@>=
1311
@{
1312
a[i] = i;
1313
@}
1314
@end example
1315
1316
@noindent
1317
There are several details to notice about the above example. First,
1318
@FWEAVE{} considers module names to be simple expressions (such as the
1319
single identifier @var{x}). In C, expressions are made into complete
1320
statements (as is required in the body of a @b{for} statement) by
1321
appending a semicolon. In this case, a @emph{pseudo-semicolon}
1322
@samp{@@;} is appropriate; for more discussion of that,
1323
see @ref{AT;}.
1324
1325
Second, after a name has appeared once in full, it may be
1326
abbreviated by a unique prefix followed by three periods, as demonstrated in
1327
the above example. By convention, a complete module name cannot be a
1328
subset of another. For example, @samp{@@<Test@@>} and @samp{@@<Test of
1329
graphics@@>} will elicit an error message.
1330
1331
Commonly, the first unnamed section in the code indicates its modular
1332
structure. For example, a C code might begin with
1333
1334
@example
1335
@@c
1336
@@* DEMO.
1337
@@a
1338
@@<Include files@@>@@;
1339
@@<Typedefs@@>@@;
1340
@@<Function prototypes@@>@@;
1341
@@<Global variables@@>@@;
1342
@end example
1343
1344
@noindent
1345
Subsequently one can accrete to the above named sections, as often as
1346
desired and in any order. This way, definitions of global variables can
1347
be introduced anywhere in the @code{web} source file as logical and pedagogical
1348
exposition dictates, but will
1349
be guaranteed to appear at the top of the code. Function prototypes
1350
could be handled this way as well; alternatively, they could all be
1351
collected into one section, perhaps at the end of the source file. (The
1352
above organization still guarantees that they will appear at the
1353
beginning of the output.) Functions could be introduced one at a time
1354
in subsequent unnamed sections.
1355
1356
Very rarely, one might try the following construction:
1357
1358
@example
1359
@@
1360
@@a
1361
@@< @i{Left side} @@> = @@< @i{Right side} @@>@@;
1362
@end example
1363
@noindent
1364
Here the intent is to construct an assignment statement. However, this
1365
will be flagged as an error because @FWEB{} thinks one is trying to
1366
define the named module @samp{@@<@i{Left side}@@>}, which one shouldn't be
1367
doing while in code mode. To make it work, just put the invisible
1368
expression @samp{@@e} (@pxref{ATe}) before the equals sign.
1369
1370
@node Phases, Structure, Processors, Concepts
1371
@comment node-name, next, previous, up
1372
1373
@section Phases of processing
1374
1375
The @FWEB{} processors perform their work in several distinct phases.
1376
(The following is somewhat technical. Scan it, then use it for
1377
reference later if necessary.)
1378
1379
@subsection The phases of @FTANGLE{}
1380
1381
@cindex Phases, of @FTANGLE{}
1382
@FTANGLE{} has two phases. In phase 1, the source file is read; in phase
1383
2, compilable code is written out in the order specified by the web.
1384
1385
More specifically, phase 1
1386
1387
@quotation
1388
@itemize @bullet
1389
@item
1390
discards @TeX{} documentation;
1391
1392
@item
1393
tokenizes the source;
1394
1395
@item
1396
expands @FWEB{} preprocessor commands such as @samp{@@#if}
1397
(@pxref{Preprocessing});
1398
1399
@item
1400
expands @samp{@@'...'} (@pxref{ATquote}), @samp{@@"..."} (@pxref{ATdquote}),
1401
and the binary notation @samp{0b...} (@pxref{C}) [in @sc{Fortran}, also
1402
the octal notation @samp{0...} and the hexadecimal notation @samp{0x...}];
1403
1404
@item
1405
stores code text in appropriate modules;
1406
1407
@item
1408
memorizes macro definitions (@samp{@@d} and @samp{@@m})
1409
(@pxref{ATd} and @ref{ATm}).
1410
@end itemize
1411
@end quotation
1412
1413
Phase 2
1414
1415
@quotation
1416
@itemize @bullet
1417
@item
1418
outputs outer macro definitions (@samp{@@d});
1419
1420
@item
1421
outputs the unnamed module (@samp{@@a});
1422
1423
@item
1424
expands @FWEB{} macros (@samp{@@m});
1425
1426
@item
1427
expands built-in macros such as @samp{$IF} or @samp{$PI}
1428
(@pxref{Built-in functions});
1429
1430
@item
1431
translates @sc{Ratfor} statements (@pxref{Ratfor}).
1432
@end itemize
1433
@end quotation
1434
1435
@subsection The phases of @FWEAVE{}
1436
1437
@cindex Phases, of @FWEAVE{}
1438
@FWEAVE{} has three phases. In phase 1, the source file is read and
1439
cross-reference information is collected. In phase 2, the source file
1440
is read again, then pretty-printed with some cross-reference
1441
information. (For discussion of pretty-printing, see
1442
@ref{Pretty-printing}.) In phase 3, an automatically-generated Index,
1443
List of Modules, and Table of Contents are written.
1444
1445
More specifically, phase 1
1446
1447
@quotation
1448
@itemize @bullet
1449
@item
1450
tokenizes and stores identifiers and module names;
1451
1452
@item
1453
collects cross-reference information (including, in C and C++, the
1454
scanning of @samp{#include} files for @samp{typedef} and/or @samp{class}
1455
declarations (@pxref{-H_});
1456
1457
@item
1458
stores limbo text definitions made with @samp{@@l} (@pxref{ATl});
1459
1460
@item
1461
collects information about overloaded operators (@samp{@@v}) and
1462
identifiers (@samp{@@W}). @xref{ATv} and @ref{ATW_}.
1463
@end itemize
1464
@end quotation
1465
1466
Phase 2
1467
1468
@quotation
1469
@itemize @bullet
1470
@item
1471
outputs limbo text;
1472
1473
@item
1474
outputs special @TeX{} macros for overloaded operators;
1475
1476
@item
1477
copies @TeX{} material directly to output;
1478
1479
@item
1480
treats material between vertical bars (@samp{|...|}) as code to be
1481
typeset;
1482
1483
@item
1484
tokenizes and stores contents of each code section;
1485
1486
@item
1487
analyzes code syntax and converts it to appropriate @TeX{} macros.
1488
@end itemize
1489
@end quotation
1490
1491
Phase 3 writes out cross-reference information. (To eliminate some of
1492
that, see @ref{-x}.) Specifically, it
1493
1494
@quotation
1495
@itemize @bullet
1496
@item
1497
writes out the Index (@file{INDEX.tex} by default, but see @ref{Output
1498
files} and @ref{Index params});
1499
1500
@item
1501
writes out a list of named modules (@file{MODULES.tex} by default, but
1502
see @ref{Output files} and @ref{Module params});
1503
1504
@item
1505
writes out macros to generate the Table of Contents. (Table of Contents
1506
information is actually processed by La@TeX{}, not @FWEAVE{}. The
1507
information is written to the @file{aux} file.)
1508
@end itemize
1509
1510
@end quotation
1511
1512
1513
@node Files, Starting, Concepts, Top
1514
@comment node-name, next, previous, up
1515
1516
@chapter FILES
1517
1518
@cindex Files
1519
@FWEB{} works with a variety of files. File names have the form
1520
@samp{[path]/root[.ext]}, where the brackets denote optional. Here the slash
1521
is called the @dfn{prefix end character}. Since this character differs
1522
for various
1523
operating systems, it can be changed by system installers in @file{custom.h}
1524
(@pxref{Customization}).
1525
The character that initiates the file-name extension (normally a period)
1526
can be changed with the @samp{-E} command-line option (@pxref{-E_}).
1527
1528
1529
@menu
1530
* Input files:: Input files.
1531
* Output files:: Output files.
1532
* Change files:: Change files.
1533
@end menu
1534
1535
@node Input files,Output files,Files,Files
1536
@comment node-name, next, previous, up
1537
1538
@section Input files
1539
1540
@cindex Files, input
1541
@FWEB{} reads files with a variety of default extensions.
1542
1543
@quotation
1544
1545
@file{.fweb} --- Initialization file (optional; for setting up default options
1546
used for all runs). This file is always in the user's home directory.
1547
@xref{Initialization}.
1548
@findex .fweb
1549
1550
@file{fweb.sty} --- Style file (optional; for customizing the behavior
1551
of a particular @code{web} file or group of files). @xref{Style}. This
1552
file is always in
1553
the directory of the @code{web} file that is being tangled unless that
1554
is changed by environment variable @code{FWEB_STYLE_DIR}. The basic
1555
name can be changed by the @samp{-z} option (@pxref{-z}).
1556
@findex fweb.sty
1557
A sample @file{fweb.sty} file is provided with the @FWEB{} distribution.
1558
1559
@file{@i{name}.web} --- Source file.
1560
1561
@file{@i{name}.ch} --- Change file (optional; for making incremental changes
1562
to a @code{web} source file). @xref{Change files}.
1563
1564
@file{@i{name}.hweb} --- Code included into web file with @samp{@@i}
1565
(@pxref{ATi}).
1566
Include files are searched for in the path set by the environment
1567
variable @code{FWEB_INCLUDES} and/or the @samp{-I} option (@pxref{-I_}).
1568
If that path is empty, then the current directory is searched.
1569
1570
@file{@i{name}.hch} --- Optional change file for include file.
1571
@end quotation
1572
1573
@menu
1574
* Completion:: Automatic file-name completion.
1575
@end menu
1576
1577
@node Completion,,Input files,Input files
1578
@comment node-name, next, previous, up
1579
1580
@subsection Automatic file-name completion
1581
1582
@cindex File-name completion
1583
@cindex Completion, automatic file-name
1584
Automatic completion of input file names is turned on by the @samp{-e}
1585
command-line option (@pxref{-e}). When this option is in effect, input
1586
file names that
1587
include no period (have no extension) are completed automatically
1588
according to the contents of the following style-file entries:
1589
1590
@quotation
1591
@multitable { for include file} {Style-file entry} {Default}
1592
@item
1593
@r{Type of file} @tab @r{Style-file entry} @tab @r{Default}
1594
@item
1595
@r{WEB file} @tab @code{ext.web} @tab @code{web}
1596
@item
1597
@r{Change file} @tab @code{ext.ch} @tab @code{ch}
1598
@item
1599
@r{Include file} @tab @code{ext.hweb} @tab @code{hweb}
1600
@item
1601
@r{Change file for include file} @tab @code{ext.hch} @tab @code{hch}
1602
@end multitable
1603
@end quotation
1604
@noindent
1605
More than one extension may be specified, as a space-delimited
1606
list---e.g., @samp{ext.web = "web wb"}; the first one that matches is used.
1607
1608
@node Output files,Change files,Input files,Files
1609
@comment node-name, next, previous, up
1610
1611
@section Output files
1612
1613
@cindex Files, output
1614
@FWEAVE{} writes a variety of output files.
1615
1616
@quotation
1617
@file{@i{name}.tex} --- Woven output to be processed with La@TeX{}.
1618
1619
@file{CONTENTS.tex} --- Temporary file that accumulates
1620
Table-of-Contents information. (For La@TeX{}, the @file{aux} file is
1621
used instead.)
1622
@findex CONTENTS.tex
1623
1624
@file{INDEX.tex} --- Temporary file that stores indexing information.
1625
@findex INDEX.tex
1626
1627
@file{MODULES.tex} --- Temporary files that stores module list.
1628
@findex MODULES.tex
1629
@end quotation
1630
1631
@noindent
1632
@cindex Output files, changing names of
1633
The names of the three temporary files can be changed with style-file
1634
parameters (@pxref{Style}). Commonly, one may put into the style file
1635
@file{fweb.sty} commands such as
1636
1637
@example
1638
index.tex "#.ndx"
1639
modules.tex "#.mds"
1640
contents.tex "#.cts"
1641
@end example
1642
1643
@noindent
1644
The @samp{#} is replaced by the root name of the @code{web} file.
1645
1646
@FTANGLE{} writes files of the form
1647
1648
@quotation
1649
@file{@i{name}.@i{ext}} --- Compilable output file.
1650
@end quotation
1651
@noindent
1652
The extensions for the compilable output file(s) have certain defaults,
1653
but can be changed by style-file parameters according to the following
1654
table:
1655
1656
@quotation
1657
@multitable {Fortran-77} {style-file entry} {unix default} {non-unix default}
1658
@item
1659
@r{Language} @tab @r{Style-file entry} @tab @r{@sc{unix} default} @tab @r{non-@sc{unix} default}
1660
@item
1661
C @tab @code{suffix.C} @tab @code{c} @tab @code{c}
1662
@item
1663
C++ @tab @code{suffix.Cpp} @tab @code{C} @tab @code{C}
1664
@item
1665
Fortran--77 @tab @code{suffix.N} @tab @code{f} @tab @code{for}
1666
@item
1667
Fortran--90 @tab @code{suffix.N90} @tab @code{f90} @tab @code{for90}
1668
@item
1669
Ratfor--77 @tab @code{suffix.R} @tab @code{r} @tab @code{rat}
1670
@item
1671
Ratfor--90 @tab @code{suffix.R90} @tab @code{r90} @tab @code{rat90}
1672
@item
1673
TeX @tab @code{suffix.X} @tab @code{sty} @tab @code{sty}
1674
@item
1675
VERBATIM @tab @code{suffix.V} @tab @code{mk} @tab @code{mk}
1676
@end multitable
1677
@end quotation
1678
@noindent
1679
For example, to change the default extension for a C++ file from
1680
@samp{C} to @samp{c++}, put into @file{fweb.sty} the line
1681
1682
@example
1683
suffix.C = "c++"
1684
@end example
1685
1686
@node Change files,,Output files,Files
1687
@comment node-name, next, previous, up
1688
1689
@section Change files
1690
1691
@cindex Files, change
1692
The primary input to the @FWEB{} processors is the @file{test.web}
1693
source file. However, a @dfn{change file} @file{test.ch} can also be
1694
specified. A change file consists of instances of the following
1695
structure:
1696
1697
@example
1698
@@x
1699
(One or more lines of text, EXACTLY as in the web file. Copy these
1700
lines with an editor; don't type them from scratch.)
1701
@@y
1702
(Replacement text.)
1703
@@z
1704
@end example
1705
1706
@noindent
1707
The change-file mechanism allows one to insert local changes or test new
1708
code without physically modifying the original web file.
1709
1710
To specify a change file, use its name as the second file name on the
1711
command line. The extension @samp{.ch} is assumed by default. For
1712
example,
1713
1714
@example
1715
ftangle test test
1716
@end example
1717
1718
@noindent
1719
processes @file{test.web} with the change file @file{test.ch}.
1720
1721
@findex @@[
1722
@findex @@]
1723
In addition to @samp{@@x}, @samp{@@y}, and @samp{@@z}, the only
1724
@samp{@@} commands allowed in a change file are language-changing
1725
commands such as @samp{@@c} and the special commands @samp{@@[} and
1726
@samp{@@]}. The command @samp{@@[} is used for column-oriented
1727
languages such as @sc{Fortran}--77 and means @dfn{switch into code
1728
mode}. Similarly, @samp{@@]} means @dfn{switch out of code mode}.
1729
1730
All @samp{@@} commands in a change file must begin in column 1. Lines
1731
not beginning with @samp{@@} are ignored, so may be used as comments.
1732
Comments may also be included on the @samp{@@x}, @samp{@@y}, and/or
1733
@samp{@@z} lines.
1734
1735
@node Starting, AT commands, Files, Top
1736
@comment node-name, next, previous, up
1737
1738
@chapter RUNNING @FWEB{}
1739
1740
@FWEB{} has a @sc{unix}-style command-line syntax. There are many
1741
command-line options, but few or none of these are necessary for
1742
standard appplications. Proceed in blissful ignorance until you need to
1743
do something tricky, then scan the list of options to see if they can
1744
help.
1745
1746
Commonly-used command-line options can be placed into the initialization
1747
file @file{.fweb} (@pxref{Options}) that resides in one's home directory.
1748
1749
A @dfn{style file} (patterned after the utility @code{makeindex};
1750
@pxref{Style}) can be associated with each manuscript or collection of
1751
related manuscripts in order to customize their appearance. This file
1752
is read @emph{after} the command-line options are processed, except that
1753
the @samp{-p} option gets special treatment; see @ref{-p}.
1754
1755
@menu
1756
* Syntax:: Command-line syntax.
1757
* Options:: Command-line options.
1758
@end menu
1759
1760
@node Syntax, Options, Starting, Starting
1761
@comment node-name, next, previous, up
1762
1763
@section Command-line syntax
1764
1765
The command-line syntax is
1766
@cindex Syntax, command-line
1767
1768
@example
1769
@{ftangle | fweave@} [-option...] webfile[.web] [changefile[.ch]]
1770
@end example
1771
@noindent
1772
A file name is anything that doesn't begin with a @samp{-}, except that
1773
a lone hyphen stands for the special file name
1774
@file{stdin}, which means `read from the standard input.' (This should
1775
not be used except for very special effects.)
1776
@findex -
1777
1778
Command-line options begin with a @samp{-}. File names and options can
1779
be intermixed, or the
1780
options may appear after the file names. The first file name
1781
encountered is the web source file; the second, if it exists, is
1782
the change file (@pxref{Change files}). [When no change file is
1783
specified, @FWEB{} attempts
1784
to read from the null file (@file{/dev/null} on @sc{unix} systems). This
1785
name should be specified when @FWEB{} is installed
1786
(@pxref{Customization}), or can be set in the style file @file{fweb.sty}.
1787
@xref{null_file}.]
1788
1789
The web file is shown as required since one is normally processing a
1790
source. However, some of the information options (@pxref{Info options})
1791
will work without specifying any file name. For example, one can obtain a
1792
list of all of the style-file parameters and their default values by saying
1793
@w{@samp{ftangle -Z}}.
1794
1795
@node Options, , Syntax, Starting
1796
@comment node-name, next, previous, up
1797
1798
@section Command-line options
1799
1800
Command-line options may be put, one per line, into the initialization file
1801
@file{.fweb} (which is always in the user's home directory).
1802
In that file, options beginning with a hyphen are processed @emph{before}
1803
the command-line options (so command-line options can override the
1804
defaults). To force an option to be processed @emph{after} the
1805
command-line options, preface it with an ampersand
1806
rather than a hyphen; this is rarely necessary.
1807
1808
To make sense of the plethora of options, it helps to know that options
1809
beginning with @samp{n} are related to @sc{Fortran}; those beginning
1810
with @samp{r} are related to @sc{Ratfor}. Some flags that can be set
1811
separately for those two languages also have a global option that sets the
1812
flags for both languages simultaneously; cf. @samp{-n/}, @samp{-r/}, and
1813
@samp{-/}.
1814
1815
Some options take arguments. For example, an @FWEB{} macro can be
1816
defined from the command line by saying something like @samp{-mIBMPC=1}.
1817
Unlike many @sc{unix} utilities, @emph{no spaces are allowed between any
1818
option and its argument.} For example, if one says @samp{-m IBMPC},
1819
@FWEB{} will think that @file{IBMPC} is a file name.
1820
1821
@menu
1822
* Negating options:: How to invert the meaning of an option.
1823
* -1:: Brief debugging mode.
1824
* -2:: Verbose debugging mode.
1825
* -@@: -AT. Display information about control codes.
1826
* -A: -A_. Turn on ASCII translations.
1827
* -B: -B_. Turn off audible beeps.
1828
* -b:: Number blocks.
1829
* -C: -C_. Set the color mode.
1830
* -c:: Set global language to C.
1831
* -c++: -cpp. Set global language to C++.
1832
* -D: -D_. Display information about @FWEB{}'s reserved words.
1833
* -d:: Convert unnumbered `do...enddo's to Fortran--77.
1834
* -E: -E_. Change the delimiter of a file-name extension.
1835
* -e:: Turn on automatic file-name completion.
1836
* -F: -F_. Compare output files with old versions.
1837
* -f:: Turn off module references for identifiers.
1838
* -H: -H_. Scan #include files to format typedef and/or class commands.
1839
* -h:: Where to get help.
1840
* -I: -I_. Append a directory to search list for include files.
1841
* -i:: Don't print contents of @@I include files.
1842
* -i!:: Don't even read @@I include files.
1843
* -j:: Inhibit multiple includes of the same file.
1844
* -k:: Don't recognize lower-case forms of Fortran I/O keywords.
1845
* -L: -L_. Select global language.
1846
* -l:: Echo the input line.
1847
* -M: -M_. Set output message level.
1848
* -m:: Define an @FWEB{} macro.
1849
* -m4:: Understand the m4 built-in commands.
1850
* -m;:: Append pseudo-semicolons to @FWEB{} macro definitions.
1851
* -n:: Set global language to Fortran--77.
1852
* -n9:: Set global language to Fortran--90.
1853
* -n@@;: -nAT;. For Fortran, supply pseudo-semicolons automatically (default).
1854
* -n;:: For Fortran, supply actual semicolons automatically.
1855
* -ncolon:: In Fortran, place statement labels on separate lines.
1856
* -nb:: In Fortran, number the ifs and dos.
1857
* -nC:: In Fortran, ignore single-line comments ('C', 'c', or '*').
1858
* -np:: Print semicolons in woven Fortran output.
1859
* -n\:: In Fortran--90, free-form syntax continued with '\\'.
1860
* -n&:: In Fortran--90, free-form syntax continued with '&'.
1861
* -n/:: In Fortran, recognize '//' as the start of a short comment.
1862
* -n!:: In Fortran, make '!' denote the start of a short comment.
1863
* -n):: In Fortran, reverse array indices.
1864
* -o:: Turn off @FWEAVE{}'s mechanisms for overloading operators.
1865
* -q:: Don't translate Ratfor.
1866
* -P: -P_. Select TeX processor.
1867
* -p:: Set style parameter.
1868
* -r:: Set the global language to Ratfor--77.
1869
* -r9:: Set the global language to Ratfor--90.
1870
* -rb:: In Ratfor, number the ifs and dos.
1871
* -rg:: Set |goto| parameters.
1872
* -rk:: Suppress comments about Ratfor statement translation.
1873
* -rK: -rK_. Write out comments about Ratfor statement translation.
1874
* -r@@;: -rAT;. Turn on Ratfor's auto-semi mode, using pseudo-semicolons.
1875
* -r;:: Turn on Ratfor's auto-semi mode, using actual semicolons.
1876
* -r/:: In Ratfor, recognize '//' as the start of a short comment.
1877
* -r!:: In Ratfor, make '!' denote the start of a short comment.
1878
* -r):: In Ratfor, reverse array indices.
1879
* -s:: Print statistics about memory usage.
1880
* -T: -T_. Flag-setting commands for @FTANGLE{}.
1881
* -t:: Truncate identifiers.
1882
* -U: -U_. Convert reserved output tokens to lower case.
1883
* -u:: Undefined a predefined or command-line macro.
1884
* -V: -V_. Print version number.
1885
* -v:: Make all comments verbatim.
1886
* -W: -W_. Flag-setting commands for @FWEAVE{}.
1887
* -w:: Change name of @FWEB{}'s macro package.
1888
* -X: -X_. Print selected cross-reference information.
1889
* -x:: Reduce or eliminate cross-reference information.
1890
* -y:: Allocate dynamic memory.
1891
* -Z: -Z_. Display default values of style-file parameters.
1892
* -z:: Change name of style file.
1893
* -.:: Don't recognize dot constants.
1894
* -\:: Explicitly escape continued strings.
1895
* -(: -lp. Continue parenthesized strings with backslashes.
1896
* -colon:: Set starting automatic statement number
1897
* ->:: Redirect tangled output.
1898
* -=:: Redirect tangled output.
1899
* -#:: Don't print comments about line numbers and module names
1900
in tangled output.
1901
* -+: -plus. Don't interpret compound assignment operators.
1902
* -/:: Recognize '//' as the start of a short comment.
1903
* -!:: Make '!' denoted the start of a short comment.
1904
1905
* Info options:: Information options.
1906
@end menu
1907
1908
@node Negating options,-1,Options,Options
1909
@comment node-name, next, previous, up
1910
1911
@subsection Negating options
1912
1913
@cindex Options, negating
1914
To negate a command-line option, use an extra hyphen. For example,
1915
@samp{--v} means `Don't make all comments verbatim.' This kind of
1916
construction isn't used very often, but it is useful if an option such
1917
as @samp{-v} is turned on in the @file{.fweb} initialization file and
1918
one wishes to turn it off for just one run.
1919
1920
@node -1,-2,Negating options,Options
1921
@comment node-name, next, previous, up
1922
1923
@subsection @samp{-1}: Turn on brief debugging mode (@FWEAVE{})
1924
1925
@findex -1
1926
@cindex Debugging
1927
This option tells @FWEAVE{} to display irreducible scrap sequences.
1928
@cindex Scrap, irreducible
1929
1930
A @dfn{scrap} is a part of speech. The expression @samp{x + y} consists of
1931
three scraps: @samp{x} (an expression), @samp{+} (a binary operator),
1932
and @samp{y} (an expression). @FWEAVE{} contains @dfn{production rules}
1933
such as ``replace the combination @samp{expr binop expr} with
1934
@samp{expr}.'' If all goes well, the result of @FWEAVE{}'s reduction
1935
process is ultimately just one scrap, such as @samp{function}. If
1936
@FWEAVE{} is left with more than one scrap at the end of a section,
1937
this is called an @dfn{irreducible scrap sequence}; @samp{-1} displays
1938
them.
1939
1940
Irreducible scrap sequences can arise either because the programmer made
1941
a mistake or because @FWEAVE{} has not been taught the proper grammar.
1942
1943
@cindex Output, changing appearance of
1944
While @FWEAVE{} is reducing the scraps, it appends @TeX{} macros that
1945
ultimately produce the pretty-printed output. Frequently people ask how
1946
to change the appearance of that output. Fundamentally, this is not
1947
possible at present; the grammar rules and the associated @TeX{} are
1948
hard-coded. A completely general, user-customizable scheme is very
1949
complex and daunting; it has not been attempted.
1950
1951
This brief debugging mode can be turned on more locally by means of the
1952
@samp{@@1} command. @xref{AT1}.
1953
1954
@node -2,-AT,-1,Options
1955
@comment node-name, next, previous, up
1956
1957
@subsection @samp{-2}: Turn on verbose debugging mode (@FWEAVE{})
1958
1959
@findex -2
1960
@cindex Debugging
1961
This option tells @FWEAVE{} to display detailed reductions of the
1962
scraps as it does the pretty-printing. (For a discussion of scraps, see
1963
@ref{-1}.) Sometimes @FWEAVE{} fails spectacularly at
1964
pretty-printing a section, either because of a syntax error on the
1965
part of the user or because of a bug in @FWEAVE{}'s logic. This
1966
option helps one (usually the system developer!) to figure out why.
1967
1968
This feature can be turned on more locally by means of the @samp{@@2}
1969
command. @xref{AT2}.
1970
1971
@node -AT, -A_, -2, Options
1972
@comment node-name, next, previous, up
1973
1974
@subsection @samp{-@@}: Display the control-code mappings
1975
1976
@findex -@@
1977
@cindex Options, information
1978
This option supplies information about the @samp{@@} control codes
1979
(@pxref{AT commands}). It shows the associated style-file parameters
1980
that can be used to remap the codes (but @emph{don't do that!}), and it
1981
displays the precedence. (Some codes such as @samp{@@@@} may be used
1982
anywhere; others such as @samp{@@*} begin
1983
a new section or part of section. Codes that begin the definition part
1984
are labelled by @samp{[D]}; codes that begin the code part are labelled
1985
by @samp{[C]}; codes that begin a new section are labelled by
1986
@samp{[S]}.)
1987
1988
The option produces two columns of output: the first is sorted
1989
numerically, the second alphabetically. The notation @samp{USED_BY_OTHER}
1990
means that this command is ignored by whatever processor (@FTANGLE{}
1991
or @FWEAVE{}) is currently being run, but may be used by the other
1992
processor. (For technical reasons, a very few commands such as
1993
@samp{@@i} do not show up in this output at present.)
1994
1995
If one says just @samp{-@@}, information about all control codes is
1996
produced. Selected control codes may be queried by listing them after
1997
the @samp{-@@}. For example, to learn about the commands @samp{@@~} and
1998
@samp{@@a}, say @samp{-@@~a}. Remember to quote certain characters on
1999
@sc{unix} systems---e.g., @samp{-@@'*?'}. If a command is used by
2000
neither processor, its description will be replaced by a question mark.
2001
2002
@node -A_,-B_,-AT,Options
2003
@comment node-name, next, previous, up
2004
2005
@subsection @samp{-A}: Turn on ASCII translations
2006
2007
@findex -A
2008
This option is used primarily for debugging. @FWEB{} works
2009
internally with the ASCII character set. If @FWEB{} is run on a
2010
non-ASCII machine (notably IBM mainframes), translations to and from the
2011
internal ASCII are done automatically; on an ASCII machine, these
2012
translations are unnecessary and are not performed unless the @samp{-A}
2013
option is used.
2014
2015
@node -B_, -b, -A_, Options
2016
@comment node-name, next, previous, up
2017
2018
@subsection @samp{-B}: Turn off audible beeps
2019
2020
@findex -B
2021
@cindex Marriage
2022
@FWEB{} sometimes beeps the terminal when it encounters certain errors. The
2023
@samp{-B} option turns off the beeps, replacing them by a printed
2024
exclamation point.
2025
2026
(This option is sometimes called the ``marriage-saver,'' after the
2027
situation that prompted a user's request for this feature.)
2028
2029
@node -b,-C_,-B_,Options
2030
@comment node-name, next, previous, up
2031
2032
@subsection @samp{-b}: Number blocks (@FWEAVE{})
2033
2034
@findex -b
2035
@cindex Numbering blocks
2036
@cindex Blocks, numbering
2037
Number @b{do} and @b{if} blocks in woven @sc{Fortran} and @sc{Ratfor} output.
2038
This feature is particularly useful in @sc{Fortran}-77 to help correlate
2039
the beginnings and ends of long blocks (but note that appropriate use of
2040
literate programming techniques can keep all of one's blocks short!).
2041
Output something like the following is produced, where the comments are
2042
inserted automatically by the @samp{-b} option:
2043
2044
@example
2045
do i=1,10 // Block 1
2046
do j=1,10 // Block 2
2047
if(i==j) then // Block 3
2048
call sub1(i)
2049
else // Block 3
2050
call sub2(i,j)
2051
endif // Block 3
2052
end do // Block 2
2053
end do // Block 1
2054
@end example
2055
@noindent
2056
2057
The precise form of the block comment that is emitted can be changed by
2058
redefining the macro @code{\Wblock} in @file{fwebmac.sty}.
2059
@findex \Wblock
2060
2061
@node -C_, -c, -b, Options
2062
@comment node-name, next, previous, up
2063
2064
@findex -C
2065
@subsection @samp{-C}: Set the color mode
2066
2067
@cindex Color, setting
2068
The option @samp{-C@var{n}} sets the color mode to @var{n}, where the
2069
color modes are, briefly,
2070
2071
@quotation
2072
@table @kbd
2073
@item 0
2074
No color
2075
@item 1
2076
ANSI color
2077
@item 2
2078
Bilevel
2079
@item 3
2080
Trilevel
2081
@item 4
2082
User-defined
2083
@end table
2084
@end quotation
2085
@noindent
2086
These modes, and color output in general, are described more thoroughly
2087
in @ref{Color}.
2088
2089
For obscure technical reasons, this command is processed differently
2090
than all other command-line options. In the present incomplete
2091
implementation, @emph{the color mode must be set on the command line},
2092
not in @file{.fweb}! To work around this annoyance, @sc{unix} users
2093
could alias commands such as @w{@samp{ftangle -C1}}.
2094
2095
@node -c, -cpp, -C_, Options
2096
@comment node-name, next, previous, up
2097
2098
@findex -c
2099
@subsection @samp{-c}: Set global language to C
2100
2101
@cindex Language, setting
2102
Usually the global language (@ref{Languages}) is set to C by means of
2103
the command @samp{@@c} in limbo, rather than using @samp{-c} on the
2104
command line. However, one may need to use the command-line option
2105
@samp{-c} if a subsequent command-line option is language-dependent.
2106
See, for example, the discussion of the option @samp{-D} in @ref{-D_}.
2107
2108
@node -cpp, -D_, -c, Options
2109
@comment node-name, next, previous, up
2110
2111
@subsection @samp{-c++}: Set global language to C++
2112
2113
@findex -c++
2114
For more information, see the discussion of @samp{-c} in @ref{-c}.
2115
2116
@node -D_, -d, -cpp, Options
2117
@comment node-name, next, previous, up
2118
2119
@subsection @samp{-D}: Display reserved words
2120
2121
@findex -D
2122
@cindex Options, information
2123
@cindex Reserved words
2124
@cindex Words, reserved
2125
@cindex Intrinsic functions
2126
@cindex Functions, intrinsic
2127
@cindex Keywords, I/O
2128
@cindex I/O keywords
2129
This information option displays the list of reserved words for the
2130
language currently in force. (For the purposes of this option,
2131
`reserved words' include ``true'' reserved words such as @samp{int};
2132
they also include the names of intrinsic functions such as @samp{sin}
2133
and, for @sc{Fortran} and @sc{Ratfor}, I/O keywords such as
2134
@samp{IOSTAT}.) Thus, to see the reserved words for @sc{Ratfor}--90,
2135
say
2136
2137
@example
2138
ftangle -Lr9 -D
2139
@end example
2140
2141
@noindent
2142
(For this option one must set the language on the command line, because
2143
the @samp{-D} option is processed before the limbo section of the web file is
2144
read.)
2145
2146
If one says @samp{-Dabc}, one will get just the reserved words that begin with
2147
"abc".
2148
2149
If one says @samp{-D*}, one will get all reserved words for all languages.
2150
2151
The @samp{-D} may be followed by a list of one or more optional letters
2152
enclosed in square brackets. (For @sc{unix} systems, don't forget to
2153
quote the brackets, as they mean something special to the shell.) The
2154
letters represent which kind of reserved word to display; they may be
2155
@samp{i} (`intrinsic'), @samp{k} (`keyword'), or @samp{r} (`reserved').
2156
Thus, to see a list of the @sc{Fortran} keywords, say @samp{-D[k]}. To
2157
see a list of the intrinsic functions for C++ that begin with @samp{s},
2158
say @samp{-Lc++ -D[i]s}.
2159
2160
@node -d,-E_,-D_,Options
2161
@comment node-name, next, previous, up
2162
2163
@subsection @samp{-d}: Convert do...enddo
2164
2165
@findex -d
2166
@emph{(This option is obsolete.)}
2167
2168
@node -E_,-e,-d,Options
2169
@comment node-name, next, previous, up
2170
2171
@subsection @samp{-E}: Change the delimiter of a file-name extension
2172
2173
@findex -E
2174
The standard delimiter for file-name extensions is a period, as in
2175
@file{test.web}. To change this character to a comma, for example, say
2176
@samp{-E,}. This feature is required by at least one perverse system.
2177
2178
@node -e,-F_,-E_,Options
2179
@comment node-name, next, previous, up
2180
2181
@subsection @samp{-e}: Turn on automatic file-name completion
2182
2183
@findex -e
2184
When the @samp{-e} option is in effect, @FWEB{} attempts to be helpful in
2185
figuring out what file name one intends. For any input file name that
2186
has no extension (no embedded period), @FWEB{} completes the name by adding
2187
the extension contained in the style-file parameter listed in the
2188
following table:
2189
2190
@example
2191
@r{Type of file} @r{Style-file entry} @r{Default}
2192
WEB file @code{ext.web} @code{web}
2193
Change file @code{ext.ch} @code{ch}
2194
Include file @code{ext.hweb} @code{hweb}
2195
Change file
2196
for include file @code{ext.hch} @code{hch}
2197
@end example
2198
2199
@noindent
2200
More than one extension may be specified, as a space-delimited
2201
list---e.g., @samp{ext.web = "web wb"}; the first one that matches is used.
2202
2203
@node -F_,-f,-e,Options
2204
@comment node-name, next, previous, up
2205
2206
@subsection @samp{-F}: Compare output files with old versions (@FTANGLE{})
2207
2208
@findex -F
2209
When the @samp{-F} option is in effect, @FTANGLE{} writes its output
2210
to a temporary file (or files) instead of to its ultimate
2211
destination such as @file{test.c} and/or @file{test.f}. After all
2212
output is written, the temporary files are compared with the old version
2213
of the files, if they exist. If the files are identical, the
2214
appropriate temporary file is deleted; otherwise, the temporary file is
2215
renamed, effectively overwriting the old version. This feature avoids
2216
updating the time stamp on the file unnecessarily, so a @code{make} file won't
2217
recompile the output unless it really has to.
2218
2219
Note that with this option in effect, if one uses the @sc{unix} utility
2220
@code{touch} to force processing of a group of files, but the @code{web}
2221
sources are never changed, the @code{make} file will continue to tangle
2222
the sources no matter how many times it is run, since @FTANGLE{} will
2223
never update the time stamp on the files. This is harmless, but
2224
annoying. To get things back in sync, do a run without the @samp{-F}.
2225
2226
The location of the temporary file as well as details of the renaming
2227
procedure are determined by the automatic configuration script
2228
@code{./configure} during
2229
installation of the processors. The script first looks for
2230
the (non-ANSI) function @code{tempnam}.
2231
@findex tempnam
2232
If it finds it, it uses it to place
2233
the temporary file in the directory that @FWEB{} would normally use for
2234
output in the absence of the @samp{-F} option. (That is usually the current
2235
directory.) If @code{tempnam} is not available, the ANSI routine
2236
@code{tmpnam} is used.
2237
@findex tmpnam
2238
That places the temporary file in a directory
2239
determined by the system.
2240
2241
To implement the renaming, the @code{rename} function is used. That may fail
2242
if @code{tmpnam} placed the temporary file on a different device. If so, an
2243
attempt is made to force the rename by using the @code{system} routine to
2244
issue a @code{mv} command. Terminal output indicates the progress of the
2245
renaming. An asterisk following an output file name indicates that
2246
@code{rename} did not succeed, but the @code{mv} command did.
2247
2248
Some of the above-mentioned file names and system commands are
2249
system-dependent; see @ref{Customization}.
2250
2251
@node -f,-H_,-F_,Options
2252
@comment node-name, next, previous, up
2253
2254
@subsection @samp{-f}: Turn off module references for identifiers (@FWEAVE{})
2255
2256
@findex -f
2257
In an attempt to be helpful, @FWEAVE{} appends subscripts to many
2258
identifiers indicating in which section they are first defined
2259
(@pxref{Subscript params}). Sometimes these result in output that is
2260
too cluttered and confusing. The @samp{-f} option turns off the
2261
subscripting operations.
2262
2263
@node -H_,-h,-f,Options
2264
@comment node-name, next, previous, up
2265
2266
@subsection @samp{-H}: Scan C/C++ include files (@FWEAVE{})
2267
2268
@findex -H
2269
@findex -Hx
2270
@findex -HX
2271
@findex -Hr
2272
@cindex Include files, scanning
2273
For C or C++, the @samp{-H} option tells @FWEAVE{} to do a phase-1 scan
2274
of @code{#include} files for @samp{typedef} and/or @samp{class}
2275
declarations. This removes the necessity of including many redundant
2276
@samp{@@f} format statements (@pxref{ATf}), which would otherwise be
2277
necessary in order that the code be pretty-printed correctly. For
2278
example, if one uses the @samp{-H} option with the code
2279
2280
@example
2281
@@c++
2282
@@
2283
#include <Complex.h>
2284
Complex z;
2285
@end example
2286
@noindent
2287
the identifier @b{Complex} will be properly formatted as a reserved
2288
word (in boldface), as though one had said @samp{@@f Complex int}.
2289
2290
In addition to the basic @samp{-H}, there are several more detailed
2291
options:
2292
2293
@quotation
2294
@table @code
2295
@item -Hx
2296
Make index entries only for double-quoted include files.
2297
@item -HX
2298
Make index entries for all include files.
2299
@item -Hr
2300
Retain temporary files generated by the preprocessor.
2301
@end table
2302
@end quotation
2303
2304
By default, index entries are not made for variables that are read
2305
during such scans. If one says @samp{-Hx}, index entries will be made
2306
only for include files whose names are enclosed in double quotes rather
2307
than angle brackets, such as @samp{#include "myheader.h"}
2308
(usually these are defined by the user and reside in the local
2309
directory). If one says @samp{-HX}, index entries will be made for all
2310
include files. This can generate many entries, since system header
2311
files may be complicated and may include other files as well.
2312
2313
This command is implemented as follows. When @FWEAVE{} reads an
2314
@code{#include} statement, it issues a @code{system} command to run the
2315
C preprocessor on the included file. Output from the preprocessor is
2316
written to a temporary file, which @FWEAVE{} scans.
2317
2318
By default, the C preprocessor will look in certain default paths for
2319
the included files. To add to those defaults, use one or more @samp{-I}
2320
options @emph{after} the @samp{-H}. These colon-delimited lists are
2321
concatenated to the contents of the environment variable
2322
@code{FWEB_HDR_INCLUDES}, if that is defined. The entire list is then
2323
passed as multiple @samp{-I} options to the preprocessor.
2324
2325
This command, new with version 1.53, is @emph{highly experimental} and
2326
incomplete. The installation script attempts to determine what command
2327
to use to run the preprocessor, but that is not guaranteed to work in
2328
general. @samp{-H} has been tested only with @code{gcc}.
2329
2330
To send arguments to the C preprocessor, see @ref{-WH_}.
2331
2332
The @samp{-H} mechanism uses temporary files to do its work. By
2333
default, those are deleted after use. However, for debugging purposes,
2334
one can force those to be retained by saying @samp{-Hr}. That option
2335
also has the side effect of displaying the actual command line that was
2336
sent to the preprocessor.
2337
2338
@node -h,-I_,-H_,Options
2339
@comment node-name, next, previous, up
2340
2341
@subsection @samp{-h}: Get help
2342
2343
@findex -h
2344
If just @samp{-h} is typed, a message is printed saying where further
2345
help is available. It refers one to the various information options
2346
(@pxref{Info options}) and the on-line documentation
2347
(@pxref{Support}). If the stand-alone @code{info} program (the GNU
2348
hypertext browser) is installed, one can enter
2349
@samp{info FWEB} at this time by typing @samp{?} or a space-separated
2350
list of @FWEB{} menu items such as @samp{Macros FWEB built-in $PI}.
2351
In fact, since @samp{$PI} appears in the detailed node listing, one can
2352
simply type @samp{$PI}. More generally, one can type anything that
2353
@code{info} accepts on its command line (the option @samp{-f FWEB} is
2354
implicit).
2355
2356
One can bypass the printed message and directly enter @code{info} by
2357
specifying the @code{info} arguments as arguments to @samp{-h}. For
2358
example, on a @sc{unix} system, one could type @samp{-h'\$PI'}. Here
2359
the dollar sign must be escaped because it has special significance to
2360
the shell, and the quotes are necessary in order to preserve that escape
2361
character as the argument is supplied to @code{info}. To get to the
2362
top-level @FWEB{} info directory, type
2363
@samp{-h.} or @samp{-h'?'}.
2364
2365
@node -I_,-i,-h,Options
2366
@comment node-name, next, previous, up
2367
2368
@subsection @samp{-I}: Append to search list for include files
2369
2370
@findex -I
2371
@cindex Include files, finding
2372
The fundamental search list for @dfn{include files} (read in via @samp{@@i} or
2373
@samp{@@I}) is defined by the environment variable @code{FWEB_INCLUDES},
2374
which is a colon-delimited list such as
2375
2376
@example
2377
setenv FWEB_INCLUDES .:/usr/fweb:/other/stuff
2378
@end example
2379
2380
@noindent
2381
The @samp{-I} option appends to this list.
2382
2383
For information about include files, see @ref{ATi}.
2384
2385
@node -i,-i!,-I_,Options
2386
@comment node-name, next, previous, up
2387
2388
@subsection @samp{-i}: Don't print @samp{@@I} include files (@FWEAVE{})
2389
2390
@findex -i
2391
@findex -ix
2392
@cindex Include files, skipping
2393
@cindex Include files, indexing
2394
If a web file is included via @samp{@@I} (@pxref{ATI_}),
2395
for example
2396
2397
@example
2398
@@I formats.hweb
2399
@end example
2400
2401
@noindent
2402
then the @samp{-i} option means to read and process the web file, but don't
2403
print its contents. This option is often used for large files of macro
2404
definitions, formats, or @b{typedef} statements that must be included at the
2405
beginning of even very short web files; it clutters things up to print
2406
such header files all of the time. (C and C++ programmers will find that the
2407
@samp{-H} option substantially reduces the need to include such header
2408
files; see @ref{-H_}.)
2409
2410
Note that files included via @samp{@@i} (lower case) do not respond to
2411
@samp{-i} or @samp{-i!}.
2412
2413
By default, identifiers that are referenced in non-printed include files
2414
are not cross-referenced or indexed in any way. To force them to be
2415
cross-referenced, say @samp{-ix} instead of @samp{-i}. In the present
2416
implementation, the cross-reference information for such non-printed
2417
files is presented in the form
2418
@samp{#@i{n}}, where @i{n} is the integer section number. (The La@TeX{}
2419
section label is undefined for sections in non-printed files.)
2420
2421
The option @samp{-i!} means skip the include files completely. This is
2422
usually not very useful.
2423
2424
@node -i!,-j,-i,Options
2425
@comment node-name, next, previous, up
2426
2427
@subsection @samp{-i!}: Don't read @samp{@@I} include files
2428
2429
If a web file is included via @samp{@@I}, for example
2430
2431
@example
2432
@@I formats.hweb
2433
@end example
2434
2435
@noindent
2436
then the @samp{-i!} option means to ignore such files completely. This option
2437
is seldom useful; the @samp{-i} option (@pxref{-i}) is more often used.
2438
2439
@node -j,-k,-i!,Options
2440
@comment node-name, next, previous, up
2441
2442
@subsection @samp{-j}: Inhibit multiple includes
2443
2444
@findex -j
2445
@cindex Include files, inhibiting
2446
File inclusion via @FWEB{}'s @samp{@@i} command suffers from a design
2447
deficiency: they cannot be inhibited by means of @FWEB{}'s
2448
preprocessor commands. (The reason is that @samp{@@i} is processed very
2449
early in the input stage, before tokenization. This design decision was
2450
inherited from @sc{Cweb}, and is very difficult to change.) A
2451
particularly annoying situation arises when the same file is included
2452
multiple times; various array space may be eaten up unnecessarily. The
2453
@samp{-j} option inhibits such multiple includes.
2454
2455
@node -k,-L_,-j,Options
2456
@comment node-name, next, previous, up
2457
2458
@subsection @samp{-k}: Don't recognize lower-case forms of keywords
2459
2460
@findex -k
2461
By definition, in @sc{Fortran} and @sc{Ratfor}, a keyword is one of the
2462
parameters such as @code{IOSTAT} used in the parameter list of an I/O
2463
statement. For example,
2464
2465
@example
2466
open(21, FILE=file_name, STATUS='old', IOSTAT=io_flag)
2467
@end example
2468
@noindent
2469
Such keywords are typeset in @code{typewriter type} to better highlight them.
2470
In @sc{Fortran}, these keywords are case-insensitive. However,
2471
note that certain of the lower-case forms---in particular, @samp{end},
2472
@samp{read}, and @samp{write}---have other special meanings, and one can
2473
in principle use any of these keywords as ordinary variables in other parts of
2474
the code; however, @FWEB{} identifiers can have just one meaning
2475
throughout the code. By default, the lower-case forms are also
2476
recognized as keywords (except for the three special identifiers just
2477
mentioned), so one shouldn't use those as regular variables. To cause
2478
only the upper-case forms to be recognized, use the @samp{-k} option.
2479
2480
@node -L_,-l,-k,Options
2481
@comment node-name, next, previous, up
2482
2483
@subsection @samp{-L}: Select global language
2484
2485
@findex -L
2486
To select a global language from the command line, say @samp{-L@i{l}},
2487
where @i{l} is one of @code{@r{@{}c,c++,n,n9,r,r9,v,x@r{@}}}. @xref{Languages}.
2488
2489
Usually, the global language is set via an @samp{@@} command in limbo,
2490
not on the command line. However, one may need to use a command-line
2491
option such as @samp{-L_} if a subsequent command-line option is
2492
language-dependent. See, for example, the discussion of the option
2493
@samp{-D} in @ref{-D_}.
2494
2495
@node -l,-M_,-L_,Options
2496
@comment node-name, next, previous, up
2497
2498
@subsection @samp{-l}: Echo input line
2499
2500
@findex -l
2501
The option @samp{-l@i{[mmm[:nnn]]}} echoes the input lines constructed
2502
by the input
2503
driver between lines @i{mmm} and @i{nnn}. Missing @i{nnn} means echo to
2504
the end of file. Missing @i{mmm} means echo from the beginning.
2505
2506
This option is useful as a debugging tool (usually by the system
2507
developer). It is often used to verify that the input driver is
2508
inserting semicolons correctly. For @sc{Fortran}--77, it is also useful to
2509
verify that comments are being processed correctly.
2510
2511
@node -M_, -m, -l, Options
2512
@comment node-name, next, previous, up
2513
2514
@subsection @samp{-M}: Set output message level
2515
2516
@cindex Message level
2517
@cindex Level, message
2518
@findex -M
2519
By default, @FWEB{} is relatively verbose; as it proceeds, it prints
2520
messages about what files it is reading and writing, numbers of the
2521
starred sections, line numbers, etc. However, different levels of
2522
verbosity can be set by the command @samp{-M@i{level}}, where the level
2523
may be 0 (least verbose) through 4 (most verbose; the default), as
2524
described in the following table:
2525
2526
@quotation
2527
2528
@table @kbd
2529
@item 0
2530
Like level 1, but the start-up banner is not printed. If @FWEB{} runs
2531
to completion with no errors, nothing at all will be printed.
2532
2533
@item 1
2534
Print only error messages.
2535
2536
@item 2
2537
Print error and warning messages.
2538
2539
@item 3
2540
Print errors, warnings, and short information messages (excluding
2541
starred section numbers and line numbers).
2542
2543
@item 4
2544
Print everything.
2545
2546
@end table
2547
@end quotation
2548
2549
The start-up banner, which includes the version number, is printed for
2550
all message levels except 0. For level 0, one can use the @samp{-V}
2551
option to request the start-up banner. @xref{-V_}.
2552
2553
This option is very recent, and may not be fully debugged for obscure
2554
combinations of command-line options. Please report any annoyances.
2555
2556
Another way of discriminating message types is via color output.
2557
@xref{Color}.
2558
2559
@node -m,-m4,-M_,Options
2560
@comment node-name, next, previous, up
2561
2562
@subsection @samp{-m}: Define @FWEB{} macro (@FTANGLE{})
2563
2564
@findex -m
2565
The command-line construction
2566
2567
@example
2568
-mA(x)=x
2569
@end example
2570
@noindent
2571
defines the @FWEB{} macro @code{A} as though the definition
2572
2573
@example
2574
@@m A(x) x
2575
@end example
2576
2577
@noindent
2578
had appeared in the first definition part of the web file.
2579
2580
One can also say @samp{-m'A(x) x'}, where the quotes are removed by the
2581
shell. That is, an @samp{=} appearing @emph{immediately} after the
2582
macro name (or argument list, if there is one) plays the role of the
2583
space in the conventional definition. Thus, carefully distinguish the forms
2584
2585
@example
2586
-m'A(x)=x' // @r{A(x) expands to @samp{x}}
2587
-m'A(x) =x' // @r{A(x) expands to @samp{=x}}
2588
-m'A(x)==x' // @r{Precisely equivalent to the previous example.}
2589
@end example
2590
2591
The equals sign is permitted only with command-line macro definitions,
2592
not with @samp{@@m} commands (@pxref{ATm}) in the definition parts of
2593
the web file.
2594
2595
@node -m4,-m;,-m,Options
2596
@comment node-name, next, previous, up
2597
2598
@subsection @samp{-m4}: Understand @code{m4} built-in commands
2599
2600
@findex -m4
2601
@cindex Preprocessor, m4
2602
This tells @FWEAVE{} to properly format the reserved words of the @code{m4}
2603
preprocessor. The use of that preprocessor is @emph{not recommended} in
2604
conjunction with @FWEB{}; use @FWEB{}'s built-in C-like preprocessor
2605
instead.
2606
2607
@node -m;,-n,-m4,Options
2608
@comment node-name, next, previous, up
2609
2610
@subsection @samp{-m;}: Append pseudo-semicolons
2611
2612
@findex -m;
2613
When @samp{-m;} is in effect, the construction @samp{@@;} is appended
2614
automatically to all @FWEB{} macro definitions.
2615
2616
@emph{This option is not recommended.} Please insert the @samp{@@;} by
2617
hand when necessary, as in
2618
2619
@example
2620
@@m SET(x,y) x=1; y=2@@;
2621
@@m TEST(x) if(x) y; else z@@;
2622
@end example
2623
2624
@node -n,-n9,-m;,Options
2625
@comment node-name, next, previous, up
2626
2627
@subsection @samp{-n}: Set global language to @sc{Fortran}--77
2628
2629
@findex -n
2630
This is @FWEB{}'s default, so it generally does not need to be used
2631
explicitly. (See also the discussion of @ref{-L_}.) However, variants
2632
of this option, as described below, may be useful.
2633
2634
See also @ref{Languages} and @ref{Fortran}.
2635
2636
@node -n9,-nAT;,-n,Options
2637
@comment node-name, next, previous, up
2638
2639
@subsection @samp{-n9}: Set global language to @sc{Fortran}--90
2640
2641
@findex -n9
2642
@xref{Languages} and @ref{Fortran}; see also the discussion of @samp{-L}
2643
in @ref{-L_}.
2644
2645
@node -nAT;, -n;, -n9, Options
2646
@comment node-name, next, previous, up
2647
2648
@subsection @samp{-n@@;}: Supply automatic pseudo-semicolons [@sc{Fortran}]
2649
2650
@findex -n@@;
2651
@cindex Pseudo-semicolons, automatic
2652
@cindex Automatic pseudo-semicolons
2653
(Don't forget that a semicolon has special meaning to @sc{unix} shells,
2654
so you'll probably have to quote this command: @samp{-n'@@;'}.)
2655
2656
This is the default mode of operation for free-form @sc{Fortran}-90; the
2657
input driver automatically appends a pseudo-semicolon (invisible) to
2658
each logical line of source code. Since it is the default, one doesn't
2659
have to use it unless one wishes to negate it (@pxref{Negating
2660
options}). In that case, it is best to place the @samp{--n@@;} command
2661
in the source file, as @samp{@@n9[--n@@;]}. If one places it on the
2662
command line, be sure to set the language first: @code{-n9 --n@@;}.
2663
2664
For free-format @sc{Fortran}-90, when @samp{-n@@;} is in effect (the
2665
default), @samp{-np} is also turned on. @xref{-np}.
2666
2667
For further discussion, see the companion command @ref{-n;}.
2668
2669
@node -n;,-ncolon,-nAT;,Options
2670
@comment node-name, next, previous, up
2671
2672
@subsection @samp{-n;}: Supply automatic semicolons [@sc{Fortran}]
2673
2674
@findex -n;
2675
@cindex Semicolons, automatic
2676
@cindex Automatic semicolons
2677
(Don't forget that a semicolon has special meaning to @sc{unix} shells,
2678
so you'll probably have to quote this command: @samp{-n';'}.)
2679
2680
This command functions the same as @samp{-n@@;} (@pxref{-nAT;}, except
2681
that actual
2682
(visible) semicolons rather than pseudo-semicolons are appended. This
2683
is the default mode of operation for @sc{Fortran}-77 (and for that
2684
language, it cannot be turned off by negation).
2685
2686
The distinction between @samp{-n@@;} and @samp{-n;} has to do with what
2687
is visible on output. In @sc{Fortran}-77, semicolons are not printed by
2688
default since that seemed to annoy many users. However, that causes
2689
trouble with @sc{Fortran}-90 code containing multiple statements per
2690
line, as in
2691
2692
@example
2693
a = b; c = d
2694
@end example
2695
@noindent
2696
If @samp{-np} is not used, then the semicolon in the above
2697
example is not printed, hindering legibility. Thus, the default mode of
2698
operation for free-format @sc{Fortran}-90 is @samp{-n@@;} and
2699
@samp{-np}. This turns the above example into @samp{a = b; c = d@@;}
2700
and displays it correctly.
2701
2702
When @samp{-n;} is used, semicolons will not be printed by default.
2703
To force them to be printed, use the @samp{-np} option (@pxref{-np}).
2704
2705
Do not insert semicolons by hand in @sc{Fortran}-77; they are always
2706
inserted automatically. If you have terminated @sc{Fortran}-90
2707
statements by hand, turn off auto-semis by @samp{-n;} (and use
2708
@samp{-np} at your discretion).
2709
2710
The following table summarizes the defaults for auto-semi insertion and
2711
semicolon printing in @sc{Fortran}, both fixed and free formats (`N/A'
2712
means `not applicable'):
2713
2714
@quotation
2715
@multitable {F90}{Fixed}{ `-nA; -np' }
2716
2717
@item @tab Fixed @tab Free
2718
@item F77 @tab @samp{-n;} @tab N/A
2719
@item F90 @tab @samp{-n;} @tab @samp{-n@@; -np}
2720
2721
@end multitable
2722
@end quotation
2723
2724
2725
@node -ncolon,-nb,-n;,Options
2726
@comment node-name, next, previous, up
2727
2728
@subsection @samp{-n:}: Put statement label on separate line [@sc{Fortran}]
2729
2730
@findex -n:
2731
By default, in @sc{Fortran} statement labels are placed on the same
2732
line, and backspaced from, the command that is being labeled, as in
2733
2734
@example
2735
EXIT: continue
2736
@end example
2737
@noindent
2738
This can look ugly if the label is very long. The command @samp{-n:}
2739
places the label on a separate line, as is done automatically for
2740
@sc{Ratfor}---e.g.,
2741
2742
@example
2743
EXIT:
2744
continue
2745
@end example
2746
2747
If neither of these options appeals to you, you could try redefining the
2748
macro @code{\Wlbl}, found with some discussion in @file{fwebmac.web}.
2749
That macro is emitted only when @samp{-n:} is @emph{not} used.
2750
@findex \Wlbl
2751
2752
@node -nb,-nC,-ncolon,Options
2753
@comment node-name, next, previous, up
2754
2755
@subsection @samp{-nb}: Number @b{if}s and @b{do}s [@sc{Fortran}] (@FWEAVE{})
2756
2757
@findex -nb
2758
@cindex Numbering blocks
2759
@cindex Blocks, numbering
2760
In the woven output, extra comments are added to help one correlate the
2761
block structure of the code. For more discussion, see @ref{-b}.
2762
2763
@node -nC, -np, -nb, Options
2764
@comment node-name, next, previous, up
2765
2766
@subsection @samp{-nC}: Ignore single-line comments [@sc{Fortran}]
2767
2768
@findex -nC
2769
@cindex Comments, ignore single-line Fortran
2770
Ignore, at the input-driver stage, comment lines beginning with
2771
@samp{C}, @samp{c}, or @samp{*}.
2772
2773
Interpretation: In the usual mode of operation, the @sc{Fortran}-77 input
2774
driver makes a heroic attempt to mix the original single-line column-1
2775
commenting style with the @FWEB{} style (@samp{/*...*/} and
2776
@samp{//}). It converts single-line comments to the @samp{/*...*/}
2777
style and passes them along to the innards of the processors.
2778
2779
Problems sometimes arise when converting an existing @sc{Fortran} code
2780
to @FWEB{}. Such codes may have very large blocks of code or
2781
documentation commented out with a @samp{C} in column 1. Special @TeX{}
2782
characters in those comments can cause problems for @FWEAVE{};
2783
sometimes @FTANGLE{} gets confused as well. The @samp{-nC} option
2784
short-circuits these problems by simply throwing all such lines away at
2785
the input driver stage.
2786
2787
This option is not a recommended long-term solution. Instead, consider
2788
the following:
2789
2790
@quotation
2791
@itemize @bullet
2792
2793
@item
2794
In @FWEB{}, blocks of code should be commented out with the
2795
preprocessor commands @code{@@#if 0...@@#endif}; see @ref{Temporary
2796
comments}.
2797
2798
@item
2799
Textual comments for documentation should be converted to the standard
2800
@FWEB{} commenting style.
2801
2802
@item
2803
If one has a block of code prefaced by an extremely long comment,
2804
replace that by a named module and put the comment into the @TeX{} part
2805
of that section.
2806
2807
@end itemize
2808
@end quotation
2809
2810
@node -np,-n\,-nC,Options
2811
@comment node-name, next, previous, up
2812
2813
@subsection @samp{-np}: Print semicolons [@sc{Fortran}] (@FWEAVE{})
2814
2815
@findex -np
2816
@cindex Semicolons, printing
2817
Although the @sc{Fortran} input driver automatically terminates logical
2818
lines with semicolons (@sc{Fortran}-77; see @ref{-n;}) or pseudo-semicolons
2819
(@sc{Fortran}-90; see @ref{-nAT;}) so that the innards of @FWEAVE{}
2820
can process them correctly, the semicolons are not printed by default.
2821
To make actual semicolons be printed, use the @samp{-np} option.
2822
2823
@samp{-np} is turned on automatically for free-format @sc{Fortran}-90 when
2824
@samp{-n@@;} is in effect (the default). For more discussion, see
2825
@ref{-n;}.
2826
2827
@node -n\,-n&,-np,Options
2828
@comment node-name, next, previous, up
2829
2830
@subsection @samp{-n\}: Free-form syntax continued by backslash
2831
2832
@findex -n\
2833
@cindex Syntax, free-form
2834
In @sc{Fortran}--90, this turns on free-form syntax and sets the continuation
2835
character to be the backslash (as it would be in C). For example,
2836
2837
@example
2838
-n9[-n\]
2839
@@
2840
@@a
2841
program main
2842
x = \
2843
y
2844
end
2845
@end example
2846
@noindent
2847
In the tangled output the backslash is converted into @sc{Fortran}-90's
2848
standard continuation character, the ampersand.
2849
2850
See also @ref{-n&}.
2851
2852
@node -n&,-n/,-n\,Options
2853
@comment node-name, next, previous, up
2854
2855
@subsection @samp{-n&}: Free-form syntax continued by ampersand
2856
2857
@findex -n&
2858
@cindex Syntax, free-form
2859
In @sc{Fortran}--90, this turns on free-form syntax and sets the continuation
2860
character to be the ampersand. For example,
2861
2862
@example
2863
-n9[-n&]
2864
@@
2865
@@a
2866
program main
2867
x = &
2868
y
2869
end
2870
@end example
2871
2872
For @sc{Fortran}-90, free-form syntax continued by the ampersand is
2873
@FWEB{}'s default, so one probably will not need to use @samp{-n&}
2874
explicitly.
2875
2876
See also @ref{-n\}.
2877
2878
@node -n/,-n!,-n&,Options
2879
@comment node-name, next, previous, up
2880
2881
@subsection @samp{-n/}: Recognize short comments [@sc{Fortran}]
2882
2883
@findex -n/
2884
The standard @FWEB{} notation for a short comment (one terminated by
2885
the next newline) is @samp{// ...}. However, in @sc{Fortran} the
2886
@samp{//} denotes concatenation by default. To make it denote a short
2887
comment, use the @samp{-n/} option. One can do this in the @file{.fweb}
2888
file (@pxref{Customization}) or with the language-setting command in
2889
limbo, as in @samp{@@n/}.
2890
2891
@noindent
2892
In @FWEB{}, one may always use @samp{\/} for concatenation, so there's
2893
no penalty for using @samp{-n/}.
2894
@cindex Concatenation
2895
@findex \/
2896
2897
@node -n!,-n),-n/,Options
2898
@comment node-name, next, previous, up
2899
2900
@subsection @samp{-n!}: Make @samp{!} denote short comment [@sc{Fortran}]
2901
2902
@findex -n!
2903
@cindex Comments, @sc{Fortran}
2904
In @sc{Fortran}-90, @samp{!} starts a short comment. However,
2905
by default @FWEB{} usurps @samp{!} for the logical not, as in
2906
@samp{if(x != y)}. To force it to recognize @samp{!} as a comment, use
2907
@samp{-n!}. However, the recommended style is to use @FWEB{}'s
2908
standard convention that @samp{//} denotes the start of a short
2909
comment (@pxref{-n/}). See also @ref{-!} and @ref{-r!}.
2910
2911
In @sc{Fortran}-77, to include the exclamation point inside a string,
2912
escape it with a backslash, as in
2913
2914
@example
2915
s = "A \! inside a string"
2916
@end example
2917
@noindent
2918
This possibly annoying restriction arises because the unduly complicated
2919
@sc{Fortran} input driver does some preprocessing of the @sc{Fortran}
2920
source before it feeds it to the cores of the processors.
2921
2922
@node -n), -o, -n!, Options
2923
@comment node-name, next, previous, up
2924
2925
@subsection @samp{-n)}: Reverse array indices [@sc{Fortran}] (@FTANGLE{})
2926
2927
@findex -n)
2928
This @emph{somewhat experimental} flag permits @sc{Fortran} programmers to
2929
use C-style array indices.
2930
Conversions such as the following are made (during the output phase of
2931
@FTANGLE{}):
2932
2933
@example
2934
a(k)(i) @r{=>} a(i,k)
2935
a(k)(i,j) @r{=>} a(i,j,k)
2936
a(k)(j)(i) @r{=>} a(i,j,k)
2937
@end example
2938
@noindent
2939
[No spaces may intervene between @samp{)} and @samp{(}; effectively,
2940
@samp{)(} is treated as one token for the purposes of @samp{-n)}.]
2941
This feature permits convenient definitions of macros that deal with
2942
multi-dimensional vectors.
2943
2944
Unfortunately, @FTANGLE{} doesn't fully understand the syntax of the
2945
source code---and never will, unless it is fully integrated with a
2946
compiler. It will therefore be confused by situations like the
2947
following @sc{Fortran} example:
2948
2949
@example
2950
dimension x(0:4)(1:2) // @r{OK}
2951
character*90 ch(4) // @r{OK}
2952
write(6,*) ((x(i)(j),i=1,2), j=3,4) // @r{Will reverse incorrectly.}
2953
c = ch(4)(3:4) // @r{Shouldn't reverse, but will.}
2954
@end example
2955
@noindent
2956
One solution, due to Charles Karney, is to insert a space to prevent
2957
@samp{)(} from being recognized as a single token. However,
2958
since ordinary white space is eaten on input, one must resort to
2959
something like the following (@samp{$UNQUOTE} is a built-in @FWEB{}
2960
function; @pxref{$UNQUOTE}):
2961
2962
@example
2963
@@m SP $UNQUOTE(' ')
2964
@@a
2965
dimension x(0:4)(1:2)
2966
character*90 ch(4)
2967
write(6,*) SP ((x(i)(j),i=1,2), j=3,4)
2968
c = ch(4)SP(3:4)
2969
@end example
2970
2971
This option is controlled by the three style-file parameters
2972
@samp{paren.len}, @samp{paren.num}, and @samp{paren.nest}. (@xref{Style}.)
2973
@samp{paren.len} is the default number of bytes to be allocated for each
2974
index; if an index is longer than this number, the current length is
2975
increased by this number and storage is automatically reallocated.
2976
@samp{paren.num} is the maximum number of allowed indices; for example,
2977
when processing @samp{a(i)(j)(k)}, @samp{paren.num} is 3.
2978
@samp{paren.nest} is the maximum parenthesis nesting level. In the
2979
example @samp{x(a(i)(j)(k))}, @samp{paren.nest} is 2. If either of the
2980
last two parameters is exceeded, a message will be issued asking you to
2981
increase the appropriate value.
2982
2983
@node -o,-q,-n),Options
2984
@comment node-name, next, previous, up
2985
2986
@subsection @samp{-o}: Don't overload operators
2987
2988
@findex -o
2989
@cindex Operators, overloading
2990
This option inhibits the operator-overloading feature invoked by the
2991
command @samp{@@v} (@pxref{Overloading}).
2992
2993
@node -q,-P_,-o,Options
2994
@comment node-name, next, previous, up
2995
2996
@subsection @samp{-q}: Don't translate @sc{Ratfor}
2997
2998
@findex -o
2999
@emph{(This option is obsolete.)}
3000
3001
@node -P_,-p,-q,Options
3002
@comment node-name, next, previous, up
3003
3004
@subsection @samp{-P}: Select @TeX{} processor
3005
3006
@findex -P
3007
@cindex Processor, @TeX{}
3008
@cindex Processor, La@TeX{}
3009
Say @samp{-PT} or @samp{-PL} to inform @FWEAVE{} that its output will
3010
be processed by @TeX{} or La@TeX{}, respectively. Beginning with
3011
Version 1.50, the default processor is LaTeX (@samp{-PL}). If you
3012
always use @TeX{}, it's easiest to put @samp{-PT} into the @file{.fweb}
3013
initialization file.
3014
3015
@emph{Please note that @samp{-PT} is no longer supported; @FWEB{}
3016
development is now based exclusively on La@TeX{}.}
3017
3018
@node -p,-r,-P_,Options
3019
@comment node-name, next, previous, up
3020
3021
@subsection @samp{-p}: Buffer up a style-file entry
3022
3023
@findex -p
3024
This option specifies a style-file entry (@pxref{Style}). Its argument
3025
is exactly the same as a line that one may put into the local @FWEB{}
3026
style file. Thus, if in @file{fweb.sty} one would say
3027
@samp{entry="value"}, the form of the @samp{-p} option would be
3028
@samp{-pentry='"value"'}. (The single quotes are required on a
3029
@sc{unix} system because the double quotes have special significance to
3030
the shell.)
3031
3032
This option can be used either in the @file{.fweb} initialization file
3033
(@pxref{Initialization}), to record style-file entries that are common
3034
to all runs, or on the command line, to override a local style-file
3035
entry for a single run. This behavior is a consequence of the following
3036
order of processing style parameters:
3037
3038
@quotation
3039
@enumerate
3040
@item
3041
@samp{-p} options in @file{.fweb};
3042
3043
@item
3044
entries in the local style file @file{fweb.sty};
3045
3046
@item
3047
@samp{-p} options on the command line.
3048
3049
@end enumerate
3050
@end quotation
3051
3052
@node -r,-r9,-p,Options
3053
@comment node-name, next, previous, up
3054
3055
@subsection @samp{-r}: Set global language to @sc{Ratfor}--77
3056
3057
@xref{Languages} and @ref{Ratfor}. See also @ref{-L_}.
3058
@findex -r
3059
3060
@node -r9,-rg,-r,Options
3061
@comment node-name, next, previous, up
3062
3063
@subsection @samp{-r9}: Set global language to @sc{Ratfor}--90
3064
3065
@xref{Languages} and @ref{Ratfor}. See also @ref{-L_}.
3066
@findex -r9
3067
3068
@node -rg,-rk,-r9,Options
3069
@comment node-name, next, previous, up
3070
3071
@subsection @samp{-rg}: Set @b{goto} parameters
3072
3073
@findex -rg
3074
This obscure option is used for configuring @sc{Ratfor} (and really
3075
should be a style-file parameter). (Discussion not finished.)
3076
3077
@node -rk,-rK_,-rg,Options
3078
@comment node-name, next, previous, up
3079
3080
@subsection @samp{-rk}: Suppress comments about @sc{Ratfor} translation (@FTANGLE{})
3081
3082
@findex -rk
3083
By default, the @sc{Ratfor} translator writes comments about what command it
3084
is translating. The @samp{-rk} option suppresses those comments. Arguments
3085
to this option allows one to suppress comments about only particular
3086
commands, according to the following list:
3087
3088
@example
3089
b @r{---} break
3090
c @r{---} case
3091
t @r{---} default
3092
d @r{---} do
3093
f @r{---} for
3094
i @r{---} if
3095
n @r{---} next
3096
p @r{---} repeat, until
3097
r @r{---} return
3098
s @r{---} switch
3099
h @r{---} where
3100
w @r{---} while
3101
@end example
3102
3103
@noindent
3104
For example, one can say @samp{-rkrb} to suppress comments about the
3105
@b{return} and @b{break} statements.
3106
3107
@node -rK_,-rAT;,-rk,Options
3108
@comment node-name, next, previous, up
3109
3110
@subsection @samp{-rK}: Write comments about @sc{Ratfor} translation (@FTANGLE{})
3111
3112
@findex -rK
3113
This is the negative of @samp{-rk} (@pxref{-rk}); it forces comments
3114
about particular @sc{Ratfor} commands.
3115
3116
@node -rAT;, -r;, -rK_, Options
3117
@comment node-name, next, previous, up
3118
3119
@subsection @samp{-r@@;}: Turn on auto-semi mode using pseudo-semis [@sc{Ratfor}]
3120
3121
@findex -r@@;
3122
Please don't use this option (it may not work). Insert semicolons by
3123
hand in your @sc{Ratfor} code, just as one does in C.
3124
3125
@node -r;, -rb, -rAT;, Options
3126
@comment node-name, next, previous, up
3127
3128
@subsection @samp{-r;}: Turn on auto-semi mode using actual semis [@sc{Ratfor}]
3129
3130
@findex -r;
3131
Please don't use this option (it may not work). Insert semicolons by
3132
hand in your @sc{Ratfor} code, just as one does in C.
3133
3134
@node -rb,-r/,-r;,Options
3135
@comment node-name, next, previous, up
3136
3137
@subsection @samp{-rb}: Number @b{if}s and @b{do}s [@sc{Ratfor}]
3138
3139
@findex -rb
3140
@cindex Numbering blocks
3141
@cindex Blocks, numbering
3142
In the woven output, extra comments are added to help one correlate the
3143
block structure of the code. For more discussion, see @ref{-b}.
3144
3145
@node -r/,-r!,-rb,Options
3146
@comment node-name, next, previous, up
3147
3148
@subsection @samp{-r/}: Recognize short comments [@sc{Ratfor}]
3149
3150
@findex -r/
3151
The standard @FWEB{} notation for a short comment is @samp{// ...}.
3152
However, in @sc{Ratfor} the @samp{//} denotes concatenation by default.
3153
To make it denote a short comment, use the @samp{-r/} option. For
3154
concatenation, use @samp{\/}.
3155
3156
For an example, see @ref{-n/}.
3157
3158
@node -r!,-r),-r/,Options
3159
@comment node-name, next, previous, up
3160
3161
@subsection @samp{-r!}: Make @samp{!} denote short comment [@sc{Ratfor}]
3162
3163
@findex -r!
3164
See the corresponding discussion of @samp{-!} in @ref{-!} and @ref{-n!}.
3165
3166
In @sc{Fortran}-77, to include the exclamation point inside a string,
3167
escape it with a backslash, as in
3168
3169
@example
3170
s = "A \! inside a string"
3171
@end example
3172
3173
@node -r), -s, -r!, Options
3174
@comment node-name, next, previous, up
3175
3176
@subsection @samp{-r)}: Reverse array indices [@sc{Ratfor}] (@FTANGLE{})
3177
3178
@findex -r)
3179
See the corresponding discussion of @samp{-n)} in @ref{-n)}.
3180
3181
@node -s, -T_, -r), Options
3182
@comment node-name, next, previous, up
3183
3184
@subsection @samp{-s}: Print statistics
3185
3186
@findex -s
3187
@findex -sm
3188
@cindex Statistics, printing
3189
@samp{-s} prints statistics about memory usage at the end of the run.
3190
3191
@samp{-sm} prints statistics about memory usage at the end of the run, just
3192
as does @samp{-s}; it also prints information about dynamic memory
3193
allocations as they occur. @samp{-sm@i{nnn}} displays allocations of nnn bytes
3194
or more; if @i{nnn} is missing, 10000 is assumed.
3195
3196
@node -T_, -t, -s, Options
3197
@comment node-name, next, previous, up
3198
3199
@subsection @samp{-T}: Flag-setting options for @FTANGLE{}
3200
3201
This is a family of options that set miscellaneous flags appropriate
3202
only for @FTANGLE{}.
3203
3204
@menu
3205
* -TD:: Permit processing of deferred macro definitions.
3206
* -Tb:: Permit built-functions such as @code{$IF} to be redefined.
3207
* -Tm:: Permib user-defined macros to be redefined.
3208
* -Tv:: Don't print header info at top of output.
3209
* -T%:: Don't retain trailing comments.
3210
* -T#:: Don't insert @samp{#line} command after @samp{@@%}.
3211
@end menu
3212
3213
@node -TD, -Tb, -T_, -T_
3214
@comment node-name, next, previous, up
3215
3216
@subsubsection @samp{-TD}: Permit processing of deferred macro definitions
3217
3218
@findex -TD
3219
@cindex Macros, deferred
3220
@dfn{Deferred macro definitions} are @samp{@@m} (or, equivalently,
3221
@samp{@@#define}) commands that appear in the code part rather than
3222
the usual definition part. These definitions are evaluated during the
3223
output (phase 2), and can cause confusion when used with the
3224
preprocessor commands, which are evaluated during the input (phase 1).
3225
Because of this confusion, deferred macro definitions are prohibited by
3226
default. To permit them, use the @samp{-TD} option (then be prepared
3227
to make some obscure programming errors).
3228
3229
@node -Tb, -Tm, -TD, -T_
3230
@comment node-name, next, previous, up
3231
3232
@subsubsection @samp{-Tb}: Permit built-functions to be redefined
3233
3234
@findex -Tb
3235
@cindex built-in functions, redefining
3236
3237
By default, built-in functions such as @code{$IF} (@pxref{Built-in functions})
3238
may not be redefined by an @code{@@m} command. To allow this extremely
3239
dangerous operation, use the @samp{-Tb} option.
3240
3241
@node -Tm, -Tv, -Tb, -T_
3242
@comment node-name, next, previous, up
3243
3244
@subsubsection @samp{-Tm}: Permit user macros to be redefined
3245
3246
@findex -Tm
3247
@cindex macros, redefining
3248
3249
By default, user macros may not be redefined by an @code{@@m} command.
3250
To permit this, use the @samp{-Tm} option. Note that many functions
3251
described under @ref{Built-in functions}, such as @code{$PI}, are in fact
3252
implemented as macros.
3253
3254
@node -Tv, -T%, -Tm, -T_
3255
@comment node-name, next, previous, up
3256
3257
@subsubsection @samp{-Tv}: Don't print header info
3258
3259
@findex -Tv
3260
@cindex Header comments, printing
3261
By default, @FTANGLE{} attempts to be helpful and writes some
3262
information about the command line, input and change files, etc.@ at the
3263
beginning of the output file. This information can be deleted by means
3264
of the @samp{-Tv} flag. [This is done automatically when the @samp{-F}
3265
flag (@pxref{-F_}) is in effect, since the header information includes a
3266
time stamp that would defeat a successful file comparison.]
3267
3268
@node -T%, -T#, -Tv, -T_
3269
@comment node-name, next, previous, up
3270
3271
@subsubsection @samp{-T%}: Don't retain trailing comments (@TeX{})
3272
3273
@findex -T%
3274
@cindex Comments, @TeX{}
3275
Unless the @samp{-v} option is used, comments are generally deleted by
3276
@FTANGLE{} as it writes the output file. However, in the @TeX{}
3277
language such deletions can change the behavior of the output (by
3278
introducing extra spaces). Therefore, @TeX{} comments that do not
3279
begin a line are always retained unless the @samp{-T%} option is used.
3280
This option has no effect for languages other than @TeX{}.
3281
3282
@node -T#, , -T%, -T_
3283
@comment node-name, next, previous, up
3284
3285
@subsubsection @samp{-T#}: Don't insert @samp{#line} command after @samp{@@%}
3286
3287
@findex -T#
3288
If the @samp{@@%} command (@pxref{AT%}) is used to comment out a line,
3289
it eats the trailing newline. An undesirable consequence of this is
3290
that, if nothing is done, the subsequent line numbering will be
3291
misunderstood by a debugger, at least until @FWEB{} inserts a
3292
@samp{#line} command for some reason. To prevent this, @FWEB{}
3293
inserts by default an implicit @samp{@@#line} command
3294
(@pxref{Preprocessing}) after each @samp{@@%} that begins a line. To
3295
prevent this from happening (possibly because the feature doesn't work
3296
correctly, in which case you should report it; @pxref{Support}), use the
3297
@samp{-T#} option.
3298
3299
@node -t, -U_, -T_, Options
3300
@comment node-name, next, previous, up
3301
3302
@subsection @samp{-t}: Truncate identifiers
3303
3304
@findex -t
3305
@cindex Identifiers, truncating
3306
The truncation option enables one to use a wider character set for
3307
identifiers than the language compiler will accept. The standard
3308
example is vanilla-flavored @sc{Fortran}-77, which doesn't allow the underscore.
3309
If one says @samp{`-tn6@{_@}}', underscores will be removed from all
3310
identifiers, then the result will be truncated to length 6. If the
3311
truncation procedure results in non-unique identifiers, these are
3312
listed.
3313
3314
@node -U_, -u, -t, Options
3315
@comment node-name, next, previous, up
3316
3317
@subsection @samp{-U}: Convert reserved output tokens to lower case (@FTANGLE{})
3318
3319
@findex -U
3320
@cindex Tokens, upper-case
3321
Particularly during @sc{Ratfor} expansion, certain tokens such as
3322
@samp{DO} are output by @FTANGLE{} in upper case. The @samp{-U}
3323
option forces such tokens to be produced in lower case.
3324
3325
@node -u,-V_,-U_,Options
3326
@comment node-name, next, previous, up
3327
3328
@subsection @samp{-u}: Undefine @FWEB{} macro (@FTANGLE{})
3329
3330
@findex -u
3331
@samp{-uA} undefines the @FWEB{} macro @samp{A} previously defined on the
3332
command line (or in @file{.fweb}) via @samp{-m}.
3333
3334
@emph{CAUTION}: This option can also undefine built-in
3335
functions such as @code{$IF}. Don't do that, since built-ins can use other
3336
built-ins behind the scenes; undefining one can cause very strange behavior.
3337
3338
@node -V_, -v, -u, Options
3339
@comment node-name, next, previous, up
3340
3341
@subsection @samp{-V}: Print @FWEB{} version number
3342
3343
@cindex Version number
3344
@findex -V
3345
This flag requests the startup banner, which includes the @FWEB{}
3346
version number, to be printed. This is usually done anyway, so it
3347
is only relevant when the message level is 0 (@pxref{-M_}).
3348
3349
@node -v,-W_,-V_,Options
3350
@comment node-name, next, previous, up
3351
3352
@subsection @samp{-v}: Make all comments verbatim (@FTANGLE{})
3353
3354
@findex -v
3355
@cindex Comments, verbatim
3356
By default, comments are not passed to the tangled output. With @samp{-v},
3357
all comments are included verbatim in the tangled output. Since there's
3358
generally no harm in this, one might want to put this option into
3359
@file{.fweb} (@pxref{Initialization}).
3360
3361
@node -W_,-w,-v,Options
3362
@comment node-name, next, previous, up
3363
3364
@subsection @samp{-W}: Flag-setting options for @FWEAVE{}
3365
3366
@findex -W
3367
This is a family of options that set miscellaneous flags appropriate
3368
only for @FWEAVE{}.
3369
Options such as @samp{-W[} and @samp{-Wf} can be combined as @samp{-W[f}.
3370
3371
@menu
3372
* -W@@: -WAT. Set module warning flag.
3373
* -W1:: Completely cross-reference single-character identifiers.
3374
* -W[:: Turn on processing of bracketed array indices.
3375
* -WH: -WH_. Send extra arguments to the C preprocessor.
3376
3377
Commands that inhibit printing:
3378
3379
* -Wd: -Wnoprint. Don't print @@d or @@D in woven output.
3380
* -Wf: -Wnoprint. Don't print @@f.
3381
* -WF: -Wnoprint. Don't print @@F.
3382
* -Wl: -Wnoprint. Don't print @@l.
3383
* -Wm: -Wnoprint. Don't print @@m or @@M.
3384
* -Wv: -Wnoprint. Don't print @@v.
3385
* -Ww: -Wnoprint. Don't print @@w or @@W.
3386
@end menu
3387
3388
@node -WAT, -W1, -W_, -W_
3389
@comment node-name, next, previous, up
3390
3391
@subsubsection @samp{-W@@}: Set module warning flag.
3392
3393
@findex -W@@
3394
@cindex Modules, warning level for
3395
@cindex Warning level for modules
3396
3397
@FWEAVE{} can check module names for the possible anomalous conditions of
3398
``never used'' or ``multiple uses.'' These correspond to a module
3399
warning level, as in the following numbered list:
3400
3401
@enumerate
3402
@item
3403
Never used.
3404
3405
@item
3406
Multiple uses.
3407
3408
@end enumerate
3409
@noindent
3410
The module warning flag is the bitwise OR of the desired warning
3411
levels; warning messages are printed only when the relevant bits are
3412
turned on. By default, it is 1, so only messages about never-used
3413
modules are printed. The @samp{-W@@@i{flag}} overrides the default.
3414
For example, to get messages only about multiple uses, say @samp{-W@@2};
3415
to get no messages, say @samp{-W@@0}. One can put such an option into the
3416
@file{.fweb} initialization file (@pxref{Initialization}).
3417
3418
@FWEAVE{} will always complain about module names that are never defined.
3419
3420
3421
@node -W1, -W[, -WAT, -W_
3422
@comment node-name, next, previous, up
3423
3424
@subsubsection @samp{-W1}: Cross-reference single-character identifiers
3425
3426
@findex -W1
3427
@cindex Identifiers, single-character
3428
By default, @FWEB{} does not index uses of single-character
3429
identifiers (following Knuth's original design). (It does index their
3430
definitions.) To get complete cross-reference information for
3431
single-character identifiers, use the @samp{-W1} option.
3432
3433
@node -W[, -WH_, -W1, -W_
3434
@comment node-name, next, previous, up
3435
3436
@subsubsection @samp{-W[}: Process bracketed array indices
3437
3438
@findex -W[
3439
@cindex Brackets, active
3440
This @emph{experimental} option makes square brackets behave like
3441
parentheses in the context of array indices.
3442
3443
In @sc{Fortran}, @FTANGLE{} will just replace the brackets by parentheses.
3444
In C, the brackets will be left alone.
3445
3446
@findex \WARRAY
3447
@FWEAVE{}, however, will typeset the indices according
3448
to the @file{fwebmac.sty} macro @samp{\WARRAY}. This macro takes one
3449
argument, which is just the array index or indices. (In C, indexing
3450
like @samp{a[i][j][k]} generates the argument @samp{i,j,k}.) By
3451
default, @samp{\WARRAY} just surrounds its argument with brackets.
3452
However, the user may change its definition to get special effects such
3453
as superscripted or subscripted indices. A simple example macro
3454
@samp{\WSUB} is provided in @file{fwebmac.sty}; one can say
3455
@samp{\let\WARRAY\WSUB} in the limbo section to have bracketed indices
3456
print as subscripts.
3457
3458
This feature may not work when the contents of the brackets
3459
are too complicated (so that @FWEAVE{} tries to typeset them by going
3460
in and out of math mode).
3461
3462
For more information, experts can see @file{fwebmac.web}, command @code{\WXA}.
3463
@findex \WXA
3464
3465
@node -WH_, -Wnoprint, -W[, -W_
3466
@comment node-name, next, previous, up
3467
3468
@subsubsection @samp{-WH}: Send additional arguments to the C preprocessor
3469
3470
@findex -WH
3471
@cindex Preprocessor, sending additional arguments to
3472
When the @samp{-H} option (@pxref{-H_}) is used, the C preprocessor is
3473
invoked to scan include header files for @b{typedef}'s and @b{class}
3474
declarations. That is called with a standard set of options.
3475
(Presently, @code{gcc} is actually called to invoke the preprocessor; it
3476
is sent the options @samp{-E}, @samp{-P}, and @samp{-I}.) Occasionally
3477
it may be necessary to send additional options. Those can be specified
3478
as the (string) argument to @samp{-WH}. Thus, to define two macros to the
3479
preprocessor, one could say either of
3480
3481
@example
3482
-WH-Dtest1=1 -WH-Dtest2=2
3483
-WH"-Dtest1=1 -Dtest2=2"
3484
@end example
3485
@noindent
3486
The first form shows that @samp{-WH} accretes to earlier uses. The
3487
second form shows how to handle embedded blanks (in a @sc{unix} shell).
3488
Then, if one were programming in C, use of @samp{-H} would issue the
3489
system command
3490
3491
@example
3492
gcc -E -P -Dtest1=1 -Dtest2=2
3493
@end example
3494
3495
3496
@node -Wnoprint, , -WH_, -W_
3497
@comment node-name, next, previous, up
3498
3499
@subsubsection @samp{-WdfFlmvw}: Don't print various things in woven output
3500
3501
@findex -W
3502
The printing of selected definition-part commands can be suppressed as
3503
follows:
3504
3505
@example
3506
-Wd @r{--- outer definitions (@samp{@@d} or @samp{@@D})}
3507
-Wf @r{--- format statements (@samp{@@f})}
3508
-WF @r{--- format statements (@samp{@@F})}
3509
-Wl @r{--- limbo text definitions (@samp{@@l})}
3510
-Wm @r{--- FWEB macro definitions (@samp{@@m} or @samp{@@M})}
3511
-Wv @r{--- operator overloads (@samp{@@v})}
3512
-Ww @r{--- identifier overloads (@samp{@@w} or @samp{@@W})}
3513
@end example
3514
3515
@noindent
3516
When these options used, associated cross-referencing is suppressed
3517
as well.
3518
@cindex Cross-references, suppressing
3519
3520
@node -w,-x,-W_,Options
3521
@comment node-name, next, previous, up
3522
3523
@subsection @samp{-w}: Change name of macro package (@FWEAVE{})
3524
3525
@findex -w
3526
The option @samp{-w} means ``Don't print @samp{\input fwebmac.sty} as
3527
the first line of the @file{.tex} output file.'' The option
3528
@samp{-w@i{fname}} means ``Print @samp{\input fname} as the first line.''
3529
For example, when working with REV@TeX{} (@pxref{REVTeX}), one needs to
3530
say @samp{-wrwebmac.sty}.
3531
3532
This option can be used for special effects when one is trying to obtain
3533
behavior different from that defined by @FWEB{}'s macro package
3534
@file{fwebmac.sty} (@pxref{fwebmac.sty}). However, try to not do that.
3535
Please submit requests for such behavior modifications to the developer;
3536
see @ref{Support}.
3537
3538
@node -x,-X_,-w,Options
3539
@comment node-name, next, previous, up
3540
3541
@subsection @samp{-x}: Eliminate or reduce cross-reference information (@FWEAVE{}).
3542
3543
@findex -x
3544
@cindex Cross-references, eliminating
3545
Cross-reference information (for @FWEAVE{}) includes the Table of Contents
3546
('c'), the Index ('i'), and the Module List ('m'). The option @samp{-x}
3547
eliminates all of that information. The option @samp{-x@i{letters}}
3548
eliminates the piece of information corresponding to each letter in the
3549
list. For example, @samp{-xim} eliminates the Index and the Module List.
3550
3551
Another possibility is to say @samp{-xu}, which prevents
3552
cross-references from unnamed sections (begun with @samp{@@a} or
3553
@samp{@@A}) from appearing in the Index.
3554
3555
@node -X_,-y,-x,Options
3556
@comment node-name, next, previous, up
3557
3558
@subsection @samp{-X}: Print selected cross-reference information (@FWEAVE{})
3559
3560
@findex -X
3561
When used with any of the arguments @samp{cim}, this option is the
3562
opposite of @samp{-x}. @xref{-x}.
3563
3564
The option @samp{-XI} tells @FWEAVE{} to write its index
3565
cross-references to a file formatted for input by the @code{makeindex}
3566
utility. This feature facilitates creation of a master index that spans
3567
several individual @code{web} files. For more discussion, see
3568
@ref{Using makeindex}.
3569
3570
The construction @samp{-XI} stands alone; one may not mix the @samp{I}
3571
with the list @samp{cim}. Also, this option is overridden by
3572
@samp{-xi}, which suppresses output of all index information.
3573
3574
@node -y,-Z_,-X_,Options
3575
@comment node-name, next, previous, up
3576
3577
@subsection @samp{-y}: Allocate dynamic memory
3578
3579
@findex -y
3580
@cindex Memory allocation
3581
@cindex Allocation, memory
3582
This option changes the default size for a dynamically allocated memory
3583
buffer. The buffers are indicated by a one- or two-character
3584
abbreviation such as @samp{op}. For example, the option @samp{-yop200}
3585
allocates 200 units for the @samp{op} buffer.
3586
3587
To query the default allocations, just say @samp{-y}.
3588
3589
When @FWEB{} runs out of space, it usually (but not always) issues a
3590
message telling one which @samp{-y} command to use in order to increase
3591
the allocations. (Someday it will reallocate automatically.) One may
3592
wish to add some such options to the @file{.fweb} file.
3593
3594
For a more detailed discussion of memory allocation and a menu of the
3595
various dynamic arrays, see @ref{Memory allocation}.
3596
3597
@node -Z_,-z,-y,Options
3598
@comment node-name, next, previous, up
3599
3600
@subsection @samp{-Z}: Display default style-file parameters
3601
3602
@findex -Z
3603
@cindex Options, information
3604
The information option @samp{-Zabc} prints to the screen the default
3605
contents of the style-file parameters beginning with @samp{abc}. Just
3606
@samp{-Z} prints everything.
3607
3608
After printing the defaults, the @samp{-p} options (@pxref{-p}) and the
3609
style file @file{fweb.sty} are processed. If that processing has
3610
overridden any of the defaults, the parameters are printed again,
3611
preceded by an asterisk.
3612
3613
To see only the parameters that have been modified from the defaults,
3614
say @samp{--Z}.
3615
3616
The @samp{-Z} option behaves slightly differently for color escape
3617
sequences than for other parameters; see @ref{Color}.
3618
3619
3620
@node -z,-.,-Z_,Options
3621
@comment node-name, next, previous, up
3622
3623
@subsection @samp{-z}: Change name of style file
3624
3625
@findex -z
3626
@cindex Style file, changing name of
3627
The command @samp{-znew.sty} changes the default style-file name
3628
@file{fweb.sty} to @file{new.sty}. The command @samp{-z} (with no
3629
argument) means ``Don't read any style file.''
3630
3631
Normally the style file is read from the same directory in which the
3632
@code{web} source file resides (or from the path defined by the
3633
environment variable @code{FWEB_STYLE_DIR}). To force @code{fweb.sty}
3634
to be read from the current directory, say @samp{-z.}.
3635
3636
@node -.,-\,-z,Options
3637
@comment node-name, next, previous, up
3638
3639
@subsection @samp{-.}: Don't recognize dot constants
3640
3641
@findex -.
3642
@cindex Dot constants, recognizing
3643
If this command is used, the processors will not understand that
3644
constructions such as @samp{.LT.} are operators in @sc{Fortran} or
3645
@sc{Ratfor}. This command is useful if one is trying to modernize the
3646
source code to use @FWEB{} conventions such as @samp{<} instead of
3647
@samp{.LT.}.
3648
3649
@node -\,-lp,-.,Options
3650
@comment node-name, next, previous, up
3651
3652
@subsection @samp{-\}: Explicitly escape continued strings
3653
3654
@findex -\
3655
@cindex Strings, long
3656
@cindex Strings, continuing
3657
In @FWEB{}, long strings are continued with the backslash. Normally,
3658
the continuation of the string must start in the first column of the
3659
next line; otherwise, spurious blanks will be introduced. However, when
3660
the @samp{-\} option is in effect, @FWEB{} expects that the
3661
continuation will also begin with the backslash, and it will ignore
3662
leading white space and the backslash. (This feature was inspired by
3663
@sc{Fortran}-90.) Thus, in the example
3664
3665
@example
3666
"This is \
3667
\continued";
3668
@end example
3669
@noindent
3670
the effective string is @code{"This is continued"} when @samp{-\} is in
3671
effect.
3672
3673
Note that this option affects all strings in the source file; one cannot
3674
mix and match.
3675
3676
@node -lp,-colon,-\,Options
3677
@comment node-name, next, previous, up
3678
3679
@subsection @samp{-(}: Continue parenthesized strings with backslashes
3680
3681
@findex -(
3682
@cindex Strings, parenthesized
3683
This option is like @samp{-\} (@pxref{-\}), but it refers to certain
3684
strings that are not normally quoted, such as the arguments of
3685
@samp{ifelse} commands in @code{m4}.
3686
3687
@node -colon,->,-lp,Options
3688
@comment node-name, next, previous, up
3689
3690
@subsection @samp{-:}: Set starting automatic statement number
3691
3692
@findex -:
3693
@cindex Statement numbers, automatic
3694
This option is useful for @sc{Fortran} and @sc{Ratfor}. Symbolic
3695
statement labels that are defined with the @samp{#:0} macro command
3696
(@ref{Tokens}; @ref{Fortran}), as in @samp{@@m EXIT #:0}, are incremented
3697
starting with the default of 90000. To change this to, e.g., 789, say
3698
@samp{-:789}.
3699
3700
@node ->,-=,-colon,Options
3701
@comment node-name, next, previous, up
3702
3703
@subsection @samp{->}: Redirect output (@FTANGLE{})
3704
3705
@findex ->
3706
@cindex Ouput, redirecting
3707
This changes the name of @FTANGLE{}'s output file. If no name is
3708
given, output is redirected to the terminal.
3709
3710
This command has no effect for @FWEAVE{}.
3711
3712
Although the appearance of this command is highly intuitive, it may be
3713
hard to type quickly. An equivalent command is @samp{-=} (@pxref{-=}).
3714
3715
@node -=,-#,->,Options
3716
@comment node-name, next, previous, up
3717
3718
@subsection @samp{-=}: Redirect output (@FTANGLE{})
3719
3720
@findex -=
3721
@cindex Ouput, redirecting
3722
Equivalent to @samp{->} (@pxref{->}), and faster to type on many keyboards.
3723
3724
@node -#,-plus,-=,Options
3725
@comment node-name, next, previous, up
3726
3727
@subsection @samp{-#}: Turn off comments about line and section numbers (@FTANGLE{})
3728
3729
@findex -#
3730
By default, tangled output includes comments about the line and section
3731
numbers corresponding to the current piece of code. To eliminate this
3732
clutter, say @samp{-#}. (But note that the line-number information is very
3733
useful for debugging in C and C++, as it enables the debugger to display
3734
the source line in the web file.)
3735
3736
In some cases, bugs in tangled output, particularly from @sc{Fortran}, can be
3737
eliminated by using @samp{-#}. (But please report the bug anyway;
3738
@ref{Support}.)
3739
3740
In some cases, it is useful to turn off the line- and section-number
3741
information locally. This can be done with the @samp{@@q} command.
3742
@xref{ATq}.
3743
3744
@node -plus,-/,-#,Options
3745
@comment node-name, next, previous, up
3746
3747
@subsection @samp{-+}: Don't interpret compound assignment operators
3748
3749
@findex -+
3750
@cindex Assignment operators, compound
3751
Both @sc{Ratfor} and @sc{Fortran} attempt to translate the commands
3752
@samp{++}, @samp{--}, @samp{+=}, @samp{-=}, @samp{*=}, and @samp{/=}
3753
into code that behaves as their C/C++ counterparts. To turn this feature off,
3754
use @samp{-+}.
3755
3756
@cindex Not equal
3757
Notice that in @sc{Fortran}-90 @samp{/=} is a token for ``not equal,''
3758
so if you want to use that you must turn off the compound assignment
3759
operators with use @samp{-+}. However, a better solution is to leave
3760
them turned on and use @FWEB{}'s standard @samp{!=} token for ``not equal.''
3761
3762
See also @ref{-ylx}.
3763
3764
@node -/,-!,-plus,Options
3765
@comment node-name, next, previous, up
3766
3767
@subsection @samp{-/}: Recognize short comments (@sc{Fortran} & @sc{Ratfor})
3768
3769
@findex -/
3770
3771
@cindex Comments, short
3772
If this command is not used with the @sc{Fortran}-like languages, the
3773
@samp{//} construction will be interpreted
3774
as concatenation rather than as the beginning of a short comment.
3775
3776
Concatenation can be signified with @FWEB{}'s token@samp{\/}, so no
3777
penalty is incurred for using @samp{-/}.
3778
3779
One way of invoking this option is with the global language command,
3780
such as @samp{@@n/}. Another is to put the command into the
3781
initialization file @file{.fweb}.
3782
3783
See also @ref{-n/} and @ref{-r/}.
3784
3785
@node -!,Info options,-/,Options
3786
@comment node-name, next, previous, up
3787
3788
@subsection @samp{-!}: Make @samp{!} denote short comment (@sc{Fortran} & @sc{Ratfor})
3789
3790
@findex -!
3791
@cindex Comments, short
3792
This option is not recommended; use @FWEB{}'s standard @samp{//} to
3793
begin short comments.
3794
3795
To include the exclamation point inside a string, escape it with a
3796
backslash, as in
3797
3798
@example
3799
s = "A \! inside a string"
3800
@end example
3801
3802
@node Info options,,-!,Options
3803
@comment node-name, next, previous, up
3804
3805
@subsection Information options
3806
3807
@cindex Options, information
3808
@cindex Information options
3809
Several of the command-line options can be used to elicit information
3810
about the initial state of @FWEB{}.
3811
3812
@quotation
3813
@samp{-@@} displays information about the control codes. @xref{-AT}.
3814
3815
@samp{-D} displays information about reserved words. @xref{-D_}.
3816
3817
@samp{-y} displays default dynamic memory allocations. @xref{-y}.
3818
3819
@samp{-Z} displays default values of style-file parameters. @xref{-Z_}.
3820
@end quotation
3821
@noindent
3822
The @samp{-h} option reminds one about these information options; it
3823
also provides convenient access to the GNU @code{info} browser.
3824
@xref{-h}.
3825
3826
@node AT commands,Comments,Starting,Top
3827
@comment node-name, next, previous, up
3828
3829
@chapter @FWEB{} COMMANDS
3830
3831
All @FWEB{} commands begin with the character @samp{@@}. It is recommended
3832
that these begin in column 1 if possible. This is required in some
3833
cases [e.g., the @samp{@@x}, @samp{@@y}, and @samp{@@z} in change files
3834
(@pxref{Change files}), or column-oriented @sc{Fortran}-77 processing].
3835
3836
Some of these control codes may be used anywhere; others begin a new
3837
part of the current section. (For a discussion of sections and parts,
3838
see @ref{Structure}.) For a quick summary of the control-code mappings
3839
and to see which codes begin new parts, say @samp{ftangle -@@}.
3840
@xref{-AT}.
3841
3842
@menu
3843
Debugging commands:
3844
* @@0: AT0. Turn off debugging.
3845
* @@1: AT1. Display irreducible scraps.
3846
* @@2: AT2. Display detailed scrap reductions.
3847
3848
Literal control characters:
3849
* @@@@: ATAT. Insert an '@@'.
3850
* @@|: AT|. Vertical bar/optional line break.
3851
3852
Beginning of section:
3853
* @@ : ATspace. Begin minor section.
3854
* @@*: AT*. Begin major section.
3855
3856
Beginning of code part:
3857
* @@<: AT<. Begin module name.
3858
* @@>: AT>. End module name.
3859
* @@A: ATA_. Begin code part.
3860
* @@a: ATa. Begin code part and mark next identifier.
3861
3862
Control codes b--z:
3863
* @@B: ATB_. Insert left brace; suppress default insertion of breakpoint command.
3864
* @@b: ATb. Insert breakpoint command.
3865
* @@c: ATc. Set language to C.
3866
* @@c++: ATcpp. Set language to C++.
3867
* @@D: ATD_. Define outer macro.
3868
* @@d: ATd. Define outer macro and mark it.
3869
* @@E: ATE_. Treat next identifier as ordinary expression.
3870
* @@e: ATe. Invisible expression.
3871
* @@f: ATf. Format identifier or module name.
3872
* @@I: ATI_. Include a WEB file, but don't print it.
3873
* @@i: ATi. Include a WEB file.
3874
* @@K: ATK_. Expand global RCS-like keyword.
3875
* @@k: ATk. Expand local RCS-like keyword.
3876
* @@L: ATL_. Set language.
3877
* @@l: ATl. Specify limbo text.
3878
* @@M: ATM_. Define an @FWEB{} macro.
3879
* @@m: ATm. Define a @FWEB{} macro and mark it.
3880
* @@N: ATN_. Turn on language-independent mode.
3881
* @@n: ATn. Set language to Fortran--77.
3882
* @@n9:ATn9. Set language to Fortran--90.
3883
* @@O: ATO_. Open new output file (global scope).
3884
* @@o: ATo. Open new output file (local scope).
3885
* @@q: ATq. Turn off or on module and line information locally.
3886
* @@R: ATR_. Treat next identifier as integer-like reserved word.
3887
* @@r: ATr. Set language to Ratfor--77.
3888
* @@r9: ATr9. Set language to Ratfor--90.
3889
* @@u: ATu. Undefine an outer macro.
3890
* @@v: ATv. Overload an operator.
3891
* @@W: ATW_. Overload an identifier.
3892
* @@x: ATx. Terminate ignorable material.
3893
* @@y: ATy. End first part of change.
3894
* @@z: ATz. Begin ignorable material.
3895
3896
Conversion to ASCII:
3897
* @@': ATquote. Convert single character to ASCII.
3898
* @@": ATdquote. Convert string to ASCII.
3899
3900
Forward referencing:
3901
* @@[: AT[. Mark next identifier as defined in this section.
3902
3903
Comments:
3904
* @@/*: AT/*. Begin a long verbatim comment.
3905
* @@//: AT//. Begin a short verbatim comment.
3906
* @@%: AT%. Ignore everything to next newline.
3907
* @@?: AT?. Begin a compiler directive.
3908
* @@(: ATlp. Begin a meta-comment.
3909
* @@): AT). End a meta-comment.
3910
3911
Special brace:
3912
* @@@{: ATlb. Insert left brace; suppress newlines in pretty-printing.
3913
3914
Index entries:
3915
* @@_: AT_. Force an index entry to be underlined (marked as defined).
3916
* @@-: AT-. Delete index entry for following identifier.
3917
* @@+: ATplus. Force index entry for following identifier.
3918
* @@^: AT^. Make index entry in Roman type.
3919
* @@.: ATdot. Make index entry in typewriter type.
3920
* @@9: AT9. Make index entry in format controlled by `\9'.
3921
3922
Control text:
3923
* @@t: ATt. Put control text into TeX \hbox.
3924
* @@=: AT=. Pass control text verbatim to the output.
3925
3926
Spacing:
3927
* @@comma: ATcomma. Insert a thin space.
3928
* @@/: AT/. Insert a line break, preserving indentation.
3929
* @@\: ATbs. Insert a line break and backspace.
3930
* @@|: AT|_. Insert optional line break in an expression.
3931
* @@#: AT#. Force line break with blank line.
3932
* @@~: AT~. Cancel a line break (tie adjacent lines together).
3933
* @@&: AT&. Join left and right items.
3934
3935
Pseudo (invisible) operators:
3936
* @@e: ATe. Invisible expression.
3937
* @@;: AT;. Invisible semicolon.
3938
* @@colon: ATcolon. Invisible colon.
3939
3940
Miscellaneous:
3941
* @@!: AT!. Inhibit expansion for next macro.
3942
@end menu
3943
3944
@node AT0, AT1, AT commands, AT commands
3945
@comment node-name, next, previous, up
3946
3947
@section Debugging commands
3948
3949
Several commands provide localized versions of the @samp{-1} and
3950
@samp{-2} options related to debugging of pretty-printing.
3951
3952
@subsection @samp{@@0}: Turn off debugging
3953
3954
@findex @@0
3955
@cindex Debugging
3956
This cancels the effect of a previous @samp{@@1} or @samp{@@2}
3957
(see @ref{AT1} and @ref{AT2}). The @samp{@@0} command should appear in a
3958
different section from the @samp{@@1} or @samp{@@2} commands.
3959
3960
@node AT1, AT2, AT0, AT commands
3961
@comment node-name, next, previous, up
3962
3963
@subsection @samp{@@1}: Display irreducible scraps
3964
3965
@findex @@1
3966
@cindex Debugging
3967
This is a local version of the command-line option @samp{-1}
3968
(@pxref{-1}); refer to that discussion for more information.
3969
3970
@node AT2, ATAT, AT1, AT commands
3971
@comment node-name, next, previous, up
3972
3973
@subsection @samp{@@2}: Display detailed reductions of the scraps
3974
3975
@findex @@2
3976
@cindex Debugging
3977
This is a local version of the command-line option @samp{-2}
3978
(@pxref{-2}); refer to that discussion for more information.
3979
3980
@node ATAT, AT|, AT2, AT commands
3981
@comment node-name, next, previous, up
3982
3983
@section Literal control characters
3984
3985
Several commands insert specific characters.
3986
3987
@subsection @samp{@@@@}: The character @samp{@@}
3988
3989
@findex @@@@
3990
@samp{@@@@} inserts the single character @samp{@@}.
3991
3992
Don't forget to double the @samp{@@} even inside strings. For example,
3993
the @FWEB{} source line
3994
3995
@example
3996
puts("'@@@@' is represented by `@@@@@@@@'");
3997
@end example
3998
3999
@noindent
4000
will be tangled to
4001
4002
@example
4003
puts("'@@' is represented by `@@@@'");
4004
@end example
4005
4006
@node AT|,ATspace,ATAT,AT commands
4007
@comment node-name, next, previous, up
4008
4009
@subsection @samp{@@|}: Literal vertical bar, or optional line break
4010
4011
@findex @@|
4012
@cindex Bar, vertical
4013
@cindex Vertical bar
4014
In the @TeX{} (documentation) part of a section, @samp{@@|} inserts a
4015
vertical bar. This is useful inside La@TeX{} verbatim environments. (A
4016
simple bar would signal a shift into code mode, which is probably not
4017
what one wants.) For an example, see @ref{AT|_}.
4018
4019
@cindex Line break, optional
4020
In a code part, @samp{@@|} inserts an optional line break in an
4021
expression---e.g.,
4022
4023
@example
4024
@samp{f(a,b,@@|c+d,...)}.
4025
@end example
4026
@noindent
4027
This helps @TeX{} to break the line at an appropriate place. If the
4028
line does not need to be broken, the command does nothing. [Compare
4029
@samp{@@|} with @samp{@@\} (@pxref{ATbs}) and @samp{@@/} (@pxref{AT/}),
4030
which always break the line.]
4031
4032
@node ATspace, AT*, AT|, AT commands
4033
@comment node-name, next, previous, up
4034
4035
@section Beginning of section
4036
4037
Sections are begun by either @samp{@@*} or @ASP{}.
4038
4039
@subsection @samp{@@ }: Begin minor section
4040
4041
@findex @@
4042
@cindex Section, beginning minor
4043
@ASP{}@ begins a new minor (unstarred or unnamed) section that is not entered
4044
into the Table of Contents. For example,
4045
4046
@example
4047
@@ This is an example of a minor (unnamed) section. (No entry is made
4048
in the Table of Contents.)
4049
4050
@@a
4051
main()
4052
@{@}
4053
@end example
4054
4055
@node AT*, AT<, ATspace, AT commands
4056
@comment node-name, next, previous, up
4057
4058
@subsection @samp{@@*}, @samp{@@*@i{n}}: Begin major section
4059
4060
@findex @@*
4061
@cindex Section, beginning major
4062
@cindex Major section, beginning
4063
@cindex Table of contents, entries for
4064
@samp{@@*} begins a new major (starred) section (of level 0). The
4065
command must be followed by the name of the section (entry in the Table
4066
of Contents), followed by a period. (If a period appears in the name
4067
itself, it must be protected by braces.)
4068
4069
@cindex Major section, optional argument for
4070
@cindex Section names, long
4071
@cindex Section names, short
4072
The section name is also used as a running head on the output pages. To
4073
deal with the possibility that the full name may be too long, the
4074
section name may be preceded by an optional argument enclosed in
4075
brackets. If it is present, the optional argument is used as the
4076
running head. (If a period appears as part of the optional argument, it
4077
must be protected by braces.)
4078
4079
@cindex Subsection, beginning major
4080
@cindex Major subsection
4081
If @samp{@@*} is followed by a digit @i{n}, it begins a new major
4082
(sub)section of level @i{n}. This is also entered into the Table of Contents.
4083
Thus, the complete syntax to begin a major section is
4084
4085
@example
4086
@@*@i{n} [Short name]Full name.
4087
@end example
4088
4089
For example,
4090
4091
@example
4092
@@* MAIN PROGRAM. This begins a major section (of level 0).
4093
4094
@@a
4095
main()
4096
@{@}
4097
4098
@@*1 [Input routines\dots]A very long section name that essentially
4099
means ``input routines.'' Now follow some subroutines.
4100
4101
@@a
4102
get_input()
4103
@{@}
4104
@end example
4105
4106
For La@TeX{}, the highest permissible major level is 2 (a subsubsection).
4107
4108
Section names can contain reasonably arbitrary @TeX{} text, including
4109
font-changing commands and other macros. However, it is necessary to
4110
understand that @emph{fragile} commands (in the sense of La@TeX{}) may
4111
not work because the section name is used in various contexts (e.g., as
4112
a page header). If a macro in a section name doesn't work properly,
4113
try preceding it with @samp{\protect}.
4114
4115
@FWEAVE{} converts @samp{@@*} commands to section numbers. For a
4116
discussion of section numbering, see @ref{Numbering}.
4117
4118
@node AT<, AT>, AT*, AT commands
4119
@comment node-name, next, previous, up
4120
4121
@section Beginning of code part
4122
4123
The code part is begun by the appearance of either @samp{@@a} or
4124
@samp{@@< @i{Module name} @@>=}.
4125
4126
@subsection @samp{@@<}: Begin module name
4127
4128
@findex @@<
4129
@cindex Module name, beginning
4130
@samp{@@<} begins a module name, which has the form
4131
@samp{@@< @i{@TeX{} text} @@>}. (Module names inside @FWEB{} macro definitions
4132
begin with @samp{@@#}, not @samp{@@<}.)
4133
4134
@node AT>, ATA_, AT<, AT commands
4135
@comment node-name, next, previous, up
4136
4137
@subsection @samp{@@>}: End module name
4138
4139
@findex @@>
4140
@cindex Module name, ending
4141
@samp{@@>} ends a module name, of the form @samp{@@< @i{@TeX{} text} @@>}.
4142
4143
Technically, @samp{@@>} is not a command; rather, it is a delimiter
4144
that terminates @samp{@@<}. An unmatched @samp{@@>} is simply ignored
4145
(after a warning message is issued).
4146
4147
@node ATA_, ATa, AT>, AT commands
4148
@comment node-name, next, previous, up
4149
4150
@subsection @samp{@@A}: Begin code part of unnamed section
4151
4152
@findex @@A
4153
@cindex Code part, beginning unnamed
4154
@samp{@@A} begins the code part of an unnamed section. For example,
4155
4156
@example
4157
@@ In an unnamed section, the code part begins with @samp{@@a} or @samp{@@A}.
4158
@@A
4159
main()
4160
@{@}
4161
@end example
4162
4163
For more discussion of the distinction between @samp{@@A} and
4164
@samp{@@a}, see @ref{ATa}.
4165
4166
@node ATa, ATB_, ATA_, AT commands
4167
@comment node-name, next, previous, up
4168
4169
@subsection @samp{@@a}: Begin code part of unnamed section, and mark
4170
4171
@findex @@a
4172
@cindex Code part, beginning unnamed
4173
@samp{@@a} begins the code part of an unnamed section (just as does
4174
@samp{@@A}), and in addition marks the next unreserved identifier it
4175
finds as defined in this section. Precisely,
4176
4177
@example
4178
@samp{@@a} == @samp{@@A@@[}
4179
@end example
4180
4181
Originally, @FWEB{} did not contain the @samp{@@A} command, so when
4182
the functionality of automatically marking the next unreserved
4183
identifier (@pxref{AT[}) was added, it was natural to add it to @samp{@@a}. A
4184
reasonable style of coding is to always use @samp{@@a} if you don't know
4185
any better; if you sometime run into trouble, you can then change
4186
selected @samp{@@a}s to @samp{@@A}s. For example, it is appropriate to
4187
use @samp{@@a} if one codes one function per section. E.g.,
4188
4189
@example
4190
@@c
4191
@@
4192
@@a
4193
int
4194
subrtn()
4195
@{@}
4196
@end example
4197
@noindent
4198
Here the @samp{@@a} marks @samp{subrtn} as defined in this section; if
4199
that identifier is used elsewhere, it will be subscripted with the
4200
section number. (To turn this feature off, use @samp{-f}; see @ref{-f}.)
4201
However, if a section contains an arbitrary code fragment, the code part should
4202
probably begin with @samp{@@A}. E.g.,
4203
4204
@example
4205
@@c
4206
@@
4207
@@A
4208
x = y;
4209
@end example
4210
@noindent
4211
If one had used @samp{@@a} here, the @code{x} would have been marked as
4212
defined here, which is not what one wants.
4213
4214
4215
@node ATB_, ATb, ATa, AT commands
4216
@comment node-name, next, previous, up
4217
4218
@section Control codes b--z
4219
4220
@subsection @samp{@@B}: Suppress insertion of breakpoint command
4221
4222
@findex @@B
4223
@cindex Breakpoints, suppressing
4224
@cindex Left brace, inserting
4225
This is for detailed debugging of @FWEB{} codes. It inserts a left
4226
brace and suppresses the insertion of a breakpoint command. See the
4227
discussion of @samp{@@b} in @ref{ATb}.
4228
4229
@node ATb, ATc, ATB_, AT commands
4230
@comment node-name, next, previous, up
4231
4232
@subsection @samp{@@b}: Insert a breakpoint command
4233
4234
@findex @@b
4235
@cindex Breakpoints, inserting
4236
(Discussion to be finished. Useful only for very intimate debugging of
4237
@FWEB{} codes. In these days of safe sex, such intimacy may not be
4238
desirable.)
4239
4240
See also @ref{ATB_}.
4241
4242
@node ATc, ATcpp, ATb, AT commands
4243
@comment node-name, next, previous, up
4244
4245
@subsection @samp{@@c}: Set language to C
4246
4247
@findex @@c
4248
The command @samp{@@c} is a shorthand for @samp{@@Lc}. For a discussion
4249
of language commands in limbo, see @ref{ATL_}.
4250
4251
@xref{Languages} and @ref{C}.
4252
4253
@node ATcpp, ATD_, ATc, AT commands
4254
@comment node-name, next, previous, up
4255
4256
@subsection @samp{@@c++}: Set language to C++
4257
4258
@findex @@c++
4259
The command @samp{@@c++} is a shorthand for @samp{@@Lc++}. For a discussion
4260
of language commands in limbo, see @ref{ATL_}.
4261
4262
@xref{Languages} and @ref{Cpp}.
4263
4264
@node ATD_, ATd, ATcpp, AT commands
4265
@comment node-name, next, previous, up
4266
4267
@findex @@D
4268
@cindex Outer macro, defining
4269
@subsection @samp{@@D}: Define outer macro
4270
4271
@emph{This command begins the definition part.}
4272
4273
@samp{@@D} defines an outer macro. For more discussion, see @ref{Outer macros}.
4274
For example, in C
4275
4276
@example
4277
@@D A 1
4278
@end example
4279
@noindent
4280
will be tangled to the beginning of the output file as @samp{#define A 1}.
4281
4282
@node ATd, ATE_, ATD_, AT commands
4283
@comment node-name, next, previous, up
4284
4285
@subsection @samp{@@d}: Define outer macro, and mark
4286
4287
@findex @@d
4288
@emph{This command begins the definition part.}
4289
4290
@samp{@@d} defines an outer macro (just as @samp{@@D} does), and also marks the
4291
next identifier as defined in the present section. It is equivalent to
4292
4293
@quotation
4294
@samp{@@d} == @samp{@@D@@[}
4295
@end quotation
4296
4297
@noindent
4298
(@pxref{AT[}).
4299
4300
The distinction between @samp{@@d} and @samp{@@D} is analagous to the
4301
distinction between @samp{@@a} and @samp{@@A}. @xref{ATa}.
4302
4303
@node ATE_, ATf, ATd, AT commands
4304
@comment node-name, next, previous, up
4305
4306
@subsection @samp{@@E}: Treat next identifier as ordinary expression (@FWEAVE{})
4307
4308
@findex @@E
4309
For formatting purposes, treat the next identifier as an ordinary
4310
expression.
4311
4312
This command is useful in pretty-printing certain kinds of macro
4313
constructions. Further discussion is given in @ref{Macros and
4314
formatting}.
4315
4316
@node ATf, ATi, ATE_, AT commands
4317
@comment node-name, next, previous, up
4318
4319
@subsection @samp{@@f}: Format identifier or module name
4320
4321
@findex @@f
4322
@cindex Identifier, formatting
4323
@emph{This command begins the definition part.}
4324
4325
The construction
4326
4327
@example
4328
@@f identifier old_identifier
4329
@end example
4330
4331
@noindent
4332
makes @FWEAVE{} treat @i{identifier} like @i{old_identifier}. For example,
4333
4334
@example
4335
@@f mytype int
4336
@end example
4337
4338
@noindent
4339
says to treat the variable @code{mytype} just as @code{int} is treated
4340
(e.g., as a reserved word in C or C++).
4341
4342
Traditionally, C programmers needed to use this command to format
4343
identifiers that were defined in @code{#include} files. This annoying
4344
redundancy has now been eliminated by means of the @samp{-H} command,
4345
which tells @FWEAVE{} to scan @code{#include} files automatically.
4346
@xref{-H_}.
4347
4348
The @i{old_identifier} may be one of the following special names, which
4349
insert extra spaces according to the positions of the underscores and
4350
behave as the part of speech indicated by the base names:
4351
4352
@example
4353
$_BINOP_
4354
$_COMMA_
4355
$_EXPR
4356
$_EXPR_
4357
$EXPR_
4358
$UNOP_
4359
@end example
4360
@noindent
4361
These are useful for dealing with certain macro constructions. For
4362
example,
4363
4364
@example
4365
@@f PLUS $_BINOP_
4366
@@m PLUS +
4367
@@m ADD(x, y) ((x) PLUS (y))
4368
@end example
4369
@noindent
4370
Without the format command, the @samp{ADD} macro will pretty-print
4371
without spaces before and after the @samp{PLUS}.
4372
4373
When the current language is @TeX{}, the format command can be used to
4374
change a category code according to the format
4375
4376
@example
4377
@@f `TeXchar new_cat_code
4378
@end example
4379
4380
@noindent
4381
Difficulties may ensue if one try to change the category code of
4382
@samp{@@} in this way; a fully operational @sc{web} for @TeX{} is quite
4383
difficult and has been neither accomplished nor attempted.
4384
4385
@node ATi, ATI_, ATf, AT commands
4386
@comment node-name, next, previous, up
4387
4388
@subsection @samp{@@i}: Include file (unconditional)
4389
4390
@findex @@i
4391
@cindex File, including web
4392
If one says
4393
4394
@example
4395
@@i test.hweb
4396
@end example
4397
4398
@noindent
4399
the file @file{test.hweb} is inserted at the present point of the web file. By
4400
default, the current directory is searched. Files can be included from
4401
other directories by means of the @code{FWEB_INCLUDES} environment variable
4402
and/or the @samp{-I} command-line option.
4403
See @ref{Environment variables} and @ref{-I_}.
4404
4405
In principle, the included file may contain any fragment of source text.
4406
However, it is best to make it a complete section (begun by @samp{@@*}
4407
or @ASP{}) if at all possible.
4408
4409
Unfortunately, the @samp{@@i} command cannot be commented out or
4410
conditionally included by use of an @FWEB{} preprocessor command.
4411
That is because @samp{@@i} is processed very early in the parsing
4412
process. (Consider: @samp{@@i} could include @TeX{} text, but the
4413
preprocessor is only active in the definition and code parts.)
4414
4415
Include commands may be nested to a depth set by the option
4416
@samp{-yid}. @xref{-yid}.
4417
4418
@cindex Include file, printing name of
4419
@findex \WIF
4420
@cindex Include file, formatting name of
4421
@findex \WIFfmt
4422
In the woven output, if a section comes from an include file, the name
4423
of the include file is printed in square brackets as the first text of
4424
the @TeX{} part. To inhibit printing of that name, say
4425
4426
@example
4427
\def\WIF#1@{@}
4428
@end example
4429
@noindent
4430
in the limbo section. To change the way that name is formatted,
4431
redefine the macro @samp{\WIFfmt}, whose single argument is the name of
4432
the include file. (It is not called when there is no current include
4433
file.) The default definition is
4434
4435
@example
4436
\def\WIFfmt#1@{[@{\tt#1@}]@}
4437
@end example
4438
4439
4440
@node ATI_, ATK_, ATi, AT commands
4441
@comment node-name, next, previous, up
4442
4443
@subsection @samp{@@I}: Include file (conditional)
4444
4445
@findex @@I
4446
@cindex File, including web
4447
This command behaves like @samp{@@i} if the command-line option
4448
@samp{-i} is not used. If it is used, then the contents of the included
4449
file is not printed in the woven output.
4450
@xref{-i} and @ref{-i!}.
4451
4452
@node ATK_, ATk, ATI_, AT commands
4453
@comment node-name, next, previous, up
4454
4455
@subsection @samp{@@K}: Extract global RCS-like keyword
4456
4457
The construction @samp{@@K @i{Keyword} @@>} accesses the value of a global
4458
RCS-like keyword. (For more discussion of such keywords, see @ref{ATz}.)
4459
The command is treated differently by @FTANGLE{} and @FWEAVE{}
4460
depending on its location in the source file.
4461
4462
@FWEAVE{} will expand the construction
4463
in the limbo section and @TeX{} parts only. The value is not surrounded
4464
by quotes. For
4465
example,
4466
4467
@example
4468
@@z
4469
$Id: test $
4470
@@x
4471
4472
@@c
4473
4474
\def\ID@{Id = \.@{"@@K Id @@>"@}@}
4475
4476
@@ \ID. This is a @@K Id @@>.
4477
@end example
4478
@noindent
4479
will expand into
4480
4481
@example
4482
@@c
4483
4484
@@ \ID. This is a test.
4485
@end example
4486
@noindent
4487
and when La@TeX{} is run the macro @code{\ID} will expand to @samp{Id =
4488
\.@{"Test"@}}. The quotes are not necessary in the macro definition;
4489
they are included only to emphasize that in this (limbo) context the
4490
@samp{@@K} construction can effectively be put inside a string. This is
4491
possible because the routine that copies the limbo section simply copies
4492
characters; it does not tokenize anything.
4493
4494
@FWEAVE{} does not expand @samp{@@K} constructions in the definition
4495
or code parts; it merely gives them a symbolic representation.
4496
4497
@FTANGLE{}, on the other hand, expands @samp{@@K} constructions in the
4498
definition or code parts (during input). The values are surrounded by
4499
quotes. (As usual, @FTANGLE{} ignores material in the limbo section
4500
and @TeX{} parts.)
4501
4502
For @FTANGLE{}, the built-in function @samp{$KEYWORD}
4503
(@pxref{$KEYWORD}) behaves essentially as does @samp{@@K}, except that
4504
it is expanded during output, not input. @FWEAVE{} does not expand
4505
@samp{$KEYWORD}.
4506
4507
The command @samp{@@k} behaves as does @samp{@@K} except that it
4508
accesses local keywords, not global ones. @xref{ATk}.
4509
4510
@node ATk, ATL_, ATK_, AT commands
4511
@comment node-name, next, previous, up
4512
4513
@subsection @samp{@@k}: Access local RCS-like keyword
4514
4515
The construction @samp{@@k keyword} behaves as @samp{@@K} does
4516
(@pxref{ATK_}), except it accesses local keywords (defined at the top of
4517
include files).
4518
4519
@node ATL_, ATl, ATk, AT commands
4520
@comment node-name, next, previous, up
4521
4522
@subsection @samp{@@L}: Set language
4523
4524
@findex @@L
4525
@cindex Language, setting
4526
@samp{@@Ll} sets the language to @i{l}, where @i{l} is one of
4527
@samp{@{c,c++,n,n9,r,r9,v,x@}}.
4528
@xref{Languages}.
4529
4530
There are shorthand forms of this command for some languages; see
4531
@samp{@@c} (@ref{ATc}), @samp{@@c++} (@ref{ATcpp}), @samp{@@n}
4532
(@ref{ATn}), @samp{@@n9} (@ref{ATn9}), @samp{@@r} (@ref{ATr}), and
4533
@samp{@@r9} (@ref{ATr9}).
4534
4535
Generally, the global language should be set in the limbo section by
4536
means of @samp{@@L}, @samp{@@c}, etc.@ rather on the command line by
4537
options such as @samp{-L} or @samp{-c}.
4538
4539
@node ATl, ATM_, ATL_, AT commands
4540
@comment node-name, next, previous, up
4541
4542
@subsection @samp{@@l}: Specify limbo text
4543
4544
@findex @@l
4545
@emph{This command begins the definition part.}
4546
4547
Limbo text is material that @FWEAVE{} should output before
4548
the start of the first section.
4549
@cindex Limbo text
4550
For example,
4551
4552
@example
4553
@@l "\\def\\A@{abc@}"
4554
@end example
4555
@noindent
4556
Note that @samp{\\} stands for a backslash. In general, characters must be
4557
escaped just as in C [so that one can include things like @samp{\n}
4558
(newline) in the definitions].
4559
4560
Limbo text may also be typed directly into the limbo section; in that
4561
case, no escapes are necessary since one is typing ordinary @TeX{} text.
4562
Sometimes, however, the @samp{@@l} command is useful for pedagogical
4563
purposes, as the limbo material can then be defined at the point where
4564
the logical discussion is made.
4565
4566
@node ATM_, ATm, ATl, AT commands
4567
@comment node-name, next, previous, up
4568
4569
@subsection @samp{@@M}: Define @FWEB{} macro
4570
4571
@findex @@M
4572
@emph{This command begins the definition part.}
4573
4574
For a detailed discussion of @FWEB{} macros, see @ref{Macros}.
4575
4576
@node ATm, ATN_, ATM_, AT commands
4577
@comment node-name, next, previous, up
4578
4579
@subsection @samp{@@m}: Define @FWEB{} macro, and mark
4580
4581
@findex @@m
4582
@emph{This command begins the definition part.}
4583
4584
@samp{@@m} defines an @FWEB{} macro, and also marks the next identifier
4585
as defined here. It is equivalent to
4586
4587
@quotation
4588
@samp{@@m} == @samp{@@M@@[}
4589
@end quotation
4590
@noindent
4591
(@pxref{AT[}).
4592
4593
For a detailed discussion of @FWEB{} macros, see @ref{Macros}.
4594
4595
The distinction between @samp{@@m} and @samp{@@M} is analagous to the
4596
distinction between @samp{@@a} and @samp{@@A}. @xref{ATa}.
4597
4598
@node ATN_, ATn, ATm, AT commands
4599
@comment node-name, next, previous, up
4600
4601
@subsection @samp{@@N}: Turn on N mode
4602
4603
@findex @@N
4604
@emph{This command must appear before the code part.} Generally, this
4605
means immediately before @samp{@@a}. @emph{Do not use this command in
4606
limbo; use @samp{@@Lv} instead.}
4607
4608
The N mode invokes language-independent behavior within the scope of
4609
a particular language. The scoping rules are the same as for language
4610
changes; i.e., using @samp{@@N} within a given section produces
4611
language-independent behavior for that section and for any modules first
4612
referenced in that section.
4613
4614
Fundamentally, @dfn{language-independent} behavior essentially means a literal
4615
transcription of the input to the output. For example, it inhibits
4616
blank compression by @FTANGLE{} and tells @FWEAVE{} to turn off
4617
``pretty-printing'' (instead, the output is printed in typewriter type
4618
within a @samp{\begin@{verbatim@}...\end@{verbatim@}} environment).
4619
4620
There are some subtleties with this mode (not to mention the likelihood
4621
of bugs):
4622
4623
@enumerate
4624
@item
4625
@FWEB{} macros and built-in
4626
functions will normally be expanded even in the N mode. To inhibit
4627
expansion of a particular identifier, place @samp{@@!} before the
4628
identifier. For example,
4629
4630
@example
4631
@@
4632
@@m A 1
4633
@@N
4634
@@a
4635
@@!A = A;
4636
@end example
4637
4638
@noindent
4639
expands to @samp{A = 1}.
4640
4641
@item
4642
Blank lines are significant. The N mode is ended by the appearance of
4643
the @samp{@@*} or @ASP{} denoting the start of the next section. If
4644
that were preceded by one or more blank lines, those would show up in
4645
both the tangled and woven output. They might or might not be
4646
significant in the tangled output, but they almost certainly will look
4647
ugly in the woven output. To avoid this, use the command @samp{@@%%},
4648
which deletes the remainder of the current line and all immediately
4649
following empty lines. For example,
4650
4651
@example
4652
@@
4653
@@N
4654
@@a
4655
x;@@%%
4656
4657
4658
4659
@@ Next section.
4660
@end example
4661
4662
@item
4663
If the N mode is invoked from a compiler-like language such as @sc{Fortran},
4664
cross-referencing of variables is done as usual. However, if the
4665
language is @sc{verbatim} (which turns on the N mode automatically), no
4666
cross-referencing is done. (Identifiers are still recognized according
4667
to @FWEB{}'s rules. Those rules as currently implemented may be
4668
essentially meaningless for some languages; in the future, provision may
4669
be made for generalizing these rules by the user.) To force an
4670
identifier to be placed into the Index, precede it by @samp{@@+}.
4671
4672
@item
4673
A module name must be within the scope of an @samp{@@N} the first time
4674
the name is seen, if it is ever to be within such scope. Thus, the
4675
following does not work properly:
4676
4677
@example
4678
@@ Consider the module @@<Test@@>. (Not yet within scope of \.@{@@N@}.)
4679
@@N
4680
@@a
4681
x;
4682
@@<Test@@>@@;
4683
y;
4684
@end example
4685
@noindent
4686
What happens is that the N mode is not restored after the code-part use
4687
of @samp{@@<Test@@>}. This is a bug. There are very tricky design
4688
issues to be dealt with here.
4689
4690
@end enumerate
4691
4692
@node ATn, ATn9, ATN_, AT commands
4693
@comment node-name, next, previous, up
4694
4695
@subsection @samp{@@n}: Set language to @sc{Fortran}--77
4696
4697
@findex @@n
4698
@sc{Fortran}-77 is @FWEB{}'s default language, so this command is usually not
4699
strictly necessary. However, it is good practice to include it, so a
4700
user looking at the @code{web} file can tell immediately what language
4701
it is supposed to process.
4702
4703
For more discussion of languages, see @ref{ATL_} and @ref{Languages}.
4704
4705
@node ATn9, ATO_, ATn, AT commands
4706
@comment node-name, next, previous, up
4707
4708
@subsection @samp{@@n9}: Set language to @sc{Fortran}--90
4709
4710
@findex @@n9
4711
For more discussion of languages, see @ref{ATL_} and @ref{Languages}.
4712
4713
For hints about @FWEB{} programming in @sc{Fortran}, see @ref{Fortran}.
4714
4715
@node ATO_, ATo, ATn9, AT commands
4716
@comment node-name, next, previous, up
4717
4718
@subsection @samp{@@O}: Open output file (global scope)
4719
4720
@findex @@O
4721
@cindex File, opening output
4722
A statement of the form
4723
4724
@example
4725
@@O @i{new_output_file_name}
4726
@end example
4727
4728
@noindent
4729
changes the name of @FTANGLE{}'s output file. This change remains
4730
in effect for the duration of the file, or until another @samp{@@O} is
4731
encountered. (If that occurs, the previously open file is closed.)
4732
4733
This command is expanded during output, so it must appear in the code part.
4734
4735
For an example of using the @samp{@@O} command to produce both C header
4736
files (@samp{.h}) and source files (@samp{.c}), see the discussion in
4737
@ref{Outer macros}.
4738
4739
To change the name of the output file locally (for just the present
4740
section), see @ref{ATo}.
4741
4742
@node ATo, ATq, ATO_, AT commands
4743
@comment node-name, next, previous, up
4744
4745
@subsection @samp{@@o}: Open output file (local scope)
4746
4747
@findex @@o
4748
@cindex File, opening output
4749
This behaves like @samp{@@O}, except that the new file name is in effect only
4750
for the current section. A subsequent @samp{@@o} issued in a different
4751
section but for the same file name accretes material to the file.
4752
4753
An annoying problem arises in C programming when @samp{@@o}s are used to create
4754
multiple source files that are subsequently compiled under the control
4755
of a @code{Makefile}. Remember that by default line-number information
4756
is written into the C files. This means that a change in the @code{web}
4757
file code for one source file can affect all of the others, because the
4758
line numbering in the @code{web} file changes. Therefore, a trivial change to
4759
the code for just one source file can cause all of the others to be
4760
recompiled.
4761
4762
As long as one desires debugging information relative to the original
4763
@code{web} file, there is really no solution to this problem; one needs
4764
the proper line information in each file in order to work with the
4765
debugger, so if line numbers change the sources must be recompiled. One
4766
can, of course, turn off the line numbering with the command-line option
4767
@samp{-#} (@pxref{-#}), but then debugger statements will refer to the
4768
tangled C code, which is undesirable. A better partial solution is to
4769
use @samp{@@q} (@pxref{ATq}) to turn off the line numbering for output
4770
code that is currently stable. In the following example, the code for
4771
each file is put into a module, then the modules are output in the
4772
unnamed section; it is assumed that the programmer is currently
4773
making changes to the code for @file{file2.c}:
4774
4775
@example
4776
@@
4777
@@a
4778
@@q0
4779
@@o file1.c
4780
@@<File 1@@>@@;
4781
@@q1
4782
@@o file2.c
4783
@@<File 2@@>@@;
4784
@@q0
4785
@@o file3.c
4786
@@<File 3@@>@@;
4787
@end example
4788
4789
For very large projects, another solution is to maintain multiple
4790
@code{web} source files. To avoid losing the substantial benefits of
4791
the automatic index, refer to the discussion in @ref{Merging indexes} to
4792
learn how to create a master index that contains information about
4793
several @code{web} files.
4794
4795
4796
@node ATq, ATR_, ATo, AT commands
4797
@comment node-name, next, previous, up
4798
4799
@subsection @samp{@@q}: Turn off module and line info locally
4800
4801
@findex @@q
4802
@cindex Line numbering, turning off
4803
The command-line option @samp{-#} (@pxref{-#}) turns off comments about
4804
module and line numbers globally, for the entire code. However, in some
4805
cases one wants to turn that off in just a small block of code. One
4806
important example arises in @sc{Fortran}. Consider
4807
4808
@example
4809
@@
4810
@@a
4811
x = @@<Some action@@>
4812
4813
@@
4814
@@<Some action@@>=
4815
y + z
4816
@end example
4817
@noindent
4818
This example will tangle to something like
4819
4820
@example
4821
x =
4822
C* 1: *
4823
*line 20 "test.web"
4824
y + z
4825
C* :1 *
4826
*line 5 "test.web"
4827
@end example
4828
@noindent
4829
Unfortunately, the information comments have created invalid code that
4830
will not compile.
4831
4832
The @samp{@@q} command solves this problem by turning off or on the
4833
information comments locally. @samp{@@q0} turns them off; @samp{@@q1}
4834
turns them on. Thus, if one rewrites the above example as
4835
4836
@example
4837
@@
4838
@@a
4839
@@q0
4840
x = @@<Some action@@>
4841
@@q1
4842
@end example
4843
@noindent
4844
it will tangle to
4845
4846
@example
4847
x = y + z
4848
@end example
4849
@noindent
4850
as one desires.
4851
4852
For another use of the @samp{@@q} command, see @ref{ATo}.
4853
4854
@node ATR_, ATr, ATq, AT commands
4855
@comment node-name, next, previous, up
4856
4857
@subsection @samp{@@R}: Treat next identifier as integer-like reserved
4858
word (@FWEAVE{})
4859
4860
@findex @@R
4861
For formatting purposes, treat the next identifier as an integer-like
4862
reserved word.
4863
4864
This command is useful in pretty-printing certain kinds of macro
4865
constructions. Further discussion is given in @ref{Macros and
4866
formatting}.
4867
4868
@node ATr, ATr9, ATR_, AT commands
4869
@comment node-name, next, previous, up
4870
4871
@subsection @samp{@@r}: Set language to @sc{Ratfor}--77
4872
4873
@findex @@r
4874
@xref{ATL_} and @ref{Languages}.
4875
4876
@node ATr9, ATu, ATr, AT commands
4877
@comment node-name, next, previous, up
4878
4879
@subsection @samp{@@r9}: Set language to @sc{Ratfor}--90
4880
4881
@findex @@r9
4882
@xref{ATL_} and @ref{Languages}.
4883
4884
@node ATu, ATv, ATr9, AT commands
4885
@comment node-name, next, previous, up
4886
4887
@subsection @samp{@@u}: Undefine outer macro
4888
4889
@findex @@u
4890
@cindex Outer macros, undefining
4891
@emph{This command begins the definition part.}
4892
4893
@samp{@@u} is the inverse of @samp{@@d}. For example, in C the command
4894
@samp{@@u A} tangles to @samp{#undef A}.
4895
4896
@node ATv, ATW_, ATu, AT commands
4897
@comment node-name, next, previous, up
4898
4899
@subsection @samp{@@v}: Overload operator
4900
4901
@findex @@v
4902
@cindex Operators, overloading
4903
@emph{This command begins the definition part.}
4904
4905
@samp{@@v} is used to change the woven appearance of an operator. If
4906
one defines a new operator, for example by a statement such as
4907
4908
@example
4909
interface operator(.BETA.)
4910
@end example
4911
@noindent
4912
in @sc{Fortran}-90, one should also use an @samp{@@v} in the definition
4913
part---for example,
4914
4915
@example
4916
@@v .BETA. "\\beta" +
4917
@end example
4918
@noindent
4919
For a detailed discussion of overloading (the output appearance of)
4920
operators, see @ref{Overloading}.
4921
4922
@node ATW_, ATx, ATv, AT commands
4923
@comment node-name, next, previous, up
4924
4925
@subsection @samp{@@W}: Overload identifier
4926
4927
@findex @@W
4928
@cindex Identifiers, overloading
4929
@emph{This command begins the definition part.}
4930
4931
For a detailed discussion of overloading (the output appearance of)
4932
identifiers, see @ref{Overloading}.
4933
4934
@node ATx, ATy, ATW_, AT commands
4935
@comment node-name, next, previous, up
4936
4937
@subsection @samp{@@x}: Terminate ignorable material, or begin material to be changed
4938
4939
@findex @@x
4940
In a change file, this command begins material to be changes; see
4941
@ref{Change files}.
4942
4943
In @code{web} source files, this command has a different use;
4944
see the discussion of the @samp{@@z} command (@pxref{ATz}).
4945
4946
@node ATy, ATz, ATx, AT commands
4947
@comment node-name, next, previous, up
4948
4949
@subsection @samp{@@y}: Begin change material
4950
4951
@findex @@y
4952
The @samp{@@y} command is permitted only in change files. @xref{Change
4953
files}.
4954
4955
@node ATz, ATquote, ATy, AT commands
4956
@comment node-name, next, previous, up
4957
4958
@subsection @samp{@@z}: Begin ignorable material, or terminate change
4959
4960
@findex @@z
4961
@FWEB{} files may begin with the construction
4962
4963
@example
4964
@@z
4965
.
4966
.
4967
@@x
4968
@end example
4969
4970
@noindent
4971
where the @samp{@@z} occupies the very first two characters of the file, and
4972
where the @samp{@@z} and @samp{@@x} must begin in column 1.
4973
Material between the @samp{@@z} and @samp{@@x} is @dfn{pure commentary} and is
4974
ignored by both processors, with one exception.
4975
4976
@findex @@K
4977
@findex @@k
4978
@findex $KEYWORD
4979
@findex $L_KEYWORD
4980
@cindex RCS-like keyword
4981
@cindex Keyword, RCS-like
4982
The exception is that an RCS-like line (RCS stands for
4983
``revision-control system'') with syntax
4984
4985
@example
4986
$Keyword: Text of Keyword $
4987
@end example
4988
@noindent
4989
(at least one blank after the colon, and at least one before the last
4990
dollar sign; @sc{unix} users, see @samp{man ident}) is parsed, and the
4991
text of the @code{Keyword} is made
4992
available to the control codes @samp{@@K} (@pxref{ATK_}) and @samp{@@k}
4993
(@pxref{ATk}) as well as to @FTANGLE{}'s built-in function @code{$KEYWORD}
4994
(@pxref{$KEYWORD}.
4995
4996
A distinction is made between keywords that are found in the ignorable
4997
commentary at the beginning of the master web file, which are called
4998
@dfn{global keywords}, and ones that are found at the beginning of files
4999
included via @samp{@@i}, which are called @dfn{local keywords}.
5000
5001
The commands that access RCS-like keywords function as follows:
5002
5003
@quotation
5004
@itemize @bullet
5005
@item
5006
@samp{$KEYWORD(Keyword)} accesses a global keyword. It is a built-in
5007
function that is
5008
expanded by @FTANGLE{} (during output) into the quoted character
5009
string @code{"Text of Keyword"}.
5010
5011
@item
5012
@samp{@@K} and @samp{@@k} are expanded during input. @samp{@@K}
5013
accesses a global keyword, whereas @samp{@@k} accesses a local keyword.
5014
5015
@item
5016
In the limbo section or a @TeX{} part, @FWEAVE{} will expand @samp{@@K
5017
Keyword @@>} into @code{Text of Keyword} (without the surrounding
5018
quotes), and similarly for @samp{@@k}. (The intention is that the
5019
expanded text can be used as bodies of @TeX{} macros.)
5020
@FWEAVE{} will also print the
5021
values of global keywords at the end of its output, whether or not they
5022
are referenced by @samp{@@K}.
5023
5024
@item
5025
Elsewhere @FWEAVE{} will just print the keyword name itself,
5026
surrounded by double angle brackets. If the keyword was local
5027
(@samp{@@k}), the brackets will carry the subscript 0.
5028
5029
@item
5030
@FTANGLE{} treats the global command @samp{@@K Keyword @@>}
5031
essentially like it does @samp{$Keyword}, except that the construction
5032
is expanded on input rather than output.
5033
5034
@item
5035
@FTANGLE{} expands the command @samp{@@k keyword @@>} on input,
5036
generating a quoted string containing the value of the local keyword.
5037
5038
@end itemize
5039
@end quotation
5040
5041
The command @samp{@@z} is also used in change files to end a change.
5042
@xref{Change files}.
5043
5044
@node ATquote, ATdquote, ATz, AT commands
5045
@comment node-name, next, previous, up
5046
5047
@section Conversion to ASCII
5048
5049
@cindex ASCII, converting to
5050
Several commands are useful for generating machine-independent code.
5051
For example, @FWEB{} works internally with the ASCII character set, so
5052
uses these commands heavily to convert from the possibly non-ASCII
5053
native character set of the machine on which @FWEB{} is running.
5054
5055
@subsection @samp{@@'}: Convert character to ASCII
5056
5057
@findex @@'
5058
The construction @samp{@@'c'} converts @samp{c} to its ASCII value. In
5059
C and C++, it is converted to octal; for example, @samp{@@'A'} is output
5060
as @samp{0101}. In @sc{Fortran} and @sc{Ratfor}, it is converted to decimal; the
5061
previous example would be output as @samp{65}.
5062
5063
If the native character set of one's machine is ASCII, the conversion
5064
will not be done unless the @samp{-A} command-line option is used.
5065
@xref{-A_}.
5066
5067
@node ATdquote, AT[, ATquote, AT commands
5068
@comment node-name, next, previous, up
5069
5070
@subsection @samp{@@"}: Convert string to ASCII
5071
5072
@findex @@"
5073
The construction @samp{@@"abc"} converts the enclosed string to its ASCII
5074
representation. For example, in C and C++
5075
@samp{@@"abc"} will be output as @samp{"\141\142\143"}.
5076
5077
@findex ASCIIstr
5078
In @sc{Fortran} and @sc{Ratfor}, no such simple mechanism exists in the
5079
language, so a function call is issued. For example, the previous
5080
example would be output as @samp{ASCIIstr('abc')}. The user is
5081
responsible for defining the function @samp{ASCIIstr}. The name of this
5082
function can be changed by the style-file entry @samp{ASCII_fcn}.
5083
@xref{ASCII_fcn}.
5084
5085
If the native character set of one's machine is ASCII, the conversion
5086
will not be done unless the @samp{-A} command-line option is used.
5087
@xref{-A_}.
5088
5089
@node AT[, AT/*, ATdquote, AT commands
5090
@comment node-name, next, previous, up
5091
5092
@section Forward referencing
5093
5094
@cindex References, forward
5095
5096
@subsection @samp{@@[}: Mark as defined
5097
5098
@findex @@[
5099
This command marks the next (non-reserved) identifier that appears after
5100
the @samp{@@[} as being defined in the current section. It is usually
5101
issued automatically; for example, @samp{@@a} is equivalent to
5102
@samp{@@A@@[}, @samp{@@d} is equivalent to @samp{@@D@@[}, and @samp{@@m}
5103
is equivalent to @samp{@@M@@[}.
5104
5105
If the appropriate style-file parameter @code{mark_defined.???} is 1,
5106
this command causes any appearance of the identifier to be subscripted
5107
with a section number. For more information, see @ref{Subscript params}.
5108
5109
The utility of this command can be seen from the characteristic
5110
construction
5111
5112
@example
5113
@@ This is section 5.
5114
@@a @@% Issues an implicit @@[, which marks |test| as defined in section 5.
5115
subroutine test
5116
...
5117
end
5118
5119
@@ This is section 6.
5120
@@a
5121
program main
5122
call test // This will print as $|test|_5$.
5123
end
5124
@end example
5125
5126
The @samp{@@[} command should be distinguished from @samp{@@_}
5127
(@pxref{AT_}). The
5128
latter causes the index entry for the identifier to be underlined; the
5129
former possibly causes the identifier to be subscripted by a section
5130
number. One may wish to turn off the subscripts because they become too
5131
cluttered; however, the underlined index entries remain useful and
5132
unobtrusive.
5133
5134
@node AT/*, AT//, AT[, AT commands
5135
@comment node-name, next, previous, up
5136
5137
@section Comments
5138
5139
@FWEB{} supports a variety of commenting styles borrowed from C, C++,
5140
and @TeX{}. For more discussion, see @ref{Comments}.
5141
5142
@cindex Comments
5143
5144
@subsection @samp{@@/*}: Begin long verbatim comment
5145
5146
@findex @@/*
5147
The following comment is copied to the tangled output. (By default,
5148
comments are not copied.) If you desire all comments to be so copied,
5149
use @samp{-v}. @xref{-v}.
5150
5151
@node AT//, AT%, AT/*, AT commands
5152
@comment node-name, next, previous, up
5153
5154
@subsection @samp{@@//}: Begin short verbatim comment
5155
5156
@findex @@//
5157
See the discussion of @samp{@@/*} in @ref{AT//}.
5158
5159
@node AT%, AT?, AT//, AT commands
5160
@comment node-name, next, previous, up
5161
5162
@subsection @samp{@@%}: Ignorable comment
5163
5164
@findex @@%
5165
@findex @@%%
5166
@cindex Comments, ignorable
5167
If any line in a web source code contains the command @samp{@@%}, all
5168
remaining material on that line (to and including the newline character)
5169
is ignored by the input driver and never processed at all.
5170
5171
A stronger form of this command is @samp{@@%%}. This deletes the
5172
current line as well any empty lines that immediately follow. This command
5173
is particularly useful when the N mode is in effect. @xref{ATN_}.
5174
5175
Line-numbering problems can arise when these commands are used. For a
5176
discussion, see @ref{-T#}.
5177
5178
@node AT?, ATlp, AT%, AT commands
5179
@comment node-name, next, previous, up
5180
5181
@subsection @samp{@@?}: Begin compiler directive
5182
5183
@findex @@?
5184
@cindex Compiler directives
5185
The remainder of the line is processed as a compiler directive. Optional
5186
material may be inserted automatically at the beginning of the tangled
5187
output line by means of the style-file option @code{cdir_start}.
5188
@xref{Miscellaneous params}.
5189
5190
@node ATlp, AT), AT?, AT commands
5191
@comment node-name, next, previous, up
5192
5193
@subsection @samp{@@(}: Begin meta-comment
5194
5195
@findex @@(
5196
Material between @samp{@@(} and @samp{@@)} is treated in the N mode.
5197
For example,
5198
5199
@example
5200
@@(
5201
Comment 1
5202
Comment 2
5203
@@)
5204
@end example
5205
5206
Style-file parameters allow optional material to be insert at the
5207
beginning and end of the meta-comment, and at the beginning of each line
5208
of output. For more information, see the style-file parameters
5209
beginning with @samp{meta} (@pxref{Miscellaneous params}).
5210
5211
@node AT), ATlb, ATlp, AT commands
5212
@comment node-name, next, previous, up
5213
5214
@subsection @samp{@@)}: End meta-comment
5215
5216
@findex @@)
5217
See the discussion of @samp{@@(}, @ref{ATlp}.
5218
5219
@node ATlb, AT_, AT), AT commands
5220
@comment node-name, next, previous, up
5221
5222
@section Special left brace
5223
5224
The command @samp{@@@{} is useful in C/C++ programming to beautify some
5225
of the pretty-printing. It translates into a left brace, but also
5226
suppresses the automatic insertion of newlines into the subsequent
5227
function body or block. This is desirable for very short functions, such
5228
as simple constructors in C++. For example,
5229
5230
@example
5231
class C
5232
@{
5233
private:
5234
int i;
5235
5236
public:
5237
C(int i0) @@@{i = i0;@}
5238
@}
5239
@end example
5240
@noindent
5241
Here the function will be typeset as
5242
5243
@example
5244
C(int i0)
5245
@{ i = i0; @}
5246
@end example
5247
@noindent
5248
rather than the default
5249
5250
@example
5251
C(int i0)
5252
@{
5253
i = i0;
5254
@}
5255
@end example
5256
5257
@node AT_, AT-, ATlb, AT commands
5258
@comment node-name, next, previous, up
5259
5260
@section Index entries
5261
5262
@cindex Indexing commands
5263
Although most information for the Index is gathered automatically, in
5264
some situations it must be done by hand.
5265
5266
@subsection @samp{@@_}: Force index entry to be underlined
5267
5268
@findex @@_
5269
@cindex Index entries, underlining
5270
This command applies to the next identifier that appears after the
5271
@samp{@@_}. The index entry for that identifier will be underlined.
5272
(By convention, this means `defined' or `declared'.)
5273
5274
This command is usually issued automatically. For example, the index
5275
entries for the variables @samp{i} and @samp{j} in the C statement
5276
@samp{int i, j;} will be underlined, since @FWEAVE{} understands
5277
enough of the syntax to know that variables are being defined. Macro
5278
definitions (begun by
5279
@samp{@@D} or @samp{@@M}) will also be underlined automatically.
5280
5281
@node AT-, ATplus, AT_, AT commands
5282
@comment node-name, next, previous, up
5283
5284
@subsection @samp{@@-}: Delete index entry
5285
5286
@findex @@-
5287
@cindex Index entries, deleting
5288
This command applies to the next identifier that appears after the
5289
@samp{@@-}; it prevents an index entry associated with that identifier
5290
from being made. This might be useful when the N mode is in effect.
5291
5292
@node ATplus, AT^, AT-, AT commands
5293
@comment node-name, next, previous, up
5294
5295
@subsection @samp{@@+}: Force index entry
5296
5297
@findex @@+
5298
@cindex Index entries, forcing
5299
This command applies to the next identifier that appears after the
5300
@samp{@@+}; it forces an index entry for that identifier. It is
5301
particularly useful when the language is @sc{verbatim}, since
5302
cross-referencing is turned off in that case.
5303
5304
@node AT^, ATdot, ATplus, AT commands
5305
@comment node-name, next, previous, up
5306
5307
@subsection @samp{@@^}: Make index entry (Roman type)
5308
5309
@findex @@^
5310
@cindex Index entries, Roman type
5311
To insert one's own index entry in Roman type, say @samp{@@^@i{My entry}@@>}.
5312
5313
@node ATdot, AT9, AT^, AT commands
5314
@comment node-name, next, previous, up
5315
5316
@subsection @samp{@@.}: Make index entry (typewriter type)
5317
5318
@findex @@.
5319
@cindex Index entries, typewriter type
5320
To insert one's own index entry in typewriter type, say @samp{@@.@i{My
5321
entry}@@>}.
5322
5323
@node AT9, ATt, ATdot, AT commands
5324
@comment node-name, next, previous, up
5325
5326
@subsection @samp{@@9}: Make index entry (user-defined format)
5327
5328
@findex @@9
5329
@cindex Index entries, user format
5330
The construction @samp{@@9@i{Text}@@>} is used to create an index entry in a
5331
format defined by the user. It is associated with the macro @code{\9}, which
5332
will be called during @TeX{}'s processing of the Index as
5333
@code{\9@{@i{Text}@}}. The user must define @code{\9} according to the format
5334
5335
@example
5336
\def\9#1@{...@}
5337
@end example
5338
@noindent
5339
where argument @samp{#1} is the text between @samp{@@9} and @samp{@@>}.
5340
For example, to print that text in a sans serif font, say
5341
5342
@example
5343
\def\9#1@{@{\sf #1@}@}
5344
@end example
5345
@noindent
5346
(Note the extra level of braces to prevent the font command from propagating.)
5347
5348
@node ATt, AT=, AT9, AT commands
5349
@comment node-name, next, previous, up
5350
5351
@section Control text
5352
5353
@cindex Control text
5354
@cindex Text, control
5355
@dfn{Control text} is material terminated by @samp{@@>}; it must be all
5356
on one line and must not contain any @samp{@@}s.
5357
5358
@subsection @samp{@@t}: Put control text into a @TeX{} \hbox (@FWEAVE{})
5359
5360
@findex @@t
5361
When @FWEAVE{} sees the command @samp{@@t@i{control text}@@>}, it packages
5362
the control text into an @code{\hbox} and ships it to the output. This
5363
command is ignored by @FTANGLE{}.
5364
5365
@node AT=, ATcomma, ATt, AT commands
5366
@comment node-name, next, previous, up
5367
5368
@subsection @samp{@@=}: Pass control text verbatim to the output
5369
5370
@findex @@=
5371
For @FTANGLE{}, the command @samp{@@=@i{control text}@@>} sends the control
5372
text to the output exactly as input. @FWEAVE{} highlights the control
5373
text by drawing a box around it.
5374
5375
@node ATcomma, AT/, AT=, AT commands
5376
@comment node-name, next, previous, up
5377
5378
@section Spacing
5379
5380
@cindex Spacing commands
5381
5382
The spacing commands are used to refine @FWEAVE{}'s pretty-printed
5383
output. Generally it's not necessary to bother with these until one is
5384
putting the final touches on a code.
5385
5386
@subsection @samp{@@,}: Insert a thin space
5387
5388
@findex @@,
5389
@cindex Spacing, thin space
5390
Extra spacings are sometimes necessary when working with unusual macro
5391
constructions. @samp{@@,} inserts a thin space, analogous to @TeX{}'s
5392
@code{\,}.
5393
5394
An example where explicit spacing would be necessary is as follows:
5395
5396
@example
5397
@@c
5398
@@
5399
@@m OP +
5400
@@m A(x,y) x @@, OP @@, y
5401
5402
@@a
5403
z = A(a, b);
5404
@end example
5405
5406
@noindent
5407
Without the @samp{@@,}'s, the body of the @code{A} macro will weave as
5408
the unappealing @samp{xOPy}. This occurs because although @code{OP} is
5409
defined to be a binary operator, @FWEAVE{} thinks of it as just a mere
5410
expression, and one of its fundamental production rules is to
5411
concatenate expressions with no intervening expressions.
5412
5413
This demonstrates that situations arise in which one needs to override
5414
@FWEAVE{}'s default processing. But for the above example, there is
5415
actually a better solution. Instead of using the @samp{@@,}'s, include
5416
the format command @samp{@@f OP $_BINOP_}. @xref{ATf}.
5417
5418
@node AT/, ATbs, ATcomma, AT commands
5419
@comment node-name, next, previous, up
5420
5421
@subsection @samp{@@/}: Force a line break, preserving indentation.
5422
5423
@findex @@/
5424
@cindex Line break, forcing
5425
This command is used to override @FWEAVE{}'s natural inclinations.
5426
For example, if one wants each piece of a declaration to appear on a
5427
separate line, one can say
5428
5429
@example
5430
int@@/
5431
i,@@/
5432
j,@@/
5433
k;
5434
@end example
5435
5436
This command preserves the natural indentation that would have happened
5437
if @FWEAVE{} or La@TeX{} had broken a long line spontaneously. Thus, the
5438
declared variables are indented in the above example. To remove that
5439
indent, use @samp{@@\} instead. @xref{ATbs}.
5440
5441
Try to use the line-break commands sparingly---i.e., let @FWEAVE{} do
5442
the work.
5443
Often, if lines run together in an unexpected or unreadable way,
5444
it's because @FWEAVE{} wasn't able to parse the relevant block of
5445
code, perhaps because it didn't understand that some variable in an
5446
include file has a special meaning. In such cases, trying to fix things
5447
with @samp{@@/} is the wrong solution. Either use @samp{@@f}
5448
(@pxref{ATf}) or @samp{-H} (@pxref{-H_}).
5449
5450
Distinguish the @samp{@@/} command from @samp{@@|} (@pxref{AT|}), which
5451
inserts an optional breakpoint into an expression.
5452
5453
@node ATbs, AT|_, AT/, AT commands
5454
@comment node-name, next, previous, up
5455
5456
@subsection @samp{@@\}: Force a line break, then indent
5457
5458
@findex @@\
5459
@cindex Line break, forcing with indent
5460
The @samp{@@\} command behaves like @samp{@@/} (@pxref{AT/}), except
5461
that it backspaces one notch after the line break. This usually has the
5462
effect of undoing the natural indentation that would have been inserted
5463
had a long line been spontaneously broken. One common case where the
5464
@samp{@@\} command might be used would be to put the return type of a C
5465
function on a separate line:
5466
5467
@example
5468
int @@\
5469
main()
5470
@{@}
5471
@end example
5472
5473
It would be nice to have @FWEAVE{} do that automatically.
5474
Unfortunately, the syntax of a function isn't recognized until the
5475
opening braces are sensed; by that time, the declaration part of the
5476
statement has already been processed. This is one example of the fact
5477
that the @FWEB{} processors are much less intelligent and sophisticated
5478
than language compilers. A clever (and simple) idea for getting around
5479
this kind of problem is lacking at this point.
5480
5481
@node AT|_, AT#, ATbs, AT commands
5482
@comment node-name, next, previous, up
5483
5484
@subsection @samp{@@|}: Literal vertical bar, or optional line break
5485
5486
@findex @@|
5487
@cindex Bar, vertical
5488
@cindex Vertical bar
5489
In the @TeX{} (documentation) part of a section, @samp{@@|} inserts a
5490
vertical bar. Here's a La@TeX{} example:
5491
5492
@example
5493
\begin@{verbatim@}
5494
The constructions @@|x@@| and |x| are very different.
5495
\end@{verbatim@}
5496
@end example
5497
5498
@noindent
5499
You might wish to try this out to see what @FWEAVE{} produces.
5500
5501
@cindex Line break, optional
5502
In a code part, @samp{@@|} inserts an optional line break in an expression.
5503
5504
@node AT#, AT~, AT|_, AT commands
5505
@comment node-name, next, previous, up
5506
5507
@subsection @samp{@@#}: Blank line
5508
5509
@findex @@#
5510
@samp{@@#} forces a line break with some extra vertical white space.
5511
However, note
5512
that @emph{blank lines in the source are significant}, so this command should
5513
seldom if ever be necessary.
5514
5515
if @samp{@@#} is immediately followed by a letter (e.g., @samp{@@#if}),
5516
it is assumed that a preprocessor command is beginning. @xref{Preprocessing}.
5517
5518
5519
@node AT~, AT&, AT#, AT commands
5520
@comment node-name, next, previous, up
5521
5522
@subsection @samp{@@~}: Cancel line break
5523
5524
@findex @@~
5525
@cindex Line break, canceling
5526
@samp{@@~} is analogous to @TeX{}'s @samp{~} (tie); it prevents a line
5527
break, which @FWEAVE{} usually inserts after each complete statement
5528
it recognizes. For example,
5529
5530
@example
5531
printf("Working..."); @@~ fflush(stdout);
5532
x = y; @@~ break;
5533
@end example
5534
5535
@node AT&, ATe, AT~, AT commands
5536
@comment node-name, next, previous, up
5537
5538
@subsection @samp{@@&}: Join items
5539
5540
@findex @@&
5541
@cindex Joining items
5542
@cindex Items, joining
5543
During @FWEAVE{}'s output, @samp{@@&} joins the items to either side
5544
with no spaces or line breaks inbetween.
5545
5546
This command must be distinguished from the preprocessor construction
5547
@code{##} (paste tokens together). In a macro definition, @samp{a##bc}
5548
creates the single identifier @samp{abc}. If one said @samp{a@@&bc},
5549
two identifiers would be output with no spaces separating them. In
5550
simple cases, the results may look identical, but consider how things
5551
would differ if @code{abc} were itself an @FWEB{} macro that should
5552
itself be expanded.
5553
5554
@node ATe, AT;, AT&, AT commands
5555
@comment node-name, next, previous, up
5556
5557
@section Pseudo (invisible) operators
5558
5559
@cindex Pseudo-operators
5560
@cindex Operators, pseudo-
5561
Pseudo- or invisible operators are ignored by @FTANGLE{} and not
5562
printed by @FWEAVE{}; however, they retain grammatical significance
5563
that helps out @FWEAVE{} in its attempts to understand the syntax.
5564
5565
@subsection @samp{@@e}: Pseudo-expression
5566
5567
@cindex Pseudo-expression
5568
@cindex Expression, pseudo
5569
@findex @@e
5570
@samp{@@e} is an invisible expression (`pseudo-expression')
5571
(@pxref{Pseudo-operators}). It is
5572
sometimes useful in situations where @FWEAVE{}'s pretty-printing has
5573
broken down because it didn't properly understand the language syntax.
5574
If, for example, @FWEAVE{} failed to properly parse the C statement
5575
5576
@example
5577
p = (int (*))q;
5578
@end example
5579
5580
@noindent
5581
one might get things to work properly by saying
5582
5583
@example
5584
p = (int (*@@e))q;
5585
@end example
5586
5587
In this particular case, one is patching up a deficiency (all right, a
5588
bug) in @FWEAVE{}'s ``production rules.'' (This particular bug may no
5589
longer exist.) However, there are other situations in which the use of
5590
@samp{@@e} might be necessary. Consider, for example, the C macro
5591
definition
5592
5593
@example
5594
#define A(x) = x
5595
@end example
5596
@noindent
5597
Here the replacement text of the macro is @samp{= x}, which by itself is
5598
not a valid construction in C. When the @samp{-1} or @samp{-2} options
5599
are used, @FWEAVE{} will report an ``irreducible
5600
scrap sequence'' in this situation (although it may typeset it correctly
5601
anyway). To eliminate the warning message, say instead
5602
5603
@example
5604
#define A(x) @@e = x
5605
@end example
5606
@noindent
5607
Now the fragment @samp{@@e = x} is interpreted as a valid expression.
5608
5609
@node AT;, ATcolon, ATe, AT commands
5610
@comment node-name, next, previous, up
5611
5612
@subsection @samp{@@;}: Pseudo-semicolon
5613
5614
@cindex Pseudo-semicolon
5615
@cindex Semicolon, pseudo
5616
@findex @@;
5617
@samp{@@;} is an invisible semicolon. These are often used in C
5618
programming to terminate a module name that expands to a compound
5619
statement. Carefully compare the uses of @samp{@@;} and @samp{;} in the
5620
following example:
5621
5622
@example
5623
@@c
5624
@@a
5625
if(flag)
5626
@@<Compound statement@@>@@;
5627
else
5628
@@<Simple statement@@>;
5629
5630
@@ This compound statement ends with a brace, but is used as an
5631
expression above.
5632
@@<Com...@@>=
5633
5634
@{
5635
x;
5636
y;
5637
@}
5638
5639
@@ This fragment does not end with a semicolon, so one must be
5640
supplied above.
5641
5642
@@<Sim...@@>=
5643
z
5644
@end example
5645
5646
Here is a case for which the pseudo-semicolon is not necessary. Consider
5647
5648
@example
5649
@@c
5650
@@ The code fragment |x = y| ...
5651
@end example
5652
@noindent
5653
If the @samp{-1} is turned on, one might think that @FWEAVE{} would
5654
report an ``irreducible scrap sequence'' because @samp{x = y} is an
5655
expression but not a complete statement. (Turning on @samp{-2}
5656
demonstrates this.) However, it is not necessary to say @samp{|x = y@@;|}
5657
because the warning message is not issued if the parsing reduces to just
5658
one unresolved scrap.
5659
5660
On the other hand, @samp{|goto done|} does not reduce to just one
5661
unresolved scrap, so say @samp{|goto done@@;|} in cases such as this.
5662
@xref{Pseudo-operators}.
5663
5664
In some situations, pseudo-semicolons are inserted automatically. An
5665
important case is free-format @sc{Fortran}-90. There the language
5666
syntax says that newlines terminate statements (except when there's a
5667
trailing ampersand). However, newlines are thrown away before tokenized
5668
text is seen by @FWEAVE{}'s parser (and in any event would just be
5669
interpreted as white space). Therefore, by default newlines that
5670
terminate statements are replaced by pseudo-semicolons, so the parsing
5671
proceeds correctly.
5672
5673
In the @sc{Fortran}-90 case, one could also insert pseudo-semicolons or
5674
actual semicolons by hand, and some users prefer that. The
5675
possibilities are controlled by the options @samp{-n@@;} (@pxref{-nAT;})
5676
and @samp{-n;} (@pxref{-n;}).
5677
@findex -n@@;
5678
@findex -n;
5679
@cindex Pseudo-semicolons, automatic
5680
@cindex Automatic pseudo-semicolons
5681
5682
@node ATcolon, AT!, AT;, AT commands
5683
@comment node-name, next, previous, up
5684
5685
@subsection @samp{@@:}: Pseudo-colon
5686
5687
@cindex Pseudo-colon
5688
@cindex Colon, pseudo
5689
@findex @@:
5690
@samp{@@:} is an invisible colon (@pxref{Pseudo-operators}).
5691
It can be helpful in formatting certain C constructions correctly. For
5692
example, if one has a named module defined as
5693
5694
@example
5695
@@<Cases@@>=
5696
case 1:
5697
case 2:
5698
case 3@@: @@;
5699
@end example
5700
5701
@noindent
5702
then one can use it as a case construction followed by the usual colon,
5703
as in
5704
5705
@example
5706
switch(c)
5707
@{
5708
@@<Cases@@>:
5709
stuff;
5710
break;
5711
@}
5712
@end example
5713
5714
@node AT!, , ATcolon, AT commands
5715
@comment node-name, next, previous, up
5716
5717
@section Miscellaneous commands
5718
5719
@subsection @samp{@@!}: Inhibit macro expansion
5720
5721
@findex @@!
5722
@cindex Macros, inhibiting expansion of
5723
@FWEB{} macros and built-in functions are always expanded by default.
5724
This may not be desirable, particularly in the N mode. To inhibit
5725
expansion of an individual identifier, preface it by @samp{@@!}.
5726
5727
@node Comments,Languages,AT commands,Top
5728
5729
5730
@comment node-name, next, previous, up
5731
5732
@chapter COMMENTING STYLES
5733
5734
@FWEB{} allows a variety of commenting styles. The visible comments are in
5735
the font @code{\cmntfont}, which defaults to @code{\mainfont}, a
5736
ten-point Roman font.
5737
@cindex Commenting styles
5738
@cindex Comments
5739
5740
@menu
5741
* Invisible comments:: Skipping input material.
5742
* Visible comments:: Comments in code mode.
5743
* Temporary comments:: Temporarily commenting out code.
5744
@end menu
5745
5746
@node Invisible comments,Visible comments,Comments,Comments
5747
@comment node-name, next, previous, up
5748
5749
@section Invisible comments
5750
5751
@cindex Comments, invisible
5752
@table @code
5753
@item @@z...@@x
5754
If a source or include file begins with @samp{@@z} (in the very first
5755
two characters of the file), then all material is skipped until and
5756
including a line beginning in column 1 with @samp{@@x} [except that
5757
lines of the form @w{@samp{$Keyword: text of keyword $}} are processed; see
5758
@ref{$KEYWORD}, @ref{ATK_} (source files), or @ref{ATk} (include
5759
files)].
5760
5761
@item @@%
5762
All material until and including the next newline is completely ignored.
5763
5764
@item @@%%
5765
As @samp{@@%}, but also skip blank lines that immediately follow the current line.
5766
@end table
5767
5768
For example,
5769
5770
@example
5771
@@z
5772
Author: J. A. Krommes
5773
@@x
5774
@@c @@% This sets the global language to C.
5775
@@* EXAMPLE.
5776
@end example
5777
5778
@node Visible comments, Temporary comments, Invisible comments, Comments
5779
@comment node-name, next, previous, up
5780
5781
@section Visible comments
5782
5783
@cindex Comments, visible
5784
5785
@samp{/* ... */} is a long comment (it may extend over several lines).
5786
5787
@samp{// ...} is a short comment (terminated by the next newline).
5788
5789
@samp{@@(...@@)} is a meta-comment. Meta-comments are a localized form
5790
of the N mode (@pxref{Languages}). Tangled meta-comments are begun by
5791
the contents of the style-file entry @samp{meta.top} and terminated by
5792
@samp{meta.bottom}. Each line of the meta-comment is begun by
5793
@samp{meta.prefix}. Woven meta-comments are begun by
5794
@samp{meta_code.begin} and ended by @samp{meta_code.end}.
5795
@xref{Miscellaneous params}.
5796
5797
@example
5798
@@n
5799
@@a
5800
program main
5801
/* Get input. */
5802
call get_input // Read the parameter file.
5803
/* Process information. Comments like this
5804
can be split over several lines. */
5805
@@(
5806
Meta-comments provide a poor-person's alignment feature
5807
i --- counter
5808
x --- data value
5809
@@)
5810
i = 1
5811
x = 2.0
5812
call exec(i,x)
5813
end
5814
@end example
5815
5816
@emph{The use of meta-comments is not recommended;} they are only
5817
marginally supported. Use ordinary long comments
5818
instead. Inside of them, use the various powerful features of @TeX{} or
5819
La@TeX{} (such as @code{\halign} or
5820
@code{\begin@{verbatim@}} @code{...} @code{\end@{verbatim@}}) to format
5821
your comment appropriately.
5822
5823
@node Temporary comments, , Visible comments, Comments
5824
@comment node-name, next, previous, up
5825
5826
@section Temporary comments
5827
5828
@cindex Comments, temporary
5829
@cindex Code, temporarily commenting out
5830
5831
During development, one frequently desires to temporarily comment out a
5832
section of code. C programmers sometimes try to do this by enclosing the
5833
code in @code{/*...*/}, but this is @emph{not} good
5834
style for several reasons. First, it is impossible if the code itself
5835
includes comments, since comments do not nest in C. Second, @FWEAVE{}
5836
will treat the commented code as @TeX{} rather than C code and will (at best)
5837
format it very poorly. In fact, La@TeX{} will frequently complain,
5838
because the commented code might contain characters such as underscores
5839
that @TeX{} expects to be in math mode. (Those are dealt with
5840
automatically when @FWEAVE{} is in code mode.) The trivial example
5841
@w{@samp{/* a_b; */}} is sufficient to illustrate this point.
5842
5843
The proper way of commenting out sections of code is to use preprocessor
5844
constructions: @code{#if 0...#endif} in C, or more generally @code{@@#if
5845
0...@@#endif} (usable in all languages). (The @FWEB{} preprocessor is
5846
described in @ref{Preprocessing}.) With this method, there is no
5847
trouble with nested comments, and @FWEAVE{} will continue to format
5848
the code as code, so the documentation will make sense.
5849
5850
For @sc{Fortran} programmers converting an existing code to @FWEB{},
5851
the @samp{-nC} option (@pxref{-nC}) may be helpful.
5852
5853
@node Macros,Ratfor,Languages,Top
5854
@comment node-name, next, previous, up
5855
5856
@chapter MACROS and PREPROCESSING
5857
5858
@FWEB{} offers a built-in preprocessor facility, especially useful for
5859
@sc{Fortran} programmers. It is closely patterned after the C/C++
5860
preprocessor, but with some extensions such as variable numbers of
5861
arguments. In addition, there are some built-in functions that provide
5862
functionality that cannot be emulated by user-defined macros.
5863
5864
When working with a language such as C that has its own preprocessor,
5865
the question arises when to use that and when to use @FWEB{}'s
5866
facilities. The answer generally comes with experience. Remember that
5867
@FWEB{}'s macros have been expanded by the time the tangled output
5868
file is produced, whereas language-specific preprocessor commands are
5869
just passed through to that file.
5870
5871
If you're a @sc{Fortran} programmer, @emph{strongly} consider the use of
5872
@FWEB{}'s macro facilities; they will simplify your present and future
5873
life by creating more legible codes and reducing programming errors by
5874
eliminating redundant pieces of code. C/C++ programmers may also
5875
appreciate the preprocessor extensions.
5876
5877
In addition to conventional macro processing, @FWEB{} also offers the
5878
convenience of certain built-in functions that behave in many ways like
5879
macros. As a trivial example, the value of @PI{} is available through
5880
the built-in function @samp{$PI}. Built-in functions are described in
5881
@ref{Built-in functions}. They can be useful to programmers in all languages.
5882
5883
@FWEB{} recognizes two kinds of macros: @dfn{outer macros}, and @dfn{WEB
5884
macros} (@dfn{inner macros}). Control codes associated with either of
5885
these kinds normally begin the definition part. However, @FWEB{}
5886
macros are sometimes allowed in the code part as well; see @ref{FWEB macros}.
5887
5888
Macros are expanded by @FTANGLE{} only; @FWEAVE{} merely prints
5889
them as they occur in the source file.
5890
5891
@cindex Macros
5892
5893
@menu
5894
* Outer macros:: Macros copied to beginning of output file (@@d).
5895
* FWEB macros:: Macros and built-in functions expanded by @FWEB{} (@@m).
5896
* Macros and formatting:: How to format macros for pretty-printing.
5897
* Preprocessing:: @FWEB{}'s preprocessing language (@@#if, etc.)
5898
@end menu
5899
5900
@node Outer macros,FWEB macros,Macros,Macros
5901
@comment node-name, next, previous, up
5902
5903
@section Outer macros
5904
5905
@cindex Macros, outer
5906
Outer macros provide a shorthand way of invoking macro definitions in
5907
the source language; they are not expanded by @FWEB{}. Outer macros are
5908
defined by @samp{@@d} (@pxref{ATd}) or @samp{@@D}
5909
(@pxref{ATD_}). They may be placed in any definition part. @FTANGLE{}
5910
collects them during phase 1; during phase 2, they are simply copied in
5911
order of their appearance to the beginning of the output file. This is
5912
most useful for C or C++ codes; it's a quick way of typing
5913
@samp{#define} when the positioning of the @samp{#define} is
5914
unimportant.
5915
5916
As an example,
5917
5918
@example
5919
@@c
5920
@@
5921
@@d YES 1
5922
@@d NO 0
5923
@@a
5924
main()
5925
@{@}
5926
5927
@@
5928
@@d BUF_LEN 100
5929
@@a
5930
...
5931
@end example
5932
5933
The keyword into which the @samp{@@d} is translated is
5934
language-dependent; it is controlled by the style-file parameter
5935
@samp{outer_def}. @xref{Miscellaneous params}.
5936
5937
Outer macros can be undefined by @samp{@@u}. The translation is
5938
controlled by the style-file parameter @samp{outer_undef}.
5939
@xref{Miscellaneous params}.
5940
5941
The default behavior, in which the outer macro definitions are just
5942
copied to the top of the output file, is fine for simple applications.
5943
However, often C programmers prefer to maintain their macro definitions
5944
in a header file such as @file{test.h}. One way of accomplishing this is to
5945
redirect @FTANGLE{}'s output from the command line, as in
5946
@samp{ftangle test -=test.h}, then use an @samp{@@O} command immediately
5947
after the first @samp{@@a} in the @code{web} file to open up
5948
@file{test.c}. A more complicated variant of this allows additional
5949
information to be placed into the header file, as in the following example:
5950
5951
@example
5952
@@c
5953
@@* INTRO.
5954
We assume command-line redirection into \.@{test.h@} (`\.@{-=test.h@}').
5955
5956
@@d A 1 // This will go into \.@{test.h@}.
5957
5958
@@a
5959
@@<Header material@@>@@; // Also goes into \.@{test.h@}.
5960
@@O test.c // Remaining unnamed sections go into \.@{test.c@}.
5961
5962
@@ Header material may be defined as needed throughout the code, but
5963
with this design it will all go into \.@{test.h@}.
5964
5965
@@<Header material@@>=
5966
5967
@@<Includes@@>@@;
5968
@@<Typedefs@@>@@;
5969
@@<Global variables@@>@@;
5970
5971
@end example
5972
5973
@node FWEB macros,Macros and formatting,Outer macros,Macros
5974
@comment node-name, next, previous, up
5975
5976
@section @FWEB{} macros
5977
5978
@cindex Macros, @FWEB{}
5979
@FWEB{} macros (sometimes called @dfn{inner macros}) are defined by
5980
@samp{@@m} (@pxref{ATm}) or @samp{@@M}
5981
(@pxref{ATM_}). These should normally be placed in the definition
5982
part, as in
5983
5984
@example
5985
@@n
5986
@@ Documentation...
5987
5988
@@m CUBE(x) (x)**3
5989
5990
@@a
5991
z3 = CUBE(x) + CUBE(y)
5992
@end example
5993
@noindent
5994
(the appearance of an @samp{@@m} in the documentation part begins the
5995
definition part). They are collected during
5996
@FTANGLE{}'s phase 1 and effectively placed at the top of the unnamed
5997
section, so they are all known during the output in phase 2.
5998
5999
In unusual situations when macros are being conditionally defined and/or
6000
undefined, the order of processing a macro definition becomes
6001
significant. If the command-line option @samp{-TD} is used, then
6002
@FWEB{} macros may be used in the code part as well; they are then
6003
called @dfn{deferred macros}. These definitions will be processed during
6004
phase 2 in the order that the code sections are processed, which may not
6005
be the same as the physical order in the source file.
6006
6007
@emph{The use of deferred macros is highly discouraged}, for the
6008
following reason. @FWEB{} macros are often used in conjunction with
6009
the @FWEB{} preprocessor commands. @emph{Preprocessor commands are
6010
always processed during phase 1}, so they do not interact properly with
6011
deferred macros. It is for this reason that deferred macros are
6012
normally prohibited from appearing in the code part.
6013
6014
@menu
6015
* Macro features:: Various points about @FWEB{} macros.
6016
* Tokens:: Special tokens used in @FWEB{} macros.
6017
* Built-in functions:: Macro-like functions built into @FWEB{}.
6018
* Debugging with macros:: Debugging glitches, and their solutions.
6019
@end menu
6020
6021
@node Macro features, Tokens, FWEB macros, FWEB macros
6022
@comment node-name, next, previous, up
6023
6024
@subsection Various features of @FWEB{} macros
6025
6026
@quotation
6027
@itemize @bullet
6028
@item
6029
Fundamentally, @FWEB{} macros follow the syntax for ANSI C. There are
6030
also a few extensions, notably the possibility of variable (optional) arguments
6031
(@pxref{Variable arguments}) and some additional preprocessing tokens
6032
(@pxref{Tokens}).
6033
6034
@item
6035
Adjacent strings in macro text are automatically concatenated.
6036
@end itemize
6037
@end quotation
6038
6039
@menu
6040
6041
EXTENSIONS of ANSI-C MACRO SYNTAX
6042
6043
* Variable arguments:: @FWEB{} macros with variable arguments.
6044
* Recursion:: @FWEB{} macros may be recursive (proceed at your own risk).
6045
* Macro protection:: Protecting @FWEB{} macros against redefinition.
6046
6047
@end menu
6048
6049
@node Variable arguments, Recursion, Macro features, Macro features
6050
@comment node-name, next, previous, up
6051
6052
@subsubsection @FWEB{} macros with variable arguments
6053
6054
@cindex Macros, with variable arguments
6055
@cindex Variable arguments
6056
An important extension to the ANSI-C syntax is to allow macros with
6057
variable (optional) arguments. @FWEB{} macros with a variable number of arguments
6058
are indicated by an ellipsis, as in
6059
6060
@example
6061
@@m VAR(x,y,z,...) text
6062
@end example
6063
@noindent
6064
The tokens @samp{#0} (number of variable arguments), @samp{#@i{n}}
6065
(value of the @i{n}th optional argument), and @samp{#.} (comma-delimited list of
6066
the optional arguments) are useful in this context.
6067
6068
@node Recursion, Macro protection, Variable arguments, Macro features
6069
@comment node-name, next, previous, up
6070
6071
@subsubsection Recursion
6072
6073
@cindex Recursion
6074
ANSI C does not permit recursive macros (for good reason). Thus, in the
6075
example
6076
6077
@example
6078
@@m recurse recurse
6079
@end example
6080
@noindent
6081
the identifier @code{recurse} simply expands as `@code{recurse}', not as
6082
an infinite loop. However, in @FWEB{} recursion may be useful in
6083
conjunction with some of the built-in functions
6084
(@pxref{Built-in functions}). To permit a macro to be recursive, say @samp{@@m*}.
6085
6086
@emph{No formal support is provided for recursive macros!} If they
6087
don't work, or suddenly stop working in a new release, @emph{you're on
6088
your own}!
6089
6090
@node Macro protection, , Recursion, Macro features
6091
@comment node-name, next, previous, up
6092
6093
@subsubsection Protecting macros against redefinition
6094
6095
@cindex Macros, redefinition of
6096
Normally an @FWEB{} macro can be redefined at will. The example
6097
6098
@example
6099
@@m PI 3.14159
6100
@@m PI (-3)
6101
@end example
6102
@noindent
6103
is permissible, but probably not a good idea. If you want to ensure
6104
that a crucial macro definition is never redefined inadvertently, say
6105
@samp{@@m!}, as in
6106
6107
@example
6108
@@m! PI 3.14159
6109
@end example
6110
@noindent
6111
That is called @dfn{protecting} the macro.
6112
6113
@FWEB{}'s built-in functions and macros (beginning with @samp{$}) are
6114
protected by default; see
6115
@ref{Protection}. To override that protection, use the command-line
6116
options @samp{-Tb} (@ref{-Tb}; for built-in functions) or @samp{-Tm}
6117
(@ref{-Tm}; for macros).
6118
6119
6120
@node Tokens, Built-in functions, Macro features, FWEB macros
6121
@comment node-name, next, previous, up
6122
6123
@subsection Special tokens
6124
6125
@cindex Macros, special tokens for
6126
The following special tokens may be used in the text of @FWEB{} macro
6127
definitions:
6128
6129
@subsubsection ANSI C-compatible tokens
6130
6131
@example
6132
## @r{--- Paste tokens on either side to form a new identifier.}
6133
#@i{parameter} @r{--- Convert parameter to string (without expansion).}
6134
@end example
6135
6136
For example,
6137
6138
@example
6139
@@m FORTRAN(type, name) type _##name()
6140
@@m TRACE(where) puts("At " #where)
6141
@@a
6142
FORTRAN(int, fcalc); // @r{Expands to @samp{int _fcalc();}}
6143
TRACE(predictor); // @r{Expands to @samp{puts("At " "predictor");}}
6144
@end example
6145
6146
@subsubsection Extensions to ANSI C macro syntax
6147
6148
The most frequently used extensions are the following ones associated
6149
with variable arguments: @samp{#0}, @samp{#@i{n}}, and @samp{#.}.
6150
@sc{Fortran}-77 users should also employ @samp{#:0} to allow symbolic
6151
rather than numeric statement labels. Try not to use the other
6152
extensions; they are experimental, complicated, and unlikely to work in
6153
all situations.
6154
6155
In the following list, the forms @samp{#@{n@}} and @samp{#[n]} may not
6156
work correctly in complicated situations. This is a design deficiency
6157
that may be corrected someday.
6158
6159
@quotation
6160
@table @code
6161
@item #*@i{param}
6162
Like @samp{#@i{parameter}}, but pass a quoted string through unchanged.
6163
@item #!@i{param}
6164
Don't expand argument.
6165
@item #'@i{param}
6166
Convert parameter to a single-quoted string (no expansion).
6167
@item #"@i{param}
6168
Convert parameter to a double-quoted string (no expansion).
6169
@item #0
6170
Number of variable arguments.
6171
@item #@i{n}
6172
n-th variable argument, counting from 1.
6173
@item #@{0@}
6174
Like @samp{#0}, but the argument may be a macro expression known at run time.
6175
@item #@{@i{n}@}
6176
Like @samp{#@i{n}}, but the argument may be a macro expression.
6177
@item #[0]
6178
The total number of arguments (fixed + variable). (The
6179
argument inside the brackets may be a macro expression.)
6180
@item #[@i{n}]
6181
The @i{n}th argument (including the fixed ones), counting
6182
from 1. (The argument inside the brackets may be a macro expressions.
6183
@item #.
6184
Comma-separated list of all variable arguments.
6185
@item #:0
6186
Unique statement number (expanded in phase 1).
6187
@item #:@i{nnn}
6188
Unique statement number for each invocation of this macro (expanded in phase 2).
6189
@item #<
6190
Begin a module name.
6191
@item #,
6192
Internal comma; doesn't delimit macro argument.
6193
@end table
6194
@end quotation
6195
6196
A few examples of the more important of these tokens are as follows:
6197
6198
@example
6199
@@c
6200
@@m FPRINTF(fmt,...) fprintf(fp,fmt,#.)
6201
// Use the whole list of variable args.
6202
@@m B(...) printf("There were %i arguments\n", #0)
6203
// Use the number of var args.
6204
6205
@@n
6206
@@
6207
@@m DONE #:0 // Symbolic statement label in @sc{Fortran}.
6208
@@a
6209
goto DONE
6210
...
6211
DONE:
6212
call endup
6213
@end example
6214
6215
@node Built-in functions, Debugging with macros, Tokens, FWEB macros
6216
@comment node-name, next, previous, up
6217
6218
@subsection Built-in functions
6219
6220
@cindex Functions, built-in
6221
Built-in functions behave in most ways like macros. In some cases
6222
they actually are macros, but other times they implement functions that a
6223
user could not define. They all begin with a dollar sign and are in
6224
upper case.
6225
6226
In using these built-ins, confusion may arise regarding the order of
6227
expansion of various arguments. When they are implemented as macros,
6228
they are subject to the same ANSI-C preprocessor rules as other
6229
@FWEB{} macros, which is that all arguments are fully expanded before
6230
generating the replacement text of the macro. When they are directly
6231
implemented as a primitive function, however, that rule may not apply.
6232
For example, @code{$IF} expands only its first argument during its first
6233
pass of processing; depending on the results of that expansion, it then
6234
expands @emph{either} its second or third argument, but not both.
6235
6236
The built-in function @code{$DUMPDEF} can be used to understand and
6237
debug the action of the built-in functions. @xref{$DUMPDEF}.
6238
6239
In the original @FWEB{} design, built-in functions began with an
6240
underscore. This usage conflicts with the conventions for reserved
6241
words in ANSI C, and has been eliminated. @emph{All @FWEB{} built-ins
6242
now begin with a dollar sign.}
6243
6244
@emph{No user-defined macro should begin with a dollar sign!} It might
6245
interfere with the functioning of some internal built-in function.
6246
6247
@menu
6248
6249
GENERAL INFORMATION ABOUT BUILT-IN FUNCTION DESIGN
6250
6251
* Strings and quotes:: Quoted and non-quoted strings.
6252
* Protection:: By default, built-in functions may not be redefined.
6253
6254
INDIVIDUAL BUILT-IN FUNCTIONS
6255
6256
* $A:: Convert to ASCII.
6257
* $ABS:: Absolute value.
6258
* $ASSERT:: Assert a condition.
6259
* $AUTHOR:: RCS global keyword; see $KEYWORD.
6260
* $COMMENT:: Generate a comment.
6261
* $DATE:: Today's date.
6262
* $DATE_TIME:: RCS global keyword; see $KEYWORD.
6263
* $DAY:: Today.
6264
* $DECR:: Decrement a macro.
6265
* $DEFINE:: Define a (deferred) macro.
6266
* $DO:: Macro @b{DO} loop.
6267
* $DUMPDEF:: Dump macro definitions to the terminal.
6268
* $E:: Base of the natural logarithms: 2.71828...
6269
* $ERROR:: Send error message to output.
6270
* $EVAL:: Evaluate an expression.
6271
* $EXP:: Exponential function.
6272
* $GETENV:: Get value of environment variable.
6273
* $HEADER:: RCS global keyword; see $KEYWORD.
6274
* $HOME:: The user's home directory.
6275
* $ID:: RCS global keyword; see $KEYWORD.
6276
* $IF:: Two-way conditional: ``If expression is true''
6277
* $IFCASE:: n-way conditional.
6278
* $IFDEF:: Two-way conditional: ``If macro is defined''
6279
* $IFNDEF:: Two-way conditional: ``If macro is not defined''
6280
* $IFELSE:: Two-way conditional: ``If macro1 equals macro2''
6281
* $INCR:: Increment a macro.
6282
* $INPUT_LINE:: Line number that begins current section.
6283
* $KEYWORD:: Extract text of global RCS-like keyword.
6284
* $L:: Change string to lower case.
6285
* $L_KEYWORD:: Extract text of local RCS-like keyword.
6286
* $LANGUAGE:: Identifier for current language.
6287
* $LANGUAGE_NUM:: Number of current language.
6288
* $LEN:: Length of string.
6289
* $LOCKER:: RCS global keyword; see $KEYWORD.
6290
* $LOG:: Natural logarithm.
6291
* $LOG10:: Logarithm to the base 10.
6292
* $M:: Define a (deferred) macro.
6293
* $MAX:: Maximum of one or more elements.
6294
* $MIN:: Minimum of one or more elements.
6295
* $MODULE_NAME:: Name of present @code{web} module.
6296
* $MODULES:: Total number of independent modules.
6297
* $NAME:: RCS global keyword; see $KEYWORD.
6298
* $OUTPUT_LINE:: Current line number of tangled output.
6299
* $P:: The C preprocessor symbol @code{#} (an unquoted string).
6300
* $PI:: 3.14159...
6301
* $POW:: Raise to a power.
6302
* $PP:: The C preprocessor symbol @code{#} (a character).
6303
* $RCSFILE:: RCS global keyword; see $KEYWORD.
6304
* $REVISION:: RCS global keyword; see $KEYWORD.
6305
* $ROUTINE:: Current Ratfor program, function, or subroutine.
6306
* $SECTION_NUM:: Number of current section.
6307
* $SECTIONS:: Maximum number of sections.
6308
* $SOURCE:: RCS global keyword; see $KEYWORD.
6309
* $SQRT:: Square root.
6310
* $STATE:: RCS global keyword; see $KEYWORD.
6311
* $STRING:: Expand argument, then stringize.
6312
* $STUB::
6313
* $TIME:: The local time.
6314
* $TRANSLIT:: Transliterate a string.
6315
* $U:: Change string to upper case.
6316
* $UNDEF:: Undefine an @FWEB{} macro.
6317
* $UNQUOTE:: Remove quotes from string (leaving an unquoted string).
6318
* $UNSTRING:: Remove quotes and string delimiters from string.
6319
* $VERBATIM:: (Obsolete.)
6320
* $VERSION:: @FWEB{} version number.
6321
@end menu
6322
6323
@node Strings and quotes, Protection, Built-in functions, Built-in functions
6324
@comment node-name, next, previous, up
6325
6326
@subsubsection Strings and quotes
6327
6328
@cindex String, definition of
6329
@cindex String, quoted
6330
@cindex String, unquoted
6331
6332
Several of the built-in functions expect or return a string argument.
6333
Examples include @code{$STRING} (@pxref{$STRING}), @code{$UNQUOTE}
6334
(@pxref{$UNQUOTE}), and @code{$UNSTRING} (@pxref{$UNSTRING}).
6335
In understanding the operation of those functions, it is important to
6336
understand just what a string means in the @FWEB{} context. As usual,
6337
it is a vector of characters. However, @emph{those need not be
6338
delimited by quotes}, although they may be. Internally, a string is
6339
represented by the construction @i{sqc...cqs}, where @i{s} is a special
6340
string delimiter never seen by the user, @i{q} is an optional quote
6341
character (either single or double quote depending on the language), and
6342
@i{c} is an ordinary character. Whether or not the quotes are present,
6343
the string delimiters inhibit macro expansion.
6344
6345
The difference between @code{$UNQUOTE} and @code{$UNSTRING} can now be
6346
stated as follows. Given a quoted string such as @code{"abc"} (in C),
6347
6348
@itemize @bullet
6349
@item
6350
@samp{$UNQUOTE} removes the quote characters @i{q}, leaving @i{sabcs} (still a
6351
string).
6352
6353
@item
6354
@samp{$UNSTRING} removes both the quote characters @i{q} and the string
6355
delimiters @i{s}, leaving @i{abc} (a collection of three characters). This
6356
collection is @emph{not} tokenized; it does @emph{not} represent the
6357
single identifier name @code{abc} (and therefore is not very useful).
6358
@code{$UNSTRING} is primarily used internally.
6359
6360
@end itemize
6361
6362
The built-ins @code{$P} (@pxref{$P}) and @code{$PP} (@pxref{$PP}), which
6363
both generate the preprocessor character @samp{#}, provide a good
6364
illustration of the differences between @code{$UNQUOTE} and
6365
@code{$UNSTRING}. Consider @sc{Fortran} as an example. Essentially,
6366
@code{$P} is defined as @samp{$UNQUOTE('#')}, which is internally
6367
@i{s@t{#}s}. When this single-character string is sent to the output, it is
6368
treated like any other expression and therefore would appear in column 7
6369
or greater even if the construction appeared at the very beginning of
6370
the line. On the other hand, @code{$PP} is (essentially) defined as
6371
@samp{$UNSTRING('#')}, which is internally the single character @t{#}.
6372
Because this character is not a string, the @sc{Fortran} output driver
6373
treats it as a special control character, defined in this case to force
6374
the character into the first column.
6375
6376
@node Protection, $A, Strings and quotes, Built-in functions
6377
@comment node-name, next, previous, up
6378
6379
@subsubsection Redefining built-in functions
6380
6381
By default, built-in functions are @dfn{protected}---that is, they may not be
6382
redefined by an @code{@@m} command. (To do so cavalierly invites many
6383
kinds of weird disasters.) If it is absolutely necessary to redefine a
6384
built-in function, use the command-line option @samp{-Tb} (@pxref{-Tb}).
6385
6386
Many of @FWEB{}'s ``built-in functions'' are in fact ordinary macros
6387
that are implemented in terms of lower-level built-ins. An example is
6388
@code{$POW} (@pxref{$POW}), which is constructed from the built-in
6389
function @code{$EVAL} (@pxref{$EVAL}). By default, such macros are also
6390
protected against redefinition; to override, use the option @samp{-Tm}
6391
(@pxref{-Tm}).
6392
6393
@node $A, $ABS, Protection, Built-in functions
6394
@comment node-name, next, previous, up
6395
6396
@subsubsection @code{$A}: Convert to ASCII
6397
6398
@findex $A
6399
@cindex ASCII, converting to
6400
@samp{$A(@i{string})} is the built-in equivalent of @samp{@@'...'} or
6401
@samp{@@"..."}. (See @ref{ATquote} and @ref{ATdquote}.)
6402
Note the extra parentheses required by the built-in.
6403
6404
@code{$A} first expands its argument, in case it is a macro defined as a
6405
string.
6406
6407
@node $ABS,$ASSERT,$A,Built-in functions
6408
@comment node-name, next, previous, up
6409
6410
@subsubsection @code{$ABS}: Absolute value
6411
6412
@findex $ABS
6413
@cindex Absolute value
6414
@cindex Macros, absolute value of
6415
@samp{$ABS(@i{expression})} returns the absolute value of the macro
6416
expression. It is a macro implemented in terms of @code{$IF} and @code{$EVAL}.
6417
6418
@node $ASSERT,$AUTHOR,$ABS,Built-in functions
6419
@comment node-name, next, previous, up
6420
6421
@subsubsection @code{$ASSERT}: Assert a condition
6422
6423
@findex $ASSERT
6424
@cindex Asserting a condition
6425
@cindex Condition, asserting
6426
@samp{$ASSERT(@i{expression})} evaluates the macro expression. If the
6427
expression is false, an error message is printed and the run aborts.
6428
6429
This built-in is useful for ensuring that @FWEB{} macros required by
6430
the code are properly initialized. Because it is expanded during the
6431
output phase, it must appear in the @emph{code
6432
part} (not in the definition part).
6433
6434
@node $AUTHOR, $COMMENT, $ASSERT, Built-in functions
6435
@comment node-name, next, previous, up
6436
6437
@subsubsection @code{$AUTHOR}: Value of RCS global keyword @code{Author}
6438
@findex $AUTHOR
6439
@cindex Author
6440
6441
Equivalent to @samp{$KEYWORD(Author)}. @xref{$KEYWORD}.
6442
6443
@node $COMMENT,$DATE,$AUTHOR,Built-in functions
6444
@comment node-name, next, previous, up
6445
6446
@subsubsection @code{$COMMENT}: Generate a comment
6447
6448
@findex $COMMENT
6449
@cindex Comments, generating
6450
@samp{$COMMENT}(@i{string}) generates a comment in the output file.
6451
6452
This function is sometimes useful in conjunction with the processing of
6453
@FWEB{} macros, since ordinary comments are removed when macros are
6454
processed. For example, if one says
6455
6456
@example
6457
@@c
6458
@@
6459
@@m M "abc" $COMMENT("Test")
6460
@@a
6461
m = M
6462
@end example
6463
@noindent
6464
the tangled output will be @samp{m= "abc"/* Test */}
6465
6466
@node $DATE,$DATE_TIME,$COMMENT,Built-in functions
6467
@comment node-name, next, previous, up
6468
6469
@subsubsection @code{$DATE}: Today's date
6470
6471
@findex $DATE
6472
@cindex Date, generating the
6473
@samp{$DATE} generates a string consisting of the date in the form
6474
@code{"August 16, 2001"}. It is implemented as a macro that calls other
6475
macros and primitive functions.
6476
6477
@node $DATE_TIME, $DAY, $DATE, Built-in functions
6478
@comment node-name, next, previous, up
6479
6480
@subsubsection @code{$DATE_TIME}: Value of RCS global keyword @code{Date}
6481
6482
@findex $DATE_TIME
6483
@cindex Date
6484
@cindex Time
6485
Equivalent to @samp{$KEYWORD(Date)}. @xref{$KEYWORD}.
6486
6487
@node $DAY,$DECR,$DATE_TIME,Built-in functions
6488
@comment node-name, next, previous, up
6489
6490
@subsubsection @code{$DAY}: The day
6491
6492
@findex $DAY
6493
@cindex Day, generating the
6494
@samp{$DAY} generates a string consisting of the day of the week, such
6495
as @code{"Monday"}. It is implemented as a macro that calls other
6496
macros and primitive functions.
6497
6498
@node $DECR,$DEFINE,$DAY,Built-in functions
6499
@comment node-name, next, previous, up
6500
6501
@subsubsection @code{$DECR}: Decrement a macro
6502
6503
@findex $DECR
6504
@cindex Macros, decrementing
6505
@samp{$DECR(@var{N})} redefines the numeric macro @var{N} to be one less
6506
than its previous value. (If @var{N} does not simplify to a number, an
6507
error results.) In other words, in the language of C the effect is to
6508
say @samp{@i{N}--}.
6509
6510
The two-argument form @samp{$DECR(@var{N,m})} executes the equivalent of
6511
@samp{@i{N} -= @i{m}}.
6512
6513
@node $DEFINE,$DO,$DECR,Built-in functions
6514
@comment node-name, next, previous, up
6515
6516
@subsubsection @code{$DEFINE}: Deferred macro definition
6517
6518
@findex $DEFINE
6519
@cindex Macros, defining
6520
@samp{$DEFINE} behaves like the @FWEB{} macro command @code{@@m}, but
6521
it is intended to appear in the @emph{code} part, not the definition part (so
6522
it is processed during @emph{output}, not input). Thus, the code fragment
6523
6524
@example
6525
a = A;
6526
$DEFINE(A 1)@@%
6527
a = A;
6528
@end example
6529
@noindent
6530
tangles to
6531
6532
@example
6533
a= A;
6534
a= 1;
6535
@end example
6536
@noindent
6537
(Notice how the @samp{@@%} command was used to kill an unwanted newline,
6538
analogous to the @samp{dnl} macro in @code{m4}.)
6539
6540
In the above example, one could also say @samp{$DEFINE(A=1)}.
6541
To define a macro with arguments, say something like
6542
@samp{$DEFINE(A(x)x*x)}. Do @emph{not} say @samp{$DEFINE(A(x)=x*x)}, as
6543
in this case the equals sign will be included in the macro expansion.
6544
One must use the equals sign as a means of preventing parentheses from
6545
being interpreted as an argument in examples like
6546
6547
@example
6548
$DEFINE(A=(x))
6549
@end example
6550
@noindent
6551
This expands to @samp{(x)}.
6552
6553
A completely equivalent shorthand notation for @code{$DEFINE} is
6554
@code{$M}.
6555
6556
@node $DO,$DUMPDEF,$DEFINE,Built-in functions
6557
@comment node-name, next, previous, up
6558
6559
@subsubsection @code{$DO}: Macro do loop
6560
6561
@findex $DO
6562
@cindex Macros, repetitively defining
6563
@samp{$DO(@i{macro,imin,imax[,di]})@{...@}} repetitively defines
6564
@i{macro} as would the @sc{Fortran} statement @samp{do macro =
6565
imin,imax,di}. For example,
6566
6567
@example
6568
$DO(I,0,2)
6569
@{
6570
a[I] = I;
6571
@}
6572
@end example
6573
6574
@noindent
6575
generates the three statements
6576
6577
@example
6578
a[0] = 0;
6579
a[1] = 1;
6580
a[2] = 2;
6581
@end example
6582
6583
In general, the macro name used as loop counter should @emph{not} be
6584
explicitly defined as a macro prior to the @code{$DO}. If it is not, it
6585
will remain undefined after the end of the iteration.
6586
6587
Instead of the delimiting braces, parentheses may be used. These may be
6588
useful to help @FWEAVE{} format certain constructions correctly.
6589
6590
Nested delimiters are handled correctly. The delimiters are required
6591
even if only a single statement is to expanded.
6592
6593
@findex $UNROLL
6594
@code{$DO} is implemented in terms of a command @code{$UNROLL}.
6595
However, if one says something like @samp{$DUMPDEF($UNROLL(0,5,1))},
6596
@FWEB{} will respond that @code{$UNROLL} is not an @FWEB{} macro.
6597
Rather, @code{$UNROLL} is processed like expandable commands in
6598
@sc{Ratfor} such as @code{while}. This implies that it cannot be
6599
redefined as ordinary macros or built-in functions can be.
6600
6601
@node $DUMPDEF,$E,$DO,Built-in functions
6602
@comment node-name, next, previous, up
6603
6604
@subsubsection @code{$DUMPDEF}: Dump macro definitions to the terminal
6605
6606
@findex $DUMPDEF
6607
@cindex Debugging macros
6608
@cindex Macros, debugging
6609
In the call @samp{$DUMPDEF(@i{m1, m2, ...})}, @i{m1}, @i{m2}, and so on
6610
are macro calls (with arguments if appropriate). Two lines of output
6611
are generated for each argument. Line 1 is the macro definition; line 2
6612
is its expansion using the provided arguments.
6613
6614
One can use this built-in to debug one's own macros, or to find out the
6615
secrets of @FWEB{}'s built-ins. As an example, if one says
6616
6617
@example
6618
$DUMPDEF($EVAL(2^^4))@@%
6619
@end example
6620
@noindent
6621
it responds with the two lines
6622
6623
@example
6624
$EVAL($0) = $$EVAL($0)
6625
$EVAL(2**4) = 16
6626
@end example
6627
@noindent
6628
(The @code{$@i{n}} notation indicates the @i{n}-th argument of the macro.)
6629
If one replaces @code{$EVAL} with @code{$$EVAL} in the above
6630
@code{$DUMPDEF}, it will respond
6631
6632
@example
6633
$$EVAL($0) = <built-in>
6634
$$EVAL(2**4) = 16
6635
@end example
6636
@noindent
6637
6638
The purpose of code such as @samp{$EVAL($0) = $$EVAL($0)} is to ensure
6639
that the argument of @code{$EVAL} is expanded if it contains macros; the
6640
primitive function @code{$$EVAL} does not do that expansion
6641
automatically.
6642
6643
Names indicated as @samp{<built-in>} by @code{$DUMPDEF} may be redefined
6644
as ordinary macros, but this is in general a @emph{very bad idea}; other
6645
parts of @FWEB{} may mysteriously stop working.
6646
6647
@node $E, $ERROR, $DUMPDEF, Built-in functions
6648
@comment node-name, next, previous, up
6649
6650
@subsubsection @code{$E}: Base of the natural logarithms
6651
6652
@findex $E
6653
@cindex Logarithms, natural
6654
The expression @samp{$E} returns @var{e}, the base of the natural
6655
logarithms, to the default machine precision.
6656
The expression @samp{$E(@i{iprec})} returns @var{e} to the decimal precision
6657
@var{iprec} (which must be less than 50).
6658
6659
@node $ERROR, $EVAL, $E, Built-in functions
6660
@comment node-name, next, previous, up
6661
6662
@subsubsection @code{$ERROR}: Send error message to output
6663
6664
@findex $ERROR
6665
@cindex Error messages, printing
6666
@samp{$ERROR(@i{string})} prints an error message in @FWEB{}'s
6667
standard form.
6668
6669
@node $EVAL, $EXP, $ERROR, Built-in functions
6670
@comment node-name, next, previous, up
6671
6672
@subsubsection @code{$EVAL}: Evaluate a macro expression
6673
6674
@findex $EVAL
6675
@cindex Expressions, evaluating
6676
@cindex Macros, evaluating
6677
@samp{$EVAL(@i{expression})} uses @FWEB{}'s macro-expression evaluator
6678
(@pxref{Preprocessing}) to reduce the macro expression to its simplest
6679
form. An attempt to perform arithmetic on combinations of non-macro
6680
identifiers and numbers generates a warning message.
6681
6682
@node $EXP, $GETENV, $EVAL, Built-in functions
6683
@comment node-name, next, previous, up
6684
6685
@subsubsection @code{$EXP}: Exponential function
6686
6687
@findex $EXP
6688
@cindex Exponentiation
6689
@samp{$EXP(@i{x})} returns
6690
@tex
6691
$e^x$.
6692
@end tex
6693
@ifinfo
6694
@var{e} to the power @var{x}.
6695
@end ifinfo
6696
6697
@node $GETENV, $HEADER, $EXP, Built-in functions
6698
@comment node-name, next, previous, up
6699
6700
@subsubsection @code{$GETENV}: Get value of environment variable
6701
6702
@findex $GETENV
6703
@cindex Environment, obtaining the
6704
@cindex Environment variables
6705
@samp{$GETENV(@var{name})} returns a string consisting of the current
6706
value of the environment variable @var{name}. (Under VMS, logical names
6707
behave like environment variables.)
6708
6709
The argument to @code{$GETENV} need not be a string (double-quoted), but
6710
it may be if necessary to avoid the expansion of a macro.
6711
6712
@node $HEADER, $HOME, $GETENV, Built-in functions
6713
@comment node-name, next, previous, up
6714
6715
@subsubsection @code{$HEADER}: Value of RCS global keyword @code{Header}
6716
6717
@findex $HEADER
6718
@cindex Header
6719
6720
Equivalent to @samp{$KEYWORD(Header)}. @xref{$KEYWORD}.
6721
6722
@node $HOME,$ID,$HEADER,Built-in functions
6723
@comment node-name, next, previous, up
6724
6725
@subsubsection @code{$HOME}: The user's home directory
6726
6727
@findex $HOME
6728
@samp{$HOME} is a convenience macro equivalent to @samp{$GETENV(HOME)}.
6729
6730
@node $ID, $IF, $HOME, Built-in functions
6731
@comment node-name, next, previous, up
6732
6733
@subsubsection @code{$ID}: Value of RCS global keyword @code{Id}
6734
6735
@findex $ID
6736
@cindex Identification
6737
Equivalent to @samp{$KEYWORD(Id)}. @xref{$KEYWORD}.
6738
6739
@node $IF,$IFCASE,$ID,Built-in functions
6740
@comment node-name, next, previous, up
6741
6742
@subsubsection @code{$IF}: Two-way conditional
6743
6744
@findex $IF
6745
@cindex Conditional, two-way
6746
@code{$IF} is a primitive function (not a macro) that is the code-part
6747
version of @samp{@@#if}.
6748
The syntax is
6749
6750
@example
6751
$IF(@i{expr}, @i{action-if-true}, @i{action-if-false})
6752
@end example
6753
@noindent
6754
The @i{expr} is an @FWEB{} macro expression that must reduce to 0
6755
(false) or 1 (true). First that argument is expanded. If it is true,
6756
@i{action-if-true} is expanded; otherwise @i{action-if-false} is expanded.
6757
6758
There may be peculiarities with this and the other built-in @code{$IF}
6759
function having to do with the order of expansion when the actions
6760
contain macros whose arguments themselves are macros. Therefore, do not
6761
use them unless absolutely necessary.
6762
6763
@emph{Do not redefine} @code{$IF} or any other built-in conditionals, as they
6764
are used internally to @FWEB{}.
6765
6766
@node $IFCASE,$IFDEF,$IF,Built-in functions
6767
@comment node-name, next, previous, up
6768
6769
@subsubsection @code{$IFCASE}: n-way conditional
6770
6771
@findex $IFCASE
6772
@cindex Conditional, n-way
6773
This primitive built-in behaves like @TeX{}'s @samp{\ifcase} command.
6774
The syntax is
6775
6776
@example
6777
$IFCASE(@i{expr}, @i{case-0}, @i{case-1}, ...,@i{case-n-1}, @i{default})
6778
@end example
6779
@noindent
6780
If @i{expr} reduces to an integer between 0 and @emph{n-1},
6781
inclusively, the appropriate case is selected; otherwise, the default
6782
case is selected.
6783
6784
As examples,
6785
6786
@example
6787
$IFCASE(2, zero, one, two, default) @r{=>} `two'
6788
$IFCASE(2, zero, one, three) @r{=>} `three'
6789
$IFCASE(2, zero, one) @r{=>} `one'
6790
@end example
6791
6792
@node $IFDEF,$IFNDEF,$IFCASE,Built-in functions
6793
@comment node-name, next, previous, up
6794
6795
@subsubsection @code{$IFDEF}: Two-way conditional
6796
6797
@findex $IFDEF
6798
@cindex Conditional, two-way
6799
This built-in primitive is the code-part version of @samp{@@#ifdef}.
6800
The syntax is
6801
6802
@example
6803
$IFDEF(@var{macro}, @i{action-if-defined},@i{action-if-not-defined})
6804
@end example
6805
6806
@node $IFNDEF,$IFELSE,$IFDEF,Built-in functions
6807
@comment node-name, next, previous, up
6808
6809
@subsubsection @code{$IFNDEF}: Two-way conditional
6810
6811
@findex $IFNDEF
6812
@cindex Conditional, two-way
6813
This built-in primitive is the code-part version of @samp{@@#ifndef}.
6814
The syntax is @samp{$IFNDEF(@var{macro}, @i{action-if-not-defined},
6815
@i{action-if-defined})}.
6816
6817
@node $IFELSE,$INCR,$IFNDEF,Built-in functions
6818
@comment node-name, next, previous, up
6819
6820
@subsubsection @code{$IFELSE}: Two-way conditional
6821
6822
@findex $IFELSE
6823
@cindex Conditional, two-way
6824
The syntax of this built-in primitive is @samp{$IFELSE(@i{expr1},
6825
@i{expr2}, @i{action-if-equal}, @i{action-if-not-equal})}. The
6826
expansions of @i{expr1} and @i{expr2} are compared on a byte-by-byte
6827
basis. If they are equal, the first action is taken, otherwise the
6828
second action is taken.
6829
6830
For example,
6831
6832
@example
6833
$M(S="abc")@@%
6834
$IFELSE("abc", S, yes, no)
6835
@end example
6836
@noindent
6837
evaluates to @samp{yes}.
6838
6839
@node $INCR,$INPUT_LINE,$IFELSE,Built-in functions
6840
@comment node-name, next, previous, up
6841
6842
@subsubsection @code{$INCR}: Increment a macro
6843
6844
@findex $INCR
6845
@cindex Macros, incrementing
6846
@samp{$INCR(@var{N})} redefines the numeric macro @var{N} to be one greater
6847
than its previous value. (If @var{N} does not simplify to a number, an
6848
error results.) In other words, in the language of C the effect is to
6849
say @samp{@var{N}++}.
6850
6851
The two-argument form @samp{$INCR(@var{N,m})} executes the equivalent of
6852
@samp{@var{N} += @var{m}}.
6853
6854
@node $INPUT_LINE,$KEYWORD,$INCR,Built-in functions
6855
@comment node-name, next, previous, up
6856
6857
@subsubsection @code{$INPUT_LINE}: Line number that begins current section
6858
6859
@findex $INPUT_LINE
6860
@cindex Input line, number of
6861
@samp{$INPUT_LINE} is the number of the line in the @code{web} source file
6862
that @emph{begins the current section} (not the source line in which the
6863
@code{$INPUT_LINE} command appears). Compare @code{$OUTPUT_LINE},
6864
@ref{$OUTPUT_LINE}.
6865
6866
@node $KEYWORD, $L, $INPUT_LINE, Built-in functions
6867
@comment node-name, next, previous, up
6868
6869
@subsubsection @code{$KEYWORD}: Value of global RCS-like keyword
6870
6871
@findex $KEYWORD
6872
@cindex Keyword, RCS
6873
@cindex RCS-like keyword
6874
@samp{$KEYWORD} provides a built-in function alternative to the use of
6875
@samp{@@K} in a code part. (@pxref{ATK_}).
6876
6877
@samp{$KEYWORD(@i{Keyword})} extracts (as a character string) the text of an
6878
RCS-like keyword defined in the ignorable commentary between @samp{@@z}
6879
and @samp{@@x} at the beginning of the web source file (@pxref{ATz}).
6880
(@dfn{RCS} stands for ``revision-control system.'') The general syntax
6881
is (@sc{unix} users, see @samp{man ident})
6882
6883
@example
6884
$@i{Keyword}: @r{text of keyword} $
6885
@end example
6886
@noindent
6887
For example,
6888
6889
@example
6890
@@z
6891
$Author: krommes $
6892
@@x
6893
6894
@@c
6895
@@
6896
@@a
6897
char author[] = $KEYWORD(Author);
6898
@end example
6899
@noindent
6900
This tangles to
6901
6902
@example
6903
char author[] = "krommes";
6904
@end example
6905
6906
In this example, @samp{$Author} is one of the standard RCS keywords.
6907
However, any keyword that fits the syntax
6908
@samp{$@i{keyword}: @i{contents} $} can be accessed by @samp{$KEYWORD}.
6909
(At least one blank is necessary before and after @i{contents}.)
6910
The argument of @samp{$KEYWORD} need not be quoted, but it may be. In
6911
either event, the output is a quoted string.
6912
6913
Keywords extracted from ignorable commentary at the beginning of a web
6914
file are called @dfn{global} and are known throughout the code.
6915
Distinguish these from @dfn{local} keywords extracted from ignorable
6916
commentary at the beginning of an include (@samp{@@i}) file. Such
6917
keywords are known only during the time that file is being read and are
6918
accessible via @samp{@@k} (@pxref{ATk}).
6919
6920
For convenience, built-ins are defined for some standard RCS global keywords.
6921
These are
6922
6923
@example
6924
$AUTHOR @r{=>} $KEYWORD(Author)
6925
$DATE_TIME @r{=>} $KEYWORD(Date)
6926
$HEADER @r{=>} $KEYWORD(Header)
6927
$ID @r{=>} $KEYWORD(Id)
6928
$LOCKER @r{=>} $KEYWORD(Locker)
6929
$NAME @r{=>} $KEYWORD(Name)
6930
$RCSFILE @r{=>} $KEYWORD(RCSfile)
6931
$REVISION @r{=>} $KEYWORD(Revision)
6932
$SOURCE @r{=>} $KEYWORD(Source)
6933
$STATE @r{=>} $KEYWORD(State)
6934
@end example
6935
@noindent
6936
There are no such abbreviations for local keywords, because such
6937
abbreviations would be expanded during output whereas it is necessary to
6938
recognize and expand the local keywords during input. Presumably such local
6939
keywords will be used rarely, if at all.
6940
6941
@node $L,$L_KEYWORD,$KEYWORD,Built-in functions
6942
@comment node-name, next, previous, up
6943
6944
@subsubsection @code{$L}: Change to lower case
6945
6946
@findex $L
6947
@cindex Lower case
6948
@cindex Case, changing
6949
@samp{$L(@var{string})} changes @var{string} to lower case. The argument is
6950
first expanded in case it is a macro.
6951
6952
@node $L_KEYWORD, $LANGUAGE, $L, Built-in functions
6953
@comment node-name, next, previous, up
6954
6955
@subsubsection @code{$L_KEYWORD}: Value of local RCS-like keyword
6956
6957
@findex $L_KEYWORD
6958
@cindex Keyword, RCS
6959
@cindex RCS-like keyword
6960
For most purposes, @samp{$L_KEYWORD} behaves as @samp{@@k}
6961
(@pxref{ATk}). It is still under development and should not be used yet.
6962
6963
@samp{$L_KEYWORD("@i{Keyword}")} extracts (as a character string) the text of
6964
an RCS-like keyword defined in the ignorable commentary between
6965
@samp{@@z} and @samp{@@x} at the beginning of a file included via
6966
@samp{@@i}. @samp{$L_KEYWORD("@i{local keyword}")} is expanded during
6967
input, and the results are known only during the time the include file
6968
is being read.
6969
6970
Note that the argument of @samp{$L_KEYWORD} must be a quoted string.
6971
For more discussion of the distinction between local and global
6972
keywords, please see @ref{ATz} and @ref{$KEYWORD}.
6973
6974
It is expected that local keywords will rarely be used, as
6975
fundamental revision-control information should presumably be extracted
6976
from the top of the master web file.
6977
6978
@node $LANGUAGE,$LANGUAGE_NUM,$L_KEYWORD,Built-in functions
6979
@comment node-name, next, previous, up
6980
6981
@subsubsection @code{$LANGUAGE}: Identifier for current language
6982
6983
@findex $LANGUAGE
6984
@cindex Language, determining the
6985
This expands to an identifier that denotes the current language, as
6986
follows:
6987
6988
@quotation
6989
@multitable {..VERBATIM..} {LANGUAGE}
6990
@item Language @tab @code{$LANGUAGE}
6991
@item C @tab @code{$C}
6992
@item C++ @tab @code{$CPP}
6993
@item Fortran @tab @code{$N}
6994
@item Fortran-90 @tab @code{$N90}
6995
@item Ratfor @tab @code{$R}
6996
@item Ratfor-90 @tab @code{$R90}
6997
@item TeX @tab @code{$X}
6998
@item VERBATIM @tab @code{$V}
6999
@end multitable
7000
@end quotation
7001
7002
@noindent
7003
Note that this outputs identifiers, not @FWEB{} macros. They are intended
7004
to be used in @code{$IF} or @code{$IFELSE} statements such as
7005
7006
@example
7007
$IF($LANGUAGE==$C, @i{C-text}, @i{other-text})
7008
@end example
7009
7010
For multiway switches, the @code{$LANGUAGE_NUM} built-in is more useful;
7011
see @ref{$LANGUAGE_NUM}.
7012
7013
@node $LANGUAGE_NUM,$LEN,$LANGUAGE,Built-in functions
7014
@comment node-name, next, previous, up
7015
7016
@subsubsection @code{$LANGUAGE_NUM}: Number of current language
7017
7018
@findex $LANGUAGE_NUM
7019
@cindex Language number
7020
@cindex Language, determining
7021
@samp{$LANGUAGE_NUM} expands to an integer that uniquely defines the
7022
current language, as follows:
7023
7024
@quotation
7025
@multitable {..VERBATIM..} {LANGUAGE_NUM}
7026
@item Language @tab @code{$LANGUAGE_NUM}
7027
@item C @tab @code{0}
7028
@item C++ @tab @code{1}
7029
@item Fortran @tab @code{2}
7030
@item Fortran-90 @tab @code{3}
7031
@item Ratfor @tab @code{4}
7032
@item Ratfor-90 @tab @code{5}
7033
@item TeX @tab @code{6}
7034
@item VERBATIM @tab @code{7}
7035
@end multitable
7036
@end quotation
7037
7038
@noindent
7039
This built-in is useful in conjunction with an @code{$IFCASE}
7040
construction; see @ref{$IFCASE}.
7041
7042
@node $LEN, $LOCKER, $LANGUAGE_NUM, Built-in functions
7043
@comment node-name, next, previous, up
7044
7045
@subsubsection @code{$LEN}: Length of string
7046
7047
@findex $LEN
7048
@cindex String length
7049
@cindex Length of string
7050
@samp{$LEN(@var{string})} returns the length of @var{string} in bytes. If
7051
@var{string} is not surrounded by quotes, it is interpreted as if it were
7052
quoted (so it is not expanded if it is a macro). Thus, in the example
7053
7054
@example
7055
@@m SS string
7056
$LEN(SS)
7057
@end example
7058
7059
@noindent
7060
the value returned is 2, not 5.
7061
7062
To expand the argument before taking the length, one can say something
7063
like
7064
7065
@example
7066
@@m $XLEN(s) $LEN(s)
7067
@end example
7068
7069
@node $LOCKER, $LOG, $LEN, Built-in functions
7070
@comment node-name, next, previous, up
7071
7072
@subsubsection @code{$LOCKER}: Value of RCS global keyword @code{Locker}
7073
7074
@findex $LOCKER
7075
@cindex Lock
7076
Equivalent to @samp{$KEYWORD(Locker)}. @xref{$KEYWORD}.
7077
7078
@node $LOG, $LOG10, $LOCKER, Built-in functions
7079
@comment node-name, next, previous, up
7080
7081
@subsubsection @code{$LOG}: Natural logarithm
7082
7083
@findex $LOG
7084
@cindex Logarithms, natural
7085
@samp{$LOG(@i{x})} returns
7086
@tex
7087
$\ln x$.
7088
@end tex
7089
@ifinfo
7090
the natural logarithm of @i{x}.
7091
@end ifinfo
7092
7093
@node $LOG10, $M, $LOG, Built-in functions
7094
@comment node-name, next, previous, up
7095
7096
@subsubsection @code{$LOG10}: Logarithm to the base 10
7097
7098
@findex $LOG10
7099
@cindex Logarithms, base 10
7100
@samp{$LOG10(@i{x})} returns
7101
@tex
7102
$\log_{10}x$.
7103
@end tex
7104
@ifinfo
7105
the logarithm to the base 10 of @i{x}.
7106
@end ifinfo
7107
7108
@node $M, $MAX, $LOG10, Built-in functions
7109
@comment node-name, next, previous, up
7110
7111
@subsubsection @code{$M}: Define a deferred macro
7112
7113
@findex $M
7114
@cindex Macros, defining
7115
@code{$M} is equivalent to @code{$DEFINE}. @xref{$DEFINE}.
7116
7117
@node $MAX,$MIN,$M,Built-in functions
7118
@comment node-name, next, previous, up
7119
7120
@subsubsection @code{$MAX}: Maximum of a list
7121
7122
@findex $MAX
7123
@cindex Maximum
7124
@samp{$MAX(@i{x1},@i{x2},...)} returns the maximum of the list of arguments.
7125
(There must be at least one argument.)
7126
7127
@node $MIN,$MODULE_NAME,$MAX,Built-in functions
7128
@comment node-name, next, previous, up
7129
7130
@subsubsection @code{$MIN}: Minimum
7131
7132
@findex $MIN
7133
@cindex Mininum
7134
@samp{$MIN(@i{x1},@i{x2},...)} returns the minimum of the list of arguments.
7135
(There must be at least one argument.)
7136
7137
@node $MODULE_NAME,$MODULES,$MIN,Built-in functions
7138
@comment node-name, next, previous, up
7139
7140
@subsubsection @code{$MODULE_NAME}: Name of present @code{web} module
7141
7142
@findex $MODULE_NAME
7143
@cindex Module, name of
7144
@samp{$MODULE_NAME} returns the name of the present @code{web} module. If the
7145
present module is unnamed, it returns the string @code{"unnamed"}.
7146
7147
@node $MODULES,$NAME,$MODULE_NAME,Built-in functions
7148
@comment node-name, next, previous, up
7149
7150
@subsubsection @code{$MODULES}: Total number of independent modules
7151
7152
@findex $MODULES
7153
@cindex Modules, number of
7154
@samp{$MODULES} gives the total number of independent modules---that is,
7155
the number of independent module names, plus 1 for the unnamed module.
7156
7157
@node $NAME, $OUTPUT_LINE, $MODULES, Built-in functions
7158
@comment node-name, next, previous, up
7159
7160
@subsubsection @code{$NAME}: Value of RCS global keyword @code{Name}
7161
7162
@findex $NAME
7163
Equivalent to @samp{$KEYWORD(Name)}. @xref{$KEYWORD}.
7164
7165
@node $OUTPUT_LINE,$P,$NAME,Built-in functions
7166
@comment node-name, next, previous, up
7167
7168
@subsubsection @code{$OUTPUT_LINE}: Current line number of tangled output
7169
7170
@findex $OUTPUT_LINE
7171
@cindex Output line
7172
@cindex Line number
7173
This returns the current line number of the tangled output. Contrast
7174
this with @code{$INPUT_LINE}, @ref{$INPUT_LINE}.
7175
7176
@node $P,$PI,$OUTPUT_LINE,Built-in functions
7177
@comment node-name, next, previous, up
7178
7179
@subsubsection @code{$P}: The C preprocessor symbol
7180
7181
@findex $P
7182
@cindex Sharp sign
7183
@cindex Pound sign
7184
@cindex Preprocessor symbol
7185
@code{$P} is (essentially) a synonym for @samp{$UNQUOTE("#")}
7186
(@pxref{$UNQUOTE}). It is useful for constructing @FWEB{} macro
7187
definitions that expand to C preprocessor statements. For example,
7188
7189
@example
7190
@@m CHECK(flag)
7191
$P if(flag)
7192
special code;
7193
$P endif
7194
@end example
7195
7196
Another version of the preprocessor symbol is @code{$PP} (@pxref{$PP}).
7197
For most purposes, @code{$P} and @code{$PP} will behave in exactly the
7198
same way. The difference between them is that @code{$P} is treated as a
7199
string (without surrounding quotes), whereas @code{$PP} is treated as a
7200
character. The character nature of @code{$PP} is used by @sc{Fortran}
7201
to reset the column number to 1, so C-like preprocessor commands appear
7202
there rather than in column 7.
7203
7204
For further discussion of strings and the differences between @code{$P}
7205
and @code{$PP}, see @ref{Strings and quotes}.
7206
7207
@node $PI, $POW, $P, Built-in functions
7208
@comment node-name, next, previous, up
7209
7210
@subsubsection @code{$PI}: Pi
7211
7212
@findex $PI
7213
@cindex Pi
7214
The expression @samp{$PI} returns
7215
@PI{} to the default machine
7216
precision. The expression @samp{$PI(@i{iprec})} returns
7217
@ifinfo
7218
@var{pi}
7219
@end ifinfo
7220
@tex
7221
$\pi$
7222
@end tex
7223
to the decimal precision @var{iprec} (which must be less than 50).
7224
7225
@node $POW, $PP, $PI, Built-in functions
7226
@comment node-name, next, previous, up
7227
7228
@subsubsection @code{$POW}: Exponentiation
7229
7230
@findex $POW
7231
@cindex Exponentiation
7232
@samp{$POW(@i{x,y})} generates
7233
@tex
7234
$x^y$.
7235
@end tex
7236
@ifinfo
7237
@i{x} raised to the power @i{y}.
7238
@end ifinfo
7239
(It is a macro defined in terms of @code{$EVAL} (@pxref{$EVAL}) and the
7240
exponentiation operator.)
7241
7242
@node $PP, $RCSFILE, $POW, Built-in functions
7243
@comment node-name, next, previous, up
7244
7245
@subsubsection @code{$PP}: The C preprocessor symbol
7246
7247
@findex $PP
7248
@cindex Sharp sign
7249
@cindex Pound sign
7250
@cindex Preprocessor symbol
7251
@code{$PP} is shorthand for @samp{$UNSTRING($P)} (@pxref{$P}), or
7252
(essentially) a synonym for @samp{$UNSTRING("#")} (@pxref{$UNSTRING}).
7253
It is useful, particularly in @sc{Fortran}, for constructing @FWEB{}
7254
macro definitions that expand to C preprocessor statements. For an
7255
example, see @ref{$P}. For a detailed discussion of the difference
7256
between @samp{$P} and @samp{$PP}, see @ref{Strings and quotes}.
7257
7258
@node $RCSFILE, $REVISION, $PP, Built-in functions
7259
@comment node-name, next, previous, up
7260
7261
@subsubsection @code{$RCSFILE}: Value of RCS global keyword @code{$RCSfile}
7262
7263
@findex $RCSfile
7264
@cindex RCS file
7265
@cindex File, RCS
7266
Equivalent to @samp{$KEYWORD(RCSfile)}. @xref{$KEYWORD}.
7267
7268
@node $REVISION, $ROUTINE, $RCSFILE, Built-in functions
7269
@comment node-name, next, previous, up
7270
7271
@subsubsection @code{$REVISION}: Value of RCS global keyword @code{Revision}
7272
7273
@findex $REVISION
7274
@cindex Revision
7275
Equivalent to @samp{$KEYWORD(Revision)}. @xref{$KEYWORD}.
7276
7277
@node $ROUTINE,$SECTION_NUM,$REVISION,Built-in functions
7278
@comment node-name, next, previous, up
7279
7280
@subsubsection @code{$ROUTINE}: Current function (@sc{Ratfor} only)
7281
7282
@findex $ROUTINE
7283
@cindex Program unit
7284
When @sc{Ratfor} is the current language, @code{$ROUTINE} expands to a
7285
string built of the name of the current program, function, or
7286
subroutine. This function is not useful for other languages, for which
7287
it expands to the null string.
7288
7289
@node $SECTION_NUM,$SECTIONS,$ROUTINE,Built-in functions
7290
@comment node-name, next, previous, up
7291
7292
@subsubsection @code{$SECTION_NUM}: Number of current @FWEB{} section
7293
7294
@findex $SECTION_NUM
7295
@cindex Section number, current
7296
@samp{$SECTION_NUM} returns an integer greater than 0 that is the
7297
integer number of the current @code{web} section. (This is not the
7298
La@TeX{} section number such as 3.4.)
7299
7300
@node $SECTIONS,$SOURCE,$SECTION_NUM,Built-in functions
7301
@comment node-name, next, previous, up
7302
7303
@subsubsection @code{$SECTIONS}: Maximum section number
7304
7305
@findex $SECTIONS
7306
@cindex Section number, maximum
7307
@samp{$SECTIONS} is the maximum section number as understood by
7308
@FWEAVE{}.
7309
7310
@node $SOURCE, $SQRT, $SECTIONS, Built-in functions
7311
@comment node-name, next, previous, up
7312
7313
@subsubsection @code{$SOURCE}: Value of RCS global keyword @code{Source}
7314
7315
@findex $SOURCE
7316
Equivalent to @samp{$KEYWORD(Source)}. @xref{$KEYWORD}.
7317
7318
@node $SQRT, $STATE, $SOURCE, Built-in functions
7319
@comment node-name, next, previous, up
7320
7321
@subsubsection @code{$SQRT}: Square root
7322
7323
@findex $SQRT
7324
@cindex Square root
7325
@cindex Root, square
7326
@samp{$SQRT(@i{x})} returns
7327
@tex
7328
$\sqrt{x}$.
7329
@end tex
7330
@ifinfo
7331
the square root of @i{x}.
7332
@end ifinfo
7333
It is a convenience macro defined in terms of @code{$POW}. @xref{$POW}.
7334
7335
@node $STATE, $STRING, $SQRT, Built-in functions
7336
@comment node-name, next, previous, up
7337
7338
@subsubsection @code{$STATE}: Value of RCS global keyword @code{State}
7339
7340
@findex $STATE
7341
@cindex State
7342
Equivalent to @samp{$KEYWORD(State)}. @xref{$KEYWORD}.
7343
7344
@node $STRING, $STUB,$STATE, Built-in functions
7345
@comment node-name, next, previous, up
7346
7347
@subsubsection @code{$STRING}: Expand, then stringize
7348
7349
@findex $STRING
7350
@cindex String, quoting a
7351
@samp{$STRING(@i{s})} expands its argument if it is a macro, then makes
7352
the expansion into a quoted string. If the argument is already a quoted
7353
string, it is returned unchanged.
7354
7355
@node $STUB,$TIME,$STRING,Built-in functions
7356
@comment node-name, next, previous, up
7357
7358
@subsubsection @code{$STUB}: Trap for missing module
7359
7360
@findex $STUB
7361
@cindex Modules, missing
7362
When a missing module is detected, @FTANGLE{} inserts the command
7363
@samp{$STUB(@i{module_name})} into the output code. The built-in
7364
@code{$STUB} expands to a function call appropriate to the current
7365
language. For example, in C it expands to @samp{missing_mod}, in
7366
@sc{Fortran} it expands to @samp{call nomod}.
7367
7368
@node $TIME,$TRANSLIT,$STUB,Built-in functions
7369
@comment node-name, next, previous, up
7370
7371
@subsubsection @code{$TIME}: The time
7372
7373
@findex $TIME
7374
@cindex Time
7375
@samp{$TIME} returns a string consisting of the local time in the form
7376
@code{"19:59"}.
7377
7378
@node $TRANSLIT,$U,$TIME,Built-in functions
7379
@comment node-name, next, previous, up
7380
7381
@subsubsection @code{$TRANSLIT}: Transliteration
7382
7383
@findex $TRANSLIT
7384
@cindex Transliteration
7385
The macro @samp{$TRANSLIT(@var{s}, @var{from}, @var{to})} interprets each of
7386
its arguments
7387
as strings (without expanding anything). Then @var{s} is modified by
7388
replacing any of the characters found in @var{from} by the
7389
corresponding characters in @var{to}. If @var{to} is shorter than
7390
@var{from}, then the excess characters in @var{from} are deleted from
7391
@var{s}. As a limiting case, if @var{to} is empty, then all the
7392
characters in @var{from} are deleted from @var{s}. For example,
7393
@samp{$TRANSLIT(s, aeiou, 12345)} replaces the vowels in @var{s} by the
7394
corresponding digits, and @samp{$TRANSLIT(s, aeiou, )} deletes all the
7395
vowels. The backslash may be used to escape a character, as in ANSI C.
7396
For example, @samp{$TRANSLIT("a\\"\\\\d", "d\\\\a\\"", "D,A'")}
7397
translates into @samp{A',D}. Here one had to explicitly enclose strings
7398
involving @samp{\\"} in double quotes in order to avoid a complaint
7399
about an unterminated string.
7400
7401
7402
@node $U,$UNDEF,$TRANSLIT,Built-in functions
7403
@comment node-name, next, previous, up
7404
7405
@subsubsection @code{$U}: Change to upper case
7406
7407
@findex $U
7408
@cindex Case, changing
7409
@cindex Upper case
7410
@samp{$U(@i{string})} changes @i{string} to upper case.
7411
7412
@node $UNDEF,$UNQUOTE,$U,Built-in functions
7413
@comment node-name, next, previous, up
7414
7415
@subsubsection @code{$UNDEF}: Undefine a macro
7416
7417
@findex $UNDEF
7418
@cindex Macros, undefining
7419
@samp{$UNDEF(@i{macro})} undefines an @FWEB{} macro.
7420
7421
@node $UNQUOTE,$UNSTRING,$UNDEF,Built-in functions
7422
@comment node-name, next, previous, up
7423
7424
@subsubsection @code{$UNQUOTE}: Remove quotes from string
7425
7426
@findex $UNQUOTE
7427
@cindex Strings, unquoting
7428
@samp{$UNQUOTE(@var{string})} returns @var{string} without its surrounding
7429
quotes. (However, the resulting construction is still treated as a
7430
string; no macro expansion is done.)
7431
7432
For a more detailed discussion and a comparison with @code{$UNSTRING}
7433
(@pxref{$UNSTRING}), see @ref{Strings and quotes}.
7434
7435
@node $UNSTRING, $VERBATIM, $UNQUOTE, Built-in functions
7436
@comment node-name, next, previous, up
7437
7438
@subsubsection @code{$UNSTRING}: Convert string into characters
7439
7440
@findex $UNSTRING
7441
@samp{$UNSTRING(@var{string})} removes quotes from the string, if they are
7442
present, and treats the result as a collection of characters. No
7443
tokenization is done, so macro expansion does not operate on those
7444
characters.
7445
7446
For a more detailed discussion and a comparison with @code{$UNQUOTE}
7447
(@pxref{$UNQUOTE}), see @ref{Strings and quotes}.
7448
7449
@node $VERBATIM, $VERSION, $UNSTRING, Built-in functions
7450
@comment node-name, next, previous, up
7451
7452
@subsubsection @code{$VERBATIM}: (Obsolete)
7453
7454
@findex $VERBATIM
7455
This was an old name for @code{$UNQUOTE} (@pxref{$UNQUOTE}). Please
7456
remove all references to this macro from existing codes.
7457
7458
@node $VERSION,,$VERBATIM,Built-in functions
7459
@comment node-name, next, previous, up
7460
7461
@subsubsection @code{$VERSION}: Present @FWEB{} version number
7462
7463
@findex $VERSION
7464
@cindex Version, of FWEB
7465
@samp{$VERSION} returns a string built out of the @FWEB{} version
7466
number, such as @code{"1.61"}.
7467
7468
@node Debugging with macros, , Built-in functions, FWEB macros
7469
@comment node-name, next, previous, up
7470
7471
@subsection Debugging with macros
7472
7473
@cindex Macros, debugging with
7474
@findex #line
7475
7476
If an @FWEB{} macro expands to more than one output line, debugging
7477
can be a bit confusing if the debugger (e.g., @code{gdb}) displays lines
7478
in the @code{web} source file instead of the output file (as it normally
7479
does for C and C++). While single-stepping through the code, the
7480
debugger will incorrectly step the screen display for each output line
7481
even if the macro call occupies just one line in the source file. To
7482
localize the debugger's confusion, insert a @samp{@@#line} command after
7483
the macro call. For example,
7484
7485
@example
7486
@@c
7487
@@ Example of a macro that expands to several output lines.
7488
@@m UPDATE(i, delta_i)
7489
i += delta_i;
7490
store(i)@@;
7491
@@a
7492
main()
7493
@{
7494
UPDATE(j, 5);
7495
@@#line
7496
// More code. The debugger will be in sync from here on.
7497
@}
7498
@end example
7499
7500
An alternative for highly confusing situations is to use the @samp{-#}
7501
option (@pxref{-#}).
7502
7503
Another potentially confusing situation occurs when @samp{@@%} is used
7504
to comment out a line. @FWEB{} deals with the line-number problem
7505
that arises here automatically; see @ref{-T#}.
7506
7507
@node Macros and formatting, Preprocessing, FWEB macros, Macros
7508
@comment node-name, next, previous, up
7509
7510
@cindex Macros, formatting
7511
@FWEAVE{} makes a valiant attempt to pretty-print
7512
(@pxref{Pretty-printing}) the definitions of
7513
both outer macros and @FWEB{} macros in a reasonable way. However, this
7514
can be a formidable task, because macro syntax can be essentially
7515
arbitrary. Consider, for example, the following definition:
7516
7517
@example
7518
@@c
7519
@@d GET(type) type get_##type()
7520
@@a
7521
GET(int)@{@}@@; // @r{Expands into @samp{int get_int()@{@}}.}
7522
@end example
7523
@noindent
7524
The problem is that the identifier @samp{type} is used in two different
7525
ways: as the type of a reserved word (the second @samp{type}), and as
7526
an ordinary expression (the third @samp{type}). The first @samp{type} has both
7527
meanings simultaneously. Unfortunately, within any particular language
7528
@FWEAVE{} associates one unique type or @dfn{ilk} with each identifier.
7529
7530
One solution to this problem is to use the @samp{@@R} command
7531
(@pxref{ATR_}), which changes the ilk of the very next identifier to
7532
integer-like. Thus,
7533
7534
@example
7535
@@d GET(type) @@R type get_##type()@@;
7536
@end example
7537
@noindent
7538
will format correctly. An alternative solution uses the related command
7539
@samp{@@E}, which
7540
changes the ilk of the very next identifier to an ordinary expression.
7541
Thus,
7542
7543
@example
7544
@@f type int
7545
@@d GET(type) type get_##@@Etype()@@;
7546
@end example
7547
7548
Other types of troublesome situations involve spaces. When @FWEB{}
7549
understands the syntax, it inserts spaces automatically to make the
7550
output pleasing. Consider, however, the (somewhat contrived) example
7551
7552
@example
7553
@@c
7554
@@d A(x, y) x y
7555
@@d B s1;
7556
@@d C s2;
7557
@@a
7558
A(B, C)@@;
7559
@end example
7560
@noindent
7561
Here @FWEAVE{} will consider @samp{x} and @samp{y} to be ordinary
7562
identifiers (simple expressions), and will abut them with no intervening
7563
spaces, which is confusing to read. The solution is to insert a space
7564
manually with @samp{@@,}:
7565
7566
@example
7567
@@d A(x, y) x @@, y
7568
@end example
7569
@noindent
7570
(Whether one should write macros like this at all is a separate issue.)
7571
For a related example, see the discussion of @ref{ATcomma}.
7572
7573
@node Preprocessing,,Macros and formatting,Macros
7574
@comment node-name, next, previous, up
7575
7576
@section Preprocessing
7577
7578
@cindex Macros, preprocessing
7579
@cindex Preprocessing
7580
Generally, the @FWEB{} preprocessor commands follow a syntax identical
7581
to their C/C++ counterparts. The one exception is the @samp{@@#line}
7582
command. Whereas the C command takes a line number and file name as
7583
arguments, the @FWEB{} command takes no arguments; its expansion
7584
automatically inserts the current line number and file name. This
7585
command should be necessary only in rare circumstances. One of those
7586
involves situations in which an @FWEB{} macro expands to more than one
7587
output line; see @ref{Debugging with macros}.
7588
7589
The @FWEB{} preprocessor commands may appear in either the definition or the
7590
code parts. But @emph{BEWARE: No matter where they appear, they are expanded
7591
during INPUT, not output.} (This is probably a design flaw.) For more
7592
discussion, see @ref{FWEB macros}.
7593
7594
@findex @@#line
7595
@findex @@#define
7596
@findex @@#undef
7597
@findex @@#ifdef
7598
@findex @@#ifndef
7599
@findex @@#if
7600
@findex @@#elif
7601
@findex @@#endif
7602
7603
The syntax of each command is as follows:
7604
7605
@quotation
7606
@table @code
7607
@item @@#line
7608
--- Insert a @code{#line} command.
7609
7610
@item @@#define @var{identifier}
7611
--- Define an FWEB macro; equivalent to @samp{@@m}.
7612
@item @@#undef @var{identifier}
7613
--- Undefine an FWEB macro.
7614
7615
@item @@#ifdef @var{identifier}
7616
--- Is FWEB macro defined? Equivalent to @w{@samp{@@#if defined identifier}}.
7617
@item @@#ifndef @var{identifier}
7618
--- Is FWEB macro not defined? Equivalent to @w{@samp{@@#if !defined identifier}}.
7619
7620
@item @@#if @i{expression}
7621
@item @@#elif @i{expression}
7622
@item @@#else
7623
@item @@#endif
7624
@end table
7625
@end quotation
7626
7627
In the @samp{@@#if} statement, the @i{expression} may contain @FWEB{}
7628
macros, but must ultimately evaluate to a number. If that number is
7629
zero, the expression is false; otherwise, it is true.
7630
7631
@cindex Expression evaluation
7632
The @i{expression} following constructions such as @samp{@@#if} is
7633
evaluated by a built-in expression evaluator that can also be used for
7634
other purposes, such as in macro expansion. Its behavior is again
7635
motivated by expression
7636
evaluation in ANSI C; it is not quite as general, but should be more than
7637
adequate. (One design flaw that will be fixed someday is that the order
7638
of expression evaluation is not necessarily left-to-right, as it is in C.)
7639
It supports both integer and floating-point arithmetic (with type
7640
promotion from integer to floating-point if necessary), and the ANSI
7641
@code{defined} operator. Operators with the highest precedence
7642
(see table below) are evaluated first; as usual, parentheses override the
7643
natural order of evaluation. The unary operator @code{defined}
7644
has the highest
7645
precedence; all the other unary operators have the next highest (and equal)
7646
precedence; then come the binary operators. When the operator exists in C,
7647
the action taken by @FWEB{} is precisely that that the C compiler would take.
7648
Arithmetic is done in either @b{long} or @b{double} variables, as
7649
implemented by the C compiler that compiled @FTANGLE{}. (This was the
7650
easy choice, not necessarily the most desirable one.)
7651
7652
The operators, listed from highest precedence to lowest, are as
7653
follows
7654
@ifinfo
7655
(printed documentation only):
7656
@end ifinfo
7657
7658
@page
7659
7660
@tex
7661
\gdef\expr{{\it expr}}
7662
\gdef\.#1{{\tt #1}}
7663
\chardef\TL=`\~% Tilde in a string: '\.\~'.
7664
\gdef\^{\ifmmode\raise0.45ex\hbox{$\,\scriptstyle\mathchar"25E\,$}%
7665
\else\char`^ \fi}%
7666
\global\let\amp\&
7667
$$\def\<{{\rm ,$\,$}}
7668
\def\mod{\Mathop{mod}}
7669
\vtop{\halign{\tt\quad#\quad\hfil&\ ---\
7670
\vtop{\hsize=0.75\hsize\noindent\hang \strut#\strut}\hfil\cr
7671
\noalign{\medskip\leftline{@b{Unary operators}:}\smallskip}
7672
defined&@code{defined} is a unary operator that acts on identifier tokens.
7673
@samp{defined id} or equivalently @samp{defined(id)} evaluates to~1 (true) if
7674
the identifier is defined as an @sc{Fweb} macro;
7675
to~0 (false) otherwise. The construction @samp{@@\#if defined A} works the
7676
same way as @w{@samp{@@\#ifdef A}}, but one can use @samp{defined} in
7677
expressions, as in
7678
$$
7679
\hbox{@code{@@\#if defined(A) || defined(B)}}.
7680
$$
7681
(The parentheses around the macro names are optional.)
7682
With the advent of @samp{defined}, the
7683
@sc{Fweb} preprocessor statements @samp{@@\#ifdef} and @samp{@@\#ifndef}
7684
become redundant, but are often useful shorthands.\cr
7685
-&Unary minus.\cr
7686
!&Logical \hbox{\.{NOT}}. \.{!\expr} evaluates to~0 if \.{\expr}
7687
is nonzero, and evaluates to~1 if \.{\expr} is~0.\cr
7688
\TL&One's complement of an integer. For example, $\.{\TL0} =
7689
-1$.\cr
7690
\noalign{\medskip\leftline{@b{Binary operators}:}\smallskip}
7691
\^\^&Exponentiation (all languages). $2\hbox{\.{\^\^}}3 = 8$.\cr
7692
\^\<**&Exponentiation (@sc{Fortran} or @sc{Ratfor}).\cr
7693
*\</\<\%&Multiplication, division, and modulus:
7694
`\.{$a$ \% $b$}' means `$a \hbox{ mod } b$'; for example, \.{5 \% 3 = 2}. \cr
7695
+\<-&The usual plus and minus.\cr
7696
<<&`\.{$a$ << $b$}' means shift integer~$a$ left $b$~bits. $1 \ll
7697
3 = 8$.\cr
7698
>>&As above, but right-shift. $7 \gg 2 = 1$.\cr
7699
<\<<=\<>\<>=&Evaluates to~1 if the inequality holds, to~0 otherwise.
7700
E.g., `\.{(2.0 < 3.0)}' evaluates to~1.\cr
7701
==\<!=&`\.{$a$==$b$}' (`\.{$a$!=$b$'}) evaluates to~1 (0) if $a$
7702
equals~$b$; evaluates to~0 (1) otherwise.\cr
7703
\amp&Bitwise \hbox{\.{AND}}. The truth table is \.{0b1100 \amp{
7704
}0b1010 = 0b1000}.\cr
7705
\^&Bitwise \.{EXCLUSIVE OR} (C). (For @sc{Fortran}, use `\.{.xor.}'.)
7706
The truth
7707
table is {\.{0b1100}~\.{.xor.}~\.{0b1010 = 0b0110}}.\cr
7708
|&Bitwise~\hbox{\.{OR}}. The truth table is \.{0b1100 | 0b1010 =
7709
0b1110}.\cr
7710
\amp\amp&Logical~\hbox{\.{AND}}.\ `\.{$a$ \amp\amp{ }$b$}'
7711
evaluates to~1 if both~$a$ and~$b$ are true (nonzero).\cr
7712
||& Logical~\.{OR}. `\.{$a$ || $b$}' evaluates to~1 if either~$a$ or~$b$
7713
are true.\cr
7714
}}$$
7715
Note in particular the use of the single caret, which is
7716
language-dependent: it is an
7717
exponentiation operator for @sc{Fortran} (just as in @TeX{}), but is the
7718
exclusive-or operator for~C. Also, note that the bitwise operators
7719
should almost never be used. For
7720
logic, almost always one will be using @samp{==}, @samp{!=}, @samp{\&\&},
7721
and @samp{||}.
7722
@end tex
7723
7724
@node Languages,Macros,Comments,Top
7725
@comment node-name, next, previous, up
7726
7727
@chapter LANGUAGES
7728
7729
@cindex Languages
7730
@cindex Language, global
7731
@FWEB{} has the ability to work with more than one source language
7732
during a single run. The language in effect at the beginning of the
7733
first section defines the @emph{global language}. Further language
7734
changes within a section have scope local to that section.
7735
7736
Usually, `language' means a compiler language like @sc{Fortran} or C.
7737
These languages will be ``pretty-printed'' by @FWEAVE{}.
7738
Pretty-printing can be inhibited by turning on the N mode (globally,
7739
with the command-line option @samp{-N}; locally, with @samp{@@N}) or by
7740
selecting the @sc{verbatim} `language'; in both of these cases, the input
7741
text is echoed literally to the output of both @FTANGLE{} and
7742
@FWEAVE{}.
7743
7744
`Language' is a stronger concept than `mode'. For example, when a
7745
language is selected, the extension of the tangled output file is
7746
changed appropriately---for example, if @file{test.web} contains C code
7747
(that is, contains the command @samp{@@c}), @file{test.web} tangles into
7748
@file{test.c} (compressing blanks and otherwise (deliberately) making
7749
the tangled output relatively unreadable) and @FWEAVE{} pretty-prints
7750
using the C syntax. Turning on the N mode does not affect the language;
7751
@FTANGLE{} copies the source code literally into @file{test.c} (no
7752
blank compression or other modifications), and @FWEAVE{} typesets the
7753
source code within a verbatim environment (no pretty-printing). When
7754
the @sc{verbatim} language is selected, the N mode is turned on
7755
automatically, but @FTANGLE{} writes its output to a file with a
7756
special default extension that can be customized in the style file.
7757
@xref{Miscellaneous params}.
7758
7759
@menu
7760
* Setting the language:: Setting the language.
7761
7762
Special hints and considerations for each language.
7763
* C:: C
7764
* C++: Cpp. C++.
7765
* Fortran:: Fortran--77 and Fortran--90.
7766
* Ratfor: Ratfor_. RATional FORtran.
7767
* TeX:: @TeX{}.
7768
* Verbatim:: Literal mode.
7769
@end menu
7770
7771
@node Setting the language, C, Languages, Languages
7772
@comment node-name, next, previous, up
7773
7774
@section Setting the language
7775
7776
@cindex Language, setting
7777
The most general form of a language command is
7778
7779
@quotation
7780
@@@i{[}L@i{]ltext}[@i{options}]
7781
@end quotation
7782
7783
@noindent
7784
where @i{l} is a language symbol, @i{text} is converted into the
7785
option @samp{-@i{l}text}, and @i{options} have the same syntax as on the
7786
command line.
7787
7788
The language symbols must be in lower case; they are
7789
7790
@quotation
7791
@multitable{..VERBATIM..}{cpp}
7792
@item C @tab @code{c}
7793
@item C++ @tab @code{c++}
7794
@item Fortran-77 @tab @code{n}
7795
@item Fortran-90 @tab @code{n9}
7796
@item Ratfor-77 @tab @code{r}
7797
@item Ratfor-90 @tab @code{r9}
7798
@item TeX @tab @code{x}
7799
@item VERBATIM @tab @code{v}
7800
@end multitable
7801
@end quotation
7802
7803
An example of a command with the optional @i{text} field is @samp{@@n/}.
7804
By definition, this is equivalent to @samp{@@n[-n/]}. Thus, it both sets
7805
the language and invokes a command-line option.
7806
7807
As another example, @samp{@@n9} really means @samp{@@n[-n9]}. Thus the
7808
language is first set to @sc{Fortran}, then reset to @sc{Fortran}-90.
7809
One doesn't need to worry about this detail.
7810
7811
@example
7812
@@n9[-n&]
7813
@end example
7814
7815
@noindent
7816
means set the language to @sc{Fortran}--90 and use free-form syntax with the
7817
ampersand as the continuation character. (This construction is now
7818
@FWEB{}'s default.)
7819
7820
The brackets may contain more than one space-delimited option.
7821
7822
A language command should appear somewhere in limbo, before the start of
7823
the first section. The language in effect at the beginning of the first
7824
section defines the global language. For historical reasons, the
7825
default language is @sc{Fortran}-77, but @emph{do not rely on this;
7826
always include a language command}.
7827
7828
Language commands may be used within sections, but the new language
7829
remains in force only for that section. The language of a named module
7830
is inherited from the language in effect at the time the name is first
7831
used. Thus, in the following example, the global language is
7832
@sc{Fortran}--77, but an arbitrary number of C functions can be placed into a
7833
C-language module with just one @samp{@@c} language-changing command.
7834
7835
@example
7836
@@n
7837
@@
7838
@@a
7839
program main
7840
end
7841
7842
@@c
7843
@@<C@@>@@;
7844
7845
@@
7846
@@<C@@>=
7847
int fcn()
7848
@{@}
7849
@end example
7850
7851
@noindent
7852
@FTANGLE{} will write two output files for this example---e.g.,
7853
@file{test.f} and @file{test.c}. Particularly note that one did not
7854
need an @samp{@@c} command in the last section because the language was
7855
C when @samp{@@<C@@>} was first encountered.
7856
7857
@section Special hints and considerations for each language
7858
7859
One important thing to keep in mind is that in @FWEB{} an identifier
7860
may have, for each language, precisely one meaning throughout the
7861
document. This restriction is not necessarily in accord with the
7862
syntaxes of the various source languages. See, for example, the
7863
discussions in @ref{Cpp} and @ref{Fortran}.
7864
7865
@node C, Cpp, Setting the language, Languages
7866
@comment node-name, next, previous, up
7867
7868
@subsection Special considerations for C
7869
7870
@cindex C hints
7871
@cindex Hints, C
7872
7873
@itemize @bullet
7874
7875
@item
7876
@cindex Binary notation
7877
@cindex Notation, binary
7878
@FTANGLE{} treats the construction @samp{0b...} as a binary notation
7879
that it expands to an unsigned decimal number. Thus, @samp{0b101}
7880
expands to 5 and @samp{0b1111111111111111} expands to 65535.
7881
7882
@item
7883
@FWEAVE{} processes @b{typedef} statements during phase one, so they will
7884
format properly even if they are used in a documentation part before
7885
they are defined in a code part.
7886
7887
@item
7888
The @samp{-H} option helps one to deal with identifiers defined in
7889
header files. @xref{-H_}.
7890
7891
@item
7892
@cindex Tags, enum
7893
@cindex Tags, structure
7894
Note that in C structure and enum tags do not define a new type, so the
7895
tag name does not get highlighted in boldface, underlined in the index,
7896
etc. (That is, if one says @samp{struct S @{...@};}, one can't say
7897
@samp{S s;}, one must say @samp{struct S s;}.) This is a good reason
7898
for using C++, where such tags do define a new type.
7899
7900
@end itemize
7901
7902
(To be completed.)
7903
7904
@node Cpp,Fortran,C,Languages
7905
@comment node-name, next, previous, up
7906
7907
@subsection Special considerations for C++
7908
7909
@cindex C++ hints
7910
@cindex Hints, C++
7911
@itemize @bullet
7912
7913
@item
7914
All of the items in the previous section (@pxref{C}) still apply.
7915
7916
@item
7917
The @samp{@@@{} command is very useful for beautifying very short
7918
definitions of member functions such as constructors. @xref{ATlb}
7919
7920
@item
7921
Essentially, @FWEAVE{} has only one name space, global to the entire
7922
code; those names do not obey any concept of scope. In various
7923
situations in C and C++, however, multiple namespaces are used, or the
7924
interpretation of a name changes according to its scope. Thus, the
7925
design of @FWEAVE{} imposes a few restrictions on one's programming
7926
style. (Remember, @FWEAVE{} doesn't know nearly as much as a language
7927
compiler.)
7928
7929
One example in C++ has to do with formal types in templates. Consider
7930
the following example:
7931
7932
@example
7933
template <class Type>
7934
class A
7935
@{
7936
private:
7937
Type *p;
7938
@}
7939
@end example
7940
@noindent
7941
In order that the class definition be typeset correctly, @samp{Type}
7942
must be understood to be a reserved word like @b{int}, and that is
7943
correctly figured out by the first @b{class} command. However,
7944
according to C++, the scope of @samp{Type} is local to the class
7945
definition; unfortunately, @FWEAVE{} does not respect that locality and will
7946
always treat @samp{Type} as an @b{int} from the point of the
7947
@samp{class Type} construction to the end of the source code. Thus, one
7948
should use such dummy variables as @samp{Type} only as formal template
7949
parameters, never as ordinary variables.
7950
7951
@end itemize
7952
7953
@node Fortran,Ratfor_,Cpp,Languages
7954
@comment node-name, next, previous, up
7955
7956
@subsection Special considerations for @sc{Fortran}
7957
7958
@cindex Hints, @sc{Fortran}
7959
@cindex @sc{Fortran} hints
7960
7961
@subsubsection Items for both @sc{Fortran}-77 and @sc{Fortran}-90
7962
7963
@itemize @bullet
7964
7965
@item
7966
@cindex Binary notation
7967
@cindex Notation, binary
7968
@cindex Octal notation
7969
@cindex Notation, octal
7970
@cindex Hexadecimal notation
7971
@cindex Notation, hexadecimal
7972
@FTANGLE{} will translate into unsigned decimal numbers the binary
7973
notation @samp{0b...}, the octal notation @samp{0...}, and the
7974
hexadecimal notation @samp{0x...}. Thus, @samp{0b101} expands to 5,
7975
@samp{0101} expands to 65, and @samp{0x101} expands to 257.
7976
7977
@item
7978
Don't use the column 1 @samp{C} commenting convention. Use @samp{/*
7979
... */} or @samp{// ...}.
7980
7981
@item
7982
For compiler directives, use @samp{@@?} (@pxref{AT?}), not a @samp{C} in
7983
column 1.
7984
7985
@item
7986
If you are going to use the recommended @samp{// ...} convention for
7987
short comments, you must say @samp{@@n/} (@pxref{-n/}) or
7988
@samp{@@n9[-n/]} as your language command. Otherwise, \FWEB\ will treat
7989
the @samp{//} as \@sc{Fortran's} standard token for concatenation. (You
7990
may always use @samp{\/} for concatenation.)
7991
7992
@item
7993
@cindex Code, temporarily commenting out
7994
If you want to completely comment out a whole block of code,
7995
use the preprocessor construction @samp{@@#if 0...@@#endif}
7996
(@pxref{Preprocessing}). Don't put a comment character at the beginning
7997
of each line; that prevents @FWEAVE{} from formatting the code
7998
sensibly and can be annoying to undo. With the preprocessor form, one
7999
can also implement conditional comments by using @FWEB{} preprocessor
8000
macros: e.g., @samp{@@#if(DEBUG)...@@#endif}.
8001
8002
Pre-@FWEB{} codes may have such blocks commented out with a @samp{C}
8003
in column 1. Those should be converted to the preprocessor
8004
construction. However, if you're in a real hurry, temporarily use the
8005
@samp{-nC} option (@pxref{-nC}) to kill those lines very early in the
8006
processing, before they can give you all kinds of trouble.
8007
8008
@item
8009
@cindex Comments, short
8010
An unfortunate byproduct of using @samp{//} for short comments is that,
8011
in general, format constructions like @code{format(//)} won't work. (It
8012
will work if one uses @samp{-nC}; see @ref{-nC}.) Alternatively, one
8013
can say @code{format(/ /)}.
8014
8015
@item
8016
Consecutive lines commented out with a @samp{C}, @samp{c}, @samp{*}, or
8017
@samp{!} in column 1 are converted into a single comment before
8018
processing by @FWEB{}. Large blocks of such lines (common in
8019
pre-@FWEB{} code) may overflow @FWEB{}'s tables. To avoid that,
8020
insert blank lines between some of the comments. Better, however, is to
8021
move most such blocks out of the code part to the @TeX{} part of the
8022
section. It's most readable to have only a few very short comments
8023
interspersed in the code.
8024
8025
To help with conversion of existing codes, the command-line option
8026
@samp{-nC} can be used to completely ignore comment lines.
8027
8028
@item
8029
@samp{@@} commands should, by and large, start in column 1. That's not
8030
necessary for short module names that fit on one line. However, a long
8031
module name that must be broken across lines must begin in column 1, as
8032
in
8033
8034
@example
8035
@@n
8036
@@
8037
@@a
8038
@@<This is a module name
8039
broken across lines@@>@@;
8040
@end example
8041
@noindent
8042
Failure to do this results in a spurious semicolon being inserted in the
8043
middle of the name. This happens because the @sc{Fortran}-77 input driver
8044
does various low-level manipulations of the source before it presents it
8045
to the innards of @FWEB{}; it's not tokenizing the source at that time
8046
and doesn't understand all of the @FWEB{} syntax such as module names.
8047
8048
@item
8049
Define symbolic statement labels with @samp{#:0}
8050
(@pxref{Tokens}). Such names should be followed by a colon. Thus,
8051
8052
@example
8053
@@n
8054
@@
8055
@@m EXIT #:0
8056
@@m ABORT #:0
8057
@@a
8058
.
8059
.
8060
ABORT: continue
8061
.
8062
.
8063
EXIT: continue
8064
.
8065
.
8066
@end example
8067
8068
@item
8069
By default, statement labels are @code{\llap}'d from the body of the
8070
statement. With this convention, long labels can extend too far into
8071
the left margin. Instead, try the command-line option @samp{-n:}
8072
(@pxref{-ncolon}), which puts them on a separate line. Alternatively, one
8073
can redefine the macro @code{\Wlbl}, found with some discussion in
8074
@file{fwebmac.sty}.
8075
@findex \Wlbl
8076
8077
@item
8078
@cindex Keywords, I/O
8079
@findex -k
8080
As a suggestion, use upper case for I/O keywords such as @code{IOSTAT}.
8081
However, by default the lower-case forms are also recognized. To permit
8082
only upper case, use @samp{-k} (@pxref{-k}). Note that although there
8083
is a command @samp{-nk}, it is unfortunately not related to @samp{-k}.
8084
8085
@item
8086
@cindex Exponentiation
8087
One may use @samp{^} as an alternative for the exponentiation operator
8088
@samp{**}.
8089
8090
@item
8091
@findex -+
8092
@cindex Assignment operators, compound
8093
@FWEB{} attempts to be helpful and tries to expand the operators
8094
@samp{++}, @samp{--}, @samp{+=}, @samp{-=}, @samp{*=}, and @samp{/=}
8095
in a way compatible with the usage in C and C++. For example, it
8096
expands @w{@samp{x += y}} into @w{@samp{x = x + (y)}}. This feature can be a
8097
great time-saver and also makes the code substantially more legible; it
8098
is strongly recommended. To turn off this feature, use the option
8099
@samp{-+}. @xref{-plus}.
8100
8101
@cindex Not equal
8102
Notice that in @sc{Fortran}-90 @samp{/=} is a token for ``not equal,''
8103
so if you want to use that you must use the @samp{-+} option. However,
8104
a better solution is to use @samp{!=}, @FWEB{}'s preferred operator
8105
for ``not equal.''
8106
8107
@item
8108
@cindex .true.
8109
@cindex .false.
8110
By default, the operators @code{.true.} and @code{.false.} will weave as
8111
caligraphic T and F. That appearance be changed by redefining the macros
8112
@code{\WTRUE} and @code{\WFALSE} in @file{fwebmac.sty} or in the limbo
8113
section of your source file.
8114
8115
@item
8116
@findex -#
8117
If @FTANGLE{} messes up and outputs incorrect @sc{Fortran} code, try
8118
tangling with the command-line option @samp{-#} (@pxref{-#}) (and then
8119
report the problem.)
8120
8121
@end itemize
8122
8123
@subsubsection Items specific to @sc{Fortran}-77 and fixed-form @sc{Fortran-90}
8124
8125
@itemize @bullet
8126
8127
@item
8128
@cindex Semicolons, automatic
8129
@cindex Automatic semicolons
8130
By default, when processing the code part the
8131
@sc{Fortran} driver inserts semicolons automatically at the end of each
8132
logical statement. Thus, the core of @FWEB{} is presented with a
8133
uniform syntax. However, when one escapes into code mode by using
8134
vertical bars, those semicolons aren't inserted, so something that
8135
appears a first glance to be complete statement may not be formatted as
8136
one might expect. Thus, the construction @samp{|5: continue|} doesn't
8137
format quite properly (the colon disappears); this problem is solved by
8138
putting a semicolon after the @samp{continue}. Also, if one is talking
8139
about multiple statements (for example, with a shift into code mode
8140
during @TeX{} documentation), there's no choice but to insert the
8141
semicolon between statements. For example, @w{@samp{|a = b; c = d;|}}.
8142
8143
@end itemize
8144
8145
@subsubsection Items specific to @sc{Fortran}-90
8146
8147
@itemize @bullet
8148
8149
@item
8150
@cindex Syntax, free-form
8151
If @sc{Fortran}-90 is selected (@pxref{-n9}), the default is
8152
@emph{free-form} syntax (lines are continued by a trailing ampersand).
8153
However, automatic line breaking is done in a way compatible with
8154
fixed-form syntax as well.
8155
8156
@item
8157
@findex -n!
8158
With free-form syntax, comment lines in the tangled output file begin
8159
with @samp{!}. But such lines are not recognized on input unless
8160
@samp{-n!} is used. @xref{-n!}.
8161
8162
@item
8163
@cindex Pseudo-semicolons, automatic
8164
@cindex Automatic pseudo-semicolons
8165
Beginning with Version 1.61, by default (pseudo-)semicolons are automatically
8166
inserted in free-form \Fortran-90 code, as one would expect. For more
8167
discussion, see @ref{-nAT;} and @ref{-n;}.
8168
8169
@end itemize
8170
8171
(To be completed.)
8172
8173
@node Ratfor_,TeX,Fortran,Languages
8174
@comment node-name, next, previous, up
8175
8176
@subsection Special considerations for @sc{Ratfor}
8177
8178
For some warnings about @sc{Ratfor}, see @ref{Caveats}.
8179
8180
@node TeX, Verbatim, Ratfor_, Languages
8181
@comment node-name, next, previous, up
8182
8183
@subsection Special considerations for TeX
8184
8185
@cindex Hints, @TeX{}
8186
@cindex @TeX{} hints
8187
@samp{@@Lx} is supported only to the extent that @code{fwebmac.sty} can
8188
be generated correctly from @code{fwebmac.web}. You are welcome to
8189
experiment, but you may encounter difficulties (which you should report;
8190
@pxref{Support}).
8191
8192
(To be completed.)
8193
8194
@node Verbatim, , TeX, Languages
8195
@comment node-name, next, previous, up
8196
8197
@subsection Special considerations for the @sc{verbatim} language
8198
8199
Unfortunately, the @sc{VERBATIM} language is not fully debugged.
8200
Therefore, it is not recommended for general use.
8201
(To be completed.)
8202
8203
@node Ratfor,Documentation,Macros,Top
8204
@comment node-name, next, previous, up
8205
8206
@chapter @sc{Ratfor}
8207
8208
@cindex @sc{Ratfor}
8209
@cindex @sc{Fortran}, Rational
8210
@cindex Rational @sc{Fortran}
8211
``@sc{Ratfor}'' stands for ``@sc{RATional} @sc{FORtran}.'' It endows
8212
@sc{Fortran} with a
8213
C-like syntax. Certain loop and other constructions (such as
8214
@samp{switch} or @samp{i++}) that are not allowed in @sc{Fortran} are allowed
8215
in @sc{Ratfor}; @FWEB{} translates those into proper @sc{Fortran}.
8216
8217
Although @sc{Ratfor} is a definite improvement over @sc{Fortran}, it certainly
8218
does not have the power of C (e.g., elegant pointer notation) or C++
8219
(e.g., classes). Many advantages accrue by taking the time to learn C.
8220
@sc{Ratfor} offers a gentle transition. (It is not supported very
8221
actively any more.)
8222
8223
@menu
8224
* Syntax: RSyntax. Ratfor syntax.
8225
* Commands:: Ratfor commands.
8226
* Caveats:: Nuances about @FWEB{} Ratfor.
8227
@end menu
8228
8229
@node RSyntax, Commands, Ratfor, Ratfor
8230
@comment node-name, next, previous, up
8231
8232
@section @sc{Ratfor} syntax
8233
8234
A sample @sc{Ratfor} program is
8235
8236
@example
8237
@@r
8238
@@
8239
@@a
8240
program main
8241
@{
8242
integer k;
8243
real fcn, x;
8244
8245
for(k=0; k<10; k++)
8246
@{
8247
x = fcn(k);
8248
8249
if(x < 0.0)
8250
@{
8251
x = 0.0;
8252
break;
8253
@}
8254
@}
8255
@}
8256
@end example
8257
@noindent
8258
The concluding brace of a function is translated into an @b{END}
8259
statement. Note the use of semicolons to terminate statements, braces
8260
to delimit compound statements, @samp{<} instead of @samp{.LT.}, the
8261
C-like @b{for} construction, and the @samp{k++} expression.
8262
8263
Constructions like @samp{k++} or @samp{k -= l + 1} must be used with
8264
great care. They translate to statements involving @samp{=} signs, so they
8265
can be used only where simple statements are allowed, not essentially
8266
anywhere as in C (for example, they cannot be used as function
8267
arguments).
8268
8269
@node Commands,Caveats,RSyntax,Ratfor
8270
@comment node-name, next, previous, up
8271
8272
@section @sc{Ratfor} commands
8273
8274
@subsection @sc{Ratfor}--77 commands
8275
8276
@cindex @sc{Ratfor} commands
8277
@example
8278
break; // @r{Used with @code{case} or to break out of loops, as in C.}
8279
case i: // @r{Used with @code{switch}.}
8280
default: // @r{Used with @code{case}, as in C.}
8281
do ...; @{...@} // @r{Note the semicolon (unnecessary if followed by a compound stmt).}
8282
else @{...@} // @r{Used after @code{if} as in C.}
8283
for(a;b;c) @{...@} // @r{As in C.}
8284
if(condition) @{...@}
8285
next; // @r{Equivalent to C's |continue| statement; go to bottom of loop.}
8286
repeat @{...@} until(condition); // @r{Equivalent to C's @code{do @{...@} while();}}
8287
return expression; // @r{As in C.}
8288
switch(expression) @{...@} // @r{As in C.}
8289
while(condition) @{...@} // @r{Like C's @code{while}.}
8290
@end example
8291
8292
@subsection Additional @sc{Ratfor}--90 commands
8293
8294
@example
8295
contains:
8296
interface name @{...@}
8297
interface operator(op) @{...@}
8298
interface assignment(assgnmnt) @{...@}
8299
module name @{...@}
8300
private:
8301
sequence:
8302
type name @{...@}
8303
where(expression) @{...@}
8304
@end example
8305
8306
@node Caveats,,Commands,Ratfor
8307
@comment node-name, next, previous, up
8308
8309
@section Caveats about @sc{Ratfor}
8310
8311
@cindex @sc{Ratfor}, caveats about
8312
The version of @sc{Ratfor} built into @FWEB{} differs slightly from its @sc{unix}
8313
counterpart:
8314
8315
@quotation
8316
@enumerate
8317
@item
8318
Numeric statement labels must be followed by a colon; they should
8319
be first on their line. (Use symbolic statement labels instead; see the
8320
discussion of @samp{#:0} in @ref{Tokens}.)
8321
8322
@item
8323
The quoting convention for characters and strings follows that
8324
of C: Single-quote single characters, double-quote strings.
8325
8326
@item
8327
In a @b{switch}, cases fall through to the next case unless
8328
terminated by @b{break} (just as in C).
8329
8330
@item
8331
The @b{do} statement must be terminated by a semicolon if
8332
followed by a simple statement. (It's unnecessary if followed by a left
8333
brace that begins a compound statement.)
8334
8335
@item
8336
Use @t{&&} and @t{||} for the logical AND and OR.
8337
8338
@item
8339
Do not use an @b{end} statement at the very end of a @sc{Ratfor} program
8340
unit; it is added automatically by @FWEB{} when the closing brace is sensed.
8341
@end enumerate
8342
@end quotation
8343
8344
8345
@node Documentation,Index,Ratfor,Top
8346
@comment node-name, next, previous, up
8347
8348
@chapter DOCUMENTATION
8349
8350
@cindex Formatting
8351
@cindex Documentation format
8352
@FWEB{} uses La@TeX{} to produce its documentation. Plain @TeX{}
8353
is no longer supported.
8354
8355
It is not necessary to be very familiar with La@TeX{} in order to use
8356
@FWEB{} effectively. @FWEB{} does complicated things behind
8357
the scenes, relieving the programmer of many burdens. If you don't need
8358
complicated mathematics, one needs to know virtually no La@TeX{} at all
8359
in order to document a section of code. And if you do need to typeset
8360
math, consider that La@TeX{} makes this daunting task about as simple as
8361
one could hope.
8362
8363
If you're an @FWEB{} beginner, don't bother diving into the details of
8364
this section until you really need to.
8365
8366
@menu
8367
* Typesetting:: Woven output; TeX vs. LaTeX, etc.
8368
* Pretty-printing:: Turning ugly input into beautiful output.
8369
@end menu
8370
8371
@node Typesetting, Pretty-printing, Documentation, Documentation
8372
@comment node-name, next, previous, up
8373
8374
@section Typesetting
8375
8376
@cindex Typesetting
8377
@FWEB{}'s ``new look'' (beginning with version 1.40) is designed
8378
to work only with La@TeX{}. The new look is more
8379
book-like, following ideas from Briggs' @code{nuweb}. By default, it
8380
uses default La@TeX{} section numbers such as 1.5.32; however, sections
8381
may be numbered with consecutive integers by specifying the La@TeX{}2e package
8382
@code{fwebnum}; see @ref{Numbering}.
8383
8384
@menu
8385
* Output:: Structure of the TeX output from @FWEAVE{}.
8386
* fwebmac.sty:: The macro package used with @FWEAVE{}.
8387
* LaTeX:: Specifics of the LaTeX support.
8388
@end menu
8389
8390
@node Output, fwebmac.sty, Typesetting, Typesetting
8391
@comment node-name, next, previous, up
8392
8393
@subsection @FWEAVE{}'s OUTPUT
8394
8395
When one says @samp{fweave test}, the file @file{test.tex} is created.
8396
Some @TeX{} commands contained in this file are created automatically;
8397
others are copied from the web source file. They are organized into several
8398
sequential groups, as follows.
8399
8400
@quotation
8401
@enumerate
8402
@item
8403
@code{\input} command to read in @FWEAVE{}'s macro package.
8404
8405
@findex fwebmac.sty
8406
By default, the initial input command is @samp{\input fwebmac.sty}
8407
(@pxref{fwebmac.sty}). The name of the macro package can be changed
8408
with
8409
the @samp{-w} command-line option, but that is dangerous and useful only for
8410
very special effects. @xref{-w}.
8411
8412
@item
8413
@code{\Wbegin} command.
8414
8415
The @code{\Wbegin} macro sets up certain defaults (which can be overridden in
8416
the limbo section). In La@TeX{}, it also issues the
8417
@samp{\documentclass@{article@}} and @samp{\begin@{document@}} commands.
8418
8419
@item
8420
Limbo text from the style-file parameter @code{limbo.begin}. @xref{S_limbo}.
8421
8422
@item
8423
Limbo text from @samp{@@l} commands. @xref{ATl}.
8424
8425
@item
8426
User's limbo section.
8427
8428
@item
8429
Limbo text from the style-file parameter @code{limbo.end}.
8430
@xref{S_limbo}.
8431
8432
@item
8433
@TeX{} commands for individual WEB sections.
8434
8435
@item
8436
@code{\input} command to read in the index data file.
8437
8438
@item
8439
@code{\input} command to read in the module-list data file.
8440
8441
@item
8442
@code{\Winfo} command (summarizes some status information).
8443
8444
@item
8445
@code{\Wcon} command (generates the Table of Contents, and ends the run).
8446
@end enumerate
8447
@end quotation
8448
8449
8450
8451
@node fwebmac.sty, LaTeX, Output, Typesetting
8452
@comment node-name, next, previous, up
8453
8454
@subsection The macro package @file{fwebmac.sty}
8455
8456
@findex fwebmac.sty
8457
@FWEAVE{} works in conjunction with the macro package
8458
@file{fwebmac.sty}, which is always read into the @file{.tex} file by
8459
default. This file is (overly) complicated, so one should not mess with
8460
it unless in dire emergency. Most of its commands are intended for
8461
behind-the-scenes processing. However, some features may be of general
8462
interest; these are described in the items below.
8463
8464
For the most part, macros used internally by @file{fwebmac.sty} begin
8465
with an uppercase @samp{W}. If you are worried about macro conflicts, a
8466
complete list of the macros appearing in @file{fwebmac.sty} can be found
8467
in the Index produced by weaving @file{fwebmac.web}.
8468
8469
@menu
8470
* User macros:: Macros defined for user convenience.
8471
* Fonts:: Useful font commands.
8472
@end menu
8473
8474
@node User macros, Fonts, fwebmac.sty, fwebmac.sty
8475
@comment node-name, next, previous, up
8476
8477
@subsubsection User macros
8478
8479
For the user's convenience, @file{fwebmac.sty} defines a variety of
8480
macros such as @samp{\FWEB}, @samp{\Fortran}, etc. Refer to
8481
@file{fwebmac.web} for a complete list.
8482
8483
@FWEAVE{} usurps various common single-character macros such as @samp{\.} for
8484
its own purposes. So the user can still access their original
8485
definitions, those are @samp{\let} equal to alternative commands
8486
such as @samp{\period}. For example, commands such as the following are
8487
executed in @code{fwebmac.sty}:
8488
8489
@example
8490
\let\amp\&
8491
\let\at\@@@@
8492
\let\bslash\\
8493
\let\caret\^
8494
\let\dollar\$
8495
\let\dstar\*
8496
\let\equals\=
8497
\let\leftbrace\@{
8498
\let\period\.
8499
\let\rightbrace\@}
8500
\let\vertbar|
8501
\let\PM\#
8502
\let\PC\%
8503
@end example
8504
@noindent
8505
(Some of the more inscrutable synonyms are for historical reasons.)
8506
8507
For the most up-to-date and detailed information, refer to @file{fwebmac.web}.
8508
8509
@node Fonts, , User macros, fwebmac.sty
8510
@comment node-name, next, previous, up
8511
8512
@subsubsection Fonts
8513
8514
@cindex Fonts
8515
Several fonts have been declared.
8516
Those include
8517
8518
@quotation
8519
@itemize @bullet
8520
@item
8521
@samp{\titlefont} (large sans serif),
8522
8523
@item
8524
@samp{\ttitlefont} (large typewriter),
8525
8526
@item
8527
@samp{\SC} (small caps),
8528
8529
@item
8530
@samp{\Csc} (Caps/small caps), and
8531
8532
@item
8533
@samp{\tentex} (@TeX{}'s extended character set).
8534
8535
@end itemize
8536
@end quotation
8537
8538
@noindent
8539
For illustrations and further details, see @file{fwebmac.web}.
8540
8541
To typeset a string of characters in typewriter type, one may use the
8542
@samp{\.} macro. (More precisely, the name of this macro is the value
8543
of the style-file parameter @code{format.typewriter}. For more
8544
information, see @ref{S_format}.)
8545
When using this, one must escape the special
8546
characters @samp{ \#%$^_@{@}~&}, as in @samp{\.@{\\alpha@}}. (@FWEAVE{}
8547
does that escaping automatically when typesetting strings in code mode.)
8548
You may wish to surround @samp{\.@{...@}} with an @samp{\hbox}; that is
8549
not done by default because @FWEAVE{} uses special trickery to break
8550
long strings in code mode automatically, and that breaking would be
8551
inhibited by an @samp{\hbox}.
8552
8553
@node LaTeX, , fwebmac.sty, Typesetting
8554
@comment node-name, next, previous, up
8555
8556
@subsection La@TeX{} support
8557
8558
@cindex La@TeX{}
8559
@cindex La@TeX{}2e
8560
Original La@TeX{} support (through version 1.30) was substantially
8561
incomplete in that La@TeX{}'s @code{\output} routine was usurped by the
8562
relatively simple one used for @FWEB{}'s @TeX{} support. However,
8563
beginning with version 1.40, full La@TeX{} support is provided (and
8564
Plain @TeX{} is @emph{not} supported); version 1.50 supports La@TeX{}2e.
8565
La@TeX{}'s @code{\output} routine is used, as are its sectioning
8566
commands (with minor changes), Table-of-Contents facilities, etc.
8567
8568
The following discussion is based on La@TeX{}2e. If La@TeX{}2e is not
8569
installed, @FWEAVE{} recognizes that fact and issues the
8570
@samp{\documentstyle} command instead of @samp{\documentclass}.
8571
@findex \documentstyle
8572
8573
Users are strongly encouraged to upgrade to La@TeX{}2e. A useful book
8574
that describes the present state of La@TeX{} is Goossens, Mittelbach,
8575
and Samarin, @cite{The La@TeX{} Companion} (Addison--Wesley, Reading, MA,
8576
1994).
8577
8578
@menu
8579
* Document class:: LaTeX's document class, options, etc.
8580
* REVTeX:: The REV@TeX{} scientific macro package.
8581
* Packages:: Special FWEB-related La@TeX{}2e packages.
8582
* Sections:: Section numbering, spacing, etc.
8583
* Index:LIndex. Technical details about multi-columns and the Index.
8584
* Table of Contents:: The Table of Contents.
8585
* Customizing LaTeX:: Conditional flags, etc.
8586
* Inserting woven code:: How to insert @FWEAVE{}'s output into a La@TeX{} document.
8587
@end menu
8588
8589
@node Document class, REVTeX, LaTeX, LaTeX
8590
@comment node-name, next, previous, up
8591
8592
@subsubsection La@TeX{}'s document class
8593
8594
@findex \documentclass
8595
An @FWEB{}/La@TeX{} document is set up with the @samp{\Wbegin}
8596
command, issued automatically by @FWEAVE{}. See the summary at the
8597
end of this section for the essence of what the @samp{\Wbegin} command
8598
accomplishes.
8599
8600
@FWEAVE{} uses @code{\documentclass@{article@}} by default. In
8601
principle, the document class can be changed by the @FWEB{} style-file
8602
option @samp{LaTeX.class}; see @ref{Fwebmac params}. However,
8603
@emph{@FWEAVE{} has not been tested with most other document classes}.
8604
It will probably not work with most document classes that redefine the
8605
sectioning commands from those of @code{\documentclass@{article@}}.
8606
However, it @emph{may} work with the @code{revtex} scientific macro
8607
package. @xref{REVTeX}.
8608
8609
To incorporate class options---i.e., to obtain the effect of
8610
@samp{\documentclass[myoptions]@{article@}}---use the style-file parameter
8611
@code{LaTeX.class.options}, as in
8612
@cindex Class options
8613
@cindex Options, class
8614
8615
@example
8616
LaTeX.class.options "myoptions"
8617
@end example
8618
@noindent
8619
To get two-sided printing, for example, one would say
8620
@cindex Printing, two-sided
8621
8622
@example
8623
LaTeX.class.options "twoside"
8624
@end example
8625
8626
@findex \usepackage
8627
@cindex User packages
8628
@cindex Packages, user
8629
To specify user packages---i.e., to obtain the effect of
8630
@samp{\usepackage[pkgoptions]@{pkgname@}}---use the style-file parameters
8631
@code{LaTeX.package} and @code{LaTeX.package.options}, as in
8632
8633
@example
8634
LaTeX.package "pkgname"
8635
LaTeX.package.options "pkgoptions"
8636
@end example
8637
@noindent
8638
For example, to indent the first line of every section and to permit the
8639
use of the @code{multicol} package (the latter is a useful way of
8640
substantially cutting down on white space), say
8641
8642
@example
8643
LaTeX.package "indentfirst,multicol"
8644
@end example
8645
8646
Note that specifying @code{LaTeX.package} and
8647
@code{LaTeX.package.options} results in the execution (by the
8648
@code{\Wbegin} macro) of precisely @emph{one} line of the form
8649
8650
@example
8651
\usepackage[myoptions]@{mypackages@}
8652
@end example
8653
@noindent
8654
Sometimes one instead needs to have multiple @code{\usepackage} lines,
8655
such as
8656
8657
@example
8658
\usepackage[option1]@{package1@}
8659
\usepackage[option2]@{package2@}
8660
@end example
8661
@noindent
8662
To get this effect, one can put these commands explicitly into the
8663
style-file parameter @code{doc.preamble} (see discussion two paragraphs
8664
below), as in
8665
8666
@example
8667
doc.preamble = "\\usepackage[option1]@{package1@}\
8668
\\usepackage[option2]@{package2@}"
8669
@end example
8670
8671
@TeX{} commands in the user's limbo section of the @code{web} source
8672
file will be processed @emph{after} the @code{\begin@{document@}}
8673
command. Limbo commands from the style file can be inserted before
8674
and/or after those in the limbo section with the aid of the style-file
8675
parameters @samp{limbo.begin} and @samp{limbo.end}; see @ref{S_limbo}.
8676
8677
If there is a compelling reason to insert one's own La@TeX{}
8678
commands between the @samp{\usepackage} and @samp{\begin@{document@}}
8679
commands, one may use the style-file parameter @samp{doc.preamble},
8680
whose value is a string consisting of La@TeX{} commands (empty by
8681
default). Those commands are processed immediately before
8682
@samp{\begin@{document@}}. One use of @samp{doc.preamble} is to inhibit
8683
@FWEB{}'s tendency to keep a section together on one page. To make it
8684
break more readily in the middle of sections (particularly useful for
8685
multicolumn output), say
8686
8687
@example
8688
doc.preamble "\\secpenalty=0"
8689
@end example
8690
8691
In summary, the beginning of the file output by @FWEAVE{} looks like
8692
the following, where @samp{<parameter>} means the contents of the
8693
style-file string called @samp{parameter}:
8694
8695
@example
8696
\input fwebmac.sty
8697
\Wbegin@{many obscure arguments@}
8698
<limbo.begin>
8699
Optional TeX commands copied from user's limbo section
8700
<limbo.end>
8701
@end example
8702
8703
@noindent
8704
@findex \Wbegin
8705
The @samp{\Wbegin} command essentially does the following:
8706
8707
@example
8708
\documentclass[<LaTeX.class.options>]@{<LaTeX.class>@}
8709
\usepackage[<LaTeX.package.options>]@{<LaTeX.package>@}
8710
<doc.preamble>
8711
\begin@{document@}
8712
@end example
8713
@noindent
8714
For precise information about how @samp{\Wbegin} works, see
8715
@code{fwebmac.web}. If you feel that macro absolutely needs to be
8716
changed, please inform the developer (@pxref{Support}).
8717
8718
@node REVTeX, Packages, Document class, LaTeX
8719
@comment node-name, next, previous, up
8720
8721
@subsubsection Using REV@TeX{}
8722
8723
REV@TeX{} is the standard macro package used for formatting scientific
8724
papers submitted to the American Physical Society, the American
8725
Institute of Physics, and some European journals. It modifies the
8726
sectioning commands of @code{\documentclass@{article@}} and provides
8727
various other useful macros.
8728
8729
Unfortunately, as of August, 1998, REV@TeX{} is not fully compatible
8730
with La@TeX{}2e; it must be invoked with
8731
@code{\documentstyle@{revtex@}}, not @code{\documentclass}. This is
8732
annoying, because @FWEB{}'s macros in @file{fwebmac.sty} default to
8733
@code{\documentclass} if they recognize that La@TeX{}2e is loaded.
8734
8735
To use REV@TeX{}, uncomment the line in @file{fwebmac.sty} that says
8736
@code{\useREVTeXtrue}. (One cannot say @samp{\useREVTeXtrue} in the
8737
limbo section of one's @code{web} source, because the document class has
8738
already been selected by that time.) You may wish to rename the
8739
resulting file, say to @file{rwebmac.sty}, so it can be loaded in place
8740
of the standard @file{fwebmac.sty}. To do that, one would use the
8741
command-line option @samp{-wrwebmac.sty} (see @ref{-w}).
8742
8743
Saying @code{\useREVTeXtrue} selects @code{\documentstyle} rather than
8744
@code{\documentclass}. To implement a standard command such as
8745
@code{\documentstyle[aps,my_macros]@{revtex@}}, use the style-file
8746
(@file{fweb.sty}) parameters @code{LaTeX.style} and
8747
@code{LaTeX.options}, as in
8748
8749
@example
8750
LaTeX.style "revtex"
8751
LaTeX.options "aps,my_macros"
8752
@end example
8753
@noindent
8754
Here @file{my_macros.sty} would be a user's macro package loaded in
8755
addition to those of REV@TeX{} and @FWEB{}.
8756
8757
REV@TeX{} support is extremely recent. There may be glitches; please
8758
report those. In a pinch, if La@TeX{} stops while processing a
8759
REV@TeX{} file produced by @FWEAVE{}, try typing `s' (scroll mode) to
8760
force it to continue; you might get usable output.
8761
8762
@node Packages, Sections, REVTeX, LaTeX
8763
@comment node-name, next, previous, up
8764
8765
@subsubsection La@TeX{} packages related to @FWEB{}
8766
8767
The following packages are supplied with the @FWEB{} distribution and
8768
can be used to achieve special effects. Packages are invoked by giving
8769
their names as arguments to the @code{LaTeX.package} command; see
8770
@ref{S_LaTeX}.
8771
8772
@iftex
8773
@itemize @bullet
8774
@item
8775
@code{fwebinsert} --- Enables insertion of woven code into a La@TeX{}
8776
document.
8777
@xref{Inserting woven code}.
8778
8779
@item
8780
@code{fwebnum} --- Number each section in ascending integer order.
8781
@xref{Numbering}.
8782
8783
@item
8784
@code{idxmerge} --- Merge several stand-alone indexes. @xref{Merging indexes}.
8785
8786
@end itemize
8787
@end iftex
8788
8789
@menu
8790
* fwebinsert:Inserting woven code. Enable insertion of woven code into a La@TeX{} document.
8791
* fwebnum:Numbering. Number each section in ascending order.
8792
* idxmerge:Merging indexes. Merge several stand-alone indexes.
8793
@end menu
8794
8795
@node Sections, LIndex, Packages, LaTeX
8796
@comment node-name, next, previous, up
8797
8798
@subsubsection Sections in La@TeX{}
8799
8800
@cindex La@TeX{} section
8801
@findex \section
8802
@findex \subsection
8803
@findex \subsubsection
8804
@FWEB{}'s sectioning commands @samp{@@*} and @samp{@@*@i{n}}
8805
are converted into
8806
La@TeX{}'s section commands such as @code{\section} (@i{n}=0),
8807
@code{\subsection} (@i{n}=1), and
8808
@code{\subsubsection} (@i{n}=2). During La@TeX{}'s processing of the
8809
@code{.tex} file, it
8810
keeps track of the maximum depth achieved by @samp{@@*@i{n}}. This number is
8811
written as the last item in the @file{aux} file. During the next
8812
La@TeX{} run,
8813
that number is used to map the untitled @ASP{} commands to the next most
8814
insignificant sectioning command. That level of sectioning command is
8815
slightly redefined from La@TeX{}'s default, so don't try to redefine it.
8816
8817
The previous scheme means that it may be necessary to run La@TeX{} as
8818
many as three times in order to resolve all sectioning and
8819
cross-reference information correctly. You should be warned in such
8820
cases. If not, you will recognize difficulties by noting that the Table
8821
of Contents or section numbering is incomplete.
8822
8823
The @file{aux} file is also used by both processors to generate
8824
appropriate error messages that refer to the La@TeX{} section number
8825
instead of the internal one.
8826
8827
A discussion of alternative section-numbering schemes is given in
8828
@ref{Numbering}.
8829
8830
@node LIndex, Table of Contents, Sections, LaTeX
8831
@comment node-name, next, previous, up
8832
8833
@subsubsection La@TeX{}'s index.
8834
8835
@cindex Index
8836
@findex \INDEX
8837
@findex \beforeindex
8838
@findex \startindex
8839
@findex \Wfin
8840
The Index should be the last section of the code, and should be begun by the command @samp{@@* \INDEX.}. For more
8841
information, see @ref{S_index}.
8842
8843
The challenge of typesetting the Index is to get it into two-column mode
8844
in the best possible way. In the original Plain-@TeX{} @FWEB{},
8845
special code was provided for this. With La@TeX{}, however, one wants
8846
to use standard features.
8847
8848
@cindex @code{multicol}, using
8849
@cindex Package, @code{multicol}
8850
@findex multicol.sty
8851
@findex \twocolumn
8852
The best solution is to use the user package @code{multicol}. If that
8853
is loaded by means of the style-file statement @samp{LaTeX.package
8854
"multicol"}, then any text typed by the user following the @samp{@@*
8855
\INDEX.} command will
8856
be typeset in single-column mode, after which two-column mode is
8857
entered. If it is not loaded, a @samp{\twocolumn} command is issued
8858
@emph{before} the index section is begun (in order to get the Index
8859
started on a new page).
8860
8861
More precisely, what happens is the following. When the @samp{@@*
8862
\INDEX.} command is recognized, essentially the following operations are
8863
performed, where the results are bracketed in the form @samp{[multicol :
8864
nomulticol]}:
8865
8866
@example
8867
\beforeindex [\newpage : \twocolumn]
8868
[print INDEX section heading]
8869
\startindex [\begin@{multicols@}@{2@} : \medskip]
8870
\Wfin [\end@{multicols@} : \relax]
8871
@end example
8872
@noindent
8873
(Use of the asymmetrical name @samp{\Wfin} is for historical reasons.)
8874
8875
@cindex Columns, multiple
8876
The positioning of @samp{\beforeindex} suggests a way of printing the
8877
entire document in two-column mode. If one enters multi-column mode in
8878
the limbo section, then @samp{\beforeindex} can be used to terminate it.
8879
It is best to do this at the @emph{end} of the limbo section; otherwise
8880
user macro definitions in the limbo section must be made @code{\global} in order
8881
that they remain defined in the Index. The relevant commands can be
8882
placed in the style file:
8883
8884
@example
8885
LaTeX.package "multicol"
8886
8887
doc.preamble "\\secpenalty=0"
8888
8889
limbo.end "\\def\\beforeindex@{\\end@{multicols@}\\newpage@}\n\
8890
\\begin@{multicols@}@{2@}\n\
8891
\\raggedcolumns"
8892
@end example
8893
@noindent
8894
Just to repeat, use only the first command to get just the Index printed
8895
in two-column format; use the second and third ones to make the entire
8896
document two-column.
8897
8898
@node Table of Contents, Customizing LaTeX, LIndex, LaTeX
8899
@comment node-name, next, previous, up
8900
8901
@subsubsection La@TeX{}'s Table of Contents
8902
8903
@cindex Contents, table of
8904
@cindex Table of Contents
8905
@findex \FWEBtoc
8906
La@TeX{} uses the @file{aux} file to accumulate the information for the
8907
Table of Contents.
8908
8909
When La@TeX{} is used, the Table of Contents appears at the front of the
8910
document by default (beginning with version 1.61). This is accomplished
8911
by setting the default value of the style-file parameter
8912
@code{limbo.end} to @code{"\\FWEBtoc"}, where @code{\FWEBtoc} is defined
8913
in @file{fwebmac.sty}. If you initialize @code{limbo.end} yourself in
8914
@file{fweb.sty}, you should include @code{"\\FWEBtoc"} at the end of
8915
that initialization if you want the Table of Contents to appear in the
8916
beginning. Otherwise, it will appear at the end.
8917
8918
In essence, the Table of Contents is produced by the La@TeX{} commands
8919
8920
@example
8921
\pagenumbering@{roman@}
8922
\maketitle
8923
\topofcontents
8924
\tableofcontents
8925
\botofcontents
8926
\newpage
8927
@end example
8928
8929
@noindent
8930
@findex \topofcontents
8931
@findex \botofcontents
8932
@findex \maketitle
8933
@findex \Title
8934
@findex \title
8935
By default, the @FWEB{} hooks @code{\topofcontents} and
8936
@code{\botofcontents} are empty,
8937
but they may be used in special circumstances to override the usual
8938
behavior. One can set the parameters for @code{\maketitle} in the limbo
8939
section in the usual La@TeX{} way, except that it is better to use
8940
@FWEB{}'s @code{\Title} macro instead of @code{\title}:
8941
8942
@example
8943
\Title@{MYCODE.WEB@}
8944
\author@{My name@}
8945
\date@{January 1, 2001@}
8946
@end example
8947
8948
By default, the argument of the @code{\Title} macro is printed both on
8949
the title page and as a running headline in the document. The default
8950
font for the title is @code{\ttitlefont}; that for the running headline
8951
is @code{\large\tt}. However, @code{\Title} has one optional argument
8952
that allows one to override the running headline, perhaps by specifying
8953
a shorter form. Say
8954
8955
@example
8956
\Title[@i{Short title}]@{@i{Long title}@}
8957
@end example
8958
@noindent
8959
to make the running headline be @samp{\large\tt @i{Short title}} and the
8960
title-page title be @samp{\ttitlefont @i{Long title}}.
8961
8962
The \@FWEB{} @code{\Title} macro calls La@TeX{}'s @code{\title} macro
8963
with the long title as its argument.
8964
By default, @FWEAVE{} uses (in the @samp{\Wbegin} macro)
8965
8966
@example
8967
\title@{@}%
8968
\author@{@}%
8969
\date@{\today\\[3pt]\Time@}%
8970
@end example
8971
8972
@findex \numberline
8973
Section numbers in the Table of Contents are produced by the La@TeX{}
8974
macro @code{\numberline}. La@TeX{}'s default definition is inadequate
8975
when section numbers are very large; they extend to the right and can
8976
overwrite the section name. The macro is redefined more appropriately
8977
when the package @code{fwebnum} (@pxref{Numbering}) is used.
8978
8979
@node Customizing LaTeX, Inserting woven code, Table of Contents, LaTeX
8980
@comment node-name, next, previous, up
8981
8982
@subsubsection Customizing La@TeX{}'s output
8983
8984
Several (@TeX{}) flags are provided to change the appearance of the final
8985
La@TeX{} document. (This appearance is a bit experimental, and it is
8986
fair to say that not everything may be fully debugged; please report
8987
problems.) These are (@samp{...} means either @samp{true} or @samp{false})
8988
8989
@quotation
8990
@itemize @bullet
8991
@item
8992
@findex \pagerefs
8993
@code{\pagerefs...} (index references by pages or section numbers);
8994
8995
@item
8996
@findex \numberTeX
8997
@code{\numberTeX...} (number the beginning of unnamed TeX parts);
8998
8999
@item
9000
@findex \numberdefs
9001
@code{\numberdefs...} (number the beginning of the definition part);
9002
9003
@item
9004
@findex \numbercode
9005
@code{\numbercode...} (number the beginning of the code part).
9006
@end itemize
9007
@end quotation
9008
9009
@noindent
9010
The defaults for these flags are
9011
9012
@example
9013
\pagerefsfalse
9014
\numberTeXfalse
9015
\numberdefstrue
9016
\numbercodetrue
9017
@end example
9018
9019
@noindent
9020
If desired, one may override these in the limbo section.
9021
(They are defined using Plain @TeX{}'s @samp{\newif} rather than the
9022
equivalent La@TeX{} command because they may also be used when La@TeX{}
9023
is not present.)
9024
9025
@code{\numberTeX} is on the verge of obsolescence. Try to not use it;
9026
never use it in conjunction with the package @code{fwebnum}.
9027
@xref{Numbering}
9028
9029
@menu
9030
* Page references:: Indexing by page numbers.
9031
* Headers:: The content of page headers.
9032
* Numbering:: Various section numbering schemes.
9033
@end menu
9034
9035
@node Page references, Headers, Customizing LaTeX, Customizing LaTeX
9036
@comment node-name, next, previous, up
9037
9038
@subsection Page references
9039
9040
@findex \pagerefs
9041
@cindex Page numbers
9042
@cindex Sections, numbering
9043
When one says @samp{\pagerefstrue} (La@TeX{} only), index references are
9044
made by page numbers rather than module numbers or La@TeX{} section
9045
numbers. If there is more than one section per page, they are
9046
identified by @samp{a}, @samp{b}, @samp{c}, etc., such as @samp{section
9047
17b}. (Presently, this will not work correctly when @code{multicol} is
9048
used for the body of the document.)
9049
9050
The information necessary to process page references in this way is
9051
written into the @file{aux} file. As is usual with La@TeX{}, several runs
9052
may be required for the references to be fully consistent with the
9053
source file.
9054
9055
@node Headers, Numbering, Page references, Customizing LaTeX
9056
9057
@subsection Page headers
9058
9059
@cindex Headers
9060
@cindex Page headers
9061
The very top (header) line on each page of @FWEAVE{}'s output contains
9062
several pieces of information:
9063
9064
@itemize @bullet
9065
9066
@item
9067
the current section name or document title;
9068
9069
@item
9070
the page number;
9071
9072
@item
9073
the range of La@TeX{} section numbers on the
9074
page (these are preceded by the
9075
@ifinfo
9076
@samp{\S}
9077
@end ifinfo
9078
@tex
9079
\S\
9080
@end tex
9081
symbol); and
9082
9083
@item
9084
the range of integer section numbers as understood internally by
9085
@FWEAVE{} (those are in square brackets and preceded by the @samp{#} sign).
9086
9087
@end itemize
9088
9089
@node Numbering, , Headers, Customizing LaTeX
9090
@comment node-name, next, previous, up
9091
9092
@subsection Section numbering schemes
9093
9094
@cindex Sections, numbering
9095
@cindex Package, @code{fwebnum}
9096
@findex fwebnum.sty
9097
The @FWEB{} commands @samp{@@*} and @ASP{} are translated by
9098
complicated magic into La@TeX{} commands such as @code{\section},
9099
@code{\subsection}, etc. By default, use of
9100
@code{\documentclass@{article@}} then produces Dewey-decimal section
9101
numbers such as 2.13.4 (subsubsection 4 of subsection 13 of section 2).
9102
When the section tree is very deep, these numbers can look somewhat obtrusive.
9103
9104
An alternative scheme (that of the original @sc{web}) is to merely
9105
number each section in ascending integer order, beginning with 1. This
9106
can be done by specifying the package @code{fwebnum}, as in
9107
9108
@example
9109
LaTeX.package = "fwebnum"
9110
@end example
9111
@noindent
9112
This package is supplied with the @FWEB{} distribution; it is still
9113
somewhat experimental.
9114
9115
By default, @code{fwebnum} numbers all sections, including unnamed
9116
ones. To prohibit numbering of unnamed sections, use the package option
9117
@code{dontnumberunnamed}, as in
9118
9119
@example
9120
LaTeX.package.options = "dontnumberunnamed"
9121
@end example
9122
@noindent
9123
This option will eventually make @code{\numberTeX} obsolete; do not use
9124
@code{\numberTeX} in conjunction with @code{fwebnum}.
9125
9126
@node Inserting woven code, , Customizing LaTeX, Packages
9127
@comment node-name, next, previous, up
9128
9129
@subsubsection Package @code{fwebinsert}: Inserting @FWEAVE{}'s output into a La@TeX{} document
9130
9131
@cindex FWEB output, inserting into LaTeX document
9132
@findex fwebinsert.sty
9133
Beginning with version 1.61, it is (barely) possible to insert the
9134
@TeX{} output woven by @FWEAVE{} into a La@TeX{} document. For
9135
example, a code listing could be an appendix to a dissertation, or a
9136
handbook on numerical methods could insert fragments of code formatted
9137
by @FWEAVE{}.
9138
9139
Suppose one has the file @file{test.web} and used @FWEAVE{} to create
9140
@file{test.tex}. Unfortunately, it does @emph{not} work to simply
9141
@code{\input test.tex} into a La@TeX{} document, because by
9142
default @file{test.tex} operates in a ``stand-alone'' mode and tries to
9143
issue a @code{\begin@{document@}} command.
9144
9145
Instead, one must use the package @code{fwebinsert} and the special
9146
input command @code{\FWEBinput}, as in the following example. There are
9147
two important steps.
9148
9149
@quotation
9150
@enumerate
9151
@item
9152
Use @FWEAVE{} to create @file{test.tex}.
9153
[You may wish to use the @samp{-x} flag
9154
(@pxref{-x}) to prevent some of the lists at the end, such as the index
9155
or module list, from being printed.]
9156
9157
@item
9158
Now @samp{latex test} until all of the section numbering is up-to-date.
9159
(This step is necessary because information in the @file{aux} file is
9160
used in processing the section headings.)
9161
@end enumerate
9162
@end quotation
9163
@noindent
9164
Now @file{test.tex} is ready to be inserted in a code like the
9165
following:
9166
9167
@example
9168
\documentclass@{article@}
9169
\usepackage@{fwebinsert@}
9170
9171
\begin@{document@}
9172
9173
\section@{Body@}
9174
9175
The body of the document.
9176
9177
\appendix
9178
9179
\FWEBinput@{test@}
9180
9181
\end@{document@}
9182
@end example
9183
9184
Note that the @samp{@@*} commands in @file{test.web} are converted into
9185
La@TeX{} sectioning commands such as @code{\section}. The above example
9186
works correctly because the first @samp{@@*} in @file{test.web} is
9187
equivalent to a @code{\section} (level 0) command, which should indeed
9188
immediately follow an @code{\appendix} command. Suppose, however, that
9189
you wanted to input @file{test.web} as part of the body of the above
9190
example, and wanted the @samp{@@*}s to be treated as subsections (level
9191
1) rather than sections. To tell @code{fwebinsert} what level number to
9192
assign to the @samp{@@*}s, provide that number as an optional argument
9193
to @code{\FWEBinput}, as in the following example:
9194
9195
@example
9196
\documentclass@{article@}
9197
\usepackage@{fwebinsert@}
9198
9199
\begin@{document@}
9200
9201
\section@{Body@}
9202
9203
The body of the document.
9204
9205
\FWEBinput[1]@{test@}
9206
9207
\end@{document@}
9208
@end example
9209
@noindent
9210
Alternatively, say @code{\FWEBlevel@{1@}} before the @code{\FWEBinput}.
9211
(The optional argument construction merely calls @code{\FWEBlevel}.)
9212
9213
Here are some caveats about @code{fwebinsert}:
9214
9215
@itemize @bullet
9216
9217
@item
9218
Implementing this package was tricky. It may work in simple
9219
circumstances, but it is not fully debugged.
9220
9221
@item
9222
The @code{\FWEBinput} command surrounds the included @TeX{} code with
9223
@code{\begingroup}...@code{\endgroup}, in an attempt to prevent various
9224
macro conflicts. As it stands, the command @code{\fwebinput} is
9225
@code{\let} equal to @code{\FWEBinput}. If necessary, one could redefine
9226
@code{\fwebinput} to not include the enclosing
9227
@code{\begingroup}...@code{\endgroup}.
9228
9229
@item
9230
For anything except level-0 inclusions, one should have just one
9231
@code{\FWEBinput} command following each sectioning command. (This is a
9232
bug.)
9233
9234
@item
9235
@findex fwebnum.sty
9236
One is supposed to be able to use the package @code{fwebnum}
9237
(@pxref{Numbering}) in
9238
conjunction with @code{fwebinsert}. One can apply that to either the
9239
included file (via a @code{LaTeX.package} entry in @file{fweb.sty}), the
9240
including file (via a @code{\usepackage} command), or both. Try out
9241
these various combinations to see what emerges.
9242
9243
@end itemize
9244
9245
@node Pretty-printing, , Typesetting, Documentation
9246
@comment node-name, next, previous, up
9247
9248
@section Pretty-printing
9249
9250
@cindex Pretty-printing
9251
@dfn{Pretty-printing} refers to @FWEAVE{}'s attempt to typeset and
9252
highlight the code in a readable way. This is usually done
9253
automatically for all of the compiler-like languages such as C.
9254
However, it can be inhibited by turning on the N mode with
9255
@samp{@@N} or by using the @sc{verbatim} language (selected with @samp{@@Lv}).
9256
9257
Pretty-printing is one of those topics that can arouse strong passions:
9258
your idea of what's esthetic may not be mine. Unfortunately,
9259
@FWEB{}'s formatting rules are mostly hard-coded, so if, for example,
9260
you don't like
9261
the way braces are arranged in typeset C code, you're mostly stuck.
9262
Most directly, this possibly undesirable choice comes from design
9263
decisions made by previous authors. It also makes @FWEAVE{} very
9264
fast, and enables certain complicated tricks that seem difficult or
9265
impossible to accomplish with a completely customizable approach. The
9266
latter seems quite formidable, and has not been attempted---a good
9267
thesis project for the 21st century.
9268
9269
@menu
9270
* Alternatives:: Alternatives for various input tokens.
9271
* Pseudo-operators:: Invisible parts of speech.
9272
* Overloading:: Changing the appearance of various quantities.
9273
@end menu
9274
9275
@node Pseudo-operators, Overloading, Alternatives, Pretty-printing
9276
@comment node-name, next, previous, up
9277
9278
@subsection Pseudo-operators
9279
9280
@cindex Pseudo-operators
9281
Pseudo-operators behave like a particular part of speech for the
9282
purposes of @FWEAVE{}'s formatting, but are invisible on output; they
9283
are ignored by @FTANGLE{}. The pseudo-operators are
9284
9285
@example
9286
@@e @r{--- pseudo-expression. @xref{ATe}.}
9287
@@; @r{--- pseudo-semicolon. @xref{AT;}.}
9288
@@: @r{--- pseudo-colon. @xref{ATcolon}.}
9289
@end example
9290
9291
@node Alternatives, Pseudo-operators, Pretty-printing, Pretty-printing
9292
@comment node-name, next, previous, up
9293
9294
@subsection Alternatives for various input tokens
9295
9296
@FWEAVE{} translates various input constructions into allegedly more
9297
readable symbols---for example, in @sc{Fortran} it translates
9298
@samp{.LT.} into @samp{<}.
9299
@ifinfo
9300
The printed documentation contains a table of what one can type on
9301
input, and what @FWEAVE{} will output.
9302
@end ifinfo
9303
9304
@tex
9305
Here is a table of
9306
what one can type on input, and what @sc{Fweave} will typeset. The first entry
9307
is standard @sc{Fortran}; the parenthesized material is an allowable input
9308
alternative. (In most cases,
9309
the pretty input alternatives follow C's~convention.)
9310
$$
9311
\def\i(#1,#2){{\tt #1} \def\temp{#2}\ifx\temp\empty\else({\tt #2})\fi}
9312
\def\htop#1{\vtop{\halign{##\hfil&$\to \hbox{##}$\hfil\cr#1}}}
9313
\let\WL\le
9314
\let\WS\equiv
9315
\let\WI\neq
9316
\let\WG\ge
9317
\let\WW\land
9318
\let\WV\lor
9319
\def\EQV{\mathrel{?{=}}}
9320
\def\NEQV{\not\equiv}
9321
\let\WR\lnot
9322
\let\SlSl\parallel
9323
\chardef\BS=`\\
9324
\htop{
9325
\i(.lt.,<) & $<$\cr
9326
\i(.le.,<=) & $\WL$\cr
9327
\i(.eq.,==) & $\WS$\cr
9328
\i(.ne.,!=,<>) & $\WI$\cr
9329
\i(.gt.,>) & $>$\cr
9330
\i(.ge.,>=) & $\WG$\cr
9331
\i(.and.,\amp\amp) & $\WW$\cr}
9332
\qquad\qquad
9333
\htop{
9334
\i(.or.,||) & $\WV$\cr
9335
\i(.neqv.,) & $\NEQV$\cr
9336
\i(.xor.,) & $\NEQV$\cr
9337
\i(.eqv.,) & $\EQV$\cr
9338
\i(.not.,!) & $\WR$\cr
9339
\noalign{\smallskip}
9340
\i(**,\^) & {\tt (a+b)\^(c+d)} $\to (a+b)^{c+d}$\cr
9341
\i(//,\BS/) & $\SlSl$\cr
9342
}$$
9343
These same conventions are allowed in @sc{Ratfor} mode. Note that in @sc{Fortran}
9344
and @sc{Ratfor} @samp{//} is interpreted by default as the concatenation
9345
symbol, not the start of a short comment.
9346
To override that default, use one of the command-line options @samp{-n/},
9347
@samp{-r/}, or @samp{-/},
9348
or use a language-changing command of the form @samp{@@n/}.
9349
@end tex
9350
9351
9352
@node Overloading, , Pseudo-operators, Pretty-printing
9353
@comment node-name, next, previous, up
9354
9355
@subsection Overloading operators and identifiers
9356
9357
@cindex Overloading
9358
For special effects in the woven output, there are commands to help
9359
one change the appearance of operators and identifiers.
9360
9361
@subsubsection Overloading operators
9362
9363
@cindex Overloading operators
9364
@cindex Operators, overloading
9365
A feature common to both C++ and @sc{Fortran}--90 is @dfn{operator overloading},
9366
the ability to extend or redefine the definition of an operator such as
9367
@samp{.FALSE.}
9368
or @samp{=}. @sc{Fortran--90} even allows one to define new @dfn{dot
9369
operators}---for example, one might define the operator @samp{.IN.} to test
9370
for inclusion in a set. In a nontrivial extension of the original design,
9371
@FWEAVE{} allows one to define how overloaded
9372
operators should appear on output.
9373
@tex
9374
\def\{{\bf #1}}%
9375
\gdef\.#1{{\tt #1}}%
9376
\def\\#1{\leavevmode\hbox{\it#1\/\kern.05em}}%
9377
For example, in the opinion of the author it is much more readable
9378
to read `$\&{if}\.(x \in \\{set}\.)$' than `\&{if}\.(x\ \.{.IN.}\
9379
\\{set}\.).'
9380
@end tex
9381
Indeed, this feature can be used even when the compiler language itself
9382
does not permit overloading in order to customize the appearance of the
9383
woven output.
9384
9385
The @samp{@@v} control code is used to change the appearance of an operator.
9386
The format is
9387
9388
@example
9389
@@v new_operator_symbol_or_name "TeX material" old_operator
9390
@end example
9391
9392
@noindent
9393
This means ``Display the new operator according to the @i{@TeX{}
9394
material}, but treat it like the old operator---e.g., unary or binary---for
9395
formatting purposes. The
9396
quoted @TeX{} material is treated just like a C string, so if
9397
one wants to include a backslash one must escape it with another backslash.
9398
For example, one can make an equals sign display on output as
9399
a large left arrow by saying
9400
9401
@example
9402
@@v = "\\Leftarrow" =
9403
@end example
9404
9405
@noindent
9406
Two @sc{Fortran} examples are
9407
9408
@example
9409
@@v .FALSE. "\\.@{.FALSE.@}" .FALSE.
9410
@@v .IN. "\\in" +
9411
@end example
9412
9413
This feature can go a long way toward enhancing readability of the woven
9414
output, particularly when operators are actually being overloaded. It can
9415
also lead to arbitrarily bizarre output that no-one else will understand.
9416
As usual, restraint is advised.
9417
9418
@subsubsection Overloading identifiers
9419
9420
@cindex Overloading identifiers
9421
@cindex Identifiers, overloading
9422
Although operator overloading is quite useful, it does not allow one to
9423
change the appearance of identifiers. In its most general form, such a
9424
facility becomes quite complicated; one must endow @FWEAVE{} with a
9425
macro-processing facility analogous to that of @FTANGLE{}. This has
9426
not been
9427
done yet (maybe it will be someday). In the meantime, one has the
9428
command @samp{@@W},
9429
which provides a restricted form of such a facility. @emph{This
9430
command is experimental, and not firmly established. Changes in usage
9431
and/or syntax may be made in future versions.}
9432
9433
The most general form of the @samp{@@W} command is
9434
9435
@example
9436
@@W identifier "replacement text"
9437
@end example
9438
9439
@noindent
9440
This means: Replace any references to @i{identifier} in the
9441
woven output with the @i{replacement text}.
9442
9443
A more restrictive form is
9444
9445
@example
9446
@@W identifier \newmacro
9447
@end example
9448
9449
@noindent
9450
which replaces references to @i{identifier} with a call to
9451
@code{\newmacro}. (Note that there are no quotes in this form.)
9452
9453
The shortest form is
9454
9455
@example
9456
@@W identifier .
9457
@end example
9458
9459
@noindent
9460
which replaces references to @i{identifier} with a call to
9461
@code{\identifier}. For example, the identifier @i{x} normally appears in
9462
woven output as @samp{\.@{\Wshort\@{x\@}@}}. If one says
9463
9464
@example
9465
@@W x .
9466
@end example
9467
9468
@noindent
9469
one will instead get the macro reference @samp{\x}, which could
9470
be defined to give a variety of special effects. (However, one may need
9471
some rather intimate understanding of @FWEAVE{}'s output in order to
9472
ensure that things always work correctly.)
9473
9474
One of the important uses of this facility is to expedite special
9475
formatting of array references. This subject is discussed separately below
9476
in the section on ``Special array formatting'' (sorry, that isn't here
9477
yet), where an example is given.
9478
9479
9480
@node Index, Customization, Documentation, Top
9481
@comment node-name, next, previous, up
9482
9483
@chapter @FWEB{}'s INDEX.
9484
9485
@FWEB{} has several powerful indexing facilities:
9486
9487
@quotation
9488
@enumerate
9489
@item
9490
It sorts and writes its own self-contained (@dfn{internal}) index, including
9491
cross-references to all the variables as well as items inserted by the
9492
user.
9493
9494
@item
9495
It can write its cross-reference information to a file formatted for use
9496
by the @code{makeindex} utility. This feature facilitates creation of a
9497
master index that contains information about several @code{web} files.
9498
9499
@end enumerate
9500
@end quotation
9501
9502
@menu
9503
* Internal index:: The self-contained index produced by @FWEB{}.
9504
* Using makeindex:: Writing index data for use by @code{makeindex}.
9505
* Merging indexes:: Using the @code{idxmerge} utility to merge indexes.
9506
@end menu
9507
9508
@node Internal index, Using makeindex, Index, Index
9509
@comment node-name, next, previous, up
9510
9511
@section @FWEB{}'s self-generated index
9512
9513
One of the most useful features of
9514
@FWEB{} is that it automatically generates an Index of all variable
9515
usage. One
9516
can also insert one's own index
9517
entries by using the commands
9518
9519
@itemize @bullet
9520
9521
@item
9522
@samp{@@^} (entry in Roman type; see
9523
@ref{AT^}),
9524
9525
@item
9526
@samp{@@.} (entry in typewriter type; see @ref{ATdot}), and
9527
9528
@item
9529
@samp{@@9} (user-defined format; see @ref{AT9}).
9530
9531
9532
@end itemize
9533
9534
(More discussion to be completed.)
9535
9536
@node Using makeindex, Merging indexes, Internal index, Index
9537
@comment node-name, next, previous, up
9538
9539
@section Creating a stand-alone index with @code{makeindex}
9540
9541
@cindex Index, stand-alone
9542
@cindex Makeindex, using
9543
In addition to the internal index described in the previous section
9544
(@pxref{Internal index}), @FWEAVE{} can write the index data to a file
9545
formatted for later, stand-alone processing by the @code{makeindex}
9546
utility. (Several such indexes can be merged together; see @ref{Merging
9547
indexes}.) The procedure is simple, although the following discussion goes
9548
into some rather arcane details.
9549
9550
@subsection Creating a stand-alone index: Summary
9551
9552
As a quick reference for those who have already read the details in the
9553
next subsection, the procedure to print a stand-alone index with
9554
@code{makeindex} is as follows. First, create, if necessary, a file
9555
@file{index.tex} that @code{\input}s @file{index.ind}. (A skeleton
9556
is illustrated in the next subsection.) Then:
9557
9558
@example
9559
fweave -XI test.web @r{% Creates test.idx and test.sty.}
9560
makeindex -s test.sty -o index.ind test.idx @r{% Creates index.ind.}
9561
latex index
9562
@end example
9563
@noindent
9564
If you're not happy with the @code{\pg} macro supplied in
9565
@file{fwebmac.sty}, define it yourself in @file{index.tex}.
9566
9567
In this procedure, note the use of the @samp{-XI} option and the use of
9568
a different root name (@file{index} here) for the output file.
9569
9570
@subsection Creating a stand-alone index: Details
9571
9572
@findex -XI
9573
To create an index file in a form suitable for later stand-alone
9574
processing by @code{makeindex}, use the @samp{-XI} option to
9575
@FWEAVE{}. If the @code{web} file is @file{test.web}, the default
9576
name of the @code{makeindex} output file is @file{test.idx}. (This name
9577
can be overridden by the style-file parameter @code{makeindex.out}.) Run
9578
@code{makeindex} on @file{test.idx} to create the La@TeX{} file
9579
@file{index.ind} (see following discussion for details). A stand-alone
9580
index can then be produced by saying @samp{latex index}, where a skeleton
9581
version of @file{index.tex} would be
9582
9583
@example
9584
% index.tex --- skeleton for printing a stand-alone index.
9585
\documentclass@{article@}
9586
\usepackage@{fwebmac@}
9587
9588
\begin@{document@}
9589
9590
\input@{\jobname.ind@}
9591
9592
\end@{document@}
9593
@end example
9594
@noindent
9595
(In practice, a more involved procedure will probably be followed; see below.)
9596
9597
@cindex Style file, for makeindex
9598
Usually @code{makeindex} works in conjunction with a style file. [In
9599
fact, the syntax of @FWEB{}'s style file (@pxref{Style}) was motivated
9600
by that of @code{makeindex}.] When the @samp{-XI} option (@pxref{-X_}) is used,
9601
@FWEAVE{} will @emph{create} an appropriate style file for
9602
@code{makeindex}. (The default name of @file{test.sty} can be overridden
9603
by the style-file parameter @code{makeindex.sty}.) To run
9604
@code{makeindex} on the index data for @file{test.web} and create the
9605
output file @file{index.ind}, one would thus say
9606
9607
@example
9608
makeindex -s test.sty -o index.ind test[.idx]
9609
@end example
9610
@noindent
9611
It's important to use the @samp{-o} option with a name different than
9612
the original file name, because it simplifies the construction of the
9613
skeleton file @file{index.tex} that prints the stand-alone index.
9614
9615
@FWEAVE{} writes @file{test.sty} because the contents of that file may
9616
depend on parameter settings in @FWEB{}'s style file @file{fweb.sty}.
9617
@FWEB{}'s style vocabulary includes all parameters understood by
9618
@code{makeindex}. If a @code{makeindex} parameter is called
9619
@samp{param}, one references it in @file{fweb.sty} by
9620
@samp{makeindex.param}. Thus, to change the @samp{headings_flag} of
9621
@code{makeindex}, one would put into @file{fweb.sty} a line like
9622
@samp{makeindex.headings_flag = 1}. To see a list of all
9623
@code{makeindex}-related parameters, say @samp{fweave -Zmakeindex}
9624
(@pxref{-Z_}). Remember, @emph{do all @code{makeindex} customizations
9625
in @file{fweb.sty}; the actual style file @file{test.sty} that will be
9626
read by @code{makeindex} is written automatically by @FWEAVE{}.}
9627
9628
The @file{.idx} file will contain a list of entries that begin with
9629
@samp{\indexentry} (more precisely, the value of the parameter
9630
@samp{makeindex.keyword}). The general form is
9631
9632
@example
9633
\indexentry@{sort key:identifier expression|macro@}@{page number@}
9634
@end example
9635
@noindent
9636
Typical entries are
9637
9638
@example
9639
\indexentry@{istream:"\>@{istream@}|pg@{@}@{@}@}@{1@}
9640
\indexentry@{main:"\>@{main@}|pg@{@}\underline@}@{1@}
9641
\indexentry@{pow:"\@@@{pow@}|pg@{@}@{@}@}@{2@}
9642
\indexentry@{z:"\"|z|pg@{@}\underline@}@{2@}
9643
@end example
9644
@noindent
9645
Here the colon is the value of @samp{makeindex.actual}; it separates the
9646
sort key (before the colon) from the actual expression to be printed.
9647
The macros such as @samp{\>} typeset the identifiers in the appropriate
9648
way, depending on their use in the code. Note that the backslashes are
9649
quoted with the value of @samp{makeindex.quote}, which is by default the
9650
double quote.
9651
9652
Although one might guess that the typesetting macros such as @samp{\>}
9653
would be defined in @file{fwebmac.sty}, that is not true. Rather, for
9654
various technical reasons they
9655
are equated to macros in @file{fwebmac.sty} as one of the operations of
9656
the @samp{\Wbegin} macro that is executed at the beginning of every
9657
@code{tex} file output by @FWEAVE{}. For example, @samp{\Wbegin} does
9658
the equivalent of @samp{\let\>\Wid}. Unfortunately, without further
9659
action that equating would be forgotten by a La@TeX{} run made on the
9660
output @file{index.ind} of @code{makeindex}. For that reason, @FWEAVE{}
9661
appends the appropriate @samp{\Wequate} macro to the end of
9662
@samp{makeindex.preamble}. This is one specific instance that
9663
necessitates that @FWEAVE{} write the @code{makeindex} style file.
9664
9665
Each of the @samp{\indexentry}s contains the encapsulation character
9666
@samp{|} (the value of @samp{makeindex.encap}). By the conventions of
9667
@code{makeindex}, everything between the encapsulation character and the
9668
closing right brace defines a macro expression that acts on the page
9669
number. E.g., the general form above generates the command
9670
@samp{\macro@{@i{page number}@}}. The specific macro construction
9671
output by @FWEAVE{} is
9672
9673
@example
9674
\pg@{@}@{@i{possible action macro}@}@{@i{page number}@}
9675
@end example
9676
@noindent
9677
Here the name @samp{pg} is the value of @samp{makeindex.page}. The
9678
@dfn{action macro} is something like @samp{\underline}, which would be
9679
used by @FWEAVE{} to underline the page number to indicate where a
9680
variable is defined. A default definition of @samp{\pg} is given is
9681
@file{fwebmac.sty}. It is a three-argument macro,
9682
@samp{\def\pg#1#2#3@{...@}}, where the arguments are as follows:
9683
@findex \pg
9684
9685
@example
9686
#1 @r{--- Integer file identification number}
9687
#2 @r{--- Action macro.}
9688
#3 @r{--- Page number.}
9689
@end example
9690
@noindent
9691
The definition should contain the construction @samp{#2@{#3@}}---i.e.,
9692
the page number must be the argument of the action macro. The first
9693
argument is left empty in the @file{.idx} file written by @FWEAVE{}.
9694
This can be filled in later by the utility @code{idxmerge}
9695
(@pxref{Merging indexes}) that merges the indices
9696
from several @code{web} files. For example, in a master index one might
9697
ultimately print page numbers like @samp{II.5}, where @samp{II} refers to
9698
a file such as @file{test2.web}. To aid this merging process, the root
9699
name of the @code{web} file is written as a comment at the top of the
9700
@file{.idx} file output by @FWEAVE{}.
9701
9702
@node Merging indexes, , Using makeindex, Index
9703
@comment node-name, next, previous, up
9704
9705
@section Using the @code{idxmerge} utility to merge indexes
9706
9707
@cindex Indexes, merging
9708
@findex idxmerge.sty
9709
In a large project, one may maintain and work with several @FWEB{}
9710
files. It may be useful to produce a global index that spans all of
9711
those files. To this end, the utility @code{idxmerge} and associated
9712
La@TeX{} package @code{idxmerge} are supplied with
9713
the @FWEB{} distribution.
9714
9715
@subsection Using @code{idxmerge}: Summary
9716
9717
As quick reference for those who have already plowed through the
9718
following details, here is a summary of the procedure. To print a
9719
stand-alone index by merging the indexes from several @code{web}
9720
sources, do the following. First, create, if necessary, a file
9721
@file{index.tex} that @code{\input}s @file{index.ind}. Then:
9722
9723
@example
9724
fweave -XI test1.web
9725
fweave -XI test2.web
9726
fweave -XI test3.web
9727
9728
idxmerge -oindex test1.idx test2.idx test3.idx
9729
% Creates index.ind and index-names.tex.
9730
makeindex -s test1.sty index
9731
latex index
9732
@end example
9733
9734
Note the use of the @samp{-XI} option. For further background, see the
9735
previous section, @ref{Using makeindex}.
9736
9737
@subsection Using @code{idxmerge}: Details
9738
9739
Suppose one has three files, @file{test1.web}, @file{test2.web}, and
9740
@file{test3.web}. To use @code{idxmerge}, weave each of the files
9741
separately, using the @samp{-XI} option to create @file{test*.idx} and
9742
@file{test*.sty}. Then say
9743
9744
@example
9745
idxmerge -oindex test1.idx test2.idx test3.idx
9746
@end example
9747
@noindent
9748
This creates two output files: @file{index.idx}, and
9749
@file{index-names.tex}. @code{idxmerge} first sorts the list of file
9750
names. It then writes one entry into @file{index-names.tex} for each
9751
file, of the form
9752
9753
@example
9754
\idxname@{@var{n}@}@{file_name@var{n}@}
9755
@end example
9756
@noindent
9757
This file can be @code{\input} by the @code{\topofindex} command (for an
9758
example, see the La@TeX{}2e package @code{idxmerge}) (supplied with
9759
the @FWEB{} distribution) and used to create a list of the merged files.
9760
@findex \topofindex
9761
@findex \idxname
9762
9763
Then it merges the @code{\indexentry} commands from each of the input
9764
files into @file{index.idx}, filling in the integer file identifier @var{n}
9765
(the position of the file in the sorted list) into the first argument of
9766
the @code{\pg} macro. One can now say
9767
9768
@example
9769
makeindex -s test1.sty index
9770
@end example
9771
@noindent
9772
This creates @file{index.ind}, which can be processed by, for example,
9773
a simple modification of the simple La@TeX{} template given above in
9774
@ref{Using makeindex}. The only difference is that the package
9775
@code{idxmerge} was used; in that file, the macros @code{\topofindex}
9776
and @code{\idxname} are appropriately defined to print out a numbered
9777
list of the merged files to cross-reference into the numerical file- and
9778
page-number entries in the body of the index. Here is an example
9779
(provided in the @FWEB{} distribution):
9780
9781
@example
9782
% index.tex --- skeleton for printing a stand-alone index.
9783
\documentclass@{article@}
9784
\usepackage@{fwebmac,idxmerge@}
9785
9786
\begin@{document@}
9787
9788
\input@{\jobname.ind@}
9789
9790
\end@{document@}
9791
@end example
9792
@noindent
9793
9794
@node Customization, Hints, Index, Top
9795
@comment node-name, next, previous, up
9796
9797
@chapter CUSTOMIZATION
9798
9799
@cindex Customization
9800
@cindex Customizing @FWEB{}
9801
@cindex @FWEB{}, customizing
9802
The default behavior of @FWEB{} can be changed in a variety of ways.
9803
9804
@quotation
9805
@enumerate
9806
@item
9807
@sc{unix} environment variables (logical variables in VMS) affect path or
9808
file names.
9809
9810
@item
9811
An initialization file resides in the home directory.
9812
9813
@item
9814
A style file resides in the current directory.
9815
@end enumerate
9816
@end quotation
9817
9818
The initialization file (usually called @file{.fweb}) is intended to contain
9819
command-line options (one per line) that are to be used in every run.
9820
@xref{Initialization}.
9821
9822
The style file (called @file{fweb.sty} by default; see @ref{-z}) is
9823
intended to provide more local customization, perhaps
9824
differing for each source file and group of source files. The style
9825
file does not contain command-line
9826
options; rather, it contains parameter settings that override
9827
@FWEB{}'s defaults. The @samp{-p} option (@pxref{-p})
9828
may be used to specify a style-file entry in @file{.fweb} (i.e., a
9829
global value for all source files) or on the
9830
command line (i.e., a value used for a single run).
9831
9832
The order of processing is:
9833
9834
@quotation
9835
@enumerate
9836
@item
9837
Evaluate environment variables. @xref{Environment variables}.
9838
9839
@item
9840
Read @file{.fweb} and remember its contents; sort those into three
9841
groups: options beginning with @samp{-}, beginning with @samp{&}, and
9842
beginning with a letter (file names) . @xref{Initialization}.
9843
9844
@item
9845
Process @file{.fweb} options beginning with @samp{-} (or @samp{+}, for
9846
backward compatibility), except for @samp{-p}.
9847
9848
@item
9849
Read and process command-line options, except for @samp{-p}. @xref{Options}.
9850
9851
@item
9852
Process remaining @file{.fweb} options (either file names, or options
9853
beginning with @samp{&}).
9854
9855
@item
9856
Process any @samp{-p} options from @file{.fweb}. @xref{-p}.
9857
9858
@item
9859
Process the style file. @xref{Style}.
9860
9861
@item
9862
Process any @samp{-p} options from the command line.
9863
9864
@end enumerate
9865
@end quotation
9866
9867
Unfortunately, because not all options are processed immediately when
9868
they are read, errors may not show up when one expects. For example,
9869
nothing is actually processed while @file{.fweb} is being read; its
9870
contents are just being stored. It
9871
could therefore happen that a syntax error in entering a @samp{-p}
9872
option in @file{.fweb} may not be reported until after the style file
9873
has been read, possibly confusing the user as to the source of the
9874
error.
9875
9876
@menu
9877
* Environment variables:: Environment or logical variables.
9878
* Initialization:: Initialization file.
9879
* Memory allocation:: Dynamic memory allocation.
9880
* Style:: Style file.
9881
@end menu
9882
9883
@node Environment variables,Initialization,Customization,Customization
9884
@comment node-name, next, previous, up
9885
9886
@section Environment variables
9887
9888
@cindex Environment variables
9889
@cindex Variables, environment
9890
9891
@code{FWEB_HDR_INCLUDES} --- Colon-delimited list of directories for the
9892
C preprocessor (in the form of @code{gcc}) to
9893
search for @samp{#include} header files. This is used in conjunction
9894
with the @samp{-H} option; see @ref{-H_}. (One can append to this list
9895
by means of the @samp{-I} option, provided that option comes
9896
@emph{after} the @samp{-H}; see @ref{-I_}.)
9897
@findex FWEB_HDR_INCLUDES
9898
9899
@code{FWEB_INCLUDES} --- Colon-delimited list of directories to search for
9900
@samp{@@i} include files. (One can append to this list by means of the
9901
@samp{-I} option, provided that option comes @emph{before} any use of
9902
@samp{-H}; see @ref{-I_}.)
9903
@findex FWEB_INCLUDES
9904
9905
@code{FWEB_INI} --- Name of the initialization file. If not defined, either
9906
@file{.fweb} or @file{fweb.ini} is chosen, depending on the machine. The
9907
initialization file always resides in @code{$HOME}.
9908
@findex FWEB_INI
9909
9910
9911
@code{FWEB_STYLE_DIR} --- Directory in which the style file resides. If not
9912
defined, the current directory is used.
9913
@findex FWEB_STYLE_DIR
9914
9915
@node Initialization,Memory allocation,Environment variables,Customization
9916
@comment node-name, next, previous, up
9917
9918
@section Initialization
9919
9920
Although some aspects of @FWEB{}'s behavior are hard-coded, many can
9921
be changed and/or initialized by the user.
9922
9923
@subsection The initialization file
9924
9925
@cindex Initialization file
9926
@cindex File, initialization
9927
@cindex @FWEB{}, initializing
9928
@findex .fweb
9929
On startup, @FWEB{} attempts to read an initialization file. This always
9930
resides in the user's home directory. It is usually called @file{.fweb}
9931
(@file{fweb.ini} on personal computers). The default file name can be
9932
overridden by the environment variable @code{FWEB_INI}.
9933
9934
One may put into @file{.fweb} any option that might be used as a
9935
command-line option. (Presently, there must be just one entry per
9936
line.) If the option begins with a @samp{-} (or a @samp{+} for backward
9937
compatibility), it is processed @emph{before} the actual command-line
9938
options; if it begins with @samp{&} or is a file name, it is processed
9939
after. Generally, @file{.fweb} options should begin with @samp{-} so
9940
that one may override them from the command line. The @samp{%} sign
9941
begins a comment terminated by the end-of-line.
9942
9943
@node Memory allocation,Style,Initialization,Customization
9944
@comment node-name, next, previous, up
9945
9946
@subsection Memory allocation
9947
9948
@cindex Memory allocation
9949
@cindex Allocation, memory
9950
The command-line option @samp{-y} (@pxref{-y}) is used to change the
9951
default allocation for a dynamic array. The arrays have a one- or
9952
two-character abbreviation denoted by @i{aa}. Some error messages will
9953
use this abbreviation when suggesting that one increase a default
9954
allocation. To query the present allocations of variable @i{aa}, just say
9955
@samp{-y@i{aa}}. To query everything, say @samp{-y}.
9956
9957
This whole scheme is somewhat annoying. In most cases, dynamic arrays
9958
should be reallocated automatically. That can be done without too much
9959
difficulty, but I was reluctant to try it for Version 1.61 in fear of
9960
breaking something. Please wait for the year 2000.
9961
9962
If one uses @samp{-y} to examine the maximum permitted values of these
9963
parameters, one will note the magic number 10239 appearing
9964
occasionally. This number is a bit less than 64K/5; it is a signature
9965
of an inherently 32-bit design that goes back to Knuth. Unfortunately,
9966
this number can't be increased without some radical redesign. Wait for
9967
the year 2100.
9968
9969
@menu
9970
* -yb:: Maximum bytes for identifiers, index entries, and module names.
9971
* -ybs:: Size of the change buffer.
9972
* -ycb:: Size of line buffer for C output.
9973
* -ycf:: A Ratfor buffer.
9974
* -ycg:: Another Ratfor buffer.
9975
* -yd:: Increment for expanding the dots table.
9976
* -ydt:: Maximum number of deferred macro tokens.
9977
* -ydx:: Maximum number of deferred macro texts.
9978
* -yid:: Maximum depth of file inclusion.
9979
* -yif:: Maximum number of unique include-file names.
9980
* -ykt:: Stack size for @FTANGLE{}.
9981
* -ykw:: Stack size for @FWEAVE{}.
9982
* -yll:: Line length for @FWEAVE{}'s output.
9983
* -yln:: Maximum length of module names or strings.
9984
* -ylb:: Maximum number of nested loops in Ratfor.
9985
* -ylx:: Maximum length of expressions that can be expanded with
9986
the post-increment operators of Fortran or Ratfor.
9987
* -ym:: Maximum number of sections.
9988
* -yma:: Maximum number of arguments to @FWEB{} macros.
9989
* -ymb:: Size of the buffer for expanding @FWEB{} macros.
9990
* -yn:: Maximum number of identifiers and module names.
9991
* -ynf:: Maximum number of open output files.
9992
* -yop:: Maximum number of entries in the table for operator
9993
overloading.
9994
* -yr:: Maximum number of cross-references.
9995
* -ys:: Maximum number of scraps.
9996
* -ysb:: Size of style-file input-line buffer.
9997
* -ytt:: Maximum number of tokens that @FTANGLE{} can process.
9998
* -ytw:: Maximum number of tokens in the current section being
9999
processed by @FWEAVE{}.
10000
* -yx:: Maximum number of texts.
10001
* -yxb:: Size of line buffer for @TeX{} output.
10002
@end menu
10003
10004
@node -yb, -ybs, Memory allocation, Memory allocation
10005
@comment node-name, next, previous, up
10006
10007
@subsubsection @samp{-yb}: Maximum bytes for identifiers, index entries, and module names
10008
10009
@findex -yb
10010
10011
Unique identifiers, index entries, and module names are stored
10012
contiguously in a large memory area, the size of which is controlled by
10013
@samp{-yb}. The default may need to be increased for very large source
10014
files, or decreased to squeeze things into a personal computer. See
10015
also @ref{-yn}.
10016
10017
@node -ybs, -ycb, -yb, Memory allocation
10018
@comment node-name, next, previous, up
10019
10020
@subsubsection @samp{-ybs}: Size of the change buffer, in bytes
10021
10022
@findex -ybs
10023
10024
Information from change files is read into the change buffer, whose size
10025
is controlled by @samp{-ybs}. It should not be necessary to change this
10026
unless an error message specifically tells one to do so.
10027
10028
@node -ycb, -ycf, -ybs, Memory allocation
10029
@comment node-name, next, previous, up
10030
10031
@subsubsection @samp{-ycb}: Size of line buffer for C output, in bytes
10032
10033
@findex -ycb
10034
10035
@FTANGLE{} outputs lines of a fixed maximum length. It attempts to
10036
split them in a reasonable way, dependent on the language. When it
10037
absolutely can't figure out how to split the line, it will issue a
10038
warning message and split it anyway. The @samp{-ycb} option controls
10039
the maximum output line length for C and C++.
10040
10041
The analogous command @samp{-yxb} controls the output line length for
10042
@TeX{} and the verbatim mode. @xref{-yxb}.
10043
10044
@node -ycf, -ycg, -ycb, Memory allocation
10045
@comment node-name, next, previous, up
10046
10047
@subsubsection @samp{-ycf}: Size of a Ratfor buffer, in bytes
10048
10049
@findex -ycf
10050
10051
The sizes of buffers used by @sc{Ratfor} for constructing messages about
10052
the commands it is expanding are controlled by @samp{-ycf} and @samp{-ycg}.
10053
10054
@node -ycg, -yd, -ycf, Memory allocation
10055
@comment node-name, next, previous, up
10056
10057
@subsubsection @samp{-ycg}: Size of another Ratfor buffer, in bytes
10058
10059
@findex -ycg
10060
10061
The sizes of buffers used by @sc{Ratfor} for constructing messages about
10062
the commands it is expanding are controlled by @samp{-ycf} and @samp{-ycg}.
10063
10064
@node -yd, -ydt, -ycg, Memory allocation
10065
@comment node-name, next, previous, up
10066
10067
@subsubsection @samp{-yd}: Increment for expanding the dots table
10068
10069
@findex -yd
10070
10071
The ``dots'' table is used for @sc{Fortran} to hold information relating
10072
to ``dot'' operators such as @samp{.NE.}. In @sc{Fortran--90},
10073
additional such operators can be added by the program, so the table can
10074
grow dynamically. The @samp{-yd} option controls how many additional
10075
entries are made available each time the table size needs to be
10076
reallocated.
10077
10078
@node -ydt, -ydx, -yd, Memory allocation
10079
@comment node-name, next, previous, up
10080
10081
@subsubsection @samp{-ydt}: Maximum number of deferred macro tokens
10082
10083
@findex -ydt
10084
10085
Deferred @FWEB{} macros are ones defined in the code part rather in
10086
the definition part. (Their use is normally prohibited; see @ref{-TD}.)
10087
@samp{-ydt} controls how many bytes are set aside for the storage of
10088
these replacement text of those macros. See also @ref{-ydx}.
10089
10090
@node -ydx, -yid, -ydt, Memory allocation
10091
@comment node-name, next, previous, up
10092
10093
@subsubsection @samp{-ydx}: Maximum number of deferred macro texts
10094
10095
@findex -ydx
10096
10097
@samp{-ydx} controls how many deferred macros are permitted. See also
10098
@ref{-ydt}.
10099
10100
@node -yid, -yif, -ydx, Memory allocation
10101
@comment node-name, next, previous, up
10102
10103
@subsubsection @samp{-yid}: Maximum depth of file inclusion
10104
10105
@findex -yid
10106
10107
Files included by @samp{@@i} can themselves contain @samp{@@i} commands,
10108
to a nesting level controlled by @samp{-yid}.
10109
10110
@node -yif, -ykt, -yid, Memory allocation
10111
@comment node-name, next, previous, up
10112
10113
@subsubsection @samp{-yif}: Maximum number of unique include-file names
10114
10115
@findex -yif
10116
10117
The number of unique file names appearing in @samp{@@i} commands is
10118
controlled by @samp{-yif}.
10119
10120
@node -ykt, -ykw, -yif, Memory allocation
10121
@comment node-name, next, previous, up
10122
10123
@subsubsection @samp{-ykt}: Stack size for @FTANGLE{}
10124
10125
@findex -ykt
10126
10127
@FTANGLE{} uses a stack to deal with the web of module names---i.e., a
10128
named section can refer to another module name. The size of this stack
10129
is controlled by @samp{-ykt}.
10130
10131
@node -ykw, -yll, -ykt, Memory allocation
10132
@comment node-name, next, previous, up
10133
10134
@subsubsection @samp{-ykw}: Stack size for @FWEAVE{}
10135
10136
@findex -ykw
10137
10138
@FWEAVE{}'s stack handles the possibilities that code mode can be
10139
embedded in a module name, or vice versa. The maximum nesting level for
10140
such mode changes is controlled by @samp{-ykw}.
10141
10142
@node -yll, -yln, -ykw, Memory allocation
10143
@comment node-name, next, previous, up
10144
10145
@subsubsection @samp{-yll}: Line length for @FWEAVE{}'s output, in bytes
10146
10147
@findex -yll
10148
10149
@samp{-yll} controls the length of each line in the @code{.tex} file
10150
output by @FWEAVE{}.
10151
10152
@node -yln, -ylb, -yll, Memory allocation
10153
@comment node-name, next, previous, up
10154
10155
@subsubsection @samp{-yln}: Maximum length of module names or strings, in bytes
10156
10157
@findex -yln
10158
10159
When each module name or string is parsed, it is stored temporarily in a
10160
buffer whose length is controlled by @samp{-yln}.
10161
10162
@node -ylb, -ylx, -yln, Memory allocation
10163
@comment node-name, next, previous, up
10164
10165
@subsubsection @samp{-ylb}: Maximum number of nested loops in @sc{Ratfor}
10166
10167
@findex -ylb
10168
10169
In @sc{Ratfor}, various loops such as @samp{while} are translated into
10170
their @sc{Fortran} equivalents. @samp{-ylb} controls the maximum
10171
nesting level of such expandable constructions.
10172
10173
@node -ylx, -ym, -ylb, Memory allocation
10174
@comment node-name, next, previous, up
10175
10176
@subsubsection @samp{-ylx}: Maximum length of expressions that can be expanded with the post-increment operators of @sc{Fortran} or @sc{Ratfor}
10177
10178
@findex -ylx
10179
10180
@sc{Fortran} and @sc{Ratfor} can expand expressions such as @samp{x(i) +=
10181
dx} into their @sc{Fortran} counterparts such as @samp{x(i) = x(i) + dx}.
10182
It does so in a very straightforward way, by copying the expression to
10183
the left of the equals sign. @samp{-ylx} controls the maximum size of
10184
that expression.
10185
10186
@node -ym, -yma, -ylx, Memory allocation
10187
@comment node-name, next, previous, up
10188
10189
@subsubsection @samp{-ym}: Maximum number of sections
10190
10191
@findex -ym
10192
10193
@samp{-ym} limits the maximum number of sections, both named and
10194
unnamed. (Each unnamed section is counted separately.) The absolute
10195
maximum number of sections is 10239, probably one of the most stringent
10196
restrictions in @FWEB{}'s design. (This number is a bit less than 1/5
10197
of 64K.)
10198
10199
@node -yma, -ymb, -ym, Memory allocation
10200
@comment node-name, next, previous, up
10201
10202
@subsubsection @samp{-yma}: Maximum number of arguments to @FWEB{} macros
10203
10204
@findex -yma
10205
10206
The maximum number of arguments to @FWEB{} macros (defined by
10207
@samp{@@m}) is limited by @samp{-yma}.
10208
10209
@node -ymb, -yn, -yma, Memory allocation
10210
@comment node-name, next, previous, up
10211
10212
@subsubsection @samp{-ymb}: Size of the buffer for expanding @FWEB{} macros
10213
10214
@findex -ymb
10215
10216
The expansion of each @FWEB{} macro is done in a buffer whose size is
10217
controlled by @samp{-ymb}. (In some situations, particularly in
10218
@sc{Ratfor}, more than one such buffer can be open at once.)
10219
10220
@node -yn, -ynf, -ymb, Memory allocation
10221
@comment node-name, next, previous, up
10222
10223
@subsubsection @samp{-yn}: Maximum number of identifiers and module names
10224
10225
@findex -yn
10226
10227
A structure is associated with each unique identifier and module name.
10228
The maximum number of such structures is controlled by @samp{-yn}. See
10229
also @ref{-yb}.
10230
10231
@node -ynf, -yop, -yn, Memory allocation
10232
@comment node-name, next, previous, up
10233
10234
@subsubsection @samp{-ynf}: Maximum number of open output files
10235
10236
@findex -ynf
10237
10238
In addition to @FTANGLE{}'s usual output file---e.g.,
10239
@code{test.c}---additional files may be opened by means of the
10240
@samp{@@O} (@pxref{ATO_}) or @samp{@@o} (@pxref{ATo}) commands.
10241
Depending on the situation, some of these files may remain open
10242
simultaneously. The maximum number of such files is controlled by @samp{-ynf}.
10243
10244
@node -yop, -yr, -ynf, Memory allocation
10245
@comment node-name, next, previous, up
10246
10247
@subsubsection @samp{-yop}: Maximum number of entries in the table for operator overloading.
10248
10249
@findex -yop
10250
10251
In @FWEAVE{}, the appearance of an operator can be changed
10252
(@dfn{overloaded}) by means of the @samp{@@v} command (@pxref{ATv}). Each
10253
such operator is entered into a table, the maximum size of which is
10254
controlled by @samp{-yop}.
10255
10256
@node -yr, -ys, -yop, Memory allocation
10257
@comment node-name, next, previous, up
10258
10259
@subsubsection @samp{-yr}: Maximum number of cross-references
10260
10261
@findex -yr
10262
10263
The Index cross-reference information (in which sections each identifier
10264
is used or defined) is maintained in a large array of structures, one
10265
structure for each cross-reference. The maximum number of
10266
cross-references is controlled by @samp{-yr}.
10267
10268
@node -ys, -ysb, -yr, Memory allocation
10269
@comment node-name, next, previous, up
10270
10271
@subsubsection @samp{-ys}: Maximum number of scraps
10272
10273
@findex -ys
10274
10275
The maximum number of scraps is controlled by @samp{-ys}. For a
10276
discussion of scraps, see @ref{-1}.
10277
10278
@node -ysb, -ytt, -ys, Memory allocation
10279
@comment node-name, next, previous, up
10280
10281
@subsubsection @samp{-ysb}: Size of style-file input-line buffer
10282
10283
@findex -ysb
10284
10285
The maximum length of each input line of the style file (@code{fweb.sty}
10286
by default) is controlled by @samp{-ysb}.
10287
10288
@node -ytt, -ytw, -ysb, Memory allocation
10289
@comment node-name, next, previous, up
10290
10291
@subsubsection @samp{-ytt}: Maximum number of tokens that @FTANGLE{} can process
10292
10293
@findex -ytt
10294
10295
A @dfn{token} is an identifier, numerical constant, operator, etc.
10296
@FTANGLE{} must read in and store all tokens in the entire source
10297
file, because they can be output in a different order than they are
10298
input. The maximum number of tokens is controlled by @samp{-ytt}.
10299
10300
@node -ytw, -yx, -ytt, Memory allocation
10301
@comment node-name, next, previous, up
10302
10303
@subsubsection @samp{-ytw}: Maximum tokens in the current section being processed by @FWEAVE{}.
10304
10305
@findex -ytw
10306
10307
Unlike @FTANGLE{}, @FWEAVE{} need only read in one section at a
10308
time. The maximum number of tokens in any section is controlled by
10309
@samp{-ytw}.
10310
10311
@node -yx, -yxb, -ytw, Memory allocation
10312
@comment node-name, next, previous, up
10313
10314
@subsubsection @samp{-yx}: Maximum number of texts
10315
10316
@findex -yx
10317
10318
For @FTANGLE{}, a @dfn{text} is either the replacement text of a macro, or
10319
the contents of a named section. The maximum number of such texts is
10320
controlled by @samp{-yx}.
10321
10322
For @FWEAVE{}, a @dfn{text} is a phrase that arises from combining primitive
10323
scraps during the translation stage of phase 2.
10324
10325
For both processors, the absolute maximum number of texts is 10239.
10326
10327
@node -yxb, , -yx, Memory allocation
10328
@comment node-name, next, previous, up
10329
10330
@subsubsection @samp{-yxb}: Size of line buffer for @TeX{} and verbatim output
10331
10332
@findex -yxb
10333
10334
This option is like @samp{-ycb} (@pxref{-ycb}), but controls the size of
10335
the output line for the @TeX{} (@samp{@@Lx}) and verbatim (@samp{@@Lv})
10336
languages.
10337
10338
@node Style,,Memory allocation,Customization
10339
@comment node-name, next, previous, up
10340
10341
@section The Style file
10342
10343
@cindex Style file
10344
@cindex File, style
10345
@findex fweb.sty
10346
A @dfn{style file} (default name @file{fweb.sty}) may reside in the
10347
user's current directory (or the directory specified by the environment
10348
variable @code{FWEB_STYLE_DIR}). The default name can be changed by the
10349
command-line option @samp{-z} (@pxref{-z}).
10350
10351
The style file is processed after all command-line options have been
10352
processed, except that the command-line option @samp{-p} (@pxref{-p})
10353
gets special treatment. Note that that option buffers up style-file
10354
entries (i.e., one may use more than one @samp{-p} option). @samp{-p}
10355
options placed in @file{.fweb} are treated as residing in a temporary
10356
file that is read just @emph{before} the local style file; thus, those behave
10357
as `global' style-file entries that will be overridden by a matching
10358
entry in the local style file. @samp{-p} options on the command line
10359
will be processed @emph{after} the local style file, thus override
10360
corresponding options in either @file{.fweb} or the local style file.
10361
10362
To summarize the previous discussion, the local style file is intended
10363
to contain settings that are common to a particular source file.
10364
Settings common to all source files can be put into @file{.fweb} by
10365
means of the @samp{-p} option. To override a setting for a single run,
10366
use a @samp{-p} option on the command line.
10367
10368
Style-file entries have the form
10369
10370
@example
10371
@var{keyword} @i{[}=@i{]} @var{value}
10372
@end example
10373
@noindent
10374
The equals sign is always optional. The @samp{value} is usually a
10375
double-quoted string, but may sometimes be an integer or a single-quoted
10376
character. For example,
10377
10378
@example
10379
LaTeX.class.options = "twoside"
10380
LaTeX.package "indentfirst,multicol"
10381
mark_defined.fcn_name 0
10382
line_char.N 'C'
10383
color.error = "red"
10384
Color.red = "\e[01;31m"
10385
@end example
10386
@noindent
10387
The syntax is completely free-form. Periods within keywords are
10388
precisely equivalent to underscores, but are useful heuristically for
10389
associating a structure-like hierarchy to some of the commands.
10390
Non-printable characters in strings can be specified as octal constants
10391
(e.g., @samp{\033}), hexadecimal constants (e.g., @samp{\x1B}), or one
10392
of the ANSI escape sequences @samp{\a}, @samp{\b}, @samp{\f}, @samp{\n},
10393
@samp{\r}, @samp{\t}, and @samp{\v}. The non-ANSI escape sequence
10394
@samp{\e} (escape) is also supported; that is particularly useful for
10395
color processing (@pxref{Color}).
10396
10397
Various of the style-file parameters take a language subscript. Those
10398
are
10399
10400
@quotation
10401
@table @code
10402
@item C
10403
C
10404
@item Cpp
10405
C++
10406
@item N
10407
@sc{Fortran}-77
10408
@item N90
10409
@sc{Fortran}-90
10410
@item R
10411
@sc{RatFor}-77
10412
@item R90
10413
@sc{RatFor}-90
10414
@item V
10415
Verbatim
10416
@item X
10417
@TeX{}
10418
10419
@end table
10420
@end quotation
10421
@noindent
10422
Thus, @code{line_char.N} is the comment character for @FTANGLE{}'s
10423
@code{line} commands (@pxref{line_char}), for @sc{Fortran}-77 code.
10424
10425
Unfortunately, the descriptions of the parameters aren't all completed
10426
yet. To query the default values, say @samp{ftangle -Z} (see @ref{-Z_}).
10427
10428
@menu
10429
* Index params:: Customizing the Index.
10430
* Module params:: Customizing the list of sections.
10431
* Contents params:: Customizing the Table of Contents.
10432
* Subscript params:: Customizing subscripting for cross-references.
10433
* Fwebmac params:: Customizing behavior of @FWEB{}'s macros.
10434
* Completion params:: Automatic selection of file extensions, etc.
10435
* Control-code mappings:: Remapping @FWEB{}'s control codes (danger)!
10436
* Color:: @FWEB{}'s color output.
10437
* Miscellaneous params:: Other customizations.
10438
@end menu
10439
10440
@node Index params,Module params,Style,Style
10441
@comment node-name, next, previous, up
10442
10443
@subsection Customizing @FWEAVE{}'s index
10444
10445
In the following, @samp{???} denotes the name of various subparameters.
10446
10447
@menu
10448
* delim_0: S_delim. Insert after identifier in index entry.
10449
* delim_n: S_delim. Insert between section numbers in index entry.
10450
10451
* encap.infix: S_encap. Start the section number.
10452
* encap.prefix: S_encap. @TeX{} macro to begin a section number.
10453
* encap.suffix: S_encap. Ends the section number.
10454
10455
* group_skip::
10456
10457
* index.collate: S_index. Collating sequence for the Index.
10458
* index.postamble: S_index. @TeX{} material to end the Index.
10459
* index.preamble: S_index. @TeX{} material to begin the Index.
10460
* index.tex: S_index. Name of file holding the Index.
10461
10462
* item_0:: @TeX{} command to begin an index entry.
10463
10464
* language.prefix: S_language. Begin a language entry in the Index.
10465
* language.suffix: S_language. End a language entry in the Index.
10466
10467
* lethead.prefix: S_lethead. Begin a letter group.
10468
* lethead.suffix: S_lethead. End a letter group.
10469
* lethead.flag: S_lethead. Control beginning of letter group.
10470
10471
* name: S_index. Name of index.
10472
10473
* underline.prefix: S_underline. Begin an underlined index entry.
10474
* underline.suffix: S_underline. End an underlined index entry.
10475
@end menu
10476
10477
@node S_index, S_delim, Index params, Index params
10478
@comment node-name, next, previous, up
10479
10480
@subsubsection @code{index.@i{???}}
10481
10482
@findex \INDEX
10483
@cindex Index, name of
10484
@vindex index.name
10485
@code{index.name} is the name of the index section. This string is used
10486
in @code{\Wbegin} to initialize the @TeX{} macro @code{\INDEX}. The
10487
index section is recognized by matching, for a starred section, the
10488
actual section name against the contents of @code{\INDEX}. When they
10489
match, a new page and two-column mode are begun. These rules imply that
10490
the last section of one's source file can be titled @samp{\INDEX}, as in
10491
10492
@example
10493
@@* \INDEX.
10494
@end example
10495
10496
@vindex index.tex
10497
@code{index.tex} is the name of the file into which the Index is
10498
written. The character @samp{#} is translated into the root name of the web
10499
file, as for example @samp{#.ndx}.
10500
10501
@vindex index.preamble
10502
@code{index.preamble} are @TeX{} commands that begin the Index.
10503
10504
@vindex index.postamble
10505
@code{index.postamble} are @TeX{} commands that end the Index.
10506
10507
@vindex index.collate
10508
@code{index.collate} specifies the collating sequence for the Index.
10509
10510
@node S_delim, S_encap, S_index, Index params
10511
@comment node-name, next, previous, up
10512
10513
@subsubsection @code{delim_@i{?}}
10514
10515
@vindex delim_0
10516
@code{delim_0} is the string to insert after the identifier in an index
10517
entry.
10518
10519
@vindex delim_n
10520
@code{delim_n} is the string to insert between two section numbers in an
10521
index entry.
10522
10523
@node S_encap, group_skip, S_delim, Index params
10524
@comment node-name, next, previous, up
10525
10526
@node group_skip, item_0, S_encap, Index params
10527
@comment node-name, next, previous, up
10528
10529
@subsubsection @code{group_skip}
10530
10531
@vindex group_skip
10532
@code{group_skip} is a string of @TeX{} commands to insert between
10533
letter groups.
10534
10535
@node item_0, S_language, group_skip, Index params
10536
@comment node-name, next, previous, up
10537
10538
@subsubsection @code{item_0}
10539
10540
@vindex item_0
10541
@code{item_0} is the @TeX{} command to begin an index entry.
10542
10543
@node S_language, S_lethead, item_0, Index params
10544
@comment node-name, next, previous, up
10545
10546
@subsubsection @code{language.@i{???}}
10547
10548
@vindex language.prefix
10549
@vindex language.suffix
10550
@code{language.prefix} begins a language entry.; @code{language.suffix}
10551
ends one.
10552
10553
@node S_lethead, S_underline, S_language, Index params
10554
@comment node-name, next, previous, up
10555
10556
@subsubsection @code{lethead.@i{???}}
10557
10558
@vindex lethead.prefix
10559
@vindex lethead.suffix
10560
@vindex lethead.flag
10561
@code{lethead.prefix} begins a letter group; @code{lethead.suffix} ends
10562
one. The flag @code{lethead.flag} controls the format of the letter
10563
group: if it is zero, nothing is inserted; if it is positive, an
10564
upper-case letter is inserted; if it is negative, a lower-case letter is
10565
inserted.
10566
10567
10568
@node S_underline, , S_lethead, Index params
10569
@comment node-name, next, previous, up
10570
10571
@subsubsection @code{underline.@i{???}}
10572
10573
@vindex underline.prefix
10574
@code{underline.prefix} is the @TeX{} command to begin an underlined
10575
index entry.
10576
10577
@vindex underline.suffix
10578
@code{underline.suffix} is the @TeX{} command to end an underlined index
10579
entry.
10580
10581
10582
@node Module params,Contents params,Index params,Style
10583
@comment node-name, next, previous, up
10584
10585
@subsection Customizing the module list
10586
10587
@menu
10588
* modules.info: S_modules.
10589
* modules.postamble: S_modules. @TeX{} commands to end module list.
10590
* modules.preamble: S_modules. @TeX{} commands to begin module list.
10591
* modules.tex: S_modules. Name of file containing list of modules.
10592
@end menu
10593
10594
@node S_modules, , Module params, Module params
10595
@comment node-name, next, previous, up
10596
10597
@vindex modules.tex
10598
@code{modules.tex} is the name of the file into which the module names
10599
are written.
10600
10601
@vindex modules.preamble
10602
@code{modules.preamble} is a string of @TeX{} commands to begin the list
10603
of modules.
10604
10605
@vindex modules.postamble
10606
@code{modules.postamble} is a string of @TeX{} commands to end the list
10607
of modules.
10608
10609
@vindex modules.info
10610
@code{modules.info} is the name of the @TeX{} macro that formats the
10611
command line and related information.
10612
10613
@node Contents params,Subscript params,Module params,Style
10614
@comment node-name, next, previous, up
10615
10616
@subsection Customizing the Table of Contents
10617
10618
@menu
10619
* contents.postamble: S_contents. @TeX{} commands to end Table of Contents.
10620
* contents.preamble: S_contents. @TeX{} commands to begin Table of Contents.
10621
* contents.tex: S_contents. Name of contents file.
10622
@end menu
10623
10624
@node S_contents, , Contents params, Contents params
10625
@comment node-name, next, previous, up
10626
10627
@vindex contents.tex
10628
@code{contents.tex} is the name of the file into which the Table of
10629
Contents is written.
10630
10631
@vindex contents.preamble
10632
@code{contents.preamble} is the @TeX{} string that begins printing the
10633
Table of Contents.
10634
10635
@vindex contents.postamble
10636
@code{contents.postamble} is the @TeX{} string that ends the Table of
10637
Contents.
10638
10639
@node Subscript params,Fwebmac params,Contents params,Style
10640
@comment node-name, next, previous, up
10641
10642
@subsection Customizing cross-reference subscripts
10643
10644
@cindex Bullet
10645
@cindex Subscript, bullet
10646
When @FWEAVE{} pretty-prints code, it can attach cross-reference
10647
subscripts to various kinds of identifiers such as function or macro
10648
names. [A bullet
10649
@tex
10650
($\bullet$)
10651
@end tex
10652
for a subscript indicates that the name was defined in the
10653
current section.]
10654
The actual marking of the cross reference is done by
10655
the command @samp{@@[} (@pxref{AT[}). This is usually done
10656
implicitly; for example, the commands @samp{@@a}, @samp{@@d}, and
10657
@samp{@@m} issue an implicit @samp{@@[}. (See the discussion of
10658
@samp{@@a} in @ref{ATa}.) In C, various declarations of
10659
variables also result in such an implicit mark.
10660
10661
Various nuances in the type (possibly underlined) used for the
10662
subscript give a hint about what kind of identifier @FWEAVE{} thinks
10663
it's working with. For more information about the typesetting
10664
conventions, see the definition of the
10665
primitive macro @samp{\W@@IN} in @file{fwebmac.web}.]
10666
@cindex Bullet subscript
10667
The following flags select which identifiers are so subscripted.
10668
10669
To see the default values of these parameters, say @samp{ftangle
10670
-Zmark_defined}. To turn off the subscripting operations completely, use the
10671
@samp{-f} option (@pxref{-f}).
10672
10673
@menu
10674
* mark_defined.generic_name: S_mark_defined.
10675
* mark_defined.fcn_name: S_mark_defined.
10676
* mark_defined.WEB_macro: S_mark_defined.
10677
* mark_defined.outer_macro: S_mark_defined.
10678
* mark_defined.exp_type: S_mark_defined.
10679
* mark_defined.typedef_name: S_mark_defined.
10680
@end menu
10681
10682
@node S_mark_defined, , Subscript params, Subscript params
10683
@comment node-name, next, previous, up
10684
10685
@vindex mark_defined.typedef_name
10686
@vindex mark_defined.exp_type
10687
@vindex mark_defined.outer_macro
10688
@vindex mark_defined.WEB_macro
10689
@vindex mark_defined.fcn_name
10690
@vindex mark_defined.generic_name
10691
(Discussion to be completed.)
10692
10693
@node Fwebmac params,Completion params,Subscript params,Style
10694
@comment node-name, next, previous, up
10695
10696
@subsection Customizing the behavior of @file{fwebmac.sty} macros
10697
10698
@findex fwebmac.web
10699
To some extent, the behavior of @FWEB{}'s macro package
10700
@file{fwebmac.sty} can be changed by means of the following parameters.
10701
(Please try not to actually edit @file{fwebmac.sty} itself; it is
10702
produced automatically from @file{fwebmac.web}. And please don't edit
10703
that file either!)
10704
10705
@menu
10706
* doc.preamble: S_LaTeX. Preamble for entire document.
10707
* doc.postamble: S_LaTeX. Postamble for entire document.
10708
10709
* format_IDENTIFIER: S_format. Macro name for typesetting upper-case identifiers.
10710
* format.reserved: S_format. Macro for reserved words.
10711
* format.short_identifier: S_format. Macro for single-character identifiers.
10712
* format_OUTER_MACRO: S_format. Macro for upper-case @samp{@@d} identifiers.
10713
* format.outer_macro: S_format. Macro for lower-case @samp{@@d} identifiers.
10714
* format_WEB_MACRO: S_format. Macro for upper-case @samp{@@m} identifiers.
10715
* format.WEB_macro: S_format. Macro for lower-case @samp{@@m} identifiers.
10716
* format.intrinsic: S_format. Macro for intrinsic library functions.
10717
* format_KEYWORD: S_format. Macro for upper-case keywords.
10718
* format.keyword: S_format. Macro for lower-case keywords.
10719
* format.typewriter: S_format. Macro for strings.
10720
* format.wildcard: S_format. Macro for user-defined index entries.
10721
10722
* indent.TeX: S_indent. Paragraph indentation for @TeX{} part.
10723
* indent.code: S_indent. Paragraph indentation for code part.
10724
10725
* LaTeX.class: S_LaTeX. Specify the document class.
10726
* LaTeX.class.options: S_LaTeX. Specify options for document class.
10727
* LaTeX.package: S_LaTeX. Specify user package(s)
10728
* LATeX.package.options: S_LaTeX. Specify options for user package(s).
10729
@end menu
10730
10731
@node S_format, S_indent, Fwebmac params, Fwebmac params
10732
@comment node-name, next, previous, up
10733
10734
@subsubsection @code{format.@i{???}}
10735
10736
The @code{format} parameters are strings that specify the macro to be
10737
used to pretty-print various kinds of identifiers. These macro names
10738
are usually written automatically by @FWEAVE{}, but they may also be
10739
used directly by the user in the @TeX{} documentation. One can see
10740
their default values by typing @samp{ftangle -Zformat.}. For example,
10741
the default value for @code{format.typewriter} is @code{"\\."}.
10742
10743
The macro names defined by the @code{format} fields are @emph{not}
10744
defined in @file{fwebmac.sty}. They are @emph{dummy names}, and can be
10745
changed to any other name not already in use without affecting the
10746
operation of @FWEB{}. This ability is necessary because other
10747
packages might usurp macros like @code{\.} for their own purposes.
10748
10749
Thus, @FWEAVE{} normally writes out the macro @code{\.} to typeset a
10750
string. Suppose, however, that some user package uses @code{\.} for
10751
something else. (One might realize this when @sc{LaTeX} crashes
10752
when it encounteres a @code{\.} that was written automatically by
10753
@FWEAVE{}.) To fix this problem, put into @file{fweb.sty} the lines
10754
10755
@example
10756
format_KEYWORD = "\\WTT"
10757
format_keyword = "\\WTT"
10758
format_typewriter = "\\WTT"
10759
@end example
10760
@noindent
10761
Here @code{\WTT} can be any name not already in use; @emph{you need not (and
10762
should not)} give a definition for @code{\WTT}.
10763
10764
Macros like @code{\.} or @code{\WTT} are given their values during the
10765
execution of the @code{\Wbegin} macro that begins the output from
10766
@FWEAVE{}. The style-file values are written as arguments to that
10767
macro, and essentially a command like @code{\let\.\Wtypewriter} is
10768
executed, where the internal macro @code{\Wtypewriter} is defined in
10769
@file{fwebmac.sty}. If you want to change the way @FWEB{} typesets a
10770
particular kind of identifier, you must redefine the @emph{internal}
10771
macro name, not the one used in the @code{format} parameters.
10772
10773
Here are the internal macros used by @file{fwebmac.sty} to typeset the
10774
various kinds of identifiers. The associated style-file parameters are
10775
shown in parentheses.
10776
10777
@vindex format.id
10778
@vindex format.ID
10779
@vindex format.short_id
10780
@vindex format.outer_macro
10781
@vindex format.WEB_macro
10782
@vindex format.reserved
10783
@vindex format.RESERVED
10784
@vindex format.intrinsic
10785
@vindex format.keyword
10786
@vindex format.KEYWORD
10787
@vindex format.typewriter
10788
10789
@quotation
10790
@ftable @code
10791
10792
@item \Wid
10793
ordinary identifiers (@code{format.id})
10794
10795
@item \WID
10796
completely upper-case ordinary identifiers (@code{format.ID})
10797
10798
@item \Wshort
10799
single-character ordinary identifiers (@code{format.short_id})
10800
10801
@item \WidD
10802
outer macros (@code{format.outer_macro})
10803
10804
@item \WIDD
10805
completely upper-case outer macros (@code{format.outer_macro})
10806
10807
@item \WidM
10808
FWEB macros (@code{format.WEB_macro})
10809
10810
@item \WIDM
10811
completely upper-case FWEB macros (@code{format.WEB_macro})
10812
10813
@item \Wreserved
10814
reserved words (@code{format.reserved})
10815
10816
@item \WRESERVED
10817
completely upper-case reserved words (@code{format.RESERVED})
10818
10819
@item \Wintrinsic
10820
library/intrinsic function names (@code{format.intrinsic})
10821
10822
@item \Wkeyword
10823
certain Fortran keywords (@code{format.keyword})
10824
10825
@item \WKEYWORD
10826
completely upper-case keywords (@code{format.KEYWORD})
10827
10828
@item \Wtypewriter
10829
character strings (@code{format.typewriter})
10830
10831
@end ftable
10832
@end quotation
10833
10834
10835
@node S_indent, S_LaTeX, S_format, Fwebmac params
10836
@comment node-name, next, previous, up
10837
10838
@subsubsection @code{indent.@i{???}}
10839
10840
@vindex indent.TeX
10841
@code{indent.TeX} specifies paragraph indentation for the @TeX{} part.
10842
10843
@vindex indent.code
10844
@code{indent.code} specifies similar indentation for the code part.
10845
10846
@node S_LaTeX, , S_indent, Fwebmac params
10847
@comment node-name, next, previous, up
10848
10849
@subsubsection @code{LaTeX.@i{???}}
10850
10851
@vindex LaTeX.class
10852
For La@TeX{}2e, the default document class can be overridden by
10853
@code{LaTeX.class}. The default class is @code{article}, and @FWEB{}
10854
has not been tested with other document classes, except minimally with
10855
@code{revtex} (@pxref{REVTeX}).
10856
10857
@vindex LaTeX.class.options
10858
Options to the document class can be specified by
10859
@code{LaTeX.class.options}.
10860
10861
User packages can be given by @code{LaTeX.package}.
10862
10863
@vindex LaTeX.package
10864
@vindex LaTeX.package.options
10865
Options to user packages can be specified by
10866
@code{LaTeX.package.options}. There may be just one
10867
@code{LaTeX.package} command and just one @code{LaTeX.package.options}
10868
command. If it is necessary to issue multiple such commands, then put
10869
them into @code{doc.preamble}. See the discussion in @ref{Document
10870
class}.
10871
10872
@vindex LaTeX.style
10873
@vindex LaTeX.options
10874
When running under La@TeX{} prior to La@TeX{}2e (or with REVTeX; see
10875
@ref{REVTeX}), the document is
10876
(effectively) begun by the command
10877
@code{\documentstyle[options]@{style@}}. The options field can be
10878
specified by @code{LaTeX.options}; the style field by
10879
@code{LaTeX.style}.
10880
10881
10882
@node Control-code mappings, Color, Completion params, Style
10883
@comment node-name, next, previous, up
10884
10885
@subsection Remapping control codes
10886
10887
Control-code remappings are sophisticated and unwise. They are mostly
10888
intended for the developer, so are not explained here.
10889
10890
@node Color, Miscellaneous params, Control-code mappings, Style
10891
@comment node-name, next, previous, up
10892
10893
@subsection Color output
10894
10895
@cindex Color
10896
In the design of @FWEB{}, provision has been made for writing various
10897
messages to the terminal in color---e.g., serious error messages might
10898
appear in red. This feature was motivated by the color @code{ls} of Linux.
10899
It is installed automatically if the @code{termcap} library is present.
10900
10901
@cindex Message types
10902
@cindex Color, and message types
10903
Messages output from @FWEB{} are ranked according to an internal message-type
10904
table; each type can be associated with a color that can be changed
10905
in the style file. Presently, the message types (hopefully
10906
self-explanatory) are
10907
@cindex Message types
10908
@vindex color.ordinary
10909
@vindex color.program_name
10910
@vindex color.mod_name
10911
@vindex color.info
10912
@vindex color.warning
10913
@vindex color.error
10914
@vindex color.fatal
10915
@vindex color.mod_num
10916
@vindex color.line_num
10917
@vindex color.in_file
10918
@vindex color.include_file
10919
@vindex color.out_file
10920
@vindex color.timing
10921
10922
@quotation
10923
@example
10924
ordinary
10925
program_name
10926
mod_name
10927
info
10928
warning
10929
error
10930
fatal
10931
mod_num
10932
line_num
10933
in_file
10934
include_file
10935
out_file
10936
timing
10937
@end example
10938
@end quotation
10939
10940
@noindent
10941
The associated style-file parameters are the above names prefaced by
10942
@samp{color.}---e.g., @code{color.warning}. Each of those has a default
10943
value, such as @code{color.error = "red"}. Those defaults can be
10944
displayed by saying @samp{ftangle -Zcolor}.
10945
10946
What the color actually means in practice depends on the @dfn{color
10947
mode}, set by the @samp{-C} option (@pxref{-C_}). That selects one of
10948
several primitive palettes, as follows:
10949
@findex -C
10950
10951
@quotation
10952
@table @kbd
10953
@item 0
10954
@strong{No color}; ordinary black-and-white output. This is the default (and the
10955
mode used when the @code{termcap} library is not present).
10956
10957
@item 1
10958
@cindex Color, ANSI
10959
@cindex Color mode, ANSI
10960
@strong{ANSI color}. With a color terminal that supports ANSI color escape
10961
sequences, one has available the following colors: @code{"black"},
10962
@code{"red"}, @code{"green"}, @code{"yellow"}, @code{"blue"},
10963
@code{"magenta"}, @code{"cyan"}, @code{"white"}, and @code{"default"}.
10964
These are displayed with bold attribute (that is, bright, not dim).
10965
@samp{"default"} stands for the usual black on white background, or vice
10966
versa.
10967
10968
@item 2
10969
@cindex Color mode, bilevel
10970
@strong{Bilevel}. This is for terminals that don't support true color,
10971
but do support a double-bright mode and reverse video. Colors are
10972
mapped onto various combinations of those two display attributes,
10973
according to an internally defined scheme. For example, @code{"red"} is
10974
mapped onto the pair of escape sequences @samp{md}, @samp{mr}
10975
(double-bright mode in reverse video).
10976
10977
@item 3
10978
@cindex Color mode, trilevel
10979
@strong{Trilevel}. As above, but adds underlining capability.
10980
10981
@item 4
10982
@cindex Color mode, user-defined
10983
@strong{User-defined colors}. This implements a minimal set of defaults. It is
10984
intended that the user add definitions in the style file to override
10985
those defaults.
10986
10987
@end table
10988
@end quotation
10989
10990
@findex termcap
10991
@cindex Escape sequences, ANSI
10992
@vindex Color.black
10993
@vindex Color.red
10994
@vindex Color.green
10995
@vindex Color.yellow
10996
@vindex Color.blue
10997
@vindex Color.magenta
10998
@vindex Color.cyan
10999
@vindex Color.white
11000
@vindex Color.default
11001
11002
The mechanism is intended to work with systems that support the
11003
@code{termcap} library. The terminal is controlled by writing
11004
appropriate escape sequences to it. The style-file parameters that
11005
store the escape sequences are the color name preceded by @samp{Color.}
11006
(note the upper case @samp{C})---e.g., @samp{Color.red}. For cases like
11007
reverse video (standard termcap abbreviation @samp{mr}), the escape
11008
sequences are determined by querying the termcap database (usually
11009
@file{/etc/termcap}) through the @code{termcap} library functions. For
11010
ANSI color (color mode = 1), ANSI escape sequences are hard-coded into
11011
@FWEB{}. One can see the escape sequences @FWEB{} assigns to colors by
11012
saying @samp{ftangle -ZColor}.
11013
11014
For any non-zero color mode, one can override @FWEB{}'s default choices
11015
for color mappings and escape sequences by redefining one or more of the
11016
@code{Color} parameters in the style file. The escape sequences can
11017
either be specified in raw form---e.g., for color mode = 1, a
11018
default is @code{Color.red = "\e[01;31m"}---or in the form of a sequence
11019
of two-character abbreviations that are defined in the termcap
11020
documentation---e.g., for modes 2 and 3, the default is @code{Color.red
11021
= "mdmr"}. (When one displays that with the @samp{-Z} option, @FWEB{}
11022
will display the actual escape sequences that it determines from the termcap
11023
database, not the abbreviations. For both input and output, note that
11024
one may use the non-ANSI escape sequence @samp{\e} to represent the
11025
escape character @samp{\033}.)
11026
11027
When one says @samp{-ZColor}, for color modes 1--3 all of the
11028
parameters are listed as modified, even if the user redefines none.
11029
That occurs because the defaults are overwritten internally when the
11030
color mode is set.
11031
11032
@findex termcap0
11033
@FWEB{}'s configuration script attempts to determine whether the termcap
11034
library is present; if not, they link in dummy termcap routines
11035
(@file{termcap0.web}). To override this behavior, change the
11036
appropriate lines in @file{defaults.mk}, produced by the command
11037
@code{./configure}.
11038
11039
Color message output is not fully debugged (it's a frill, after all), so
11040
some messages that should reasonably be colored may not be so in the
11041
present release.
11042
11043
@node Miscellaneous params,,Color,Style
11044
11045
@comment node-name, next, previous, up
11046
11047
@subsection Miscellaneous style-file parameters
11048
11049
There are a variety of miscellaneous parameters.
11050
11051
@menu
11052
For @FTANGLE{}:
11053
11054
* ASCII_fcn:: Routine for converting strings to ASCII.
11055
* cchar:: Continuation character for Fortran.
11056
* cdir_start:: @samp{@?} translates to this.
11057
* line_char:: Comment char. for @FTANGLE{}'s @code{line} cmds.
11058
* line_length: S_line_length.
11059
11060
* paren.len: -n). Length of one parenthesized index for @samp{-n)}.
11061
* paren.levels: -n). Number of nested parentheses for @samp{-n)}.
11062
* paren.num: -n). Number of permitted indices for @samp{-n)}.
11063
11064
* meta.top: S_meta_t. Material to precede tangled meta-comment.
11065
* meta.prefix: S_meta_t. Begins each line of meta-comment.
11066
* meta.bottom: S_meta_t. Material that follows the meta-comment.
11067
11068
* meta.top.hdr: S_meta_t. Like meta.top, but for info at start of file.
11069
* meta.prefix.hdr: S_meta_t. As above.
11070
* meta.bottom.hdr: S_meta_t. As above.
11071
11072
* outer.def: S_outer. @FTANGLE{} converts @samp{@@d} to this.
11073
* outer.undef: S_outer. @FTANGLE{} converts @samp{@@u} to this.
11074
11075
* protect:: Protection character to end a continued line.
11076
* suffix:: Suffixes for output files.
11077
11078
For @FWEAVE{}:
11079
11080
* macros:: Default name of the macro package to be
11081
read in by @FWEAVE{}.
11082
* limbo.begin: S_limbo. Default material to begin the limbo section.
11083
* limbo.end: S_limbo. Default material to end the limbo section.
11084
11085
* meta.code.begin: S_meta_w.
11086
* meta.code.end: S_meta_w.
11087
11088
* meta.TeX.begin: S_meta_w. @TeX{} material to begin @FWEAVE{}'s
11089
output of a meta-comment.
11090
* meta.TeX.end: S_meta_w. As above, but end the meta-comment.
11091
11092
* preamble.named: S_preamble. @TeX{} material to begin named section.
11093
* preamble.unnamed: S_preamble. @TeX{} material to begin unnamed section.
11094
11095
For both processors:
11096
11097
* dot_constant.begin: S_dot_constant. Beginning character for dot constant.
11098
* dot_constant.end: S_dot_constant. Ending character for dot constant.
11099
11100
* null_file:: Name of the null file.
11101
@end menu
11102
11103
@node ASCII_fcn, cchar, Miscellaneous params, Miscellaneous params
11104
@comment node-name, next, previous, up
11105
11106
@subsubsection @code{ASCII_Fcn}
11107
11108
@vindex ASCII_Fcn
11109
@xref{ATdquote}.
11110
11111
@node cchar, cdir_start, ASCII_fcn, Miscellaneous params
11112
@comment node-name, next, previous, up
11113
11114
@subsubsection @code{cchar}
11115
11116
@vindex cchar
11117
Continuation character for @sc{Fortran} code output.
11118
11119
@node cdir_start, line_char, cchar, Miscellaneous params
11120
@comment node-name, next, previous, up
11121
11122
@subsubsection @code{cdir_start}
11123
11124
@vindex cdir_start
11125
This parameter has the form @code{cdir_start.@i{l}}, where @i{l} is one of
11126
@samp{C}, @samp{Cpp}, @samp{N}, @samp{N90}, @samp{R}, @samp{R90},
11127
@samp{X}, or @samp{V}. The contents of this parameter is written
11128
immediately after the @samp{@@?} that begins a compiler directive.
11129
11130
@node line_char, S_line_length, cdir_start, Miscellaneous params
11131
@comment node-name, next, previous, up
11132
11133
@subsubsection @code{line_char.@i{l}} (@FTANGLE{})
11134
11135
@vindex line_char
11136
By default, @FTANGLE{} outputs comments indicating line numbers in the
11137
@code{web} file from which the tangled output comes. (This information
11138
can be used by debuggers, especially those for C and C++, to correlate
11139
error messages to the @code{web} source.) The @code{line_char}
11140
parameter sets the comment character that begins the line comment.
11141
11142
@node S_line_length, S_meta_t, line_char, Miscellaneous params
11143
@comment node-name, next, previous, up
11144
11145
@subsubsection @code{line_length.@i{l}} (@FTANGLE{})
11146
11147
@vindex line_length
11148
This parameter is used by the @sc{Fortran}-like languages to control the
11149
length of the output line in the @file{.f} file produced by
11150
@FTANGLE{}. For @sc{Fortran}-77, its default value is the venerable
11151
72. For @sc{Fortran}-90, its default is 73. Using that value makes it
11152
possible to generate code that is compatible with both fixed- and
11153
free-form format (by continuing lines with an trailing ampersand in
11154
column 73 and another ampersand in column 6 of the next line).
11155
11156
@node S_meta_t, S_outer, S_line_length, Miscellaneous params
11157
@comment node-name, next, previous, up
11158
11159
@subsubsection @code{meta.@i{???.?}}, @code{meta.@i{???}.hdr.@i{?}} (@FTANGLE{})
11160
11161
These parameters customize the treatment of meta-comments.
11162
Fundamentally, meta-comments consist of material enclosed by
11163
@samp{@@(...@@)}. The header information usually written at the top of
11164
the file output by @FTANGLE{} (@pxref{-Tv}) is also treated as a
11165
meta-comment. For that header material, a separate set of parameters is
11166
provided, such as @code{meta.top.hdr}.
11167
11168
@vindex meta.top
11169
@vindex meta.top.hdr
11170
@code{meta.top.@var{l}} specifies text that precedes material enclosed by
11171
@samp{@@(...@@)}. Here @var{l} is one of the standard language subscripts
11172
(@pxref{Style}) such as @code{N90}.
11173
11174
@vindex meta.prefix
11175
@vindex meta.prefix.hdr
11176
@code{meta.prefix.@var{l}} begins each line of the meta-comment.
11177
11178
@vindex meta.bottom
11179
@vindex meta.bottom.hdr
11180
@code{meta.bottom.@var{l}} specifies text that follows the meta-comment.
11181
11182
@node S_outer, protect, S_meta_t, Miscellaneous params
11183
@comment node-name, next, previous, up
11184
11185
@subsubsection @code{outer.@i{???}}
11186
11187
@vindex outer.def
11188
@vindex outer.under
11189
@FTANGLE{} converts @samp{@@d} (@pxref{ATd}) to @code{outer.def}, and
11190
@samp{@@u} (@pxref{ATu}) to @code{outer.undef}.
11191
11192
@node protect, suffix, S_outer, Miscellaneous params
11193
@comment node-name, next, previous, up
11194
11195
@subsubsection @code{protect.?}
11196
11197
@vindex protect
11198
The strings @code{protect.@var{l}} specify the protection character(s) to end
11199
a continued line.
11200
11201
@node suffix, macros, protect, Miscellaneous params
11202
@comment node-name, next, previous, up
11203
11204
@subsubsection @code{suffix.?}
11205
11206
@vindex suffix
11207
The extension for the files output by @FTANGLE{} is specified by
11208
@code{suffix.@var{l}}.
11209
11210
11211
@node macros, S_limbo, suffix, Miscellaneous params
11212
@comment node-name, next, previous, up
11213
11214
@subsubsection @code{macros}
11215
11216
@vindex macros
11217
The default name of the macro package to be read in. [This is usually
11218
@file{fwebmac.sty} (@pxref{fwebmac.sty}), but can be overridden by the
11219
command-line option @samp{-w}; see @ref{-w}.]
11220
11221
@node S_limbo, S_meta_w, macros, Miscellaneous params
11222
@comment node-name, next, previous, up
11223
11224
@subsubsection @code{limbo.begin}, @code{limbo.end}
11225
11226
@vindex limbo.begin
11227
@samp{limbo.begin} is @TeX{} material to be printed at the beginning of
11228
the limbo section, just before the text from @samp{@@l} commands. @xref{ATl}.
11229
(This command was previous called just @samp{limbo}, and that still
11230
works.)
11231
11232
@vindex limbo.end
11233
Similarly, @samp{limbo.end} is printed at the end of the limbo section.
11234
11235
Thus, the beginning of the file output by @FWEAVE{} looks like this:
11236
11237
@example
11238
\input fwebmac.sty
11239
11240
\Wbegin@{...@}
11241
[contains \documentclass, \usepackage, <doc.preamble>, \begin@{document@}]
11242
11243
<limbo.begin>
11244
[contents of any @@l commands]
11245
[user's TeX commands from the limbo section]
11246
<limbo.end>
11247
@end example
11248
11249
The @samp{limbo.end} command is useful for printing the entire document
11250
in two-column format. For more discussion, see @ref{LIndex}.
11251
11252
@node S_meta_w, S_preamble, S_limbo, Miscellaneous params
11253
@comment node-name, next, previous, up
11254
11255
@subsubsection @code{meta.@i{???}} (@FWEAVE{})
11256
11257
@vindex meta
11258
(To be finished.)
11259
11260
@node S_preamble, S_dot_constant, S_meta_w, Miscellaneous params
11261
@comment node-name, next, previous, up
11262
11263
@subsubsection @code{preamble.@i{???}}
11264
11265
@vindex preamble.named
11266
@vindex preamble.unnamed
11267
Additional @TeX{} material can be inserted at the beginning of a named
11268
section with @code{preamble.named} and at the beginning of an unnamed
11269
one with @code{preamble.unnamed}.
11270
11271
@node S_dot_constant, null_file, S_preamble, Miscellaneous params
11272
@comment node-name, next, previous, up
11273
11274
@subsubsection @code{dot_constant.@i{???.?}}
11275
11276
@vindex dot_constant.begin
11277
@vindex dot_constant.end
11278
In @sc{Fortran}, `dot' constants such as @code{.LT.} are begun and ended by
11279
periods. In special circumstances, the beginning and ending characters
11280
may be modified by @code{dot_constant.begin.@var{l}} and
11281
@code{dot_constant.end.@var{l}}.
11282
11283
@node null_file, , S_dot_constant, Miscellaneous params
11284
@comment node-name, next, previous, up
11285
11286
@subsubsection @code{null_file}
11287
11288
@vindex null_file
11289
The name of the null file or device. For more discussion, see
11290
@ref{Change files}.
11291
11292
@node Completion params,Control-code mappings,Fwebmac params,Style
11293
@comment node-name, next, previous, up
11294
11295
@subsection Automatic file name completion
11296
11297
@menu
11298
* Ext.web: S_Ext. Extensions for the web file.
11299
* Ext.ch: S_Ext. Extensions for the change file.
11300
* Ext.hweb: S_Ext. Extensions for include files.
11301
* Ext.hch: S_Ext. Extensions for change files associated with
11302
include files.
11303
@end menu
11304
11305
@node S_Ext, , Completion params, Completion params
11306
@comment node-name, next, previous, up
11307
11308
@vindex ext.web
11309
@vindex ext.ch
11310
@vindex ext.hweb
11311
@vindex ext.hch
11312
11313
For more information, see @ref{-e}.
11314
11315
@node Hints, New features, Customization, Top
11316
@comment node-name, next, previous, up
11317
11318
@chapter USAGE TIPS and SUGGESTIONS
11319
11320
In this section are collected various tips and suggestions to help one make
11321
full use of @FWEB{}. Additional hints broken down by each supported
11322
source language can be found in @ref{Languages}.
11323
11324
@menu
11325
* Converting:: Converting an existing code to @FWEB{}.
11326
* Tips:: Usage tips and suggestions.
11327
* Science:: Useful features for scientific programming.
11328
@end menu
11329
11330
@node Converting, Tips, Hints, Hints
11331
@comment node-name, next, previous, up
11332
11333
@section Converting an existing code to @FWEB{}
11334
11335
@cindex Converting an existing code to @FWEB{}
11336
@cindex Code, converting to @FWEB{}
11337
To convert an existing code to @FWEB{}, one should do the
11338
following. (The following simple procedure assumes that one puts all the
11339
subroutines into the unnamed module. However, other more elaborate schemes
11340
are possible.)
11341
11342
@enumerate
11343
11344
@item
11345
Place invisible commentary
11346
about the author, version, etc. at the beginning of the source file by
11347
bracketing it with @samp{@@z...@@x}. The @samp{@@z} must be the first two
11348
characters of the file.
11349
11350
@item
11351
Next, set the language by including a command such as @samp{@@n} or
11352
@samp{@@c++}.
11353
11354
@item
11355
Place an @samp{@@a} command (switch into unnamed code) before each
11356
program unit (e.g., main @b{program}, @b{subroutine}, or @b{function}).
11357
11358
@item
11359
Before each @samp{@@a}, place an @samp{@@*} or @ASP{} command,
11360
followed by @TeX{} documentation about that particular section of code.
11361
11362
@item
11363
If you have program units longer than about twelve lines, either
11364
make them function calls, if you can afford the overhead and can impart
11365
sufficient information via the function name, or break them up into shorter
11366
fragments by using named modules. Insert the command @samp{@@<Name of
11367
module@@>} in place of the fragment you're replacing, then put that
11368
fragment somewhere else, prefaced by
11369
@ASP{} and @samp{@@<Name of module@@>=}.
11370
11371
@item
11372
Make sure your comments are valid @TeX{}. (One can't have things
11373
like raw underscores or dollar signs in comments, since those cause @TeX{}
11374
to take special actions.)
11375
11376
@item
11377
Beautify and clarify your documentation by using code mode
11378
(enclosing stuff between vertical bars) liberally within your @TeX{}.
11379
11380
@item
11381
After you've seen the woven output, you may need to go back and
11382
format a few identifiers or section names so that @FWEAVE{} understands them
11383
properly, or you may need to insert some pseudo-semicolons (@samp{@@;}),
11384
pseudo-expressions (@samp{@@e}), or pseudo-colons (@samp{@@:})
11385
(@pxref{Pseudo-operators}).
11386
11387
@item
11388
Consider using @FWEB{}'s built-in macro preprocessor (@pxref{Macros})
11389
to make your code more readable---for example, replace raw numerical
11390
constants by symbolic names.
11391
11392
@item
11393
Scientific programmers may benefit from built-in macro-like functions
11394
like @code{$PI}; see @ref{Built-in functions}.
11395
11396
@item
11397
If you are a @sc{Fortran} user, for ultimate readability
11398
consider converting to @sc{Ratfor}. The initial annoyance is getting rid of
11399
column-6 continuations. With the aid of a good editor, this can be done
11400
simply. For example, in @code{emacs} one can replace the regular expression
11401
[carriage return, five spaces, something not equal to space, tab, or 0]
11402
with [backslash, carriage return, six spaces]:
11403
11404
@example
11405
M-x replace-regexp RET
11406
C-q C-j \.@{\ \ \ \ \ @}[\^\.\ tab 0]RET
11407
\\\\ C-q C-j \.@{\ \ \ \ \ \ @}RET
11408
@end example
11409
11410
@noindent
11411
Get rid of the keywords such as @b{then} or @b{end if} in favor
11412
of braces. Change singly-quoted character strings to doubly-quoted
11413
ones. The @samp{-nC} option (@pxref{-nC}) may be helpful.
11414
11415
@end enumerate
11416
11417
@node Tips, Science, Converting, Hints
11418
@comment node-name, next, previous, up
11419
11420
@cindex Suggestions
11421
@cindex Programming tips
11422
11423
@section Programming tips and other suggestions
11424
11425
@enumerate
11426
11427
@item
11428
Learn how to use the GNU @code{info} browser to access the on-line
11429
documentation.
11430
11431
@item
11432
Read the list of new features and changes for the last several
11433
releases. @xref{New features}.
11434
11435
@item
11436
Periodically check @code{ftp.pppl.gov:/pub/fweb/READ_ME} for bug
11437
reports and other news. Make bug reports! @xref{Support}.
11438
11439
@item
11440
If you have a color terminal, try the option @samp{-C1} (@pxref{-C_},
11441
@pxref{Color}).
11442
11443
@item
11444
Any option in @file{.fweb} that is intended to be processed @emph{after}
11445
the command-line options should begin with @samp{&} rather than
11446
@samp{-}. (This is rarely necessary.)
11447
@xref{Initialization}
11448
11449
@item
11450
Put standard command-line options into @file{.fweb}. Also put there
11451
standard style parameters---e.g.,
11452
11453
@example
11454
-pindex.tex "#.ndx"
11455
-pmodules.tex "#.mds"
11456
-pcontents.tex "#.cts"
11457
@end example
11458
11459
@item
11460
Learn how to use the style file. @xref{Style}.
11461
11462
@item
11463
Use the info options @samp{-@@}, @samp{-D}, @samp{-y}, and @samp{-Z}
11464
to find out about various internal @FWEB{} tables (control codes,
11465
reserved words, memory allocations, and style-file parameters).
11466
@xref{Info options}.
11467
11468
@item
11469
Begin all @FWEB{} sources with invisible commentary
11470
bracketed by @samp{@@z...@@x}.
11471
@xref{ATz}.
11472
11473
@item
11474
Always include an explicit language-setting command in the limbo
11475
section. Under normal circumstances, do not set the language from the
11476
command line.
11477
@xref{Languages}.
11478
11479
@item
11480
Keep sections quite short.
11481
Knuth suggests a dozen lines. That's
11482
quite hard to achieve sometimes, but almost never should a section be more
11483
than a page long. If a block of code is longer than that, split it up
11484
using named modules.
11485
11486
@item
11487
It's easy to define macros from the command line to expedite
11488
conditional preprocessing.
11489
@xref{-m}.
11490
11491
@item
11492
Use the preprocessor construction @samp{@@#if 0...@@#endif} to
11493
comment out unwanted code.
11494
@xref{Preprocessing}.
11495
11496
@item
11497
For logical operations with the preprocessor, use @samp{||}, not @samp{|}.
11498
11499
@item
11500
It's conventional to identify the ends of long preprocessor
11501
constructions as follows:
11502
11503
@example
11504
@@#if A
11505
.
11506
.
11507
@@#endif // |A|
11508
@end example
11509
11510
@item
11511
To debug an errant @FWEB{} macro, use the built-in function
11512
@samp{$DUMPDEF}.
11513
@xref{$DUMPDEF}.
11514
11515
@item
11516
Use @samp{@@?} for compiler directives. @xref{AT?}.
11517
Use the style-file parameters @samp{cdir_start} to specify
11518
information that will be written out at the beginning of the line.
11519
@xref{cdir_start}.
11520
11521
@item
11522
Stick to the standard @FWEB{} commenting style @samp{/*...*/} or
11523
@samp{//...}. Don't use alternatives such as @sc{Fortran}'s column 1
11524
convention; these may not work or may not be supported someday.
11525
@xref{Comments}.
11526
11527
@item
11528
The meta-comment feature @samp{@@(...@@)} provides a poor-person's
11529
alignment feature. But it doesn't work very well, and it's not in the
11530
spirit of @TeX{}; learn to use @samp{\halign} or the La@TeX{} alternatives.
11531
11532
@item
11533
In @sc{Fortran}, use @samp{#:0} to declare readable alphabetic statement
11534
labels. See @ref{Tokens} and @ref{-colon}.
11535
11536
@item
11537
When mixing languages, define the language of a module at the highest
11538
possible level---e.g., in the unamed module, not after @samp{@@<...@@>=}.
11539
11540
@item
11541
Use La@TeX{}. Plain @TeX{} is no longer supported. Upgrade to
11542
La@TeX{}2e. @xref{LaTeX}.
11543
11544
@item
11545
If you are reading this documentation from printed pages, make sure it's
11546
also installed as an Info package on your system so it can be read
11547
interactively with @code{emacs}. You can also read it through a
11548
World-Wide Web browser such as Netscape. For the address, see
11549
@ref{Support}.
11550
11551
@end enumerate
11552
11553
11554
@node Science, , Tips, Hints
11555
@comment node-name, next, previous, up
11556
11557
@cindex Scientific programming
11558
11559
@section Features for scientific programming
11560
11561
@FWEB{} contains a few features particularly intended for scientific
11562
programming.
11563
11564
@enumerate
11565
@item
11566
Several built-in functions generate numerical constants. See @samp{$PI}
11567
(@ref{$PI}) and @samp{$E} (@ref{$E}).
11568
11569
@item
11570
Several built-in functions perform mathematical manipulations. See
11571
@samp{$EXP} (@ref{$EXP}), @samp{$POW} (@ref{$POW}), @samp{$SQRT}
11572
(@ref{$SQRT}), @samp{$LOG} (@ref{$LOG}), @samp{$LOG10} (@ref{$LOG10}),
11573
@samp{$MAX} (@ref{$MAX}), and @samp{$MIN} (@ref{$MIN}).
11574
11575
@item
11576
The do-loop macro @samp{$DO} may be useful. @xref{$DO}.
11577
11578
@item
11579
C-style array indices can be used by means of the @samp{-n)} option.
11580
@xref{-n)}.
11581
11582
@item
11583
An active bracket feature helps improve the appearance of
11584
woven code that uses subscripts and/or superscripts heavily. @xref{-W[}.
11585
11586
@end enumerate
11587
11588
@node New features, Support, Hints, Top
11589
@comment node-name, next, previous, up
11590
11591
@chapter NEW FEATURES
11592
11593
@cindex Features, new
11594
11595
This info documentation is now accessible on the World-Wide Web; see
11596
@ref{Support}.
11597
11598
Some things that have been added or changed in recent releases are
11599
described in the following.
11600
11601
@menu
11602
* V1.61::
11603
* V1.53::
11604
* V1.52::
11605
* V1.50::
11606
* V1.40::
11607
@end menu
11608
11609
@node V1.61, V1.53, New features, New features
11610
@comment node-name, next, previous, up
11611
11612
@section Version 1.61
11613
11614
@subsection Updates to documentation (v1.61)
11615
11616
@quotation
11617
@enumerate
11618
11619
@item
11620
@FWEB{} supports color modes in which messages to the terminal can
11621
appear in colors chosen by the user; see @ref{Color}. The color mode is
11622
set by the new command-line option @samp{-C} (@pxref{-C_}).
11623
11624
@item
11625
A previously undocumented feature is that for the C-like and
11626
Fortran-like languages, @FTANGLE{} expands the binary notation
11627
@samp{0b...} to an unsigned decimal number. @xref{Phases}.
11628
11629
@end enumerate
11630
@end quotation
11631
11632
@subsection Redefined commands (v1.61)
11633
11634
@cindex Commands, redefined
11635
@cindex Redefined commands, version 1.61
11636
11637
A few obscure commands have been slightly redefined. Sorry about that,
11638
but it makes for more symmetry and ease of recall, and/or solves some
11639
technical problems.
11640
11641
@quotation
11642
@enumerate
11643
11644
@item
11645
Although it was never documented, previous versions permitted either
11646
lower or upper case for the @samp{@@} commands that set the
11647
language---e.g., both @samp{@@c} and @samp{@@C} worked. Now only the
11648
lower-case forms work. (The upper-case forms may have other meanings.)
11649
11650
@item
11651
The style-file parameter @samp{Ext_delimiter} now begins with an
11652
upper-case @samp{E}; formerly it was lower-case.
11653
11654
@item
11655
The behavior of the optional argument of the @code{\Title} macro has
11656
been slightly redefined. The new, more symmetrical form is
11657
11658
@example
11659
\Title[Short title]@{Long title@}
11660
@end example
11661
@noindent
11662
where @code{Long title} is printed on the title page and @code{Short
11663
title} is used for the running header within the document. @xref{Table
11664
of Contents}.
11665
11666
@item
11667
The line-break commands @samp{@@/} and @samp{@@\} (formerly identical)
11668
now behave slightly differently. @samp{@@/} breaks the line just as it
11669
would if the line had been too long and been spontaneously broken.
11670
@xref{AT/}. @samp{@@\} backspaces one unit of indentation after
11671
breaking the line. @xref{ATbs}. Usually, one should use @samp{@@/}
11672
(sorry; I was previously recommending @samp{@@\}. For an example in
11673
which it is natural to use @samp{@@\}, see @ref{ATbs}.
11674
11675
@item
11676
The names of some of the code-typesetting macros in @code{fwebmac.sty}
11677
have been changed to conform to the convention that they should all
11678
start with @samp{W}. This change will be invisible to you unless you
11679
happen to have user macros of your own that start that way or (perish
11680
the thought) you have redefined low-level and obscure code in
11681
@file{fwebmac.sty}.
11682
11683
@end enumerate
11684
@end quotation
11685
11686
@subsection New features (v1.61)
11687
11688
@cindex Features, version 1.61
11689
This release adds some features for managing large projects, including
11690
(i) the @code{idxmerge} utility that merges indexes produced by several
11691
@FWEB{} files, (ii) a mechanism for accessing RCS-like information in
11692
the ignorable commentary at the beginning of the file, and (iii) the
11693
ability to include @FWEAVE{}-formatted code into a standard La@TeX{}
11694
document. It also fixes a variety of miscellaneous bugs.
11695
11696
@quotation
11697
@enumerate
11698
11699
@item
11700
A stand-alone index file suitable for processing by @code{makeindex} can
11701
be produced by the @samp{-XI} option. @xref{Using makeindex}.
11702
11703
@item
11704
Stand-alone indexes produced by @samp{-XI} can be merged with the
11705
@code{idxmerge} utility. @xref{Merging indexes}.
11706
11707
@item
11708
@FWEAVE{}-formatted code can be included in a standard La@TeX{}2e
11709
document by means of the @code{fwebinsert} package.
11710
@xref{Inserting woven code}.
11711
11712
@item
11713
Revision-control-system (RCS) information that appears in the ignorable
11714
commentary between the optional @samp{@@z} and @samp{@@x} that begin an
11715
@FWEB{} file (@pxref{ATz}) is accessible in the body of the file
11716
through the built-in function @code{$KEYWORD} (@pxref{$KEYWORD}) and the
11717
new commands @samp{@@K} (@pxref{ATK_}) and @samp{@@k} (@pxref{ATk}).
11718
These features can access RCS-like keywords that are not known to RCS
11719
itself, as long as they fit the proper syntax (@pxref{ATz}).
11720
11721
@item
11722
The @samp{-h} option now permits easy access to the GNU @code{info} browser if
11723
it is installed. @xref{-h}.
11724
11725
@item
11726
Underscored versions of built-in functions have been removed!!! E.g.,
11727
use @code{$IF}, not @code{_IF}. This change was warned about in the
11728
last release.
11729
11730
@item
11731
Single-character identifiers can now be completely cross-referenced via
11732
the @samp{-W1} option. @xref{-W1}.
11733
11734
@item
11735
Some module warning messages can be eliminated with the @samp{-W@@}
11736
option. @xref{-WAT}.
11737
11738
@item
11739
The @samp{@@q} command (still experimental) has been added to locally
11740
turn on or off the the line and module comments in the tangled output.
11741
@xref{ATq}.
11742
11743
@item
11744
The level of verbosity of @FWEB{}'s informational messages can be
11745
controlled with the @samp{-M} option. @xref{-M_}.
11746
11747
@item
11748
C/C++ programmers may find the command @samp{@@@{} useful. @xref{ATlb}.
11749
11750
@item
11751
The @samp{-nC} option has been added for @sc{Fortran} users; it kills
11752
commented lines at a very early stage in the processing. This can be
11753
useful when converting existing codes to @FWEB{}.
11754
@xref{-nC}
11755
11756
@item
11757
@sc{Fortran}-90 (@pxref{-n9}) now defaults to free-form syntax.
11758
11759
@item
11760
As of the non-beta Version 1.61, free-form @sc{Fortran}-90 now inserts
11761
semicolons automatically in the code part. Thus, textbook
11762
@sc{Fortran}-90 examples will weave correctly without the annoyance of
11763
explicitly terminating each statement with a semicolon. (If you prefer
11764
to put in the semicolons explicitly, use @samp{--n;} to turn off the
11765
auto-insertion.) @xref{-n;}
11766
11767
@item
11768
The default meaning of the @samp{-k} option was changed; now both lower-
11769
and upper-case forms of @sc{Fortran} I/O keywords are recognized.
11770
@xref{-k}.
11771
11772
@item
11773
Various changes were made to internal code in @file{fwebmac.sty}. This
11774
should not affect anyone @emph{unless} you have redefined @code{fwebmac}
11775
macros. If so, you'll have to compare your versions with the present
11776
ones. For example, colons as argument delimiters in @code{\def}s have
11777
been removed.
11778
11779
@item
11780
It is now (barely) possible to use @code{\documentstyle@{revtex@}}
11781
instead of the default @code{\documentclass@{article@}}. @xref{REVTeX}.
11782
11783
@end enumerate
11784
@end quotation
11785
11786
@subsection Significant bugs (v1.61)
11787
11788
@cindex Bugs, version 1.61
11789
@quotation
11790
@enumerate
11791
@item
11792
Perhaps the most significant bug is that some high-order (>= 128)
11793
characters in strings may not typeset or be processed correctly. This
11794
may be an issue for some users of foreign-language packages. The
11795
difficulty arises from a design decision made by a previous author.
11796
This has at least partly been fixed, but I eschewed a substantial
11797
overhaul for fear of breaking other things.
11798
11799
@end enumerate
11800
@end quotation
11801
11802
@node V1.53, V1.52, V1.61, New features
11803
@comment node-name, next, previous, up
11804
11805
@section Version 1.53
11806
11807
@cindex Features, version 1.53
11808
This release fixes a relatively small number of obscure bugs in
11809
@code{fweb-1.52-beta}. A few minor enhancements were also made. They include
11810
11811
@quotation
11812
@enumerate
11813
11814
@item
11815
Sections can be numbered by consecutive integers rather than LaTeX's
11816
default Dewey-decimal form by saying
11817
11818
@example
11819
LaTeX.package = "fwebnum"
11820
@end example
11821
@noindent
11822
@xref{Sections}.
11823
11824
@item
11825
The @samp{-H} option (experimental and incomplete) was added.
11826
For C and C++, this option tells @FWEAVE{} to scan @code{#include}
11827
files for @samp{typedef} and/or @samp{class} definitions. @xref{-H_}.
11828
11829
@item
11830
The @samp{-k} option was added. This tells @sc{Fortran} and @sc{Ratfor}
11831
to understand the lower-case forms of I/O keywords such as
11832
@samp{iostat} (with the exception of @samp{read}, @samp{write}, and
11833
@samp{end}). @xref{-k}.
11834
11835
@item
11836
The @samp{-n:} option was added. This tells @sc{Fortran} to place
11837
statement labels on a separate line, which is useful when the labels are
11838
relatively long. (By default, @sc{Fortran} labels are placed on the
11839
same line as the thing they are labeling, which looks good for short
11840
labels.) @xref{-ncolon}
11841
11842
@item
11843
The preprocessor command @samp{@@#line} was added. For C code, this
11844
adds an explicit @samp{#line} command to the tangled output file. This
11845
helps to keep the line numbers between debugger and source file in sync
11846
when an @FWEB{} preprocessor statement expands to several lines.
11847
@xref{Debugging with macros}.
11848
11849
An implicit @samp{@@#line} command is added after each @samp{@@%}
11850
(@pxref{AT%}) that begins a line (this keeps line numbering correct).
11851
To override this, use the option @samp{-T#}. @xref{-T#}.
11852
11853
@item
11854
@samp{-p} (style-file) options (@pxref{-p}) on the command line are now
11855
processed @emph{after} the local style file. @xref{Style}.
11856
11857
@item
11858
The functionality of the @samp{-D} command was enhanced to include
11859
optional arguments that limit the information that will be listed. @xref{-D_}.
11860
11861
@end enumerate
11862
@end quotation
11863
11864
@node V1.52, V1.50, V1.53, New features
11865
@comment node-name, next, previous, up
11866
11867
@section Version 1.52
11868
11869
@cindex Features, version 1.52
11870
This release was issued only as a beta version. It consists mostly of
11871
bug fixes. However, there are a few other interesting points.
11872
11873
@quotation
11874
@enumerate
11875
@item
11876
@code{fwebmac.sty} was enhanced to warn the user to run La@TeX{} again
11877
when the section numbering hasn't yet been brought up to date. I'm not
11878
sure I've covered all the bases, but before it didn't complain at all.
11879
11880
@item
11881
C++ classes are now formatted (identified as reserved words) on the first
11882
pass, so forward references such as
11883
11884
@example
11885
@@ The class |C|...
11886
@@a
11887
class C
11888
@{@}
11889
@end example
11890
@noindent
11891
will now work. Note that @b{typedef} has done this for a while, although
11892
there are still a few glitches.
11893
11894
@item
11895
For two years, the documentation has described two control codes as
11896
follows:
11897
11898
@example
11899
@@~ --- inhibit line break.
11900
@@+ --- force an index entry.
11901
@end example
11902
@noindent
11903
Apparently the code had these definitions inverted; it has now been brought
11904
up to date with the documentation. Fortunately these commands are
11905
evidently not heavily used, since no one complained.
11906
11907
@item
11908
@code{fwebmac.sty} was further reworked to interact properly with the
11909
user package @code{multicol}. If in @code{fweb.sty} one says
11910
@samp{LaTeX.package "multicol"}, then the two-column index is done with
11911
@code{multicol}; this gives various improvements over the
11912
@code{\twocolumn} format that was used previously. Furthermore, it's
11913
possible to use @samp{multicol} to do one's entire document in
11914
two-column format. This turned out to be relatively simple, but one
11915
needs to get the commands in the proper order. See @ref{LIndex} for more
11916
details. Two-column format substantially cuts down the white space; I
11917
saved about 50% on a 200-page code.
11918
11919
One known glitch with @FWEB{}/@code{multicol} is that if one selects
11920
page-number cross-references instead of La@TeX{} section numbers, page
11921
references such as 98c don't get the 'c' correct. This is presumably not a big
11922
deal. At this point, assume that the use of @code{multicol} is highly
11923
experimental.
11924
11925
@item
11926
Further bugs in the C and C++ production rules were fixed.
11927
11928
@end enumerate
11929
@end quotation
11930
11931
@node V1.50, V1.40, V1.52, New features
11932
@comment node-name, next, previous, up
11933
11934
@section Version 1.50
11935
11936
@cindex Features, version 1.50
11937
@quotation
11938
@enumerate
11939
@item
11940
The syntax for entries in the initialization file @file{.fweb}
11941
(@pxref{Initialization}) has been
11942
modified (in a way that is as backward-compatible as possible).
11943
Previously, @samp{+} meant process the option before the command-line
11944
options, @samp{-} meant process it after. This convention was somewhat
11945
hard to remember, given the statement that any command-line option could
11946
be put into @file{.fweb}; furthermore, just about everything in
11947
@file{.fweb} should, in fact, be processed before the command-line
11948
options. So now both @samp{+} and @samp{-} mean the same thing, namely
11949
process before (and the @samp{+} notation should fade away as time goes
11950
on). If you explicitly want something to be processed after
11951
all command-line options for some tricky reason, begin it with @samp{&}.
11952
I.e., scan your @samp{.fweb} file for any line beginning with @samp{-}
11953
and replace that with @samp{&}.
11954
11955
@item
11956
The La@TeX{} processor (@samp{-PL}) is now the default.
11957
11958
@item
11959
The experimental @file{fwebmacL.sty} macro package supplied with version
11960
1.40 has been substantially reworked and is now the default
11961
@file{fwebmac.sty}. Remove any reference to @file{fwebmacL.sty} from
11962
your @file{.fweb} file.
11963
11964
@item
11965
Support for La@TeX{}2e is now provided. @xref{LaTeX}.
11966
11967
@item
11968
The style-file parameter @code{index.name} was added. This is the
11969
section name to be given to the Index (@pxref{Index}), which should be
11970
the last major (starred) section. It becomes the contents of the macro
11971
@code{\INDEX}. Therefore, one can end one's source file by saying
11972
11973
@example
11974
@@* \INDEX.
11975
@end example
11976
11977
@item
11978
The @samp{$IF...} class of built-in functions was reworked. They should
11979
now be more robust, recursive, and intuitive. Simple uses of these
11980
functions should work as before. However, complicated uses that
11981
depended on tricky things about the order of expansion of arguments may
11982
require revision. Carefully compare the descriptions of these functions
11983
in the documentation (e.g., see @ref{$IF}) with your usage of them in
11984
any pre-existing code.
11985
11986
In some cases, if a previous constructions using @code{$IF} no longer works, it
11987
might work if you say
11988
11989
@example
11990
@@m $IF(a,b,c) $$IF(a,b,c)
11991
@end example
11992
@noindent
11993
and then use @code{$$IF} in your code. (This forces an extra level of macro
11994
expansion.) The same remark goes for @code{$DEFINE}.
11995
11996
The old forms @samp{_IF} etc. no longer work; convert to @samp{$IF}.
11997
11998
@item
11999
The option @samp{-j} was added. This inhibits multiple inclusions via
12000
@samp{@@i} of the same include file.
12001
@xref{-j}.
12002
12003
@item
12004
One now has the ability to change the comment character that begins
12005
@FTANGLE{}'s @samp{line} command. In the style file, say, e.g.,
12006
12007
@example
12008
line_char.N '#'
12009
@end example
12010
12011
@noindent
12012
to change the default @samp{*line} output by @FTANGLE{} in @sc{Fortran}
12013
mode to @samp{#line}. This could be useful if one runs the C
12014
preprocessor on the tangled @sc{Fortran} output.
12015
12016
@item
12017
@FWEAVE{}'s processing of @b{typedef} statements in C and C++ was
12018
improved.
12019
12020
@item
12021
@FWEB{} should now be able to process C++ templates and exception handling,
12022
at least in simple situations. The typesetting of C++ references (e.g.,
12023
@samp{int&}) was also improved. Please report any difficulties.
12024
12025
@item
12026
There were various miscellaneous obscure bug fixes.
12027
12028
@end enumerate
12029
@end quotation
12030
12031
@node V1.40, , V1.50, New features
12032
@comment node-name, next, previous, up@section Version 1.40
12033
12034
@section Version 1.40
12035
12036
@cindex Features, version 1.40
12037
@quotation
12038
@enumerate
12039
@item
12040
@emph{The meaning of @samp{@@+} has changed.} (SORRY!) Formerly, this
12041
inhibited a line break; that function is now performed by @samp{@@~}.
12042
The new meaning of @samp{@@+} is to force an index entry (the opposite
12043
of @samp{@@-}, which inhibits an index entry).
12044
12045
If you have large codes using the old @samp{@@+} that you do not wish to
12046
convert, you can recover the old mappings by placing the following
12047
commands into @file{fweb.sty}:
12048
12049
@example
12050
yes_index = "~"
12051
no_line_break = "+"
12052
@end example
12053
12054
@noindent
12055
However, please try to make the
12056
conversion; the new codes are intended to be more symmetrical and easier
12057
to remember.
12058
12059
@item
12060
@emph{Built-in functions now begin with @samp{$}, not @samp{_}.} The
12061
underscore prefix was a bad design decision; it introduces conflicts
12062
with ANSI C in certain circumstances. To ease conversion, the old forms
12063
are still understood. Thus, one can use @samp{$EVAL} and @samp{_EVAL}
12064
interchangably. However, @emph{do not use} the underscore forms; they
12065
will be deleted in future releases.
12066
12067
@item
12068
@emph{Full La@TeX{} support.} @FWEB{} no longer usurps La@TeX{}'s
12069
@code{\output} routine, and La@TeX{}'s sectioning commands,
12070
Table-of-Contents commands, etc. are used. The appearance of the woven
12071
output is changed to be more book-like. (This is an experiment.)
12072
12073
@item
12074
@emph{Verbatim language.} @samp{@@Lv} selects a language-independent format.
12075
@xref{Verbatim}
12076
12077
@item
12078
@emph{Language-independent mode.} The N mode inhibits pretty-printing,
12079
blank compression, etc.; source code is essentially copied literally
12080
from input to output. This mode is turned on automatically by the
12081
@sc{verbatim} language, but it can also be used with the other languages. It
12082
is turned on by the command-line option @samp{-N} or the local command
12083
@samp{@@N}. @xref{ATN_}.
12084
12085
@item
12086
@emph{Writing of temporary files.} When the @samp{-F} command-line option is
12087
in effect, tangled output is written to temporary files instead of the
12088
final target files, and the temporary files are compared to the last
12089
version of the target files on disk. If there is no change, the target
12090
files are not updated. This avoid unnecessary recompilation if only the
12091
documentation, not the code, was changed. @xref{-F_}.
12092
12093
@item
12094
@emph{Converting output tokens to lower case.} @xref{-U_}.
12095
12096
@item
12097
@emph{The built-in functions @samp{$E} and @samp{$PI}.} @xref{$E},
12098
@ref{$PI}.
12099
12100
@item
12101
@emph{The built-in functions @samp{$EXP}, @samp{$LOG}, and
12102
@samp{$LOG10}.} @xref{$EXP}, @ref{$LOG}, and @ref{$LOG10}.
12103
12104
@item
12105
@emph{@samp{$MAX} and @samp{$MIN} generalized to take arbitrary list of
12106
arguments.} @xref{$MAX}, @ref{$MIN}.
12107
12108
@item
12109
@emph{The marriage-saver option}. In response to a serious user
12110
request, see @ref{-B_}.
12111
12112
@end enumerate
12113
@end quotation
12114
12115
@node Support, Installing, New features, Top
12116
@comment node-name, next, previous, up
12117
12118
@chapter SUPPORT
12119
12120
@cindex Support
12121
@cindex Bugs
12122
@FWEB{} is supported by John Krommes, @email{krommes@@princeton.edu}.
12123
This project is a definitively @emph{spare-time activity}!!! Bug
12124
reports submitted with very short test files will be verified, although
12125
not necessarily in real time. For very simple fixes, a change file may
12126
be provided. Generally, however, bugs are not fixed until the next
12127
release. Releases occur intermittently, depending on my many other
12128
professional obligations.
12129
12130
Suggestions are very welcome. Many of @FWEB{}'s current features were
12131
incorporated in response to users' requests. However, the queue for
12132
future improvements is long; nothing may happen immediately. The next
12133
major release of @FWEB{}, Version 2.00, is planned for approximately the
12134
year 2000. (You may be relieved to know that, to the best of my
12135
knowledge, @FWEB{} does not suffer from the Y2K bug.)
12136
12137
This info documentation is now accessible on the World-Wide Web from
12138
12139
@quotation
12140
@url{http://w3.pppl.gov/~krommes/fweb_toc.html}.
12141
@end quotation
12142
12143
You can subscribe to one or both of two @FWEB{} mailing lists,
12144
@code{fweb-users} and @code{fweb-installers}. To subscribe, send e-mail
12145
to @email{majordomo@@pppl.gov}. In the @emph{body} of the message, say, e.g.,
12146
12147
@quotation
12148
@code{subscribe fweb-users}
12149
@end quotation
12150
@noindent
12151
You will receive introductory information describing how these lists are
12152
intended to be used. To unsubscribe at any time, substitute
12153
@code{unsubscribe} for @code{subscribe} in the above instructions.
12154
12155
Archive files containing the messages sent to the @FWEB{} mailing
12156
lists are kept in
12157
12158
@quotation
12159
@code{ftp.pppl.gov:/pub/fweb/archive/fweb-@{users,installers@}.archive}.
12160
@end quotation
12161
@noindent
12162
In addition to anonymous @code{ftp}, these files may be obtained by
12163
sending a message to @code{majordomo@@pppl.gov} of the form
12164
12165
@quotation
12166
@code{get fweb-users fweb-users.archive}.
12167
@end quotation
12168
12169
@node Installing, Concept index, Support, Top
12170
@comment node-name, next, previous, up
12171
12172
@appendix Installing @FWEB{}
12173
12174
Here is the bare-bones installation procedure for @sc{unix} users:
12175
12176
@cindex Installing @FWEB
12177
@enumerate
12178
@item
12179
Download the @code{zgip}-compressed @code{tar} file from
12180
@code{ftp.pppl.gov:/pub/fweb}.
12181
The name of the file contains the version number---e.g.,
12182
@file{fweb-1.61.tar.gz}.
12183
12184
@example
12185
ftp ftp.pppl.gov
12186
bin
12187
get fweb-1.61.tar.gz
12188
quit
12189
@end example
12190
12191
@item
12192
Uncompress and unpack the tar file:
12193
12194
@example
12195
gunzip fweb-1.61.tar.gz
12196
tar -xf fweb-1.61.tar
12197
@end example
12198
@noindent
12199
If the GNU @code{tar} is installed, these two steps can be combined into
12200
12201
@example
12202
gtar -xzf fweb-1.61.tar.gz
12203
@end example
12204
12205
Unpacking creates the directory @file{fweb-1.61}, with at least the two
12206
subdirectories @file{Web} and @file{Manual}.
12207
12208
@item
12209
Change to the new @file{Web} subdirectory and run the configuration script.
12210
12211
@example
12212
cd fweb-1.61/Web
12213
./configure
12214
@end example
12215
12216
@file{./configure} is an @code{sh} script. It attempts to figure out
12217
various local system features automatically, then generates the three
12218
files @file{defaults.mk}, @file{config.h}, and @file{custom.h}; those
12219
are used in the @code{make}. For further information about the
12220
operation of @file{./configure}, see @file{fweb-1.61/READ_ME.FWEB}.
12221
12222
@item
12223
Make and install the release:
12224
12225
@example
12226
make @i{[}CFLAGS='@i{special compiler flags}'@i{]}
12227
make install
12228
@end example
12229
12230
If @code{gcc} is available, it will be used in the @code{make}; in that
12231
case, the default @code{CFLAGS} should be sufficient. If another
12232
compiler is used, ensure that it is run in ANSI-compatible mode, not the
12233
old-style Kernighan and Ritchie.
12234
12235
@FWEB{} compiles on my system without any warnings with
12236
@w{@samp{gcc -ansi -pedantic}}. Please report any compiler warnings
12237
from an allegedly ANSI-C environment.
12238
12239
@end enumerate
12240
12241
@node Concept index, Option and command index, Installing, Top
12242
@comment node-name, next, previous, up
12243
12244
@unnumbered Concept index
12245
12246
@printindex cp
12247
12248
@node Option and command index, Parameter index, Concept index, Top
12249
12250
@unnumbered Option and command index
12251
12252
@printindex fn
12253
12254
@node Parameter index, , Option and command index, Top
12255
@comment node-name, next, previous, up
12256
12257
@unnumbered Parameter index
12258
12259
@printindex vr
12260
12261
@shortcontents
12262
@contents
12263
12264
@bye
Loggerhead is a web-based interface for Breezy
Version: 2.0.1