diff options
Diffstat (limited to 'support/emacs-modes/web-mode-manual.tex')
-rw-r--r-- | support/emacs-modes/web-mode-manual.tex | 1526 |
1 files changed, 1526 insertions, 0 deletions
diff --git a/support/emacs-modes/web-mode-manual.tex b/support/emacs-modes/web-mode-manual.tex new file mode 100644 index 0000000000..5dc62abf22 --- /dev/null +++ b/support/emacs-modes/web-mode-manual.tex @@ -0,0 +1,1526 @@ +\magnification=\magstep1 +\raggedbottom +% Produce verbatim listings of various sorts +\def\uncatcodespecials{\def\do##1{\catcode`##1=12 } \dospecials} +\font\TT=cmtt9 +\def\setupverbatim{% + \par \TT \spaceskip=0pt % Make sure we get fixed tt spacing + \obeylines\uncatcodespecials\obeyspaces\verbatimdefs +} +% This macro turns on verbatim mode until ?endverbatim is seen. +\def\verbatim{\begingroup \setupverbatim + \parskip=0pt plus .05\baselineskip \parindent=0pt + \catcode`\ =13 \catcode`\^^M=13 \catcode`\?=0 + \verbatimgobble} +{\catcode`\^^M=13{\catcode`\ =13\gdef\verbatimdefs{\def^^M{\ \par}\let =\ }} + \gdef\verbatimgobble#1^^M{}} +% This defines ?endverbatim to end the group which begins with \verbatim +\let\endverbatim=\endgroup +% Input a file in verbatim mode. Sometimes useful for including +% real-life examples into a paper. +\def\verbfile#1{\begingroup\setupverbatim + \parskip=0pt plus .05\baselineskip \parindent=0pt + \input#1 \endgroup +} + +\def\BIND#1#2{\kern2pt\hbox{\vrule\vtop{\vbox{\hrule + \hbox{\strut\kern2pt{\tt ESC C-#1 C-#2}\kern2pt}} + \hrule}\vrule}} % used to have a \kern2pt between the last }'s +\def\Bind#1#2{\kern2pt\hbox{\vrule\vtop{\vbox{\hrule + \hbox{\strut\kern2pt{\tt C-#1 C-#2}\kern2pt}} + \hrule}\vrule}} + + +\def\Web{{\tt WEB}} +\def\BS{\tt\char'134} +\def\Command#1#2#3#4{$$\line{{\hskip\parindent\tt #1}\hfil + \ifnum #4>2 + \BIND{#2}{#3}% + \else + \ifnum #4=1 + \Bind{#2}{#3}% + \else + \fi + \fi + } + $$% + } +\abovedisplayskip=\smallskipamount +\belowdisplayskip=\smallskipamount +\parskip=10pt plus2pt minus2pt +\overfullrule=0sp +\font\logofont=logo10 +\def\MF{{\logofont META}\-{\logofont FONT}} +\font\ninerm=cmr9 +\let\mc=\ninerm % medium caps for names like UNIX +\def\Unix{{\mc UNIX}} \let\unix=\Unix +\font\BF=cmbx10 scaled \magstep2 +\font\Bf=cmbx10 scaled \magstep1 +\font\SS=cmss10 +\font\Tt=cmtt10 scaled \magstep1 +\null\vskip3pc +\centerline{\BF A User's Manual for} +\medskip +\centerline{\BF GNU Emacs' WEB-MODE} +\bigskip +\centerline{\Bf Mark Motl} +\centerline{\bf Department of Computer Science} +\centerline{\bf \TeX{}as A\&M University} +\centerline{\tt motl@cs.tamu.edu} +\bigskip +This document is a companion to {\tt web-mode.el}, a collection of GNU +Emacs Lisp functions designed to customize GNU Emacs so that it is +sensitive to a \Web\ document. Appendix A is a complete list of the +functions. + +You should receive two files: {\tt web-mode.el \rm and \tt +limbo.material}. The first is the source {\tt web-mode.el}\null. The +second is statements that commonly appear in the limbo portion of a +\Web. This `limbo' code is borrowed from some of Knuth's \Web{}s. + +Throughout this document, I will use the symbology used by Emacs. For +example, the {\tt find-file} command can be entered two different ways +\Command{M-x find-file}{x}{f}{1} +The first way of entering the command is to actually type the command as +shown above. Press the {\tt META} key (on some terminals this may be the +{\tt ESC} key); next press the {\tt x} key; finally, enter the +characters {\tt find-file} followed by a carriage return. An alternate +way of issuing this command is to use its associated keybinding as shown +in the box to the right of the command above. In this keybinding {\tt +C-} refers to the {\tt CTRL} key. Press and hold down the {\tt CTRL} key +and then press the {\tt x} key followed by holding down the {\tt CTRL} +key and then pressing the {\tt f} key. For all commands mentioned +throughout this manual, both forms of invoking the command will be shown +if they exist. Some commands, such as +\Command{M-x what-line}{}{}{0} +do not have a keybinding and hence must be entered by typing in the +command name. All commands that are \Web{} extensions have been prefixed +with ``{\tt web-}''. + +I strongly encourage all users of {\tt web-mode.el} to {\it +byte-compile\/} it. The byte-compiled code runs considerably faster +than interpreted code. To byte-compile {\tt web-mode.el}, start GNU +Emacs. Issue the command +\Command{M-x byte-compile-file}{}{}{0} +The user will be prompted for the name of the file. Respond with {\tt +web-mode.el}\null. This will create a new file named {\tt +web-mode.elc}\null. + +\vfil\eject + +To get {\tt web-mode} automatically loaded, add the following +lines of code to the file that configures your Emacs. This file is +usually ``{\tt .emacs}'' on \Unix{} systems. +\vskip\smallskipamount +\verbatim +(setq auto-mode-alist (cons '("\\.web\$" . web-mode) auto-mode-alist)) +(autoload 'web-mode "web-mode.elc" "Major mode for editing WEB-based documents" t) +?endverbatim + +\noindent You can also enter {\tt web-mode} manually by loading the +file that contains the {\tt web-mode} functions and then invoking the +function {\tt web-mode}\null. The commands to do this are: +$$\leftline{\hskip\parindent\tt M-x load-file\quad + {\it Respond with\/} {\tt web-mode.el} {\it or\/} {\tt web-mode.elc}\hfil}$$ +and +\Command{M-x web-mode}{}{}{0} +{\null\vfill + \centerline{{\bf NOTICE}} + + The rest of this document will assume that either of the above means which + invoke {\tt web-mode} has been executed. + + \null\vfill + \centerline{{\bf CAVEAT}} + + Some of these functions may seem to be trivial and slow at first. We + believe they will pay big dividends for larger \Web{}s. +} +\vfill\eject +\leftline{\Bf Getting Started} + +{\tt Web-mode} assists in creating and/or editing \Web{}s. +\bigskip +\leftline{\SS Creating a New \Web} + +If a \Web\ is being created, Emacs will need to be started with an empty +file. For example, if the name of the new \Web\ is {\tt my.web}, you +would probably enter the \Unix\ command +\Command{\% emacs my.web}{}{}{0} +The function {\tt web-mode} (see NOTICE on previous page) will prompt +the user for the name of the file that contains the limbo portion of the +\Web\null. To accept the default file ({\tt limbo.material}), the user +need only press the return key. If, on the other hand, the user wishes +to enter the name of another file, that can be done by answering with +another file name. If the default is selected, the contents of the file +{\tt limbo.material} are inserted and the user is asked to enter a title +for the \Web\null. +\bigskip +\leftline{\SS Editing a \Web} + +If you wish to use {\tt web-mode} on an existing \Web, say {\tt +primes.web}, you would begin by invoking Emacs with the \Unix\ command +\Command{\% emacs primes.web}{}{}{0} +When the function {\tt web-mode} is executed, it will perform some +initialization of various data structures. A list of the module names +is collected. If {\tt web-mode} detects that a module name has been used +but never defined, a ``stub'' module is inserted at the {\bf end of the +major section} in which it was first used. The form of the stub module +is: + +{\vskip2pt\parskip0sp\tt\obeylines\def\SP{{\tt\char`\ }} + @\SP + @\char`\^ Stub@\char`> + @\char`< Name of undefined module@\char`>= + } +% +{\tt Web-mode} also reads in the {\tt CHange} file that accompanies the +\Web\ currently being edited. If there is no {\tt CHange} file, one is +created; however, this file is ``saved'' only if it is modified. +% +\vfill\eject +% +\leftline{\Bf Movement Within The \Tt{WEB}} +\bigskip + +Several commands facilitate movement within the \Web\ document. The user +can switch to the buffer containing the {\tt CHange} file by issuing the +command +\Command{M-x web-change-file}{c}{f}{3} +Similarly, the user can switch to the buffer containing the \Web{} file +at any time with the command +\Command{M-x web-file}{w}{f}{3} +If the \Web{} being edited is a {\tt CWEB}, the user can switch to any +of the include files with the command +\Command{M-x web-include-file}{i}{f}{3} +This command takes a numeric argument. For example, giving the function +an argument of 1 would cause the buffer containing the contents of the +first include file command ({\tt @i}) encountered in the {\tt CWEB} to +become the current buffer. + +The user can {\tt goto} any module or section at any time by issuing +either +\Command{M-x web-goto-module}{g}{m}{6} +or +\Command{M-x web-goto-section}{g}{s}{6} +respectively. The user is then prompted for the module or section +number. If a nonpositive number or a number greater than the number of +modules or sections in the \Web\ is entered, an appropriate error +message is displayed in the minibuffer. If a valid module or section +number is entered, point moves to the beginning of that module or +section in the \Web\null. The command can also be entered with a numeric +argument which represents the destination module or section number. For +example, if the user wants to {\tt goto} module 163, the command could +be entered as +$$\line{\hskip\parindent\tt C-u 163 M-x web-goto-module\hfil + {\kern2pt\hbox{\vrule\vtop{\vbox{\hrule + \hbox{\strut\kern2pt{\tt C-u 163 ESC C-g C-m}\kern2pt}} + \hrule}\vrule}}}% +$$ +If the destination module has been changed, a message is printed in the +minibuffer stating that the destination module has been changed. + +The user can also {\tt goto} the next or previous module by entering +either +\Command{M-x web-next-module}{n}{m}{3} +or +\Command{M-x web-previous-module}{p}{m}{6} +respectively. If there is no next or previous module, an appropriate +message is displayed in the minibuffer; otherwise, point moves to the +beginning of the next or previous module, whichever is appropriate. + +The user can also {\tt goto} the next or previous major section in the +\Web\ document by entering either +\Command{M-x web-next-section}{n}{s}{3} +or +\Command{M-x web-previous-section}{p}{s}{6} +respectively. If there is no next or previous section, an appropriate +message is displayed in the minibuffer; otherwise, point moves to the +beginning of the next or previous section, whichever is appropriate. It +should be noted that these commands move point to the beginning of the +next or previous section and not to the beginning of the current +section. + +The user can determine the exact module number and major section point +is positioned in at any time with the commands +\Command{M-x web-what-module}{w}{m}{3} +and +\Command{M-x web-what-section}{w}{s}{3} +respectively. + +If you are already an experienced \Web er, you might want to ask about +the {\tt change} file. Please wait until you've read that section. +% +\vfill\eject +% +\leftline{\Bf Inserting A Module Name} +\bigskip +Whenever the {\tt \char`<} key is pressed in the buffer containing the +\Web\ document, the function {\tt web-insert-module-name} is invoked. This +function must determine whether this is the beginning of a module name +or not. The function examines the preceding characters. If an odd +number of {\tt @}'s precede the {\tt \char`<}, then it is the +beginning of a module name and the function {\tt +web-options-for-module-name-insertion} is automatically invoked; +otherwise, the {\tt \char`<} is inserted and the user can continue +typing. + +If the function determines that it is the beginning of a module name, +the user is switched to another buffer with the following options: + +{\parskip=0sp\tt + \itemitem{A.} Abort + \itemitem{C.} Create New Module Name + \itemitem{L.} List All Modules Beginning with Letter + \itemitem{N.} Next Screen + \itemitem{P.} Previous Screen + \itemitem{S.} Select Existing Module Name\par } +\noindent The user must then select one of the above options. A sample +screen is shown in Figure~1. The \Web\ used for the figures is {\tt +primes.web} contained in [1]\null. + +\verbatim +Option Action +------ ------------------------------------------- + A Abort + C Create a New Module Name + L List all Module Names Beginning with Letter + N Next Screen + P Previous Screen + S Select Existing Module Name +------------------------------------------------------------------------------- +Number Name + 1 Fill table |p| with the first |m| prime numbers + 2 Give to |j_prime| the meaning: |j|~is a prime number + 3 If |p[n]| is a factor of~|j|, set |j_prime:=false| + 4 Increase |j| until it is the next prime number + 5 Initialize the data structures + 6 Other constants of the program + 7 Output a line of answers + 8 Output a page of answers + 9 Print table |p| + 10 Print the first |m| prime numbers + 11 Program to print the first thousand prime numbers + Displaying 11 Module Names of 14 +--**-Emacs: *Module Names* (Web)----All--------------------------------- +?endverbatim +\medskip +\centerline{{\bf Figure 1.}} + +{\parskip4pt plus2pt minus1pt + +\item{{\tt A.}} If this option is selected, the user is switched back +to the buffer containing the \Web\ document and the two characters +preceding point ({\tt @\char`<}) are deleted. + +The remaining options involve the list of module names. The +module names are displayed below the menu choices. The module names +are displayed in alphabetical order and are retrieved from the list +that was created when {\tt web-mode} was invoked at the beginning of +the editing session. The module names are displayed with a number to +their left. The modules are numbered sequentially beginning with +1\null. + +\item{{\tt C.}} If the option is chosen, the user is prompted for the +name of the new module. Once entered, the user is switched back to the +buffer containing the \Web\ document, the new module name is inserted, +and the ending module delimiter (either {\tt @\char`>\ \rm or \tt +@\char`> =}) is determined automatically and inserted. A check against +the existing module names is conducted to ensure that the entered +module name is indeed new. If the module name is new, a determination +of whether a stub module needs to be appended is made and the new +module name is added to the list of module names. + +\item{{\tt L.}} This causes all module names that begin with a +particular letter to be displayed. The user is prompted for the letter. +If no module names begin with the desired letter, an appropriate +message is displayed in the minibuffer. + +\item{{\tt N.}} This causes the next screen of module names to be +displayed. For example, if the screen is capable of displaying 21 +module names and currently module names 1 through 21 are displayed, +choosing {\tt N} would cause module names 22 through 42 to be +displayed. + +\item{{\tt P.}} This causes the previous screen of module names to be +displayed. For example, if the screen is capable of displaying 21 +module names and currently module names 30 through 50 are displayed, +choosing {\tt P} would cause module names 9 through 29 to be +displayed. + +\item{{\tt S.}} This option asks the user to enter the number +associated with the module name that he wishes to insert in the \Web\ +document. The ending module name delimiter (either {\tt @\char`>\ \rm +or \tt @\char`> =}) is determined automatically and inserted.\par} + +\vfil +{\it This might seem like a severe interruption of the coding +process. However, getting the ``named modules'' spelled and spaced +correctly is critical.} +\vfil +\eject +% +\leftline{\BF Viewing the Index, Module Names, and} +\leftline{\BF Section Names} +\bigskip +{\tt Web-mode} allows a programmer to view the index as created by +{\tt WEAVE}\null. A user can also display the list of module names +that is maintained by {\tt web-mode}\null. It is also possible to +view the names of the major sections of the \Web{} and the module +number where each major section begins. +\bigskip +\leftline{\SS Viewing the Index} + +The user can view the contents of the index created by {\tt WEAVE} by +issuing the command +\Command{M-x web-view-index}{v}{i}{3} +The user is first asked whether the \Web\ is a Pascal or C \Web\null. +After the language has been determined, the function creates an +asynchronous process which invokes the {\tt WEAVE} processor on the +\Web\ in the current buffer. At Texas A\&M we have modified {\tt WEAVE} +so that it writes the index to the file {\tt INDEX.tex} and the list of +module names to the file {\tt MODULE\_NAMES.tex}\null. (The changes that +must be made to {\tt WEAVE} to accomplish this are contained in Appendix +C.)\ \ Once this process has completed, the contents of {\tt INDEX.tex} +are inserted into another buffer. Some reformatting is done for a better +presentation. The user can traverse the list of module numbers for a +particular index entry by positioning the cursor anywhere on the line(s) +where the index entry of interest is located and issuing the command +\Command{M-x web-next-index}{n}{i}{3} +or +\Command{M-x web-previous-index}{p}{i}{6} +These commands can be issued from the buffer where the index is +displayed or they can be issued from the buffer that contains the \Web\ +document. If the commands are issued from the former, the user is +switched back to the buffer that contains the \Web\ document, and point +is positioned at the beginning of the module where the most recently +selected index entry was next or previously referenced from point's +current position. + +Once the user is back in the buffer that contains the \Web\ document, +the list of modules associated with the most recently selected index +entry can be traversed with the commands +\Command{M-x web-next-index}{n}{i}{3} +and +\Command{M-x web-previous-index}{p}{i}{6} +These commands work as expected and print an error message if the user +attempts to run off of either end of the list. A portion of the index +created for Knuth's {\tt primes.web} is shown in Figure~2\null. + +\midinsert +\verbatim +Bertrand, Joseph, postulate: 21. +boolean: 15. +c: 7. +cc: 5, 7, 8, 10. +Dijkstra, Edsger: 1, 15. +Eratosthenes, sieve of: 24. +false: 13, 26. +integer: 4, 7, 12, 17, 24. +j: 12. +j\_prime: 13, 14, 15, 22, 26. +k: 12. +Knuth, Donald E.: 15. +m: 2. +mult: 24, 25, 26. +n: 23. +new\_line: 6*, 9, 10. +new\_page: 6*, 9. +ord: 17, 18, 19, 20, 21, 22, 23, 24, 25. +ord\_max: 17, 19, 23, 24. +output: 2, 6*. +output format: 5, 9. +p: 4. +--**-Emacs: *INDEX for primes.web* (Web)----Top----------------------------- +?endverbatim +\medskip +\centerline{{\bf Figure 2.}} +\endinsert + +***{\bf Important}***\ \ It may be necessary for the {\tt web-view-index} +source to be changed if the {\tt WEAVE} processor for Pascal \Web s is +called something other than ``{\tt weave}'' or the {\tt WEAVE} +processor for C \Web s is called something other than ``{\tt cweave}'' +on your computer system. The {\tt web-view-index} has calls to the Emacs' +function {\tt call-process}\null. The first argument to this function +is the name of the program that is to be run as a separate process. If +the program names of the {\tt WEAVE} processors differ on your system, +these lines will need to be changed accordingly in the function {\tt +web-view-index}\null. + +\bigskip +\leftline{\SS Viewing the Module Names} + +The user can also view the contents of the list of module names that +is maintained by {\tt web-mode}\null. When the command +\Command{M-x web-view-module-names-list}{v}{m}{3} +is issued, the list is displayed in another buffer. Some reformatting +is necessary. The user is free to peruse the list as much as he likes. +The results of issuing this command on Knuth's {\tt primes.web} is shown +in Figure~3\null. + +\midinsert +\verbatim +Fill table |p| with the first |m| prime numbers (11) (3) +Give to |j_prime| the meaning: |j|~is a prime number (22) (14) +If |p[n]| is a factor of~|j|, set |j_prime:=false| (26) (22) +Increase |j| until it is the next prime number (14) (11) +Initialize the data structures (16 18) (11) +Other constants of the program (5 19) (2) +Output a line of answers (10) (9) +Output a page of answers (9) (8) +Print table |p| (8) (3) +Print the first |m| prime numbers (3) (2) +Program to print the first thousand prime numbers (2) (1) +Update variables that depend on~|j| (20) (14) +Update variables that depend on~|ord| (21 25) (20) +Variables of the program (4 7 12 15 17 23 24) (2) +--**-Emacs: *Module Name (Defined In) (Used In)* (Web)--All------------------ +?endverbatim +\medskip +\centerline{{\bf Figure 3.}} +\endinsert + +The commands +\Command{M-x web-next-define}{n}{d}{3} +\Command{M-x web-next-use}{n}{u}{3} +\Command{M-x web-previous-define}{p}{d}{6} +and +\Command{M-x web-previous-use}{p}{u}{6} +can be invoked from the buffer where the module names are displayed or +they can be invoked from the buffer containing the \Web\ document. If +they are invoked from the former, the user selects a module name by +positioning the cursor anywhere on the line(s) where the module name of +interest is located. Once a module name has been selected, the user is +switched back to the buffer containing the \Web\ document at the module +where the most recently selected module name was next/previously defined +or used, whichever is appropriate, from point's current position. + +While in the \Web{} document, the ``Defined In'' and ``Used In'' lists +can be traversed with the commands +\Command{M-x web-next-define}{n}{d}{3} +which positions point at the beginning of the module where the most +recently selected module name was next defined, +\Command{M-x web-previous-define}{p}{d}{6} +which positions point at the beginning of the module where the most +recently selected module name was previously defined, +\Command{M-x web-next-use}{n}{u}{3} +which positions point at the beginning of the module where the most +recently selected module name was next used, and +\Command{M-x web-previous-use}{p}{u}{6} +which positions point at the beginning of the module where the most +recently selected module name was previously used. + +It should be noted that these commands prevent the user from running +off either end of either list. + +{\tt Web-mode} maintains a list of the form +$$\vbox{\tabskip0sp\halign{\hfil#&(``module-name-$#$''\quad% + (Defined In Modules)\quad(Used In Modules))\hfil\cr + (&1\cr &2\cr &\omit$\ldots$\hfil\cr &n\cr )\cr + }} +$$ +This list is collected automatically by {\tt web-mode} as well as +maintained. If the user feels that this list is in error at any time +during an editing session, the list can be recollected with the +command +\Command{M-x web-collect-module-names}{}{}{0} +\vfil\eject +\leftline{\SS Viewing the Major Section Names} + +The user can also view a list of the names of the major sections in +the \Web\ document and the module number where each major section +begins. The command +\Command{M-x web-view-section-names-list}{v}{s}{3} +collects the names of the major sections along with their module numbers +and displays them in another buffer. The user is switched over to this +buffer. The result of issuing this command on Knuth's {\tt primes.web} +is shown in Figure~4\null. + +\midinsert +\verbatim +Module# Section Name + 1 Printing primes: An example of \WEB + 3 Plan of the program + 5 The output phase + 11 Generating the primes + 22 The inner loop + 27 Index +--**-Emacs: *Section Names* (Web)----All------------------------------------ +?endverbatim +\medskip +\centerline{{\bf Figure 4.}} +\endinsert + +\vfil\eject +\leftline{\Bf Support for Change Files} +\bigskip +{\tt Web-mode} also provides support for {\tt change} files. The +command +\Command{M-x web-view-changed-modules-list}{v}{c}{3} +can be invoked in either the buffer containing the \Web\ document or the +buffer containing the {\tt change} file. It displays a list of modules +that have been changed in a separate window. + +The command +\Command{M-x web-edit-module}{e}{m}{3} +will insert the contents of the module that point is positioned in when +the command is invoked in the {\tt change} file in its proper position. +The entire module's contents are copied twice---once between {\tt @x @y} +and once between {\tt @y @z}. The user is positioned at the first line +after the {\tt @y}\null. This command is only available in the buffer +containing the \Web\ document. + +The command +\Command{M-x web-what-change}{w}{c}{3} +can only be invoked in the buffer containing the {\tt change} file. This +function displays a descriptive message informing the user of what +module in the \Web\ the change that point is positioned in corresponds +to. + +Movement within the {\tt change} file is accomplished with the commands: +\Command{M-x web-goto-change-corresponding-to-module}{g}{c}{6} +If a numeric argument is not provided, the user is prompted. Point is +positioned at the beginning of the change in the {\tt change} buffer +that corresponds to the module number given as an argument. +\Command{M-x web-next-change}{n}{c}{3} +This command positions point at the beginning of the next change in the +{\tt change} buffer. +\Command{M-x web-previous-change}{p}{c}{6} +This command positions point at the beginning of the previous change in +the {\tt change} buffer. + +The command \Command{M-x web-count-changes}{c}{c}{3} +will display the number of modules that have been changed. +\vfil\eject + +\leftline{\Bf Miscellaneous Functions} +\bigskip + +The function +\Command{M-x web-count-modules}{c}{m}{3} +displays in the minibuffer the total number of modules in the \Web\ +document that is currently being edited. + +The function +\Command{M-x web-count-sections}{c}{s}{3} +displays in the minibuffer the total number of sections in the \Web\ +document that is currently being edited. + +The command +\Command{M-x web-delimiter-match-check}{d}{m}{3} +looks at the entire +\Web\ document module by module. It determines if the delimiters +surrounding module names, namely, {\tt@\char`<} and {\tt@\char`>}, are +matched. If the delimiters do not match properly, a descriptive message +is printed in a temporary buffer. + +The function +\Command{M-x web-determine-characteristics}{d}{c}{3} +creates a table that shows the number of lines of commentary, +definition/format macros, and code in each module in the \Web\ document. +A message is displayed in the minibuffer indicating to the user which +module the function is currently working on. Once completed, the user is +switched to a buffer where the characteristics have been written. The +user is free to peruse this buffer using regular Emacs commands. + +{\tt Web-mode} also makes it easier to enter index entries. When +the function +\Command{M-x web-insert-index-entry}{i}{i}{3} +is issued, the user is prompted for two things: +\null\vskip\baselineskip +{\parskip=0sp + \item{1.} The type of font to be used (Roman, typewriter, or +user-defined). This determines the opening delimiter to the index +entry (either {\tt @\char`\^\rm , \tt @\char`.\rm , or \tt @\char`:}) and + \item{2.} The text of the index entry. +} + +\noindent The complete index entry is then placed on a new line. + +\vfil\eject + +The command +\Command{M-x web-rename-module}{r}{m}{3} +allows the user to rename a module. Point should be positioned on the +name that the user wishes to rename. The user is prompted for the new +name. The user is then given the option of renaming a single +occurrence, all occurrences, or is queried if each of the remaining +occurrences should be renamed. + +There are several functions in {\tt web-mode} that are invoked +automatically whenever a particular key is pressed. These functions +include: +\Command{M-x web-is-this-a-new-module-beginning}{}{}{0} +which is invoked whenever the {\tt @} key is pressed. The function +checks to see if the {\tt @} is at the beginning of a line. If it is, +the next character is read. If this next character is either a space, +newline, tab, or asterisk, then the {\tt @} in combination with the next +character constitutes the beginning of a new module. + +Another useful function that is invoked automatically is +\Command{M-x web-newline} {}{}{0} +which is invoked whenever the newline character is pressed. This +function positions point so that the next line has the same indentation +as the current line that is being terminated. + +One keybinding that Emacs' users are familiar with has been rebound to +another function. The keybinding {\tt C-x C-c} has been bound to +the {\tt web-mode} function +\Command{M-x web-mode-save-buffers-kill-emacs}{x}{c}{1} +Before this function makes a call to Emacs' {\tt +save-buffers-kill-emacs}, it completes the journal file that is +maintained by {\tt web-mode}. This journal file keeps track of what file +is being edited, who is editing it, when the editing began, when the +editing stopped, and a count of the number of times each of {\tt +web-mode}'s interactive functions were used. +% +\vfil\eject +% +\leftline{\Bf A Final Note} +\bigskip +Any suggestions for enhancements, problems with the existing +functions, or criticisms can be submitted to +\item{$\bullet$} the author ({\tt motl@cs.tamu.edu}) or +\item{$\bullet$} Bart Childs ({\tt bart@cs.tamu.edu})\null. +% +\bigskip\null\vskip\baselineskip +% +\leftline{\Bf References} +\bigskip +{\parskip2pt plus1pt minus1pt +\raggedright +\item{1.} Donald E.~Knuth, ``Literate Programming,'' {\it The Computer +Journal}, vol.~27, no.~2, May\ 1984, pp.~97--111. + +\item{2.} Bill Lewis, Dan LaLiberte, and the GNU Manual Group, {\it +The GNU Emacs Lisp Reference Manual}, Emacs Version 18 for \Unix\ Users, +Edition 1.01, Cambridge, MA: Free Software Foundation, Apr.~1990. + +\item{3.} Richard Stallman, {\it GNU Emacs Manual}, Fifth Edition, +Version 18 for \Unix\ Users, Cambridge, MA: Free Software Foundation, +Oct.~1986. + +% +\bigskip\null\vskip\baselineskip +% +\leftline{\Bf Supplementary Sources} +\bigskip\newcount\Itemno \Itemno=0 +\def\Item#1\Enditem{\global\advance \Itemno by 1 \item{\the\Itemno.} #1} + +\Item +{Adrian Avenarius and Siegfried Oppermann, + ``FWEB: A Literate Programming System for Fortran8x,'' + {\it SIGPLAN Notices,} + vol.~25, no.~1, Jan.~1990, pp.~52--58. +} +\Enditem + +\Item +{Jon Bentley, + ``Programming Pearls: Literate Programming,'' + {\it Communications of the ACM}, + vol.~29, no.~5, May~1986, pp.~364--369. +} +\Enditem + +\Item +{Jon Bentley and David Gries, + ``Programming Pearls: Abstract Data Types,'' + {\it Communications of the ACM}, + vol.~30, no.~4, Apr.~1987, pp.~284--290. +} +\Enditem + +\Item +{Jon Bentley, Donald E.~Knuth, and Doug McIlroy, + ``Programming Pearls: A Literate Program,'' + {\it Communications of the ACM}, + vol.~29, no.~6, Jun.~1986, pp.~471--483. +} +\Enditem + +\Item +{Marcus E.~Brown, + ``An Interactive Environment for Literate Programming,'' + Ph.D.\ Dissertation, Dept.\ of Computer Science, Texas A\&M University, + College Station, TX, Aug.~1988. +} +\Enditem + +\Item +{Marcus E.~Brown and Bart Childs, + ``An Interactive Environment for Literate Programming,'' +{\it Structured Programming}, vol.~11, no.~1, Jan.~1990, pp.~11--25. +} +\Enditem + +\Item +{Peter J.~Denning, + ``Announcing Literate Programming,'' + {\it Communications of the ACM}, + vol.~30, no.~7, Jul.~1987, p.~593. +} +\Enditem + +\Item +{Klaus Guntermann and Joachim Schrod, + ``\Web\ Adapted to C,'' + {\it TUGboat}, + vol.~7, no.~3, Oct.~1986, pp.~134--137. +} +\Enditem + +\Item +{Eric Hamilton, + ``Literate Programming: Expanding Generalized Regular Expressions,'' + {\it Communications of the ACM}, + vol.~31, no.~12, Dec.~1988, pp.~1376--1385. +} +\Enditem + +\Item +{David R.~Hanson, + ``Literate Programming: Printing Common Words,'' + {\it Communications of the ACM}, + vol.~30, no.~7, Jul.~1987, pp.~594--599. +} +\Enditem + +\Item +{Michael A.~Jackson, + ``Literate Programming: Processing Transactions,'' + {\it Communications of the ACM}, + vol.~30, no.~12, Dec.~1987, pp.~1000--1010. +} +\Enditem + +\Item +{Donald E.~Knuth, + {\it \MF: The Program}, + vol.~D of {\it Computers \& Typesetting}, + Reading, MA: Addison-Wesley Publishing Co., + 1986. +} +\Enditem + +\Item +{Donald E.~Knuth, + {\it \TeX: The Program}, + vol.~B of {\it Computers \& Typesetting}, + Reading, MA: Addison-Wesley Publishing Co., + 1986. +} +\Enditem + +\Item +{Donald E.~Knuth, + ``The \Web\ System of Structured Documentation,'' + Stanford Computer Science Report STAN-CS-980, + Dept.\ of Computer Science, + Stanford University, Stanford, CA, + Sep.~1983. +} +\Enditem + +\Item +{John A.~Krommes, + ``The \Web{} System of Structured Software Design and Documentation for + Fortran, Ratfor, and C,'' + Technical Report, Princeton University, Princeton, NJ, + Nov.~1989. Available by anonymous {\tt ftp} from + {\tt ss01.pppl.gov} in directory {\tt/pub/fweb}. +} +\Enditem + +\Item +{Silvio Levy, + ``\Web\ Adapted to C, Another Approach,'' + {\it TUGboat}, + vol.~8, no.~1, +\hfil\break + Apr.~1987, pp.~12--13. +} +\Enditem + +\Item +{Donald C.~Lindsay, + ``Literate Programming: A File Difference Program,'' + {\it Communications of the ACM}, + vol.~32, no.~6, Jun.~1989, pp.~740--752. +} +\Enditem + +\Item +{Charles Lins, + ``A First Look at Literate Programming,'' + {\it Structured Programming}, + vol.~10, no.~1, 1989, pp.~60--62. +} +\Enditem + +\Item +{Charles Lins, + ``An Introduction to Literate Programming,'' + {\it Structured Programming}, + vol.~10, no.~2, 1989, pp.~107--112. +} +\Enditem + +\Item +{Norman Ramsey, + ``Literate Programming: Weaving a Language-Independent \Web,'' + {\it Communications of the ACM}, + vol.~32, no.~9, Sep.~1989, pp.~1051--1055. +} +\Enditem + +\Item +{E.~W.~Sewell, + ``How to\/ {\tt MANGLE} Your Software: The\/ \Web\ System for + Modula-2,'' +\hfil\break + {\it TUGboat}, + vol.~8, no.~2, Jul.~1987, pp.~118--122. +} +\Enditem + +\Item +{E.~W.~Sewell, + {\it Weaving a Program: Literate Programming in WEB}, + New York, NY: Van Nostrand Reinhold, 1989. +} +\Enditem + +\Item +{Richard M.~Stallman, + ``EMACS: The Extensible, Customizable, Self-Doc\-u\-men\-ting Display + Editor,'' + in {\it Interactive Programming Environments}, + David R.~Barstow, +\hfil\break + Howard E.~Shroke, and Erik Sandewall, Eds., + New York, NY: McGraw-Hill Book Co., 1984, pp.~300--325. +} +\Enditem + +\Item +{Harold~Thimbleby, + ``Experiences of `Literate Programming' using {\tt cweb} (a variant + of Knuth's \Web),'' + {\it The Computer Journal}, + vol.~29, no.~3, Jun.~1986, pp.~201--211. +} +\Enditem + +\Item +{Sho-Huan Tung, + ``A Structured Method for Literate Programming,'' + {\it Structured Programming}, + vol.~10, no.~2, 1989, pp.~113--120. +} +\Enditem + +\Item +{Christopher J.~Van Wyk, + ``Literate Programming: An Assessment,'' + {\it Communications of the ACM}, + vol.~33, no.~3, Mar.~1990, pp.~361 and 365. +} +\Enditem + +}% end reduced parskip for references. +\vfil\eject +% +\centerline{\BF Glossary} +\bigskip +{\bf buffer} --- A buffer is the basic editing unit. In Emacs, a user can +have many buffers, however, only one can be edited at any one time. + +{\bf change file} --- This file contains information that is used to +override portions of the \Web{} file. Each ``change'' consists of +repeating the lines from the \Web{} file that require modification and +the new lines that are to replace the old ones. The {\tt TANGLE} and +{\tt WEAVE} processors have the ability to scan both the \Web{} and +change files so that the new lines replace the old lines at the +appropriate places in the resulting high-level language and \TeX{} codes. + +{\bf major section} --- A major section is a ``starred'' module; that is, +it is a module that begins with the symbols `{\tt@*}'. + +{\bf minibuffer} --- The bottom line of the screen when using Emacs. +This area is used to display arguments to commands, commands that are +typed in from the keyboard, and messages to the user. For commands that +require arguments, the minibuffer area can be used for prompting as well. + +{\bf module} --- A module begins with the pair of symbols `{\tt@*}', +`{\tt@\char`<}', `{\tt@\BS t}', `{\tt@\BS n}', or `{\tt@\char`\ }'. A +module ends when the next module begins or the end of the file, whichever +comes first. + +{\bf numeric argument} --- A number which is specified before a command +to alter the effect of the command. + +{\bf section} --- A section is the same as a major section. + +{\bf web file} --- contains the source of the \Web\null. The file +consists of the limbo portion and the individual units that comprise the +\Web{} called modules. A module consists of a commentary, definition, and +code parts, any two of which can be empty. + +\vfil\eject + +\centerline{\BF Appendix A} + +% SLIDES can be prepared using TeX without resorting to SliTeX. +% SliTeX is an excellent way to do many things that will not show +% in this macro package. +% +% To use this you should start off with: +% \magnification=\magstep5 or 6. Try it and pick one. +% Look at the other parameters in the slides.tex sample. +% Now tex away! +% +% The following is taken from the first 120 lines of MANMAC.TeX. +% A few lines have been deleted. +% This is MANMAC.TEX in text format, as of Mar 31, 1986. +% Macros for The TeXbook + +\catcode`@=11 % borrow the private macros of PLAIN (with care) + +\font\tentex=cmtex10 + +\font\ninerm=cmr9 +\font\eightrm=cmr8 +\font\sixrm=cmr6 + +\font\ninei=cmmi9 +\font\eighti=cmmi8 +\font\sixi=cmmi6 +\skewchar\ninei='177 \skewchar\eighti='177 \skewchar\sixi='177 + +\font\ninesy=cmsy9 +\font\eightsy=cmsy8 +\font\sixsy=cmsy6 +\skewchar\ninesy='60 \skewchar\eightsy='60 \skewchar\sixsy='60 + +\font\ninebf=cmbx9 +\font\eightbf=cmbx8 +\font\sixbf=cmbx6 + +\font\ninett=cmtt9 +\font\eighttt=cmtt8 + +\hyphenchar\tentt=-1 % inhibit hyphenation in typewriter type +\hyphenchar\ninett=-1 +\hyphenchar\eighttt=-1 + +\font\ninesl=cmsl9 +\font\eightsl=cmsl8 + +\font\nineit=cmti9 +\font\eightit=cmti8 + +\newfam\ssfam +\font\tenss=lcmss8 scaled 1440 +\font\niness=lcmss8 scaled 1200 +\font\eightss=lcmss8 + +\newskip\ttglue +\def\X {\def\rm{\fam0\tenrm}% look at tenpoint in the TeXbook + \textfont0=\tenrm \scriptfont0=\sevenrm \scriptscriptfont0=\fiverm + \textfont1=\teni \scriptfont1=\seveni \scriptscriptfont1=\fivei + \textfont2=\tensy \scriptfont2=\sevensy \scriptscriptfont2=\fivesy + \textfont3=\tenex \scriptfont3=\tenex \scriptscriptfont3=\tenex + \def\it{\fam\itfam\tenit}% + \textfont\itfam=\tenit + \def\sl{\fam\slfam\tensl}% + \textfont\slfam=\tensl + \def\bf{\fam\bffam\tenbf}% + \textfont\bffam=\tenbf \scriptfont\bffam=\sevenbf + \scriptscriptfont\bffam=\fivebf + \def\tt{\fam\ttfam\tentt\raggedright}% + \textfont\ttfam=\tentt + \tt \ttglue=.5em plus.25em minus.15em + \def\SS{\fam\ssfam\tenss}% + \textfont\ssfam=\tenss + \normalbaselineskip=12pt + \setbox\strutbox=\hbox{\vrule height8.5pt depth3.5pt width\z@}% + \normalbaselines \parskip=\normalbaselineskip \rm} + +\def\IX {\def\rm{\fam0\ninerm}% look at ninepoint in the TeXbook + \textfont0=\ninerm \scriptfont0=\sixrm \scriptscriptfont0=\fiverm + \textfont1=\ninei \scriptfont1=\sixi \scriptscriptfont1=\fivei + \textfont2=\ninesy \scriptfont2=\sixsy \scriptscriptfont2=\fivesy + \textfont3=\tenex \scriptfont3=\tenex \scriptscriptfont3=\tenex + \def\it{\fam\itfam\nineit}% + \textfont\itfam=\nineit + \def\sl{\fam\slfam\ninesl}% + \textfont\slfam=\ninesl + \def\bf{\fam\bffam\ninebf}% + \textfont\bffam=\ninebf \scriptfont\bffam=\sixbf + \scriptscriptfont\bffam=\fivebf + \def\tt{\fam\ttfam\ninett\raggedright}% + \textfont\ttfam=\ninett + \tt \ttglue=.5em plus.25em minus.15em + \def\SS{\fam\ssfam\niness}% + \textfont\ssfam=\niness + \normalbaselineskip=11pt + \setbox\strutbox=\hbox{\vrule height8pt depth3pt width\z@}% + \normalbaselines \parskip=\normalbaselineskip \rm} + +\def\VIII {\def\rm{\fam0\eightrm}% look at eightpoint in the TeXbook + \textfont0=\eightrm \scriptfont0=\sixrm \scriptscriptfont0=\fiverm + \textfont1=\eighti \scriptfont1=\sixi \scriptscriptfont1=\fivei + \textfont2=\eightsy \scriptfont2=\sixsy \scriptscriptfont2=\fivesy + \textfont3=\tenex \scriptfont3=\tenex \scriptscriptfont3=\tenex + \def\it{\fam\itfam\eightit}% + \textfont\itfam=\eightit + \def\sl{\fam\slfam\eightsl}% + \textfont\slfam=\eightsl + \def\bf{\fam\bffam\eightbf}% + \textfont\bffam=\eightbf \scriptfont\bffam=\sixbf + \scriptscriptfont\bffam=\fivebf + \def\tt{\fam\ttfam\eighttt\raggedright}% + \textfont\ttfam=\eighttt + \tt \ttglue=.5em plus.25em minus.15em + \def\SS{\fam\ssfam\eightss}% + \textfont\ssfam=\eightss + \normalbaselineskip=9pt + \setbox\strutbox=\hbox{\vrule height7pt depth2pt width\z@}% + \normalbaselines \parskip=\normalbaselineskip \rm} +% +% This is borrowed and extended from plain.tex +% +% 0 1 2 3 4 5 +\def\magstep#1{\ifcase#1 \@m\or 1200\or 1440\or 1728\or 2074\or 2488\or + 2986\or 3583\or 4300\or 5160 \fi\relax} +% 6 7 8 9 +\catcode`@=12 +\message{} +\message{I suggest you set eight point, VIII} +\message{It also sets raggedright} +\message{} + +{ + \VIII + \newbox\AlphaCommands + \setbox\AlphaCommands=% + \vbox{\tabskip0sp\offinterlineskip + \def\tablerule{\noalign{\hrule}} + \halign{\vrule#&\strut\quad\tt#\hfil\quad + &\vrule#&\quad\hfil\tt#\hfil\quad + &\vrule#\cr + \multispan5\hfil Alphabetized Listing of {\tt web-mode} Commands\hfil\cr + \noalign{\vskip6truept} + \tablerule + &\bf Command&&\bf\hidewidth Key Binding\hidewidth&\cr + \tablerule + &web-change-file&&ESC C-c C-f&\cr\tablerule + &web-collect-module-names&&n/a${}^1$&\cr\tablerule + &web-count-changes&&ESC C-c C-c&\cr\tablerule + &web-count-modules&&ESC C-c C-m&\cr\tablerule + &web-count-sections&&ESC C-c C-s&\cr\tablerule + &web-delimiter-match-check&&ESC C-d C-m&\cr\tablerule + &web-determine-characteristics&&ESC C-d C-c&\cr\tablerule + &web-edit-module&&ESC C-e C-m&\cr\tablerule + &web-file&&ESC C-w C-f&\cr\tablerule + &web-goto-change-corresponding-to-module&&ESC C-g C-c&\cr\tablerule + &web-goto-module&&ESC C-g C-m&\cr\tablerule + &web-goto-section&&ESC C-g C-s&\cr\tablerule + &web-include-file&&ESC C-i C-f&\cr\tablerule + &web-insert-index-entry&&ESC C-i C-i&\cr\tablerule + &web-insert-module-name&&n/a${}^2$&\cr\tablerule + &web-is-this-a-new-module-beginning&&n/a${}^3$&\cr\tablerule + &web-mode&&n/a${}^1$&\cr\tablerule + &web-mode-save-buffers-kill-emacs&&C-x C-c&\cr\tablerule + &web-newline&&n/a${}^4$&\cr\tablerule + &web-next-change&&ESC C-n C-c&\cr\tablerule + &web-next-define&&ESC C-n C-d&\cr\tablerule + &web-next-index&&ESC C-n C-i&\cr\tablerule + &web-next-module&&ESC C-n C-m&\cr\tablerule + &web-next-section&&ESC C-n C-s&\cr\tablerule + &web-next-use&&ESC C-n C-u&\cr\tablerule + &web-previous-change&&ESC C-p C-c&\cr\tablerule + &web-previous-define&&ESC C-p C-d&\cr\tablerule + &web-previous-index&&ESC C-p C-i&\cr\tablerule + &web-previous-module&&ESC C-p C-m&\cr\tablerule + &web-previous-section&&ESC C-p C-s&\cr\tablerule + &web-previous-use&&ESC C-p C-u&\cr\tablerule + &web-rename-module&&ESC C-r C-m&\cr\tablerule + &web-view-changed-modules-list&&ESC C-v C-c&\cr\tablerule + &web-view-index&&ESC C-v C-i&\cr\tablerule + &web-view-module-names-list&&ESC C-v C-m&\cr\tablerule + &web-view-section-names-list&&ESC C-v C-s&\cr\tablerule + &web-what-change&&ESC C-w C-c&\cr\tablerule + &web-what-module&&ESC C-w C-m&\cr\tablerule + &web-what-section&&ESC C-w C-s&\cr\tablerule + \noalign{\vskip6truept} + \multispan5\rm${}^1$ No keybinding for this function.\hfil\cr + \multispan5\rm${}^2$ Invoked whenever {\tt\char`<} is pressed.\hfil\cr + \multispan5\rm${}^3$ Invoked whenever {\tt\char`@} is pressed.\hfil\cr + \multispan5\rm${}^4$ + Invoked whenever the newline character is pressed. + Suggested by Donald Knuth.\hidewidth\hfil\cr + } + } + + $$\box\AlphaCommands$$ +} + +With the exception of two functions +\item{$\bullet$} {\tt web-file} and +\item{$\bullet$} {\tt web-mode-save-buffers-kill-emacs} + +\noindent notice that all keybindings have a similar form that consists +of three parts. Each command is prefaced with the escape key. The next +part of the keybinding is the control key followed by the first letter +of the second word of the function name. The second part of the +keybinding is the control key followed by the first letter of the third +word of the function name. + +{\VIII + \newbox\Files + \setbox\Files=\vbox{\hbox to 103truept{\hfil Movement Among\hfil} + \hbox to 103truept{\hfil Files\hfil} + } + \ht\Files=0sp \wd\Files=0sp + + \newbox\Modules + \setbox\Modules=\vbox{\hbox to 103truept{\hfil Movement Among\hfil} + \hbox to 103truept{\hfil Modules\hfil} + } + \ht\Modules=0sp \wd\Modules=0sp + + \newbox\Sections + \setbox\Sections=\vbox{\hbox to 103truept{\hfil Interactive Access to\hfil} + \hbox to 103truept{\hfil and\hfil} + \hbox to 103truept{\hfil Movement Among\hfil} + \hbox to 103truept{\hfil Sections\hfil} + } + \ht\Sections=0sp \wd\Sections=0sp + + \newbox\Index + \setbox\Index=\vbox{\hbox to 103truept{\hfil Interactive Access to\hfil} + \hbox to 103truept{\hfil Index\hfil} + } + + \ht\Index=0sp \wd\Index=0sp + + \newbox\ModNames + \setbox\ModNames=\vbox{\hbox to 103truept{\hfil Interactive Access\hfil} + \hbox to 103truept{\hfil to Modules\hfil} + } + + \ht\ModNames=0sp \wd\ModNames=0sp \dp\ModNames=0sp + + \newbox\Change + \setbox\Change=\vbox{\hbox to 103truept{\hfil Change File\hfil} + \hbox to 103truept{\hfil Editing and Movement\hfil} + } + \ht\Change=0sp \wd\Change=0sp + + \newbox\Structure + \setbox\Structure=\vbox{\hbox to 103truept{\hfil{\tt Web}\hfil} + \hbox to 103truept{\hfil Structure\hfil} + \hbox to 103truept{\hfil Information\hfil} + } + \ht\Structure=0sp \wd\Structure=0sp + + \newbox\Misc + \setbox\Misc=\vbox{\hbox to 103truept{\hfil Miscellaneous\hfil}} + \ht\Misc=0sp \wd\Misc=0sp + + \def\tablerule{\noalign{\hrule}} + \newbox\FuncCommands + \setbox\FuncCommands=% + \vbox{\offinterlineskip\tabskip0sp% + \halign{\vrule#% + &\quad\hbox to 103truept{\hfil#\hfil}\quad% + &\vrule#% + &\quad\hbox to 200truept{\tt#\hfil}\quad% + &\vrule#% + &\quad\tt\hfil#\hfil\quad% + &\vrule#\cr + \multispan7\hfil Alphabetized Listing of {\tt web-mode} Commands by + Functionality\hfil\cr + \noalign{\vskip6truept} + \tablerule + &\strut\bf\hfil Functionality\hfil + &&\bf Command&&\bf\hidewidth Key Binding\hidewidth&\cr + \tablerule + % + &\omit\quad\strut\box\Files&&web-change-file&&ESC C-c C-f&\cr + &&&\strut web-file&&ESC C-w C-f&\cr + &&&\strut web-include-file&&ESC C-i C-f&\cr\tablerule + % + &\omit\quad\strut\box\Modules&&web-goto-module&&ESC C-g C-m&\cr + &&&\strut web-next-module&&ESC C-n C-m&\cr + &&&\strut web-previous-module&&ESC C-p C-m&\cr\tablerule + % + &\omit\quad\strut\raise6truept\box\Sections% + &&web-goto-section&&ESC C-g C-s&\cr + &&&\strut web-next-section&&ESC C-n C-s&\cr + &&&\strut web-previous-section&&ESC C-p C-s&\cr + &&&\strut web-view-section-names-list&&ESC C-v C-s&\cr\tablerule + % + &\strut Inserting a Module&&web-insert-module-name% + &&n/a${}^{1\mathstrut}$&\cr + \tablerule + % + &\omit\quad\strut\box\Index&&web-next-index&&ESC C-n C-i&\cr + &&&\strut web-previous-index&&ESC C-p C-i&\cr + &&&\strut web-view-index&&ESC C-v C-i&\cr\tablerule + % + &&&\strut web-collect-module-names&&n/a${}^{2\mathstrut}$&\cr + &&&\strut web-next-define&&ESC C-n C-d&\cr + &\omit\quad\strut\raise6truept\box\ModNames&&web-next-use&&ESC C-n C-u&\cr + &&&\strut web-previous-define&&ESC C-p C-d&\cr + &&&\strut web-previous-use&&ESC C-p C-u&\cr + &&&\strut web-view-module-names-list&&ESC C-v C-m&\cr\tablerule + % + &&&\strut web-edit-module&&ESC C-e C-m&\cr + &\omit\quad\strut\raise6truept\box\Change% + &&web-goto-change-corresponding-to-module&&ESC C-g C-c&\cr + &&&\strut web-next-change&&ESC C-n C-c&\cr + &&&\strut web-previous-change&&ESC C-p C-c&\cr\tablerule + % + &&&\strut web-count-changes&&ESC C-c C-c&\cr + &&&\strut web-count-modules&&ESC C-c C-m&\cr + &&&\strut web-count-sections&&ESC C-c C-s&\cr + &\omit\quad\strut\raise6truept\box\Structure% + &&web-delimiter-match-check&&ESC C-d C-m&\cr + &&&\strut web-determine-characteristics&&ESC C-d C-c&\cr + &&&\strut web-view-changed-modules-list&&ESC C-v C-c&\cr + &&&\strut web-what-change&&ESC C-w C-c&\cr + &&&\strut web-what-module&&ESC C-w C-m&\cr + &&&\strut web-what-section&&ESC C-w C-s&\cr\tablerule + % + &&&\strut web-insert-index-entry&&ESC C-i C-i&\cr + &&&\strut web-is-this-a-new-module-beginning&&n/a${}^3$&\cr + &\omit\quad\strut\box\Misc&&web-mode&&n/a${}^2$&\cr + &&&\strut web-mode-save-buffers-kill-emacs&&C-x C-c&\cr + &&&\strut web-newline&&n/a${}^4$&\cr + &&&\strut web-rename-module&&ESC C-r C-m&\cr\tablerule + \noalign{\vskip6truept} + \multispan7\rm${}^1$ Invoked whenever {\tt\char`<} is pressed.\hfil\cr + \multispan7\rm${}^2$ No keybinding for this function.\hfil\cr + \multispan7\rm${}^3$ Invoked whenever {\tt\char`@} is pressed.\hfil\cr + \multispan7\rm${}^4$ + Invoked whenever the newline character is pressed. + Suggested by Donald Knuth\hfil\cr + } + } + $$\box\FuncCommands$$ +} + +The non-interactive functions in {\tt web-mode} are: +\medskip +{\parindent0sp\parskip0sp\tt\obeylines + web-any-modules-undefined-initially + web-append-a-stub-module + web-binary-search-of-names + web-check-if-buffer-is-one-of-the-web-files + web-collect-list-of-changed-module-numbers + web-collect-location-of-modules + web-collect-module-names-in-buffer + web-collect-section-names + web-convert-list-to-string + web-count-the-matches + web-determine-characteristics-for-buffer + web-determine-module-name-ending + web-display-module-names + web-eliminate-control-sequences + web-eliminate-white-space + web-initialize-location-of-module-vector + web-initialize-module-names-list + web-insert-limbo-material + web-journal + web-next-or-previous-define-or-use + web-next-or-previous-index + web-options-for-module-name-insertion + web-reformat-the-index + web-update-the-location-of-module-vector + web-update-the-module-name-defined-in-used-in-list + web-write-module-names-to-a-file +} +\vfil\eject +\centerline{\BF Appendix B} +\bigskip +The global variables used in {\tt web-mode} are: +\medskip +{\parindent0sp\parskip0sp\tt\obeylines +web-buffer-name +web-change-buffer-name +web-default-directory +web-defined-in-occurrence +web-defined-in-used-in-location +web-files +web-index-buffer-name +web-index-entry +web-interactive-function-usage +web-interactive-functions +web-journal-on +web-location-in-selected-index-entry-occurrences +web-location-of-module +web-max-number-of-modules +web-mode-map +web-module-begins +web-module-changed-then-goto-change +web-module-name +web-module-name-defined-in-used-in +web-module-names +web-number-of-lines-in-window +web-number-of-module-names +web-number-of-modules-in-file +web-selected-index-entry-occurrences +web-selected-module-name +web-used-in-occurrence +} + +The documentation for the above can be viewed at any time by issuing +the command +$$\line{\hskip\parindent\tt M-x describe-variable\hfil + \kern2pt\hbox{\vrule\vtop{\vbox{\hrule + \hbox{\strut\kern2pt{\tt C-h v}\kern2pt}} + \hrule}\vrule}} +$$ +At the prompt, the name of the variable of interest should be entered. + +\vfil\eject + +\centerline{\BF Appendix C} +\bigskip +In order to get {\tt WEAVE} to create a separate file containing the +index and module names, the following changes were made to module 239: + +\verbatim +@x +@* Phase three processing. +We are nearly finished! \.{WEAVE}'s only remaining task is to write out the +index, after sorting the identifiers and index entries. + +@<Phase III: Output the cross-reference index@>= +phase_three:=true; print_nl('Writing the index...'); +if change_exists then + begin finish_line; @<Tell about changed modules@>; + end; +finish_line; out4("\")("i")("n")("x"); finish_line; +@.\\inx@> +@<Do the first pass of sorting@>; +@<Sort and output the index@>; +out4("\")("f")("i")("n"); finish_line; +@.\\fin@> +@<Output all the module names@>; +out4("\")("c")("o")("n"); finish_line; +@.\\con@> +print('Done.'); +@y +@* Phase three processing. +We are nearly finished! \.{WEAVE}'s only remaining task is to write out the +index, after sorting the identifiers and index entries. + +If the user has set the |no_xref| flag (the -x option on the command line), +just finish off the page, omitting the index, module name list, and table of +contents. + +@<Phase III: Output the cross-reference index@>= +if no_xref then begin + finish_line; + out("\"); out5("v")("f")("i")("l")("l"); + out4("\")("e")("n")("d"); + finish_line; + end +else begin +phase_three:=true; print_nl('Writing the index...'); +finish_line; +out("\"); out5("i")("n")("p")("u")("t"); out(" "); +out5("I")("N")("D")("E")("X"); +finish_line; +out("\"); out5("i")("n")("p")("u")("t"); out5(" ")("M")("O")("D")("U"); +out5("L")("E")("_")("N")("A"); out3("M")("E")("S"); +finish_line; +rewrite(tex_file,'INDEX.tex'); +if change_exists then + begin @<Tell about changed modules@>; + end; +finish_line; finish_line; out4("\")("i")("n")("x"); finish_line; +@.\\inx@> +@<Do the first pass of sorting@>; +@<Sort and output the index@>; +out4("\")("f")("i")("n"); finish_line; +@.\\fin@> +rewrite(tex_file,'MODULE_NAMES.tex'); +@<Output all the module names@>; +out4("\")("c")("o")("n"); finish_line; +@.\\con@> +print('Done.'); +end; +@z +?endverbatim +\vfil\eject + +Similarly, module 181 had to be changed in the {\tt WEAVE} for \Web s +written in C\null. The changes are: + +\verbatim +@x +@ @c phase_three() { +if (no_xref) { + finish_line(); + out_str("\\vfill\\end"); + finish_line(); +} +else { + phase=3; printf("\nWriting the index..."); + if (change_exists) { + finish_line(); @<Tell about changed modules@>; + } + finish_line(); out_str("\\inx"); finish_line(); +@.\\inx@> + @<Do the first pass of sorting@>; + @<Sort and output the index@>; + out_str("\\fin"); finish_line(); +@.\\fin@> + @<Output all the module names@>; + out_str("\\con"); finish_line(); +@.\\con@> +} +printf("Done."); +check_complete(); /* was all of the change file used? */ +} +@y +@ @c phase_three() { +if (no_xref) { + finish_line(); + out_str("\\vfill\\end"); + finish_line(); +} +else { + phase=3; printf("\nWriting the index..."); + finish_line(); + out_str("\\input INDEX"); finish_line(); finish_line(); + out_str("\\input MODULE_NAMES"); finish_line(); fclose(tex_file); + if ((tex_file=fopen("INDEX.tex","w"))==NULL) + fatal("! Cannot open ouput file ","INDEX.tex"); + if (change_exists) { @<Tell about changed modules@>; + finish_line(); finish_line(); } + out_str("\\inx"); finish_line(); +@.\\inx@> + @<Do the first pass of sorting@>; + @<Sort and output the index@>; + out_str("\\fin"); finish_line(); fclose(tex_file); +@.\\fin@> + if ((tex_file=fopen("MODULE_NAMES.tex","w"))==NULL) + fatal("! Cannot open ouput file ","MODULE_NAMES.tex"); + @<Output all the module names@>; + out_str("\\con"); finish_line(); fclose(tex_file); +@.\\con@> +} +printf("Done."); +check_complete(); /* was all of the change file used? */ +} +@z +?endverbatim + +\bye |