home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 22 gnu / 22-gnu.zip / fweb140x.zip / fweb.info-4 (.txt) < prev    next >
GNU Info File  |  1996-02-27  |  31KB  |  582 lines
  1. This is Info file fweb.info, produced by Makeinfo-1.55 from the input
  2. file fweb.texinfo.
  3.    This file documents FWEB...
  4.    Copyright 1993 John A. Krommes
  5.    Permission is granted to make and distribute verbatim      copies of
  6. this manual provided the copyright notice and      this permission
  7. notice are preserved on all copies.
  8.    Permission is granted to process this file through TeX      and
  9. print the results, provided the printed document      carries a copying
  10. permission notice identical to this      one except for the removal of
  11. this paragraph (this      paragraph not being relevant to the printed
  12. manual).
  13.    Permission is granted to copy and distribute modified      versions
  14. of this manual under the conditions for      verbatim copying, provided
  15. also that the section      entitled "Copying" is included exactly as in
  16. the original, and provided      that the entire resulting derived work
  17. is distributed      under the terms of a permission notice identical to
  18. this      one.
  19.    Permission is granted to copy and distribute      translations of
  20. this manual into another language,      under the above conditions for
  21. modified versions,      except that this permission notice may be
  22. stated in a      translation approved by the author.
  23. File: fweb.info,  Node: Environment variables,  Next: Initialization,  Prev: Customization,  Up: Customization
  24. Environment variables
  25. =====================
  26.    `FWEB_INCLUDES' -- Colon-delimited list of directories to search for
  27. include files.  (One can append to this list by means of the `-I'
  28. option; see *Note -I_::.)
  29.    `FWEB_INI' -- Name of the initialization file. If not defined, either
  30. `.fweb' or `fweb.ini' is chosen, depending on the machine.  The
  31. initialization file always resides in `$HOME'.
  32.    `FWEB_STYLE_DIR' -- Directory in which style file resides.  If not
  33. defined, the current directory is used.
  34. File: fweb.info,  Node: Initialization,  Next: Memory allocation,  Prev: Environment variables,  Up: Customization
  35. Initialization
  36. ==============
  37. The initialization file
  38. -----------------------
  39.    On startup, FWEB attempts to read an initialization file.  This
  40. always resides in the user's HOME directory.  It is usually called
  41. `.fweb' (`fweb.ini' on personal computers).  The default file name can
  42. be overridden by the environment variable `FWEB_INI'.
  43.    One may put into `.fweb' any option that might be used as a
  44. command-line option.  (Presently, there must be just one entry per
  45. line.)  If the option begins with a `+', it is processed before the
  46. actual command-line options; otherwise, it is processed after.
  47. Generally, `.fweb' options should begin with `+' so that one may
  48. override them from the command line.
  49. File: fweb.info,  Node: Memory allocation,  Next: Style,  Prev: Initialization,  Up: Customization
  50. Memory allocation
  51. -----------------
  52.    The command-line option `-y' (*note -y::.) is used to change the
  53. default allocation for a dynamic array.  The arrays have a one- or
  54. two-character abbreviation denoted by aa.  Some error messages will use
  55. this abbreviation when suggesting that you increase a default
  56. allocation.  To query the present allocations of variable aa, just say
  57. `-y'aa.  To query everything, say `-y'.
  58.    (The detailed explanations for these arrays aren't here yet.  The
  59. on-line info has a terse list.)
  60. * Menu:
  61. * -yb::         Maximum bytes for identifiers, index entries, and module names.
  62. * -ybs::        Size of the change buffer.
  63. * -ycb::        Size of line buffer for C output.
  64. * -ycf::        A Ratfor buffer.
  65. * -ycg::        Another Ratfor buffer.
  66. * -yd::         Increment for expanding the dots table.
  67. * -ydt::        Maximum number of deferred macro tokens.
  68. * -ydx::        Maximum Number of deferred macro texts.
  69. * -ykt::        Stack size for FTANGLE.
  70. * -ykw::        Stack size for FWEAVE.
  71. * -yll::        Line length for FWEAVE's output.
  72. * -yln::        Maximum length of module names or strings.
  73. * -ylb::        Maximum number of nested loops in Ratfor.
  74. * -ylx::        Maximum length of expressions that can be expanded with
  75.                         the post-increment operators of Fortran or Ratfor.
  76. * -ym::         Maximum number of sections.
  77. * -yma::        Maximum number of arguments to WEB macros.
  78. * -ymb::        Size of the buffer for expanding WEB macros.
  79. * -yn::         Maximum number of identifiers, strings, and module names.
  80. * -ynf::        Maximum number of open input files.
  81. * -yop::        Maximum number of entries in the table for operator
  82.                         overloading.
  83. * -yr::         Maximum number of cross-references.
  84. * -ys::         Maximum number of scraps.
  85. * -ysb::        Size of style-file buffer.
  86. * -ytt::        Maximum number of tokens that FTANGLE can process.
  87. * -ytw::        Maximum number of tokens in the current section being
  88.                         processed by FWEAVE.
  89. * -yx::         Maximum number of texts.
  90. * -yxb::        Size of line buffer for TeX output.
  91. File: fweb.info,  Node: -yb,  Next: -ybs,  Prev: Memory allocation,  Up: Memory allocation
  92. File: fweb.info,  Node: -ybs,  Next: -ycb,  Prev: -yb,  Up: Memory allocation
  93. File: fweb.info,  Node: -ycb,  Next: -ycf,  Prev: -ybs,  Up: Memory allocation
  94. File: fweb.info,  Node: -ycf,  Next: -ycg,  Prev: -ycb,  Up: Memory allocation
  95. File: fweb.info,  Node: -ycg,  Next: -yd,  Prev: -ycf,  Up: Memory allocation
  96. File: fweb.info,  Node: -yd,  Next: -ydt,  Prev: -ycg,  Up: Memory allocation
  97. File: fweb.info,  Node: -ydt,  Next: -ydx,  Prev: -yd,  Up: Memory allocation
  98. File: fweb.info,  Node: -ydx,  Next: -ykt,  Prev: -ydt,  Up: Memory allocation
  99. File: fweb.info,  Node: -ykt,  Next: -ykw,  Prev: -ydx,  Up: Memory allocation
  100. File: fweb.info,  Node: -ykw,  Next: -yll,  Prev: -ykt,  Up: Memory allocation
  101. File: fweb.info,  Node: -yll,  Next: -yln,  Prev: -ykw,  Up: Memory allocation
  102. File: fweb.info,  Node: -yln,  Next: -ylb,  Prev: -yll,  Up: Memory allocation
  103. File: fweb.info,  Node: -ylb,  Next: -ylx,  Prev: -yln,  Up: Memory allocation
  104. File: fweb.info,  Node: -ylx,  Next: -ym,  Prev: -ylb,  Up: Memory allocation
  105. File: fweb.info,  Node: -ym,  Next: -yma,  Prev: -ylx,  Up: Memory allocation
  106. File: fweb.info,  Node: -yma,  Next: -ymb,  Prev: -ym,  Up: Memory allocation
  107. File: fweb.info,  Node: -ymb,  Next: -yn,  Prev: -yma,  Up: Memory allocation
  108. File: fweb.info,  Node: -yn,  Next: -ynf,  Prev: -ymb,  Up: Memory allocation
  109. File: fweb.info,  Node: -ynf,  Next: -yop,  Prev: -yn,  Up: Memory allocation
  110. File: fweb.info,  Node: -yop,  Next: -yr,  Prev: -ynf,  Up: Memory allocation
  111. File: fweb.info,  Node: -yr,  Next: -ys,  Prev: -yop,  Up: Memory allocation
  112. File: fweb.info,  Node: -ys,  Next: -ysb,  Prev: -yr,  Up: Memory allocation
  113. File: fweb.info,  Node: -ysb,  Next: -ytt,  Prev: -ys,  Up: Memory allocation
  114. File: fweb.info,  Node: -ytt,  Next: -ytw,  Prev: -ysb,  Up: Memory allocation
  115. File: fweb.info,  Node: -ytw,  Next: -yx,  Prev: -ytt,  Up: Memory allocation
  116. File: fweb.info,  Node: -yx,  Next: -yxb,  Prev: -ytw,  Up: Memory allocation
  117. File: fweb.info,  Node: -yxb,  Prev: -yx,  Up: Memory allocation
  118. File: fweb.info,  Node: Style,  Prev: Memory allocation,  Up: Customization
  119. The Style file
  120. ==============
  121.    A style file (default name `fweb.sty') may reside in the user's
  122. current directory (or directory specified by the environment variable
  123. `FWEB_STYLE_DIR').  The default name can be changed by the command-line
  124. option `-z' (*note -z::.).
  125.    The style file is processed after all command-line options have been
  126. processed.  Note that the command-line option `-p' (*note -p::.)
  127. buffers up style-file entries.  Effectively, these are treated as
  128. residing in a temporary file that is read just before the local style
  129. file.  Thus, `-p' options placed in `.fweb' behave as `global'
  130. style-file entries and will be overridden by a matching entry in the
  131. local style file.
  132.    Style-file entries have the form
  133.              keyword [=] value
  134. For example,
  135.              LaTeX.options = "eqalign"
  136. The syntax is completely free-form.
  137.    The descriptions of the parameters aren't completed yet.  Please see
  138. the reference guide.
  139. * Menu:
  140. * Index params::                Customizing the index.
  141. * Module params::               Customizing the list of sections.
  142. * Contents params::             Customizing the table of contents.
  143. * Subscript params::            Customizing subscripting for cross-references.
  144. * Fwebmac params::              Customizing behavior of FWEB's macros.
  145. * Completion params::           Automatic selection of file extensions, etc.
  146. * Control-code mappings::       Remapping FWEB's control codes (danger)!
  147. * Miscellaneous params::        Other customizations.
  148. File: fweb.info,  Node: Index params,  Next: Module params,  Prev: Style,  Up: Style
  149. Customizing FWEAVE's index
  150. --------------------------
  151. * Menu:
  152. * delim_0: S_delim.             Insert after identifier in index entry.
  153. * delim_n: S_delim.             Insert between section numbers in index entry.
  154. * encap.infix: S_encap.         Start the section number.
  155. * encap.prefix: S_encap.        TeX macro to begin a section number.
  156. * encap.suffix: S_encap.        Ends the section number.
  157. * group_skip::
  158. * index.collate: S_index.       Collating sequence for index.
  159. * index.postamble: S_index.     TeX material to end the index.
  160. * index.preamble: S_index.      TeX material to begin the index.
  161. * index.tex: S_index.           Name of file holding index.
  162. * item_0::                      TeX command to begin an index entry.
  163. * language.prefix: S_language.  Begin a language entry in the index.
  164. * language.suffix: S_language.  End a language entry in the index.
  165. * lethead.prefix: S_lethead.    Begin a letter group.
  166. * lethead.suffix: S_lethead.    End a letter group.
  167. * lethead.flag: S_lethead.      Control beginning of letter group.
  168. * underline.prefix: S_underline. Begin an underlined index entry.
  169. * underline.suffix: S_underline. End an underlined index entry.
  170. File: fweb.info,  Node: S_index,  Next: S_delim,  Prev: Index params,  Up: Index params
  171. `index'
  172. .......
  173.    `index.tex' is the name of the file into which the index is written.
  174. The character '#' is translated into the root name of the web file.
  175.    `index.preamble' are TeX commands that begin the index.
  176.    `index.postamble' are TeX commands that end the index.
  177.    `index.collate' specifies the collating sequence for the index.
  178. File: fweb.info,  Node: S_delim,  Next: S_encap,  Prev: S_index,  Up: Index params
  179. `delim'
  180. .......
  181.    `delim_0' is the string to insert after the identifier in an index
  182. entry.
  183.    `delim_n' is the string to insert between two section numbers in an
  184. index entry.
  185. File: fweb.info,  Node: S_encap,  Next: group_skip,  Prev: S_delim,  Up: Index params
  186. File: fweb.info,  Node: group_skip,  Next: item_0,  Prev: S_encap,  Up: Index params
  187. `group_skip'
  188. ............
  189.    `group_skip' is a string of TeX commands to insert between letter
  190. groups.
  191. File: fweb.info,  Node: item_0,  Next: S_language,  Prev: group_skip,  Up: Index params
  192. `item_0'
  193. ........
  194.    `item_0' is the TeX command to begin an index entry.
  195. File: fweb.info,  Node: S_language,  Next: S_lethead,  Prev: item_0,  Up: Index params
  196. `language'
  197. ..........
  198.    `language.prefix' begins a language entry.; `language.suffix' ends
  199. File: fweb.info,  Node: S_lethead,  Next: S_underline,  Prev: S_language,  Up: Index params
  200. `lethead'
  201. .........
  202.    `lethead.prefix' begins a letter group; `lethead.suffix' ends one.
  203. The flag `lethead.flag' controls the format of the letter group: if it
  204. is zero, nothing is inserted; if it is positive, an upper-case letter
  205. is inserted; if it is negative, a lower-case letter is inserted.
  206. File: fweb.info,  Node: S_underline,  Prev: S_lethead,  Up: Index params
  207. `underline'
  208. ...........
  209.    `underline.prefix' is the TeX command to begin an underlined index
  210. entry.
  211.    `underline.suffix' is the TeX command to end an underlined index
  212. entry.
  213. File: fweb.info,  Node: Module params,  Next: Contents params,  Prev: Index params,  Up: Style
  214. Customizing the module list
  215. ---------------------------
  216. * Menu:
  217. * modules.info: S_modules.
  218. * modules.postamble: S_modules. TeX commands to end module list.
  219. * modules.preamble: S_modules.  TeX commands to begin module list.
  220. * modules.tex: S_modules.       Name of file containing list of modules.
  221. File: fweb.info,  Node: S_modules,  Prev: Module params,  Up: Module params
  222.    `modules.tex' is the name of the file into which the module names
  223. are written.
  224.    `modules.preamble' is a string of TeX commands to begin the list of
  225. modules.
  226.    `modules.postamble' is a string of TeX commands to end the list of
  227. modules.
  228.    `modules.info' is the name of the TeX macro that formats the command
  229. line and related information.
  230. File: fweb.info,  Node: Contents params,  Next: Subscript params,  Prev: Module params,  Up: Style
  231. Customizing the table of contents
  232. ---------------------------------
  233. * Menu:
  234. * contents.postamble: S_contents. TeX commands to end table of contents.
  235. * contents.preamble: S_contents.  TeX commands to begin table of contents.
  236. * contents.tex: S_contents.       Name of contents file.
  237. File: fweb.info,  Node: S_contents,  Prev: Contents params,  Up: Contents params
  238.    `contents.tex' is the name of the file into which the table of
  239. contents is written.
  240.    `contents.preamble' is the TeX string that begins printing the table
  241. of contents.
  242.    `contents.postamble' is the TeX string that ends the table of
  243. contents.
  244. File: fweb.info,  Node: Subscript params,  Next: Fwebmac params,  Prev: Contents params,  Up: Style
  245. Customizing cross-reference subscripts
  246. --------------------------------------
  247.    When FWEAVE pretty-prints code, it can attach cross-reference
  248. subscripts to various kinds of identifiers.  The following flags select
  249. which identifiers are so subscripted.
  250. * Menu:
  251. * mark_defined.generic_name: S_mark_defined.
  252. * mark_defined.fcn_name: S_mark_defined.
  253. * mark_defined.WEB_macro: S_mark_defined.
  254. * mark_defined.outer_macro: S_mark_defined.
  255. * mark_defined.exp_type: S_mark_defined.
  256. * mark_defined.typedef_name: S_mark_defined.
  257. File: fweb.info,  Node: S_mark_defined,  Prev: Subscript params,  Up: Subscript params
  258. File: fweb.info,  Node: Fwebmac params,  Next: Completion params,  Prev: Subscript params,  Up: Style
  259. Customizing the behavior of `fwebmac.sty' macros
  260. ------------------------------------------------
  261.    To some extent, the behavior of FWEB's macro package `fwebmac.sty'
  262. can be changed by means of the following parameters, instead of
  263. actually editing `fwebmac.web' itself.
  264. * Menu:
  265. * format.reserved: S_format.
  266. * format.short_identifier: S_format.
  267. * format.outer_macro: S_format.
  268. * format.WEB_macro: S_format.
  269. * format.intrinsic: S_format.
  270. * format.keyword: S_format.
  271. * format.typewriter: S_format.
  272. * format.wildcard: S_format.
  273. * indent.TeX: S_indent.         Paragraph indentation for TeX part.
  274. * indent.code: S_indent.        Paragraph indentation for code part.
  275. * LaTeX.options: S_LaTeX.       Set options for document style.
  276. * LaTeX.style: S_LaTeX.         Specify document style.
  277. File: fweb.info,  Node: S_format,  Next: S_indent,  Prev: Fwebmac params,  Up: Fwebmac params
  278. `format'
  279. ........
  280.    The `format' fields specify the macro to use to pretty-print various
  281. kinds of identifiers, as follows: (not finished).
  282. File: fweb.info,  Node: S_indent,  Next: S_LaTeX,  Prev: S_format,  Up: Fwebmac params
  283. `indent'
  284. ........
  285.    `indent.TeX' specifies paragraph indentation for the TeX part.
  286.    `indent.code' specifies similar indentation for the code part.
  287. File: fweb.info,  Node: S_LaTeX,  Prev: S_indent,  Up: Fwebmac params
  288.    When running under LaTeX, the documents is (effectively) begun by the
  289. command `\documentstyle[options]{style}'.  The options field can be
  290. specified by `LaTeX.options'; the style field by `LaTeX.style'.
  291. File: fweb.info,  Node: Control-code mappings,  Next: Miscellaneous params,  Prev: Completion params,  Up: Style
  292.    (To be finished.)
  293. File: fweb.info,  Node: Miscellaneous params,  Prev: Control-code mappings,  Up: Style
  294. Miscellaneous style-file parameters
  295. -----------------------------------
  296. * Menu:
  297. For FTANGLE:
  298. * ASCII_fcn::                   Routine for converting strings to ASCII.
  299. * cchar::                       Continuation character for Fortran.
  300. * cdir_start::                  `?' translates to this.
  301. * line_length: S_line_length.
  302. * meta.top: S_meta_t.           Material to precede tangled meta-comment.
  303. * meta.prefix: S_meta_t.        Begins each line of meta-comment.
  304. * meta.bottom: S_meta_t.        Material that follows the meta-comment.
  305. * outer.def: S_outer.           FTANGLE converts `@d' to this.
  306. * outer.undef: S_outer.         FTANGLE converts `@u' to this.
  307. * protect::                     Protection character to end a continued line.
  308. * suffix::                      Suffixes for output files.
  309. For FWEAVE:
  310. * macros::                      Default name of the macro package to be
  311.                                         read in by FWEAVE.
  312. * limbo::                       Default material to begin the limbo part
  313. * meta.code.begin: S_meta_w.
  314. * meta.code.end: S_meta_w.
  315. * meta.TeX.begin: S_meta_w.     TeX material to begin FWEAVE's
  316.                                                 output of a meta-comment.
  317. * meta.TeX.end: S_meta_w.       As above, but end the meta-comment.
  318. * preamble.named: S_preamble.   TeX material to begin named section.
  319. * preamble.unnamed: S_preamble. TeX material to begin unnamed section.
  320. For both processors:
  321. * dot_constant.begin: S_dot_constant.   Beginning character for dot constant.
  322. * dot_constant.end: S_dot_constant.     Ending character for dot constant.
  323. * null_file::                   Name of the null file.
  324. File: fweb.info,  Node: ASCII_fcn,  Next: cchar,  Prev: Miscellaneous params,  Up: Miscellaneous params
  325. `ASCII_Fcn'
  326. ...........
  327.    *Note AT"::.
  328. File: fweb.info,  Node: cchar,  Next: cdir_start,  Prev: ASCII_fcn,  Up: Miscellaneous params
  329. `cchar'
  330. .......
  331.    Continuation character for Fortran code output.
  332. File: fweb.info,  Node: cdir_start,  Next: S_line_length,  Prev: cchar,  Up: Miscellaneous params
  333. `cdir_start'
  334. ............
  335.    This parameter has the form `cdir_start.l', where l is one of `C',
  336. `Cpp', `N', `N90', `R', `R90', `X', or `V'.  The contents of this
  337. parameter is written immediately after the `@?' that begins a compiler
  338. directive.
  339. File: fweb.info,  Node: S_line_length,  Next: S_meta_t,  Prev: cdir_start,  Up: Miscellaneous params
  340. File: fweb.info,  Node: S_meta_t,  Next: S_outer,  Prev: S_line_length,  Up: Miscellaneous params
  341. `meta' (FTANGLE)
  342. ................
  343.    `meta.top.l' specifies text that precedes material enclosed by
  344. `@(...@)'.
  345.    `meta.prefix.l' begins each line of the meta-comment.
  346.    `meta.bottom.l' specifies text that follows the meta-comment.
  347. File: fweb.info,  Node: S_outer,  Next: protect,  Prev: S_meta_t,  Up: Miscellaneous params
  348. `outer'
  349. .......
  350.    FTANGLE converts `@d' to `outer.def', and `@u' to `outer.undef'.
  351. File: fweb.info,  Node: protect,  Next: suffix,  Prev: S_outer,  Up: Miscellaneous params
  352. `protect'
  353. .........
  354.    The strings `protect.l' specify the protection character(s) to end a
  355. continued line.
  356. File: fweb.info,  Node: suffix,  Next: macros,  Prev: protect,  Up: Miscellaneous params
  357. `suffix'
  358. ........
  359.    The extension for the files output by FTANGLE is specified by
  360. `suffix.l'.
  361. File: fweb.info,  Node: macros,  Next: limbo,  Prev: suffix,  Up: Miscellaneous params
  362. `macros'
  363. ........
  364.    The default name of the macro package to be read in.  (This can be
  365. overridden by the command-line option `-w'; see *Note -w::.)
  366. File: fweb.info,  Node: limbo,  Next: S_meta_w,  Prev: macros,  Up: Miscellaneous params
  367. `limbo'
  368. .......
  369.    TeX material to be printed at the beginning of the limbo part, just
  370. before the text from `@l' commands.  *Note ATl::.
  371. File: fweb.info,  Node: S_meta_w,  Next: S_preamble,  Prev: limbo,  Up: Miscellaneous params
  372. `meta' (FWEAVE)
  373. ...............
  374. File: fweb.info,  Node: S_preamble,  Next: S_dot_constant,  Prev: S_meta_w,  Up: Miscellaneous params
  375. `preamble'
  376. ..........
  377.    Additional TeX material can be inserted at the beginning of a named
  378. section with `preamble.named' and at the beginning of an unnamed one
  379. with `preamble.unnamed'.
  380. File: fweb.info,  Node: S_dot_constant,  Next: null_file,  Prev: S_preamble,  Up: Miscellaneous params
  381. `dot_constant'
  382. ..............
  383.    In Fortran, `dot' constants such as `.LT.' are begun and ended by
  384. periods.  In special circumstances, the beginning and ending characters
  385. may be modified by `dot_constant.begin.l' and `dot_constant.end.l'.
  386. File: fweb.info,  Node: null_file,  Prev: S_dot_constant,  Up: Miscellaneous params
  387. `null_file'
  388. ...........
  389.    The name of the null file.  For more discussion, see *Note Change
  390. files::.
  391. File: fweb.info,  Node: Completion params,  Next: Control-code mappings,  Prev: Fwebmac params,  Up: Style
  392. Automatic file name completion:
  393. -------------------------------
  394. * Menu:
  395. * ext.web: S_ext.        Extensions for the web file.
  396. * ext.change: S_ext.     Extensions for the change file.
  397. * ext.hweb: S_ext.       Extensions for include files.
  398. * ext.hchange: S_ext.    Extensions for change files associated with
  399.                                 include files.
  400. File: fweb.info,  Node: S_ext,  Prev: Completion params,  Up: Completion params
  401.    For more information, see *Note -e::.
  402. File: fweb.info,  Node: Hints,  Next: New features,  Prev: Customization,  Up: Top
  403. USAGE TIPS and SUGGESTIONS
  404. **************************
  405.    In this section we collect various tips and suggestions to help one
  406. make full use of FWEB.  *(There's more to come here!)*
  407. Converting an existing code to FWEB
  408. ===================================
  409.    In summary, to convert an existing code to FWEB, you should do the
  410. following. (The following simple procedure assumes that you put all the
  411. subroutines into the unnamed module. However, other more elaborate
  412. schemes are possible.)
  413.   1. Place invisible commentary about the author, version, etc. at the
  414.      beginning of the source file by bracketing it with `@z...@x'.  The
  415.      `@z' must be the first two characters of the file.
  416.   2. Next, set the language by including a command such as `@n'.
  417.   3. Place an `@a' command before each program unit (e.g., main
  418.      program, subroutine, or function).
  419.   4. Before each `@a', place an `@*' or `@ ' command, followed by TeX
  420.      documentation about that particular section of code.
  421.   5. If you have program units longer than about twelve lines, either
  422.      make them function calls, if you can afford the overhead and can
  423.      impart sufficient information via the function name, or break them
  424.      up into shorter fragments by using named modules. Insert the
  425.      command `@<Name of module@>' in place of the fragment you're
  426.      replacing, then put that fragment somewhere else, prefaced by `@ '
  427.      and `@<Name of module@>='.
  428.   6. Make sure your comments are valid TeX. (You can't have things like
  429.      raw underscores or dollar signs in comments, since those cause TeX
  430.      to take special actions.)
  431.   7. Beautify and clarify your documentation by using code mode
  432.      (enclosing stuff between vertical bars) liberally within your TeX.
  433.   8. After you've seen the woven output, you may need to go back and
  434.      format a few identifiers or section names so that FWEAVE
  435.      understands them properly, or you may need to insert some
  436.      pseudo-semicolons (`@;'), pseudo-expressions (`@i'), or
  437.      pseudo-colons (`@:').
  438.   9. Consider using the built-in macro preprocessor to make your code
  439.      more readable--for example, replace raw numerical constants by
  440.      symbolic names.
  441.  10. If you are a FORTRAN user,  for ultimate readability consider
  442.      converting to RATFOR. The initial annoyance is getting rid of
  443.      column~6 continuations. With the aid of a good editor, this can be
  444.      done simply. For example, in `emacs' one can replace the regular
  445.      expression [carriage return, five spaces, something not equal to
  446.      space, tab, or 0] with [backslash, carriage return, six spaces]:
  447.           M-x replace-regexp RET
  448.           C-q C-j \.{\ \ \ \ \ }[\^\.\ tab 0]RET
  449.           \\\\ C-q C-j \.{\ \ \ \ \ \ }RET
  450.      Get rid of the keywords such as then or end if in favor of braces.
  451.      Change singly-quoted character strings to doubly-quoted ones.
  452. Programming tips and other suggestions
  453. ======================================
  454.    *This section will be enlarged in the future!*  Meanwhile, please
  455. feel free to contact `krommes@princeton.edu' for help and advice, and to
  456. suggest items to include here.
  457.   1. Periodically check `ftp.pppl.gov:/pub/fweb/READ_ME' for bug
  458.      reports and other news.  Make bug reports!  *Note Support::.
  459.   2. Most options in `.fweb' should begin with `+' so they can be
  460.      overridden by command-line options for the job itself.  *Note
  461.      Initialization::
  462.   3. Put standard command-line options into `.fweb'.  Also put there
  463.      standard style parameters--e.g.,
  464.           +pindex.tex "#.ndx"
  465.           +pmodules.tex "#.mds"
  466.           +pcontents.tex "#.cts"
  467.   4. Learn how to use the style file. *Note Style::.
  468.   5. Use the info options `-@', `-D', `-y', and `-Z' to find out about
  469.      various internal FWEB tables (control codes, reserved words,
  470.      memory allocations, and style-file parameters).  *Note Info
  471.      options::.
  472.   6. Begin all FWEB sources with invisible commentary bracketed by
  473.      `@z...@x'.  *Note ATz::.
  474.   7. Always include an explicit language-setting command in the limbo
  475.      section.  *Note Languages::.
  476.   8. Keep sections quite short.  Knuth suggests a dozen lines.  That's
  477.      quite hard to achieve sometimes, but almost never should a section
  478.      be more than a page long.
  479.   9. It's easy to define macros from the command line to expedite
  480.      conditional preprocessing.  *Note -m::.
  481.  10. Use the preprocessor construction `@#if 0...@#endif' to comment
  482.      out unwanted code.  *Note Preprocessing::.
  483.  11. For logical operations with the preprocessor, use `||', not `|'.
  484.  12. It's conventional to identify the ends of long preprocessor
  485.      constructions as follows:
  486.           @#if A
  487.           .
  488.           .
  489.           @#endif // |A|
  490.  13. To debug an errant WEB macro, use the built-in function `$DUMPDEF'.
  491.      *Note $DUMPDEF::.
  492.  14. Use `@?' for compiler directives.  *Note AT?::.  Use the
  493.      style-file parameters `cdir_start' to specify information that
  494.      will be written out at the beginning of the line.
  495.  15. Stick to the standard FWEB commenting style `/*...*/' or `//...'.
  496.      Don't use alternatives such as FORTRAN's column 1 convention;
  497.      these may not work or may not be supported someday.  *Note
  498.      Comments::.
  499.  16. The meta-comment feature `@(...@)' provides a poor-man's alignment
  500.      feature.  But that's not in the spirit of TeX; learn to use
  501.      `\halign' or the LaTeX alternatives.
  502.  17. In FORTRAN, use `#:0' to declare readable alphabetic statement
  503.      labels.  *Note Macros::
  504.  18. When mixing languages, define the language of a module at the
  505.      highest possible level--e.g., in the unamed module, not after
  506.      `@<...@>='.
  507. File: fweb.info,  Node: New features,  Next: Support,  Prev: Hints,  Up: Top
  508. NEW FEATURES, version 1.40
  509. **************************
  510.   1. *The meaning of `@+' has changed.*  (SORRY!)  Formerly, this
  511.      inhibited a line break; that function is now performed by `@~'.
  512.      The new meaning of `@+' is to force an index entry (the opposite
  513.      of `@-', which inhibits an index entry).
  514.      If you have large codes using the old `@+' that you do not wish to
  515.      convert, you can recover the old mappings by placing the following
  516.      commands into `fweb.sty':
  517.           yes_index = "~"
  518.           no_line_break = "+"
  519.      However, please try to make the conversion; the new codes are
  520.      intended to be more symmetrical and easier to remember.
  521.   2. *Built-in functions now begin with `$', not `_'.*  The underscore
  522.      prefix was a bad design decision; it introduces conflicts with
  523.      ANSI C in certain circumstances.  To ease conversion, the old forms
  524.      are still understood.  Thus, one can use `$EVAL' and `_EVAL'
  525.      interchangably.  However, the underscore forms may be deleted in
  526.      future releases.
  527.   3. *Full LaTeX support.*  FWEB no longer usurps LaTeX's `\output'
  528.      routine, and LaTeX's sectioning commands, table-of-contents
  529.      commands, etc. are used.  The appearance of the woven output is
  530.      changed to be more book-like.  (This is an experiment.)
  531.   4. *Verbatim language.*  `@Lv' selects a language-independent format.
  532.      *Note Verbatim::
  533.   5. *Language-independent mode.*  The N mode inhibits pretty-printing,
  534.      blank compression, etc.; source code is essentially copied
  535.      literally from input to output.  This mode is turned on
  536.      automatically by the VERBATIM language, but it can also be used
  537.      with the other languages.  It is turned on by the command-line
  538.      option `-N' or the local command `@N'. *Note ATN_::.
  539.   6. *Writing of temporary files.*  When the `-F' command-line option is
  540.      in effect, tangled output is written to temporary files instead of
  541.      the final target files, and the temporary files are compared to
  542.      the last version of the target files on disk.  If there is no
  543.      change, the target files are not updated.  This avoid unnecessary
  544.      recompilation if only the documentation, not the code, was
  545.      changed.  *Note -F_::.
  546.   7. *Converting output tokens to lower case.*  *Note -U_::.
  547.   8. *The built-in functions `$E' and `$PI'.*  *Note $E::, *Note $PI::.
  548.   9. *The built-in functions `$EXP', `$LOG', and `$LOG10'.*  *Note
  549.      $EXP::, *Note $LOG::, and *Note $LOG10::.
  550.  10. *`$MAX' and `$MIN' generalized to take arbitrary list of
  551.      arguments.*  *Note $MAX::, *Note $MIN::.
  552.  11. *The marriage-saver option*.  In response to a serious user
  553.      request, see *Note -B_::.
  554. File: fweb.info,  Node: Support,  Next: Index,  Prev: New features,  Up: Top
  555. SUPPORT
  556. *******
  557.    FWEB is supported by John Krommes, `krommes@princeton.edu'.  This
  558. project is a *spare-time activity*!  I try for, but cannot promise,
  559. reasonably quick (one week) response to questions.  Bug reports
  560. submitted with very short test files will be verified.  For very simple
  561. fixes, a change file will be provided.  Generally, however, bugs are not
  562. fixed until the next release.  Releases occur intermittently, depending
  563. on my other professional obligations.
  564.    Suggestions are very welcome.  Many of FWEB's current features were
  565. incorporated in response to users' requests.  However, the queue for
  566. future improvements is long; nothing may happen immediately.
  567.    Marcus Speh moderates an FWEB FAQ.  See `/pub/fweb/faq'.
  568. File: fweb.info,  Node: Index,  Prev: Support,  Up: Top
  569. Index
  570. *****
  571.    The index is obviously not complete; the following are tests.
  572. * Menu:
  573. * Files:                                Files.
  574. * Literate programming:                 Intro.
  575. * Modules:                              Modules.
  576. * Named module:                         Modules.
  577. * Parts:                                Structure.
  578. * Sections:                             Structure.
  579. * tempnam:                              -F_.
  580. * tmpnam:                               -F_.
  581. * Unnamed module:                       Modules.
  582.