
                         FWEB IN QUESTIONS AND ANSWERS
                                       
   @end ifclear [last updated May 1995]
   
   [Send comments to: David A. Coker, coker@astro.sunyit.edu] 
   
   This article contains frequently asked questions and their answers
   concerning the FWEB system of Literate Programming from the LitProg
   mailing list, until July 1994. I have recently taken over this FAQ
   from Marcus Speh. As I have am new to maintaining a FAQ, any
   suggestions would be helpful in this regard. I would especially like
   to thank Marcus Speh for providing me with the texinfo source and
   makefiles for this FAQ.
   
   Most of the answers are taken from the postings, with little
   moderation from my side. The original postings are archived at
   niord.shsu.edu in directory [FILESERV.LITPROG].
   
   Comments, corrections and suggestions from several people were used to
   improve single questions and answers (see section [1][0]
   Acknowledgements). Most notably, John Krommes, FWEB's designer,
   provided a wealth of useful comments. I have dubbed him JAK in some
   places. Inside quotes, my own comments are marked [... -MS]. Sections
   of the FWEB User's Manual are referred to by their section numbers, as
   in ``[M-10.2]'' (see section [2][5] What is the difference between the
   FAQ and the manual?).
   
                        [3]INTRODUCTION AND EDITORIAL
                                       
   
   
