WEB mode: a hands-on session

• Copy the WEB input file, gamma.web, whose location is given in section 2.4.3 to your working directory. Rename it to gamma-ORIG.web.
• Enter Emacs (but it should be my Emacs from the /afs/ovpit.indiana.edu/@sys/gnu/bin directory) and visit file gamma.web: C-x C-f gamma.web.
• If this is a new WEB file that you're creating, instead of placing you directly in an editing session, Emacs will ask you two questions in the minibuffer:

  Title of Web:
  

  and then

  Author:
  

  Answer both truthfully, and, in response, you'll be placed within the WEB-mode and the first two lines of the file will have been automatically initialised to something like this:

  \Title{gamma.web}
  \author{Zdzis\l aw Meglicki}
  

• You will also find that there is a commented out header that provides general information about this new WEB file, e.g.,

  %%
  %    WEB SYSTEM  :  fweb
  %       PROGRAM  :  gamma.web
  %        AUTHOR  :  Zdzislaw Meglicki [gustav@@beige.ucs.indiana.edu]
  % CREATION DATE  :  Tue Oct  6 10:59:23 1998
  %%             
  

• Further down is a template for you to fill. It begins with

  % begin Bottom of Contents Page macro          
  

  and ends with

  % end of Bottom of Contents Page macro         
  

• Two other lines tell you to replace them with text of your own choice:

        % >>> Insert Abstract in place of this line.
        ...
        % >>> Insert any other comments here             
  

• Compare the template with the contents typed into gamma-ORIG.web. Don't view the latter using Emacs' M-x view-file, because the WEB mode will get confused (it's a bug)^2.9. Use less in an xterm window instead. Paste appropriate text into your own editing session.
• Now move to the first starred section

  @* First chapter (and section).
  

  and, again, compare it with the gamma-ORIG.web file. Paste appropriate changes onto your editing session. Keep pasting until the first (and only, on this file) occurrence of

  @a
  

• Don't past the latter into your document. Instead type it in, and observe that as you have typed @, the WEB-mode has switched to the minibuffer. It knows that you're about to create or append to an already created module, so it waits for what's to follow. In this case, as you type a, it simply puts @a in the text and puts you back in the editing window.
• Don't paste. Instead type in the following code fragment:

    real(kind=long) function big_gamma(a, x)
      real (kind=long), intent(in) :: a, x
      @<internal variables@>
      
      if (x .le. 0.0_long) then
         if (x .lt. 0.0_long) then
            stop 'error: big_gamma called with x < 0'
            /* This is an error condition: we don't define the
            value of $\Gamma(a, x)$ for $x < 0$ */
         else
            big_gamma = gamma(a)
            /* This is easy to see, because 
            $\Gamma(a, 0) = \int_0^\infty e^{-t} t^{a-1}\,\textrm{d}t = 
             \Gamma(a)$. */
         end if
      else
         @<initialize iteration@>
         @<iterate@>
         big_gamma = r_new * exp(-x + a log(x))
         /* This is simply $e^{-x} x^a (\ldots)$ where
         the stuff within the brackets is stored on |r_new| */
      end if
  

  Observe that as you type the first occurrence of @< that opens the internal variables module, the WEB-mode puts you into a new buffer and asks for section name in the minibuffer. There are no sections defined at this stage.
• Respond with the name of the section internal variables and press return. The WEB-mode adds the name of the section to a list it maintains, and creates a stub for the definition of the module on the edited file.
• Continue adding the code text. As you get to the next module @<initialize iterations@>, the WEB-mode asks you more questions, because there is already one module on the list. Here you want to create a new module. Type C and press return. The WEB-mode answers with

  New Section Name:
  

  Answer initialize iterations, the repeat the same for @<iterate@>, and finish by pasting the remainder of the code until

    end function big_gamma
  

• At this stage you have already several stub sections in your document. Pull down the Navigate menu, then the Web File... submenu and select Next Section and Previous Section. Try the same with Next Chapter and Previous Chapter. Observe how this time the WEB-mode moves you between starred sections. These the WEB-mode calls chapters.
• You can also select Goto Section and give a number, e.g., 2, or 5. Ditto for chapters.
• Go to the second section, which should read:

  @ This is the second section.
  

  and delete it. It was simply a place holder for you to remember about it. Once the WEB-mode created automatically stubs for new modules and sections, you don't need it any more.
• After you've done that, the second section is now:

  @ @^Stub@>
  @<internal variables@>=
  

• Continue editing the file by copying from the original and pasting it into your own document.
• Observe L^ATEX cross referencing, as well as the use of L^ATEX formatted comments in the code part. These let you explain, right next to the computer code, various subtle points, while using the full power of L^ATEX mathematical typesetting at the same time. These are not verbatim comments and they are not passed to the generated Fortran code by ftangle.
• Don't forget about @n9 at the beginning of the code.
• Ensure that your document looks exactly like mine (minus the author field, of course).
• Pull down the Process menu and select WEAVE Source Files. The WEB-mode will ask you, which WEB to use. Select F for FWEB. The WEB-mode should then invoke fweave to generate the .tex document.
• Pull down the Process menu and select TANGLE Source Files. Since you have already told the WEB-mode to use FWEB, ftangle will be invoked on your WEB file without further questions.
• Also try other options in the Process menu, e.g., Create A DVI File, Create A Postscript File, and then in the Preview Typeset Program... submenu Preview-With-Xdvi, and Preview-With-Ghostview.
• The tangled Fortran file will not compile, because we have not included the euler module, so that the compiler doesn't know what long is.
• Exercise:

  1.

  Convert the whole Euler module to a WEB document. Add annotations as you see fit. Generate a L^ATEX and a PostScript document with fweave, L^ATEX, and dvips.

  2.

  Generate and compile a tangled Fortran-90 code.

  3.

  Put the original WEB document under the RCS management.

  4.

  Automate, with GNU make, the whole procedure of extracting a WEB file from RCS, converting it to Fortran and L^ATEX, compiling and text formatting, and generating .o and .ps files at the end.