[4][1] What is FWEB?

   
   
   For a thorough discussion of the WEB system, I refer to the extensive
   literature, collected in Nelson Beebe's bibliography (at
   ftp.math.utah.edu in directory pub/tex/bib). For pointers, see the
   General FAQ by Dave Thompson.
   
  [5]THE WEB SYSTEM.
  
   
   
   In D.E. Knuth's [author of the original WEB, coauthor of CWEB] own
   words, [M-2.3]
   
   ``The philosophy behind WEB is that an experienced system programmer,
   who wants to provide the best possible documentation of his or her
   software products, needs two things simultaneously: a language like
   TeX for formatting, and a language like C for programming. Neither
   type of language can provide the best documentation by itself; but
   when both are appropriately combined, we obtain a system that is much
   more useful than either language separately.
   
   The structure of a software program may be thought of as a web that is
   made up of many interconnected pieces. To document such a program we
   want to explain each individual part of the web and how it relates to
   its give us an opportunity to explain the local structure of each part
   by making that structure visible, and the programming tools provided
   by languages such as C or Fortran make it possible for us to specify
   the algorithms formally and unambigously. By combining the two, we can
   develop a style of programming that maximizes our ability to perceive
   the structure of a complex piece of software, and at the same time the
   documented programs can be mechanically translated into a working
   software system that matches the documentation.''
   
  [6]FWEB - A MULTILINGUAL WEB VARIANT.
  
   
   
   FWEB which is being supported and upgraded by John Krommes is a
   substantial extension of CWEB, FWEB supports C, C++, Fortran,
   Fortran90, Ratfor, and TeX i.e. writing TeX macros (style files). It
   runs on most platforms: VMS, PC, UNIX, and pretty much anything that
   the GNU C compiler (GCC) is supported for.
   
   JAK [M-1]: 
   
   ``The principal design contributions to this version of WEB are
    1. the concept of a current language, so that one can process code
       written in multiple languages in the same WEB run;
    2. new production rules for Fortran, Ratfor, and TeX (and some rules
       for C;
    3. a C-like built-in macro preprocessor;
    4. the ability to directly translate Ratfor into Fortran.
       
   
   
   In addition, many miscellaneous details have been changed and a
   variety of convenience features has been added.''
   
[7][2] How can I subscribe to LitProg?

   
   
   If you are not yet subscribed to LitProg, but you are interested, send
   a MAIL message to LISTSERV@SHSU.BITNET, or listserv@shsu.edu, or
   LitProg-Request@shsu.edu stating in the text of the MAIL: SUBSCRIBE
   LITPROG your name in quotes. The list itself is unmoderated: messages
   sent to litprog@shsu.edu are automatically distributed to all
   subscribers.
   
[8][3] How can I get the FWEB FAQ?

   
   
   You may obtain the latest version of this FAQ via anonymous FTP from
     * niord.shsu.edu [192.92.115.8] in directory [FILESERV.FWEB-FAQ],
     * ftp.pppl.gov [192.55.106.129] in directory /pub/fweb/faq,
     * verdi.imada.ou.dk [129.142.128.14] in directory /pub/faq/fweb, and
       ftp.uni-stuttgart.de [130.83.55.75] in directory
       pub/soft/tex/web/fweb/FAQ.
       
   
   
   To retrieve the plain text file via e-mail, include

SENDME FAQ.FWEB

   in the body of a mail message to

FILESERV@SHSU.BITNET (fileserv@shsu.edu).

   
   
   Send the command

SENDME FILELIST

   in a mail message to FILESERV to get valid information on the names of
   the downloaded files if you'd like to have another version of the
   fweb-faq (see section [9][4] Which versions of the FAQ are
   available?).
   
   NOTE: do not include the message SENDME FWEB unless you want the full
   FWEB distribution!
   
[10][4] Which versions of the FAQ are available?

   
   
   Besides the text file fweb-faq, the FAQ is available as a Texinfo, a
   PostScript, an Info or a DVI file. All these can be generated from the
   Texinfo source file fweb-faq.texi. The preprocessed DVI and PostScript
   files are not included anymore. See the simple makefile which
   accompanies the fweb-faq distribution for detailed information on how
   to process the Texinfo source. Short instructions are given in the
   file README.fweb-faq.
   
   If you do not know anything about Texinfo, don't worry: With the
   texinfo.tex macro package, the principal like any ordinary TeX file at
   the expense of not getting an index -- try it!
   
   If you would like to start with Texinfo, retrieve its latest version
   from prep.ai.mit.edu in directory pub/gnu (see section [11][6] How can
   I contribute?). If you like the GNU project and what it produces,
   please order a tape if you can, since tape orders are the FSF's (Free
   Software Foundation main source of funds to pay programmers and tech
   writers. For ordering info, send mail to gnu@prep.ai.mit.edu, or
   contact the FSF:
   
   Free Software Foundation 675 Mass Ave Cambridge, MA 02139
   1-617-876-3296
   
   As of spring 1994, there is a WWW Home Page for the FWEB FAQ . This
   may not be up to date at the of the posting of this FAQ to the net,
   but will be updated shortly.
   
   http://info.desy.de/user/projects/LitProg/fweb-faq/top.html
   
[12][5] What is the difference between the FAQ and the manual?

   
   
   Most of the stuff in FAQs is in the manual, but people either don't
   read the manual, or it is too hidden to be found (the FWEB User's
   Manual currently has more than 180 pages). Thus the FAQ provides, if
   you will, an index to the manual for those questions that come up
   regularly. Where possible, sections of the User's Manual for the last
   release (FWEB version 1.3) are referred to by their section numbers in
   square brackets, as in ``[M-10.2]''. 
   
   Note that there's also a user/syntax reference guide which can be
   obtained independently of the full manual. If you are a seasoned WEB
   user, the reference guide should be adequate. 
   
[13][6] How can I contribute?

   
   
   If you think that structure or content of this part of the FAQ can be
   improved, or if you think you have discovered an error, either write
   to me or post your comment to LitProg (with fweb-faq (version)
   somewhere in the Subject line).
   
   If you find your name and email adress anywhere on these pages, I'd be
   grateful if you check whether I got them right and inform me
   otherwise. The same for errors in ftp site addresses and Archive-Date
   (look into the Makefile to learn how to make these visible).
   
   The FAQ for Literate Programming will probably not exist before there
   is a unified tool rather than a family of different environments. On
   LitProg, all these environments are subject to discussion, and a
   family of FAQ lists is planned, together with a master FAQ list for
   general questions. This general FAQ will be maintained by David B.
   Thompson .
   
   If you are interested in participating in one of the FAQ lists for
   LitProg, either contact George D. Greenwade (E-mail: bed_gdg@shsu.edu
   [Internet], bed_gdg@shsu [Bitnet], shsu::bed_gdg [DECnet]), who
   maintains LitProg as well as the FILESERV repository at Sam Houston
   State University, or simply announce your wish on the LitProg mailing
   list. If you want to write a FAQ yourself, get "FAQ writer's FAQ" (by
   Nathan Torkington and Ian Kluft) which originates from the
   faq-maintainers mailing list. It can also be obtained via email by
   including SENDME FAQ.WRITING in the body of a mail message to
   FILESERV, or retrieved from niord.shsu.edu in
   [FILESERV.FAQ]FAQ.WRITING.
   
   If you want to write your FAQ list in Texinfo, use fweb-faq.texi as a
   template for the principal source file (see section [14][4] Which
   versions of the FAQ are available?).
   
[15][7] What else should be included in the FAQ?

   
   
     * Give more details on the form of the FAQ file's Texinfo source?
     * Add thoughts on OOP using the FWEB system
       
   
   
   Please send me your opinion on these items and suggest more things
   which should be done!
   
[16][0] Acknowledgements

   
   
   I would like to thank Marcus Speh for allowing me to take over as
   administrator of this FAQ. He has done a highly professional job of
   putting the original FAQ together as a texinfo file. I would also like
   to thank those whose postings are included here. I am very much
   indebted to thank Francisco Figuerido for introducing me to literate
   programming.
   
   Marcus Speh From the first version of this FAQ
   
   Thanks to all those whose postings in LitProg I have used and who have
   sent me corrections, especially Bart Childs, Johannes Muller, David
   Thompson and Don Petcher for this number of the FAQ, and to Robert
   Chassell [FSF, GNU Texinfo and Elisp support] for help with some
   Texinfo bugs.
   
   Thanks to the sysadmins who put up the files on FTP sites, especially
   Thorbjoern Ravn Andersen (ftp.imada.ou.dk) and Joachim Schrod
   (ftp.th-darmstadt.de).
   
   Special thanks to George D. Greenwade for maintaining the list and the
   file archives at Sam Houston University, and to John Krommes for
   checking this FAQ list for his child.
   
   Personally, I feel indebted to Thorsten Ohl for having introduced me
   to FWEB in the first place, and having taught me many more things
   related to computing.
   
                    [17]FWEB SOURCES/MANUAL/INSTALLATION
                                       
   
   
[18][8] Where can I get FWEB?

   
   
   You can get FWEB (version 1.30a and version 1.4) via anonymous FTP
   (see section [19][0] Information on FTP) either from ftp.pppl.gov, in
   directory pub/fweb/:
   

  /anonymous@ftp.pppl.gov:/pub/fweb/:



  -rw-r--r--   1 4145     589          2321 May 16  1995 READ_ME
  -rw-r--r--   1 4145     589         11265 May 14  1995 READ_ME-1.50
  drwxr-xr-x   3 4145     589           512 Jun 25  1993 executables/
  drwxr-xr-x   2 4145     daemon        512 May 19  1993 faq/
  -rw-r--r--   1 4145     589       1561989 Jun 17  1993 fweb-1.30a.tar.Z

   
   
   Or from niord.shsu.edu, in directory [FILESERV.FWEB]:
   

  /anonymous@niord.shsu.edu:/ANON_DEV:/FILESERV/FWEB:



FWEB-1_30.TAR_Z;1        2934  31-MAR-1993 16:45
FWEB-1_30.ZIP;2          2292  31-MAR-1993 16:48
FWEB-1_30.ZIP-LST;1        35  31-MAR-1993 16:52
FWEB.FAQ;2                103  11-JAN-1993 12:16
     ...

   
   
   
   
[20][9] What is the latest stable version of FWEB?

   
   
   The latest stable version of FWEB is 1.30a - in October 1993, Version
   1.40 no longer exists as far as I can tell and will be replaced with
   version 1.50 which promises many new features. See "What the Future
   Holds" (see section [21][37] What is the next version of FWEB?) for
   more information.
   
   The latest version can be retrieved via anonymous FTP (see section
   [22][0] Information on FTP) as described in section [23][8] Where can
   I get FWEB?.
   
[24][10] Where can I get FWEB for the PC?

   
   
   The official FWEB PC executables are generated as part of each FWEB
   release. Retrieve them via anonymous FTP (see section [25][0]
   Information on FTP) from the FWEB distribution site ftp.pppl.gov (see
   section [26][8] Where can I get FWEB?) in the directory
   pub/fweb/executables/fweb-1.30
   




 ...
-rw-r--r-x   1 4145     589        330978 Jun 25  1993 ftangle.exe*
-rw-r--r-x   1 4145     589        294896 Jun 25  1993 ftangle0.exe*
-rw-r--r--   1 4145     589        542928 Aug 30  1993 ftangle2.exe
-rw-r--r-x   1 4145     589        302734 Jun 25  1993 fweave.exe*
-rw-r--r--   1 4145     589        462165 Aug 30  1993 fweave2.exe
 ...

   
   
   ftangle0.exe is ftangle without the Ratfor preprocessor (see section
   [27][27] Why is FWEB so huge?).
   
   Hans-Hermann Bode announced his precompiled files for the PC. They can
   be retrieved from
   
   anonymous@niord.shsu.edu:[FILESERV.PC-WEB]:
   

00INDEX.;1                2  23-JUL-1992 16:26:54.85
...
FWEBEXE.README;1            6  11-JUN-1992 00:15
FWEBEXE.READ_ME;1          42   9-JUN-1992 12:13
FWEBEXE.ZIP;2            1525  23-JUL-1992 16:06
FWEBEXE.ZIP-LST;1           2  23-JUL-1992 16:22
...

   
   
   or in Europe from dione.rz.uni-osnabrueck.de (in directory:
   pub/msdos/tex/web), and from ftp.uni-stuttgart (in directory
   soft/tex/web/cweb).
   
[28][11] Is FWEB small enough to compile on a PC?

   
   
   Yes. It is known to compile with MicroSoft C 6.00 and Turbo C.
   
   JAK: ``As a remark, it took some considerable pain to make this work.
   The larger sources, such as ftangle.web, had to be split into as many
   as 3 parts (handled by WEB macros and module names). The make file
   compiles each of those parts separately, then combines them at link
   stage. Before this was done, compilers tended to bomb with messages
   such as Out of heap space.''
   
   On LitProg, Tero Laakkonen reported that FWEB also compiles under
   linux-096c with gcc-2.2.2 on a 80386.
   
   In general, John Krommes offers support for porting FWEB to new
   systems - contact .
   
[29][12] Has anyone installed FWEB on an HP machine?

   
   
   Either get GCC (the GNU C Compiler), or use (if you have it) the
   unbundled Hewlett-Packard ANSI C Compiler, which is invoked with cc
   -Aa -D _HPUX_SOURCE (as cc(1) explains in detail). Then make should
   proceed without any problems.
   
[30][13] Has anyone installed FWEB on Linux?

   
   
   Using GCC (the GNU C Compiler) on Linux seems to work directly. Just
   type make, sit back, and relax.
   
[31][0] Information on FTP

   
   
   FTP is a a way of copying files between networked computers. If you
   need help in using or getting started with FTP, send e-mail to
   mail-server@rtfm.mit.edu with
   

        send usenet/news.answers/ftp-list/faq

   
   
   in the body, instead of asking me.
   
   Those without FTP access should send e-mail to
   mail-server@rtfm.mit.edu with
   

        send usenet/news.answers/finding-sources

   
   
   in the body, instead of asking me.
   
   To learn virtually everything about FTP, Telnet etc., personally I
   found Brendan P. Kehoe's ZEN---A Beginner's Guide to the Internet very
   helpful. The first edition of this guide is freely available as a
   Texinfo, Postscript or DVI file from ftp.cs.widener.edu in directory
   pub/zen/. An updated edition is also published as a book by Prentice
   Hall (1992).
   
                    [32]COMMON THINGS PEOPLE WANT TO KNOW
                                       
   
   
[33][14] Can I use LaTeX with FWEB?

   
   
   In principle, you may use any package of TeX macros you like. However,
   an arbitrary macro package may contain conflicts with macros used in
   fwebmac.sty. Such conflicts are supposed to be eliminated for LaTeX).
   
   As for LaTeX which is probably the package most widely used, you have
   to do two things at minimum [M-20.7.22]:
    1. Use the command-line option -PL (or place them into your
       initialization file ~/.fweb (see section [34][26] Key differences
       for FWEB on different systems?).
    2. Process fweave's output with latex instead of tex.
       
   
   
   In most cases, to use LaTeX with FWEB it suffices to just say latex
   test instead of tex test. (I.e., an attempt is made to hide internally
   whatever differences there are.) It never hurts, and sometimes helps,
   to use the command-line option -PL (select post-processor LaTeX). To
   print a | in a verbatim environment, use @|, like: \begin{verbatim}
   ... @| ... \end{verbatim}.
   
   Since FWEB overrides the \output routine of LaTeX, some clever page
   layout facilities will not work - e.g. there are no floating bodies:
   while the table environment is lost, the tabular environment still
   works. See [M-19.22] for details.
   
   Bart Childs reports that the use of AMSTeX causes some problems but
   that it has been done.
   
   Difficulties with using LaTeX should be reported directly to Krommes.
   
   For bringing in lex and yacc scripts and the problem of using LaTeX's
   \footnote, See section [35][14] Can I use LaTeX with FWEB?.
   
[36][15] Can I use lex and yacc scripts with FWEB?

   
   
   Lewis Perin reported that he has succeeded bringing in lex and yacc
   UNIX scripts in for FWEB using LaTeX's verbatim environment.
   
[37][16] Can I use the footnote environment from LaTeX?

   
   
   Lewis Perin reports that the superscripts of \footnotes appear in the
   main text while the actual footnote is nowhere to be seen. In his
   reply, Zdenek Wagner refers to a style file ftn.sty which he wrote to
   correct this (originally for use with CWEB, it seems). ftn.sty can be
   retrieved from niord.shsu.edu [192.92.115.8] in directory
   [FILESERV.STY].
   
[38][17] Which WEB shall I use for C++

   
   
   As CWEB's coauthor Silvio Levy said, starting from version 2.9 (beta),
   CWEB will understand C++ syntax as well.
   
   Successful compilation on the PC with Borland-C++ was reported on
   LitProg.
   
   In the opinion of many people, FWEB is the best CWEB available. It
   also supports C, C++, F90, Ratfor, Ratfor-90, and writing TeX macros
   wherein (f)tangle produces .sty files.
   
   As for the more general question of Object-Oriented Literate
   Programming, a very interesting discussion was started by Paul Lyon in
   December.
   
[39][18] Does FWEB support Makefiles?

   
   
   Not yet. This is planned, though [M-10.2].
   
[40][19] FWEB with the GNU Emacs editor?

   
   
   If you are developing your FWEB programs using the GNU Emacs editor,
   there is web-mode.el by Mark Motl ; the corresponding GNU Emacs mode
   can deal with WEB, CWEB and FWEB. It is capable of many things,
   including jumping to sections and modules, inserting (and previewing)
   index entries, hiding and exibiting the body of a .web file (showing
   the tree), inserting, quoting, and consistently renaming modules etc.
   It supports change files and journal files. It is especially useful
   when dealing with large .web files not to have to deal with monolithic
   FWEB files. For more information, you may obtain a 30pp. User's Manual
   and the source files from the author, from Bart Childs .
   
   The current version of web-mode (v 1.61, as of Dec 28, 1992) is
   faster, more robust, and the documentation in the manual is improved
   and more accurate now. You may also obtain this version as a 220 KByte
   shell archive web-mode-1.61.sh via anonymous FTP from
   verdi.imada.ou.dk [129.142.128.14] in directory pub/emacs/. 
   
[41][20] How do I turn off double sided pagination in FWEB?

   
   
   In FWEB, the command \identicalpageheadstrue [to be put in the so
   called limbo part of your FWEB file] makes all page headers identical,
   but it puts the page numbers in the upper LEFT corner and the section
   numbers in the upper RIGHT corner. As Don Petcher pointed out, to do
   it the other way around you can either change the macro \normaloutput
   in fwebmac.sty as indicated:
   

\def\normaloutput#1#2#3{\shipout\vbox{
  \ifodd\pageno\hoffset=\pageshift\fi
  \vbox to\fullpageheight
   {
    \iftitle\global\titlefalse
    \else\hbox to\pagewidth
        {\vbox to10pt{}%
        \ifidenticalpageheads#3\else  % THIS WAS ORIGINALLY #2



or you can include the above version in your TeX file as a
redefinition of the macro.



[42][21] Can I define (and format) new reserved words?









Assume you want to declare
far to indicate a function pointer:

void far (*reset)();




In order for fweave to treat far like a reserved word in C
(or any of the language supported by FWEB), say

  @f far int




somewhere in your source. Weave does not by default recognize |far|
as a reserved word (this property extends to cweave as well).







The formatting with @f is language-specific; it only
applies to identifiers used in the language in force at the point
the format statement is encountered. This feature allows a WEB
programmer to invent new reserved words and/or to unreserve some
reserved identifiers [M-11.12].



[43][22] Symbolic debugging of FWEB files?










FWEB inserts sync lines `#line 137 foo.web' into the code,
so any compiler/debugger worth its money should respect them.
(Including those running under MS-DOS.)



Extra FWEB comments in the tangled output can be suppressed
by a simple command line switch. See [M-14.2]
for a list of command line options.



NB: well thought out code needs less time debugging - comments like
"since I've started using anyWEB, my debugger has just been
collecting dust ..." were
reported from many people on the list.



[44][23] Inserting meta-comments in FWEB files?












Johannes Muller reported strange output from fweave
when defining two macros debug and gubed
to enclose optional code for debugging purposes.
As his global language, he chose C++.




@m debug @(
@m gubed @)
@f debug do
@f gubed while




This worked fine for him using WEB with Pascal.
@( and @) are control codes which mark
the begin and end of a meta-comment, i.e. commented
out code that will appear in the output file [M-11.38].
Though I wasn't able to reproduce his errors, it should be
remarked that the preferred way is to use the WEB preprocessor
construction @#if(0) ... @#endif instead.





JAK: ``That Muller's example doesn't work probably points out
a problem with the macro preprocessor''.



For debugging purposes, one can bracket pieces of code by
@#ifdef DEBUG ... @#endif, switching on DEBUG



by the commandline flag -mDEBUG for ftangle [M-7.5].



[45][24] Automatic referencing in documentation sections?











To produce the woven output




For info on porting, see section 5




As Steve Avery reported, you can cheat and, somewhere after you
start the module,
just throw in something like
\let\refporting=\modno and then reference it by
see section~\refporting.



In FWEB, \modno is set to the number of the module being
typeset.



Another way to refer to a section is described in [M-20.7.18]:




@ Porting.
\modlabel{PORTING}



... more ...



@ Another section.
\modlabel{ANOTHER}



For info on Porting, see \WEBsection{PORTING}.




section is inserted automagically.
In the same fashion, the label ANOTHER allows
the user to refer to that section number.



In LaTeX, forward referencing works, in Plain TeX it doesn't.
Unless you're using LaTeX, the latter recipe
requires that \modlabel{ANOTHER} is defined
before referring to it.



If you want to say module instead of section,
use \WEBmodule (or equivalently \module)
instead of \WEBsection.



[46][25] How do I make a title appear on the contents page?











Bart Childs  contributed three short
files to solve that problem. These listings will disappear
here once the full web-mode.el distribution
(see section [47][19] FWEB with the GNU Emacs editor?) is available
at FILESERV.



     * limbo.material may be used as the initial skeleton for all WEB
       files. There is a line containing \def\title which should be
       modified to include the title. Also note that the first few lines
       are to encourage a little more documentation about the source. A
       few lines further into this is a similar convenience to add an
       abstract that will appear on the cover page too.
     * limbo.sty is a convenient place to record macros that are commonly
       used in WEB files.
     * time.tex, required by limbo.material.




Note that the limbo style-file parameter can
be used to automatically insert common material into the
limbo section of an FWEB file.



  [48]LIMBO.MATERIAL





-----------------------  limbo.material ------------------
%
% ??????.web,   ?fweb version 1.23
% Author
% Address
% e-mail and phone
%
%   LIMBO MATERIAL
%
\input limbo.sty



\def\title{{\tt }}



%% Comment the previous and uncomment this if you don't use web-mode
%%\def\title{{\tt ?? I need a Title ??}}



%%% begin Bottom of Contents Page macro
\def\botofcontents{\vskip 0pt plus 1fil minus 1.5in
{\bigskip\parskip6pt plus2pt \parindent20pt
%% begin abstract
\vskip0.5in
\noindent{\bf Abstract. }\it



}%% end abstract



%% BC often puts this in as a comment about pre-release versions ...



%\vskip0.5in
%{\vfill\it %% comments on anything else ????
%
%\vfil}% end of comments on anything else
\vfil
  \rightline{My Name}% You can personalize your output here, for example.
  \rightline{\today     }% today.tex should be preloaded, input it if not
  \rightline{\miltime   }% time.tex  should be preloaded, input it if not



}%      end of botofcontents



%   END OF LIMBO MATERIAL
%
%
%   BEGINNING OF WEB
%



%% Delete the next line after appropriate substitution.
%% In fweb's you want an @c, @c++, @n, @n9, or @Lx at this point



@* First Module.



@* Index.




  [49]LIMBO.STY





------------------------  limbo.sty -------------------------
% \input today %%%%% How Ridiculous, preload it!!!!!!!!!
\font\ninett=cmtt9
\font\ninerm=cmr9
\let\mc=\ninerm % medium caps for names like UNIX
\font\Csc=cmcsc10 % Computer Modern Computer Small Caps
\def\PASCAL{{\rm Pascal}}% Does very little
\def\WEB{{\ninett WEB}}%  use like \WEB{}  to make space significant
\let\web=\WEB \def\FWEB{{\ninett FWEB}} \let\fweb=\FWEB
\def\Fortran{{\Csc Fortran}} \def\Cee{{\bf C}}
\def\Unix{{\mc UNIX}}  \let\unix=\Unix
\def\BSl{{\rm\char'134}} \def\{$\,\rangle$}
%
%%% begin Top of Contents Page macro
%
\def\topofcontents{\hsize 6in
  \vglue -30pt plus 1fil minus 1.5in
  \centerline{\title}
  \vskip 15pt
  \centerline{\today}
\bigskip \vfill
  \def\?##1]{\hbox to 1in{\hfil##1.\ }}}% end of topofcontents




  [50]TIME.TEX





--------------------------  time.tex  ----------------------
\newcount\milhours\newcount\minutes\newcount\hours
\def\thetime{\milhours=\time
\divide\milhours by 60
\minutes=\milhours
\multiply \minutes by -60
\advance\minutes by \time
\hours=\time \divide\hours by 60
\ifnum \hours>12 \advance \hours by -12 \fi
\the\hours:\ifnum \minutes > 9 \the\minutes \else 0\the\minutes \fi}



\def\miltime{\milhours=\time
\divide\milhours by 60
\minutes=\milhours
\multiply \minutes by -60
\advance\minutes by \time
\the\milhours:\ifnum\minutes>9 \the\minutes\else 0\the\minutes \fi}




[51][26] Key differences for FWEB on different systems?




The machine dependent files, especially custom.h and
defaults.mk necessary for bootstrapping, can be found
in the current distribution of FWEB (v1.30a) in subdirectory
/boot/. See the READ_ME.* files there for details.



To run FWEB, commonly used options can be put into an initialization
file [M-14.3] (default name .fweb). The subdir's of /boot/
contain sample .fweb files with necessary commandline options
for the system on which FWEB was built.



[52][27] Why is FWEB so huge?






Most of FWEB's size can be attributed to the need of supporting vastly
different languages.  The input routines for a free form language are
not usable for Fortran and vice versa.  Furthermore, FWEB has a Ratfor
processor built in (which is a big plus, though it is not strictly
related to literate programming).



JAK: ``Two other reasons for the large size are



    1. the built-in macro preprocessor, an extended version of that for
       ANSI C;
    2. the style-file mechanism.
















On the positive side, FWEB does most of its
memory allocations dynamically, so one can cut down the size of various
tables if necessary.  Type ftangle -Y to find out about the current
allocations; use the -y option to change them.
The statistics option -s is also helpful to find out how much a
job actually uses.'' (See [M-14.2] for a complete list of options.)



If you do not want the Ratfor preprocessor, you can make a smaller
ftangle with the option LOAD\_RATFOR=0 (see the file
web/ratfor0.web of the FWEB distribution, and [5]).



[53][28] What is the difference between CWEB and FWEB?






See [M-20.8], Appendix H, for a short list comparing these
two variants of the WEB system.



[54][29] What is the difference between FWEB and Funnelweb?





The following was extracted from a text by Paul Lyon
(and will eventually be merged with a FAQ for Funnelweb ...):



"FWEB and Funnelweb are quite distinct. FWEB is built on top of the
CWEB framework; although the parser in its weave processor can do
more---all of ratfor, C, C++, and (though the support is not
complete), TeX, it is still confined to those specific languages, and
still imposes on the user the formatting conventions that please its
author. To get something different you will have to hack the weave
processor. (One could possibly get somewhere by modifying the TeX
macro package that FWEB uses, but that might be the harder way to go,
unless, of course, you are already a TeXpert) ...



Funnelweb, on the other hand, does not try to parse the source code
at all; it just takes the layout of the source as written, turns off
the meaning of plain TeX special characters, sets typewriter font,
and then invokes \obeylines and \obeyspaces;
all this together causes
TeX to print the source verbatim (the paragraph formatting is turned
off, and TeX does not gobble spaces). The original WEB, CWEB, FWEB,
and Spiderweb all parse and format the source, inserting TeX math
codes for the operators, putting keywords in boldfont, adjusting the
indentation, and so on. If you like the style chosen for the
programme, it looks much nicer that way. Except for Spiderweb, which
can be adapted to various languages by allowing a fair range of
variation in specifying the pretty printing grammar using a large
awk script to process the grammar spec and generate replacement
code for significant chunks of weave, the pretty printing parser(s) in the
other are hard coded. This has it uses besides making the typeset code
more attractive; WEB, CWEB, FWEB, and Spiderweb all do an index of
identifiers for the code that can differentiate, for the most part,
between declaration and use of an identifier (they know enough about
the grammar to do that, but not, of course, as much as a compiler or
interpreter) ..."



[Rest deleted: continues with more details on Funnelweb.]






JAK: ``Don't hack fweave!  Many
effects can be obtained by modifying fwebmac.sty.
(If one knows enough to hack fweave, he presumably
knows enough to hack fwebmac.sty instead.)
Note that the style-file mechanism does provide some degree of
customization.''



Please report customizations that are really necessary to
John Krommes.



[55][30] Do FWEB files necessarily have to be monolithic?






[Later, this item might move to the general FAQ by David B. Thompson]



There is no real support for multiple source files under FWEB.
What some might like to see is a solution similar to the one
presented by Cameron Smith in his KR-CWEB-SAMPLE distribution.
He had to hack CWEB's cwebmac.sty to get a neat table of
contents and a combined index distinguishing between entries from
different source files [in fact, KR-CWEB-SAMPLE illustrates
many more things, all more or less related to breaking up a literate
C program into multiple source files].
For illustration, this is how the table of contents should look like
(sample from Cameron's files):




source module 1: main         Sect Page
introduction..................1.1  1.1
main pgm......................1.4  1.2
index.........................1.10 1.4



source module 2: getop
introduction..................2.1  2.1    etc.




while entries of the combined index are separated like




Index for source module 1: main
...
Index for source module 2: getop
...
...



Sections in source module 1: main
 used in section 4...
...




For FWEB, the inclusion of files using @i is a partial
solution [M-11-13] to avoid having to put all the source code
in one file.  So far, nobody has presented a solution in
Cameron's spirit.






This feature is put on JAK's list of possible future enhancements.
It is not in 1.30a, though. Note that CWEB has got an @i
option, too (although FWEB's is somewhat more general).



Yet another approach (not limited to FWEB) is the use of a
smart editor like GNU Emacs, combined with a smart
tool like web-mode which is effectively hiding many
of the mischiefs of monolithic source files from the programmer.
(see section [56][19] FWEB with the GNU Emacs editor?).



[57][31] How did tangle and weave get their names?











[Later, this item might move to the general FAQ by David B. Thompson]



In a reply, Cameron Smith wrote:
"One of the problems with having a single preeminent writer in a language
is that everyone always assumes that any enduring tidbit came from his
pen ...".
Fortunately, for the question
How did tangle and weave get their names, the circulus vitiosus
of erroneously quoting William Shakespeare could be broken. The full
answer:




  O, what a tangled web we weave
  When first we practise to deceive!
    -- Sir Walter Scott, _Marmion_, canto 6, verse xvii (1808)




Cameron also suggested to include these lines by Richard Palais (1982):




  O, what a tangled WEB we weave
  When TeX we practise to conceive!




Concerning FWEB, JAK reluctantly remarks [M-1]:
"We shall call this new version FWEB when necessary ...".



And more recently: ``I now think the choice of `F' in FWEB was a mistake.
`F' stands for Fortran, which motivated this project,
but the ability of FWEB to handle multiple
languages is one of its most distinctive and useful features.
But it's probably too late now.''



[58][32] How am I supposed to abbreviate ``Literate Programming''?






[Later, this item might move to the general FAQ by David B. Thompson.]



There wasn't a clean vote on the mailing list. Most people seemed
to agree that one should not misuse common abbreviations like
LP, LPR etc. Also, the acronym should be pronounceable
(thus eliminating LitPgm e.g.). The list's name LitProg,
proposed by Cameron Smith, seems to be accepted by a majority now.
This is also the acronym adopted for the FAQ list.



                     [59]GENERAL QUESTIONS/BUGS/PROBLEMS
                                       






A brief account of bugs and bug fixes according to the different
versions of FWEB, can be found in the READ_ME file at
ftp.pppl.gov (see section [60][8] Where can I get FWEB?).



[61][33] What if I think I found a bug in FWEB?







John Krommes  actively supports FWEB --
he must be considered the ultimate source of wisdom.



Once you think you've found a bug, put it out on the list. If
nobody responds, cut your file down to the smallest subfile
that still exhibits the problem you encountered.
Then, you may contact John. To be sure, you should also
check with the READ_ME file at ftp.pppl.gov
(see section [62][8] Where can I get FWEB?) for additional
information concerning your bug.



[63][34] Problem opening a new output file for tangled code?









If you're using FWEB's @o option in order to open a
new output file for tangled code (with local scope - i.e. for
the duration of the current section only [M-11.21]),
there is no problem in the current version and the output should
be correct.



[64][35] Maximum number of equal characters in different section names?






FWEB may have problems distinguishing section names,
if one of them is an exact subset of a longer
name rather than a length.



This is a bug in the mind of some, but it may as well be
regarded a good feature as it should be a warning that
poor choices of names has happened.




JAK: ``I think it's a feature, not a bug.
And unless I screwed something up, the behavior derives from CWEB.''



[65][36] Must I leave leading blanks in my fortran FWEB file?




Yes, you should. This is proven by the following example coming from
Bart Childs.




@n
@* The world is not perfect.
This wonderfully short problem blows outputs garbage
from fweave and ftangle if you don't have the leading
six columns blank.  Be careful, because in many cases
FWEB works fine without the requisite leading blanks.



@a
   program final_exam
   implicit none
   integer i, j
   do i = 1, 7, 2
     do  j = 6, 1, -1
       write(*,*) i, j
       end do
     end do
   end




To see the effect on fweave, indent with 4 leading blank spaces
instead of 6.







JAK: ``The input reader for Fortran--77 follows the rules
of Fortran--77---i.e., statement labels in columns 1--5, continuation
character in column 6, columns 6--72 for code.  However,
note that Ratfor uses free-form syntax, and Fortran--90
also has a free-form syntax mode, which FWEB attempts to support.''



[66][37] What is the next version of FWEB?







The newest version of FWEB is 1.50. This is an extension
and improvement of 1.40 that never graduated to the status of a stable release.
The original beta release was May 1, 1995. As of May 15, 1995
"fweb-1.50.tar.Z has been temporarily removed
pending resolution of a few more bugs", [JAK]. This is due to
change in the near future.



[67][38] Should I switch to the latest version?






According to JAK



"Version 1.30, which for several years has been declared to be the stable
version of choice, is gradually getting out of date.  I now recommend that
current users try VERY, VERY CAUTIOUSLY to upgrade to v1.50.  Don't do that
the week before a critical deadline."



[68][39] What new features are available?






Some of the other features include:



Quoting from READ_ME-1.50



(1) The default environment will be LaTeX and not TeX as was the case
in the past. Many of the features of LaTeX are now supported including
footnotes. TeX usage is still possible with the switch '-PT'.
LaTeX2e support is also available.



(2) FWEB should now be able to process C++ templates and exception handling,
at least in simple situations.



(3) All manuals will be in texinfo format.



(4) The experimental macro package fwebmacL.sty used for LaTeX
support with v1.40 is now the default, hence called fwebmac.sty.



(5) Extension of language independent features first introduced in version 1.40



                                  [69]INDEX
                                       







@shortcontents



NOTE: This mailing list has been inactive for awhile. However,
it appears that the list is starting up again so I urge you to
subscribe!
