Contents 1 Introduction 3 2 Installation 4 3 Using Web-mode 5 4 Book Terminology and Automatic Happenings 6 5 Movement Within the WEB 7 6 Movement Amo

Transcription

1 A User's Manual for GNU Emacs' Web-mode Mark Motl & Bart Childs Department of Computer Science TEXas A&M University Revision 3.0- October 5, 1998 Summary This is a user's manual for Web-mode, an Emacs mode for the WEB style of Literate Programming. This style of programming was introduced by Don Knuth when he wrote TEX82. The most recent changes include: mouse support, pull down menus, hilit usage, and completion in a number of cases that signicantly reduce the needed typing. The current versions have the menu and color/hilit codes integrated. We are using Web-mode with Gnu Emacs versions 19.xx on a wide array of computers. We use it on PC class machines that are based on 386 and newer systems and various unix systems. To our knowledge, we do not know of a Macintosh with a full function Emacs that supports ELisp, the version of Lisp that extensions to Emacs are written in. Use, enjoy, and let us know of constructive criticisms. We hope to x errors quickly and will make evolutionary changes only with deliberation. Edsger Dijkstra once said \if you want to make a user interface more dicult to use, add functionality to it." Change for the sake of change is not planned.

2 Contents 1 Introduction 3 2 Installation 4 3 Using Web-mode 5 4 Book Terminology and Automatic Happenings 6 5 Movement Within the WEB 7 6 Movement Among the Buffers 8 7 Inserting a Section Name 9 8 Additional Navigation Means 11 9 Support for Change Files Outline Mode Miscellaneous Functions Web-mode Menus Using Color Within web-mode An Example A Final Note References 32 A Adding Functionality to web-mode 34 B Basic Information Like Variables, etc. 35 C Changes To The WEB Processors 36 D Debugging, Hopefully 37 E Elementary.emacs 38 F Frequently Asked Questions, (FAQ) 39 G Glossary 40 H Help for web-mode 42 I Index 42 2

3 1 Introduction This document is a companion to web-modex.el, a collection of GNU Emacs Lisp functions designed to customize GNU Emacs so that it is sensitive to a WEB document. It is assumed that the reader is already familiar with the WEB style of literate programming, the general format of a WEB source, and the rules of WEB, FWEB, CWEB, or a similar one. The intent in the design of web-mode is sensitivity to WEB independent of the high level language. Thus, it works with Knuth's original WEB with Pascal, CWEB, FWEB, and some similar systems. The basic Emacs functionality is maintained along with showing matched delimiters and continuing indentation. The functions that web-mode provides include: the indices of variables and sections provided by weave, outline editing, navigation by chapter and section, preloading the search string when using indices, and automatic completion in some places. Most of these commands have convenient key-bindings or can be invoked by the use of function keys and pull-down menus. The soures of this should be accompanied by a le template.tex which can be used to make a convenient overlay for function key usage. Throughout this document, I will use the symbology used by Emacs. For example, the find-file command can be entered two dierent ways M-x find-file C-x C-f The rst way of entering the command is to actually type the command as shown above. Press the META key (on some terminals this may be the ESC key); next press the x key; nally, enter the characters 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 C- refers to the CTRL key. Press and hold down the CTRL key and then press the x key followed by holding down the CTRL key and then pressing the 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 M-x what-line do not have a keybinding and hence must be entered by typing in the command name. All commands that are WEB extensions have been prexed with \web-". The outline mode commands violate this, but the names were not changed because they were adapted from an existing mode. 3

4 2 Installation The installation instructions are really quite simple. To simplify this manual we will assume that these instructions are followed. The les web-modex.el,.emacs, limbol.sty, and limbol.material are required. The.emacs le is the version normally used at Texas A&M and should be adapted to your site(s). If we have done our work correctly, it is the only le you have to edit for each user. There are a number of alternative versions of some of the lines that you may have to edit (commented out of course.) Notice that we use web-modex.el. The X is in honor of X-windows. The current versions of emacs for Windows-NT and '95 have good support of windowing, pull-down menus, mice,... The web-mode.el is still there for version 19 without windowing, it is not supported. Notice that there are two sets of les that have the limbo in the name. The les limbol.material and limbol.sty are associated with the use of LATEX. I do almost all my work using FWEB since it supports the C's and Fortran`s for real work. John Krommes' FWEB has excellent support of LATEX and that is now my default system. Please note the usage of the les fweb.sty,.fweb, and fwebnum.sty. 1. Select a directory for the home of these les which can be shared by all users, say: /usr/local/lib/web. Place limbol.sty in that directory. Place web-modex.el in the standard place for emacs lisp codes. It is recommended that you use that site-lisp standard directory because then the path does not have to be coded in the.emacs le. Issue the following command from within emacs: M-x byte-compile-file The user will be prompted for the name of the le. Respond with web-modex.el. This will create a new le named web-modex.elc. (This can no longer be done in batch mode because while compiling it will check on some windows functions that are not available in batch.) Now, make sure that everybody can read and execute the les you have in this directory. Everybody with an appropriate.emacs le in their home directory will automatically be able to use web-mode with their les ending in.web or.w You may have to make some changes as detailed in Appendix E. Appendix E contains changes that are typical `installation setups.' 2. Take BC.emacs, rename it.emacs and place it in your root directory (probably incorporate it into your current version of the same le.) The editing of the.emacs le reects the name of the directory and some personal preferences. Appendix E is a more detailed description of this le and changes you can make. 3. Each user should select a directory to put some common styles,... The les that should go in this directory should be fweb.sty and limbol.material as a minimum. The user may also wish to personalize the limbol.sty le and hard code it into the limbol.material. This is not recommended unless the user never shares work. 4

5 3 Using Web-mode One purpose of web-mode is to assist in creating and editing WEBs. Another is to edit existing WEBs that may or may not have been created using web-mode. 3.1 Creating a New WEB If a WEB is being created, Emacs will need to be started with an empty le. For example, if the name of the new WEB is my.web, you would enter the UNIX command % emacs my.web The defaults set in the le.emacs will specify which le to use a the default outline of the WEB you are creating. I normally use limbol.material, but in some cases I use (with Pascal) limbo.material. You can modify the.emacs startup le to personalize this. The user is prompted for the title of the WEB. This is not intended to be the name of the le, but a better name like, say the title of a book about the program being written. The command invoking the editor showed an assumption that we feel should be honored. We recommend that the names of WEB's end with.web. We also allow the use of the extension.w because that is how CWEB is distributed, but doesn't that seem \illiterate?" We recommend endings like.hweb for included les. We (assume you are commands available in CWEB and FWEB). It seems more literate! These are not available in the original.web because of the Pascal standard(?) of Editing an Existing WEB If you wish to use web-mode on an existing WEB, say primes.web, you would begin by invoking Emacs with the UNIX command % emacs primes.web When the function web-mode is executed, it will perform some initialization of various data structures. A list of the section names is collected. If web-mode detects that a section name has been used but never dened, a \stub" section may be inserted at the end of the chapter in which it was rst used (see Appendix E). A stub section @<Name of undefined section@>= Web-mode also reads the CHange le that accompanies the WEB currently being edited. If there is no CHange le, one is created; however, this le is \saved" only if it is modied. 5

6 4 Book Terminology and Automatic Happenings The user should understand that we are using a `book model' for a WEB. The basic element of a WEB is a section which is roughly parallel to a paragraph in a book. The `major sections' or group of sections corresponds to a chapter in a book. Chapter titles will be in the table of contents. We have an extension of the book model in that many sections will have `names' that will appear in an index. Technical books may have subjects of paragraphs in an index. Sections are really more like \pairs of paragraphs." Each section may have documentation, denitions, and code (must have at least one or it would be trivial.) There are several functions in web-mode that are invoked automatically whenever a particular key is pressed. These functions include: web-at-sign-processing which is invoked whenever key is pressed. The function checks to see if 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 in combination with the next character constitutes the beginning of a new section. Another useful function that is invoked automatically is web-newline 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. This will be almost invisible to the user, except for the results. By default, web-mode maintains a journal le. This le contains the user's name, the name of the le being edited, the start and stop times of the editing session, total time in web-mode, and a count of each of the interactive web-mode functions invoked during the editing session. The collection of this le is governed by the Boolean variable web-journal-on which is set to t (true). This can be turned o by changing a line in.emacs to (setq web-journal-on nil). The default of creating \stubs" was done to keep the weave and tangle processors from generating warning/error messages for the neophyte users. This is easily supressed by the obvious editing of the.emacs le, look for \stub". There are many other functions of web-mode that are invoked by key sequences, function keys, and/or pull-down menus. 6

7 5 Movement Within the WEB The user can goto any section or chapter at any time by issuing either: M-x web-goto-section C-c g s S-f1 M-x web-goto-chapter C-c g c C-f1 respectively. The user is then prompted for the section or chapter number. Invalid section numbers are useful too. If the user enters zero or a negative section number, then the current section is displayed with its rst line at the top of the screen. If a section number larger than the number of sections is input, then the last section is selected. Sections are always displayed with point moving to the beginning of that section or chapter in the WEB. The command can also be entered with a numeric argument prex which some experienced Emacs users may wish to use. If the change le has an entry for the destination section, a message is printed in the minibuer stating that the destination section has been edited. (See the section on \Support for CHange Files.) The user can also goto the next or previous section or chapter by entering the commands: M-x web-next-section C-c n s S-f2 M-x web-previous-section C-c p s S-f3 M-x web-next-chapter C-c n c C-f2 M-x web-previous-chapter C-c p c C-f4 If there is no next or previous section (or chapter), an appropriate message is displayed in the minibuer; otherwise, point moves to the beginning of the next or previous section (or chapter), appropriately. The user can determine the section or chapter (number) that point is positioned within by the commands M-x web-which-section C-c w s S-f4 M-x web-which-chapter C-c w c C-f4 Also, see the section on \Support for CHange Files." are Two additional functions are often used with the other commands in this section. They M-x web-count-sections C-c # s M-x web-count-chapters C-c # c display in the minibuer the total number of sections/chapters in the WEB document that is currently being edited. These commands are available in the pull-down \navigate" menus. 7

8 6 Movement Among the Buffers Several commands facilitate movement among the buers that are active in editing the WEB document. These commands work from the WEB le, CHange le, include les, and buers containing indices. When these commands are executed, the position of point in that buer will be its position during the last visit. If that buer exists and has not been visited, then point will be at the rst character in the buer. The user can switch to the buer containing the CHange le by issuing the command M-x web-goto-buffer-change-file C-c b c S-f8 Similarly, the user can switch to the buer containing the WEB le at any time with the command M-x web-goto-buffer-web-file C-c b w S-f6 The user can switch to any of the include les with the command M-x web-goto-buffer-include-file C-c b i S-f7 This command takes a numeric argument. For example, giving the function an argument of 1 would cause the buer containing the contents of the rst include le command (@i) encountered in the CWEB to become the current buer. Unfortunately, web-mode can be confusing as to which buer you want. In particular, if there are multiple includes, how does one know which one to go to? Fortunately a solution is provided via the command: M-x buffer-menu C-x C-b When invoked, this command opens a window containing a list comprised of the following les: the WEB le, the CHange le, and the include les. The user types the command `C-x o' to change the point to the window with the list of les. Then, the user uses the next (and previous) line command to place the point of the desired buer (le). The user enters an `f' to nd that le. The user may wish to execute the command `C-x 1' to return to a single window. Experienced users of Emacs may know that several other buers will be visible as well. The information kept for using the index of variables and index of section names are buers and that the user may have a number of other buers active too. These commands are available in the pull-down \Buer" menus. 8

9 7 Inserting a Section Name Whenever the < key is pressed in the WEB buer, the function web-insert-section-name is invoked. This function must determine whether this is the beginning of a section name or not. The function examines the preceding characters. If an odd number immediately precede the <, then it is the beginning of a section name and web-mode will invoke the function web-options-for-section-name-insertion; otherwise, the < is inserted as the user continues typing. If the function determines that it is the beginning of a section name, the user is switched to a buer with contents like those shown in Figure 1. The user must then select one of the options given. Figure 1 is based on primes.web, an example in [1]. Option Action A Abort C Create a New Section Name L List all Section Names Beginning with Letter N Next Screen P Previous Screen S Select Existing Section Name Name -- for use with Selection based upon completion Fill table p with the first m prime numbers Give to j_prime the meaning: j ~is a prime number If p[n] is a factor of~ j, set j_prime:=false Increase j until it is the next prime number Initialize the data structures Other constants of the program Output a line of answers Output a page of answers Print table p Print the first m prime numbers Program to print the first thousand prime numbers Displaying 11 Section Names of 14 --**-Emacs: *Section Names* (Web)----All Figure 1. Section names for Knuth's primes.web A. If this abort option is selected, the user is switched back to the buer containing the WEB document. The two characters preceding point (@<) are deleted. (These characters will not be deleted if the command is aborted by using C-g.) The remaining options involve the list of section names. The section names are displayed below the menu choices. The section names are displayed in alphabetical order and are retrieved from the list that was created when web-mode was invoked at the beginning of the editing session. Also, additional names are inserted in the list as they are created in an editing session. 9

10 C. If this option is chosen, the user is prompted for the name of the new section. Once entered, the user is switched back to the buer containing the WEB document, the new section name is inserted, and the appropriate delimiter is inserted. A check against the existing section names is conducted to ensure that the entered section name is indeed new. If the section name is new, a determination of whether a stub section needs to be appended is made and the new section name is added to the list of section names. L. This causes all section names that begin with a particular letter to be displayed. The user is prompted for the letter. If no section names begin with the desired letter, an appropriate message is displayed in the minibuer. N. This causes the next screen of section names to be displayed. For example, if the screen is capable of displaying 21 section names and currently section names 1 through 21 are displayed, choosing N would cause section names 22 through 42 to be displayed. P. This causes the previous screen of section names to be displayed. For example, if the screen is capable of displaying 21 section names and currently section names 30 through 50 are displayed, choosing P would cause section names 9 through 29 to be displayed. S. This expects to do selection by a completion scheme that is popular with Emacs users. The L, N, and P options can be helpful. It is not required that the name being selected is visible on the screen. This is one part of web-mode that has not been implemented by pull-down menus. It is obvious that it would just make things slow and why spend a lot of time to slow things down? 10

11 8 Additional Navigation Means Web-mode allows a programmer to view the index as created by xweave. A user can also display the list of pseudo-code section names that is maintained by web-mode. Finally, the names of all chapters is kept in a list that can be used for navigation purposes. 8.1 Viewing the Index The user can view the contents of the index created by weave by issuing the command M-x web-view-index C-c v i S-f9 The user is rst asked whether the WEB is a Pascal, CWEB, or FWEB. The appropriate weave processor is invoked on the WEB in the current buer. Once this process has completed, the index produced is inserted into another buer, see Figure 2. Some reformatting is done for a better presentation. The user can traverse the list of section numbers for a particular index entry by positioning the point on the line of the index entry of interest and: M-x web-next-index C-c n i S-f10 M-x web-previous-index C-c p i S-f11 These commands can be issued from the buer where the index is displayed or they can be issued from the buer that contains the WEB document. If the commands are issued from the former, the user is switched back to the buer that contains the WEB document, and point is positioned at the beginning of the section where the most recently selected index entry was next or previously referenced from point's current position. 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 Figure 2. Index for Knuth's primes.web 11

12 8.2 Viewing the Section Names The user can also view the contents of the list of section names that is maintained by web-mode. When the command M-x web-view-section-names-list C-c v s C-f9 is issued, the list is displayed in another buer. 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 primes.web is shown in Figure 3. 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 ( ) (2) --**-Emacs: *Section Name (Defined In) (Used In)* (Web)--All Figure 3. Section names list for Knuth's primes.web The commands M-x web-next-define C-c n d C-f10 M-x web-next-use C-c n u C-f12 M-x web-previous-define C-c p d C-f11 M-x web-previous-use C-c p u S-f12 can be invoked from the buer where the section names are displayed or they can be invoked from the buer containing the WEB document. If they are invoked from the former, the user selects a section name by positioning the point anywhere on the line(s) where the section name of interest is located. Once a section name has been selected, the user is switched back to the buer containing the WEB document at the section where the most recently selected section name was next/previously dened or used, whichever is appropriate, from point's current position. It should be noted that these commands prevent the user from running o either end of these lists. Actually, it is just one list. This list is collected automatically by web-mode and dynamically 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 M-x web-collect-section-names 12

13 8.3 Viewing the Chapter Titles The user can also view a list of the titles of the chapters in the WEB document and the section number where each chapter begins. The command M-x web-view-chapter-titles-list C-c v c collects the names of the chapters along with their section numbers and displays them in another buer. The user is switched over to this buer. The result of issuing this command on Knuth's primes.web is shown in Figure 4. Chapter# -- Chapter Title 1 Printing primes: An example of \web 2 Plan of the program 3 The output phase 4 Generating the primes 5 The inner loop 6 Index --**-Emacs: *Chapter Titles* (Web)----All Figure 4. Chapter titles for Knuth's primes.web While viewing this list, the user can issue the command `C-c g c' and respond with the number of the chapter indicated above. The `C-c n c' and `C-c p c' commands are quite handy for moving to the next and previous chapters too. The commands in this chapter are also available by the use of the pull-down \view" and \navigate" menus. 13

14 9 Support for Change Files Web-mode provides support for change les. The command M-x web-view-edited-sections-list C-c v e can be invoked in either the buer containing the WEB document or the buer containing the change le. It displays, in a separate window, a list of the numbers of sections that have been edited. The command M-x web-edit-section C-c e s C-f5 will insert the contents of the section that point is positioned in when the command is invoked in the change le in its proper position. The entire section's contents are copied twice and The user is positioned at the rst line after This command is only available in the buer containing the WEB document. The command M-x web-which-edited-section C-c w e can only be invoked in the buer containing the change le. This function displays a descriptive message informing the user of what section in the WEB the change that point is positioned in corresponds to. Movement within the change le is accomplished with the commands: M-x web-goto-edited-section C-c g e The user is prompted for a numeric argument. Point is then positioned at the beginning of the change in the change buer that corresponds to the section number given as an argument. M-x web-next-edited-section C-c n e This command positions point at the beginning of the next change in the change buer: M-x web-previous-edited-section C-c p e This command positions point at the beginning of the previous change in the change buer. The command M-x web-count-edited-sections will display the number of sections that have been edited. C-c # e The commands in this chapter are also available by the use of the pull-down \buer", \view", and \navigate" menus. 14

15 10 Outline Mode An outline-mode has been included based on other Emacs modes. The changes necessary were to decide what the strings are that dene the various levels for the outline. These operations hide all information except the headings and then reverse the operation. This applies to the entire buer. M-x hide-body C-c h b C-f5 M-x show-all C-c s a C-f8 Once you have put the buer into outline mode, you can navigate in the buer based on these headings. M-x outline-next-visible-heading C-c n h M-x outline-previous-visible-heading C-c p h The outline form can have headings at several levels visible. These commands allow you to navigate based upon traveling at the same level of heading (skips subheadings) and to move from a subheading to a higher level. M-x outline-forward-same-level C-c f l M-x outline-backward-same-level M-x outline-up-heading C-c b l C-c u h The immediately following body part can be made invisible or visible: M-x hide-entry C-c h e C-f6 M-x show-entry C-c s e C-f7 The user can make parts of the body and subheadings invisible or visible: M-x hide-subtree C-c h s M-x show-subtree C-c s s The user can show children thereby making direct subheadings visible. It does not aect the visibility of the body or subheadings two (2)or more levels down. This command may be preceeded with a C-u N command to furnish an argument. The default value is one (1). M-x show-children C-c s c To make the body under heading and under its subheadings invisible while the subheadings remain visible: M-x hide-leaves C-c h l To make all subheadings at all levels visible: M-x show-branches C-c s b These commands are available from the pull-down \structure" menu. 15

16 11 Miscellaneous Functions The command M-x web-set-type C-c s t is used to change the type of WEB that is being processed. This is easier to use if you change between (say) CWEB and FWEB and do not wish to edit.emacs. This also allows you to pick dierent compilers. The command M-x web-delimiter-match-check C-c d m looks at the entire WEB document section by section. It determines if the delimiters surrounding section names, are matched. If the delimiters do not match properly, a descriptive message is printed in a temporary buer. Web-mode also makes it easier to enter index entries. When the function M-x web-insert-index-entry C-c i i is issued, the user is prompted for two things: 1. The type of font to be used (Roman, typewriter, or user-dened). This determines the opening delimiter to the index and 2. The text of the index entry. The complete index entry is then placed on a new line in the WEB le (buer). The command M-x web-rename-section C-c r s allows the user to rename a section. 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 only that occurrence, all occurrences, or is queried if each of the remaining occurrences should be renamed. The command M-x web-goto-section-of-point-other-window is useful if you really bounce around between windows. The command M-x web-xdvi enables the convenient preview of the.dvi les. C-c g o C-c x d One keybinding that Emacs' users are familiar with has been rebound to another function. The keybinding C-x C-c has been bound to the web-mode function M-x web-mode-save-buffers-kill-emacs C-c x c f12 Before this function makes a call to Emacs' save-buffers-kill-emacs, it completes the journal le that is maintained by web-mode. This journal le keeps track of what le 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 web-mode's interactive functions were used. 16

17 12 Web-mode Menus This section is based upon work done by Leslie Stoneham and was completed in April, The integration into this manual was done by Bart Childs and has been through only two or three proongs. I repeated the process Leslie did in capturing screen images to make the document smaller. We normally use X-windows and will have screens that are 30 or so lines long. I reduced each windows for the capture process. The appearance and location of the cursor is often because of the capture software. Figure 5 was prepared using METAPOST. These captured screen images vary among machines. Emacs provides functions and data structures for customizing the denitions of commands and key bindings. Data structures called keymaps dene the bindings between keys and command functions. Later versions of GNU Emacs provide a menu-bar that is dened in the global keymap. The web-mode menu-bar is simply an extension of the global menu-bar. More specically, the web-mode menu-bar is dened in a local keymap that extends the global keymap Web-mode Menu-bar The web-mode menu-bar (Figure 1.) is an extension of the standard GNU Emacs menu-bar. A subset of the web-mode commands are grouped under the menu options, Navigate, View, and Structure. The menus, Process and Synchronize, consist of new commands for synchronizing and processing WEB les. Figure 1: Web-mode Menu-bar The standard GNU Emacs menu-bar provides four menus for basic editing commands: Buers, File, Edit and Help. The Buers Menu consists of a list of the names of existing buers in the editing session. The order of the buers in the list is based on how recently a particular buer was displayed in 17

18 a selected window. The Buers Menu can be used to switch to a new buer in the currently selected window. The Buers Menu also includes a command, \List All Buers", for displaying the buer, *Buer List*. *Buer List* displays, in a separate window, the names of all existing buers along with their size, mode, visited le, and an asterisk (if the le has been modied). Figure 2: Web-mode Buers Web-mode provides several commands to facilitate movement between the WEB le, CHange le, and include les: Command Key Binding Function Key M-x web-goto-buffer-change-file C-c b c S-f8 M-x web-goto-buffer-web-file C-c b w S-f6 M-x web-goto-buffer-include-file C-c b i S-f7 Figure 3: Web-mode Basic Buer Movement Commands When web-mode is started, the Buers Menu list includes the WEB and Change le buers. Therefore, it was not necessary to include the commands web-goto-buffer-change-file and web-goto-buffer-web-file in any of the web-mode menus. Instead, a user can select the buer name from the Buers Menu to accomplish the same task. The File Menu consists of commands for manipulating (e.g. save, open, delete) les, buers and frames. The File Menu also includes a command for quitting Emacs. The Edit Menu provides basic editing commands such as cut, paste, copy, undo, and search. Figures for these two items are not included. The Help Menu groups extensive help features on key bindings, functions, global variables, editing modes and more. For example, a user can select \Describe Mode" for a listing and description of interactive web-mode commands. Or the user can request help for a specic command by selecting \Describe Function". The menus for these last two items are not shown because they are much like (probably identical to) standard Emacs, but that might change. 18

19 12.2 Navigate Menu Web-mode denes several commands that move the cursor through the text of the WEB le and CHange le. Movement is based on either the organization of the source le (i.e. chapters and sections), the section cross references (i.e. dened-in and used-in links), the organization of the CHange le (i.e. edited sections), or the location of index entries. The Navigate Menu (shown in Figure 4.) is composed of four sub-menus{web File, CHange File, Index Entry, and Section X Refs, for grouping cursor movement commands. Figure 4: Navigate Menu The various submenus dealing with navigation are shown in Figure 5. The code and documentation of a WEB are organized into small pieces referred to as sections. Related sections can be grouped into a major section, called a chapter. The Web File sub-menu consists of commands that move the cursor across chapters and sections. Navigation occurs in three directions{forward (next section/chapter), backward (previous section/chapter), and random (goto section/chapter). The menu options \Next Section", \Next Chapter", \Previous Section", and \Previous Chapter" are only enabled when the WEB le is the current buer. However, the \Goto" options are available from any buer that is in web-mode. The sections of a WEB can be associated with an \edited" section in a CHange le. Edited sections override the implementation of the WEB section during the weave and tangle process. CHange les allow users to modify and reuse existing program code and documentation without corrupting the original implementation of the WEB source le. The CHange File sub-menu consists of commands that move the cursor across edited sections. Navigation occurs in three directions{forward (next edited section), backward (previous edited section), random (goto edited section). This sub-menu also has a command (edit section) for creating a new edited section. The edit section option is enabled only from the WEB le. Once invoked the cursor is \navigated" into the CHange le for creating and inserting a new edited section. Note 19

20 Goto Section: : : C-c f s S-f1 Goto Chapter: : : C-c g c C-f1 Next Section C-c n s S-f2 Next Chapter C-c n c C-f2 Previous Section C-c p s S-f3 Previous Chapter C-c p c C-f3 Web File: : : Change File: : : Index Entry: : : Section XRefs: : : Edit (Create) Section C-c e s S-f5 Goto Edited Section: : : C-c g e Next Edited Section C-c n e Previous Edited Section C-c p e Next Index C-c n i S-f10 Previous Index C-c p i S-f11 Next Defined-In C-c n d C-f10 Previous Defined-In: : : C-c p d C-f11 Next Used-In C-c n u C-f12 Previous Used-In C-c p u S-f12 Figure 5: Navigate Submenus that if the edited section already exists, then the \Edited Section (Create)" command performs the same action as \Goto Edited Section". The options, \Next Edited Section" and \Previous Edited Section", are enabled only in a CHange le. The other option, \Goto Edited Section" is enabled from any web-mode buer. Index entries may occur at several locations within the WEB le. The Index sub-menu consists of commands that move the cursor across the locations of a selected index entry. Navigation is bi-directional { (next index entry) and (previous index entry). At the end of code sections are two types of cross references. One type (used-in) tells what other sections were used by the currently selected section. The other type (dened-in) indicates other sections that are an extension of the selected section. The Section XRefs sub-menu consists of commands that move the cursor across both types of section cross references. Navigation occurs in two directions{forward (next dened-in/used-in) and backward (previous dened-in/used-in) View Menu During the WEB process several les are created that can be viewed interactively (i.e. before being typeset) from the editing session. The View Menu contains the web-mode commands for viewing (interactively): the index, the list of section names, the list of chapter titles, and the list of edited sections. The web-mode viewing commands are shown in Figure 6. The View Menu is designed to group all of the web-mode commands that display lists useful for navigation. In fact, to navigate the section cross references and index entries, a user 20

21 Command Key Binding Function Key M-x web-view-chapter-title-list C-c v c M-x web-view-section-names-list C-c v s C-f9 M-x web-view-edited-sections-list C-c v e M-x web-view-index C-c v i S-f9 Figure 6: Web-mode Viewing Commands must rst select a reference or entry from the interactive listing. The key bindings are displayed in the menu as an option for the more experienced web-mode user. Figure 7 is a display of the open View Menu. If the user opens this menu from a buer already containing the list of section names, then the option \View Section Names" is not selectable. Likewise, the other options are not selectable if the current buer is already displaying the specied list. Otherwise, the View Menu options are always enabled. Figure 7: View Menu The rst menu option, \View Section Names", is for interactively viewing the list of section names from the WEB source le. An interactive view of the section names list is shown in Figure 8. Each list entry gives the section name, the dened-in section numbers, and the used-in section numbers. Calculate the discriminant and solutions (7) (3) Input a, b, and c, stop if unsuccessful (5) (3) Output the calculated solutions (9) (3) Variable declarations (4 6 8) (3) Figure 8: Interactive Section Names Listing The option, \View Chapter Titles", is for viewing the list of chapter titles from the current WEB source le. The interactive view of the chapter titles list is shown in Figure 9. Each list entry gives the chapter title and chapter number. The menu option \View Index", is for viewing the index le created during the weave process. The index lists the automatic and user-dened index entries. When viewed interactively, a list of index entries and their locations (i.e. section numbers) are displayed in a buer. An example of the interactive index listing is shown in Figure

22 Chapter# -- Chapter Title 1 1 The quadratic equation 2 1 The program for solving the quadratic equation 3 1 Index Figure 9: Interactive Chapter Titles Listing a: 4. b: 4. c: 4. cmplx: 7*. csqrt: 7*. discriminant: 2. discriminant: 7*, 8*, 9*. implicit none: 3. input status: 5, 6. IOSTAT: 5. none: 3. quadratic: 3. z 1: 7*, 8*, 9*. z 2: 7*, 8*, 9* Structure Menu Figure 10: Interactive Index Listing Web-mode also provides functions useful for assessing the structure or organization of a literate program. Many of the commands outline the WEB le. Other commands count and identify the sections, chapters, and edited sections. Examples of structure commands include: Command Key Binding Function Key M-x web-count-sections C-c # s M-x web-which-edited-section C-c w e M-x hide-body C-c h b C-f5 M-x show-all C-c s a C-f8 Figure 11: Web-mode Structure Commands Figure 12 displays the open Structure Menu. Typically, the structure information refers to the contents of the WEB le. Therefore, most of the options are only enabled in the WEB le. The only exception, \Which Edited Section", pertains to the contents of the CHange le. Consequently, this option is only selectable in the CHange le. The Structure Menu is not available outside of the WEB and CHange les. 22

23 Figure 12: Structure Menu The Structure Menu represents a small subset of the structure commands provided by web-mode. The menu was designed to include the most commonly used commands. Later, the means for customization of the menus are discussed Process Menu The processing of WEB source les to create executable and printable versions of a literate program is described in the introduction of this report. The purpose for the Process Menu (shown in Figure 13.) is to provide options for WEB processing the source les from the editing session. Currently, the process commands are only available through the web-mode menu-bar. In other words, the commands invoked by the Process Menu options have no corresponding key bindings. Figure 13: Process Menu The rst menu option, \WEAVE Source Files", will start a process that creates a TEX le from the WEB source les. The output of the weave process will be displayed in the buer, WEAVE-Output, in a dierent window. Figure 14. displays an example of the editing session after selecting \WEAVE Source Files". The second menu option, \TANGLE Source Files", will start a process that creates a high level language (HLL) le for the WEB source les. The output of the tangle process is displayed in the buer, TANGLE-Output. Figure 15. displays the state of the editing session after selecting \TANGLE Source Files". 23

24 Figure 14: WEAVE Output Figure 15: TANGLE Output Another menu option, \Compile HLL Program", is used for compiling the high level languge (HLL) le created by the tangle process. To ensure that the HLL le exists and to determine the HLL being used, the WEB source les are initially tangled. The HLL le is then compiled using a conventional compiler. For this menu option to work properly, the user must specify the compiler and options to be used in the.emacs le. This specication can also be changed by using the command: M-x web-set-type C-c s t 24

25 Figure 16: DVI Output The menu option, \Create A DVI File", compiles the TEX le of the current WEB into a.dvi le. If the TEX le does not exist, the user is prompted to create the.tex le. If the user responds to the prompt with \n", no further action is taken. If the user responds with \y", the.tex le is created using the weave processor. Figure 16 is a result of invoking this. The menu option, \Create A Postscript File", will create a postscript le from a.dvi le for the current WEB le. If the.dvi does not exist the user is prompted to create the.dvi le using the program dvips. Figure 17. displays a result of invoking this option. Figure 17: Postscript Output The Process Menu also has a sub-menu for previewing the typeset presentation of the WEB document that is currently being edited. Selecting the option, \Preview Typeset Program...", will cause the menu shown in Figure 18. to display. If the user selects, \Preview With Xdvi", a process is started to display the.dvi le of the current WEB in its typeset format. If the.dvi le does not exist, the user is prompted to create it. The other option, \Preview With Ghostview", will start a process to display the postscript le of the current WEB. Again, the user is given the option of creating the le if it does not already exist. 25

26 Figure 18: Preview Sub-menu The Process Menu was added to the web-mode editor to facilitate WEB processing. Users now have the option of processing directly from the editing session. Users can potentially invoke processing with the click-and-release of a mouse button instead of typing several command lines. The Process Menu options are enabled only in the WEB and CHange les Synchronize Menu The synchronize commands allow a user to coordinate and display the WEB le with either the CHange or high level language (HLL) le. In both cases, the synchronization is based on the location of the cursor in the WEB le. The open Synchronize Menu is shown in Figure 19. Figure 19: Synchronize Menu A CHange le contains information that override portions of a WEB source le. The CHange le consists of an exact duplication of the lines from the source le to be replace followed by their replacement lines. The CHange le can be used by both the weave and tangle processors to replace the documentation and code of the source le with the contents of the CHange le. 26

27 Selecting the menu option, \Synch with CHange File", will position the cursor in the CHange le at the exact location from where the command was invoked in the WEB le. Both the WEB and the CHange le are displayed in the selected window. Figure 20. demonstrates the eect of this option. Figure 20: Synchronization of the WEB and CHange File The HLL le contains only the code of the programming language in use and comments indicating the start and end of a WEB section. Selecting the menu option, \Synch with HLL File", will position the cursor in the high level language le at the beginning of the code contained in the WEB section from where the command was invoked. For example, if the menu option is selected while the cursor is in Section 5 of the WEB document, then the cursor is placed in the HLL le at the beginning of the code that was contained in Section 5. Figure 21 is the result of this type of synchronization. It is sucient to synchronize the HLL le at the the beginning of the section since most sections should contain only of few lines of code. Figure 21: Synchronization of the WEB and the HLL File Not all of the sections that appear in the WEB le are found in the CHange or HLL le. For example, sections that are composed solely of documentation do not appear in the HLL le. 27

28 Sections that have not been overridden do not appear in the CHange le. Therefore, if the WEB line or section to be synchronized does not exist in the target le, then the user is given a message and no other actions are taken. The nal option of the Synchronize Menu, \Return to WEB File", will make the buer containing the WEB le the current buer and any other window being displayed will disappear. The option, \Return to WEB le" is enabled for all web-mode buers except the WEB le. However, synchronization can only occur from the WEB le. 13 Using Color Within web-mode Web-mode has been extended to allow the use of color in the WEB source as well as in the index. This was done by by Tom McCurdy, July, By default color is turned o and it is only available when using Emacs with a windowing system such as the X Window System, Windows-95, or Windows/NT. To use Emacs in a windowing system requires the use of Emacs 19 or later. Customization of your.emacs le is done with lines containing `hilit' and `color' Hilit for web-mode To highlight parts of the screen which have not been colored or to rehighlight the screen use M-x hilit-recenter C-l There are several changes to the.emacs le that may be made and are shown in Figure 22. Files larger than 60K will not be highlighted when they are rst read into a buer because of the time taken to highlight large les. However, each time C-l is pressed the entire screen will be highlighted. To highlight the entire buer preface hilit-recenter with C-u: C-u M-x hilit-recenter C-u C-l If you wish to increase the maximum le size for automatic highlighting of the entire buer add the lines referencing hilit-auto-highlight-maxout carefully. This line should appear before \(require 'hilit19)" in your.emacs le. As mentioned earlier the use of hilit requires that Emacs is used in conjuction with a windowing system. This highlighting feature relies on the Emacs LISP code hilit19.el written by Jonathan Stigelman. To use hilit and to customize it in other major modes add (and maybe edit) the following Emacs LISP code in Figure 22. If you prefer using a light background change the line: hilit-background-mode 'dark to hilit-background-mode 'light Table 1 is a list of the default colors used by hilit in web-mode. If you wish to change any of these colors you will have to edit the web-mode source. To change these colors in the web-mode source search for the string \defconst web-hilit-default-face-table" and change the colors there. (If you are using the X Window System a list of legal color names and their RGB values can be found in the le rgb.txt which is usually in the directory 28

29 (defvar hilit-auto-highlight-maxout "* auto-highlight is disabled in buffers larger than this") (insert " Turning on color hilights.\n") (setq hilit-mode-enable-list '(not text-mode) hilit-background-mode 'dark hilit-inhibit-hooks nil hilit-inhibit-rebinding nil) (require 'hilit19) ;;(insert "Turning on auto-coloration at <CR>\n") (defun hilit-return () "Hilit a line when the return key is hit!!!!" (interactive) (if (equal mode-name "Text") (newline) (setq current-point (point)) (beginning-of-line 0) (setq b (point)) (goto-char current-point) (newline) (hilit-rehighlight-region b (point)) ) ) (cond (window-system (global-set-key "\C-m" 'hilit-return) )) Figure 22: Possible modications of the.emacs le 29

30 Hilit Colors for WEB Mode Background Color Item Highlighted Light Dark Section Reference Steel Blue4 Cyan Section Denition Royal Blue Yellow2 Chapter Lime Green Green Index Entry MediumPurple3 Plum1 Control Codes Dark Goldenrod1 Moccasin Preprocessor Maroon Orange Table 1: Colors used by hilit in Emacs' WEB mode /usr/lib/x11.) The rst column lists the WEB command category, the second column lists the color of the command for light backgrounds, the third column list the color for dark backgrounds and the last columns list the face used for monochrome backgrounds. After you make changes to the web-mode source you should byte compile the source by issuing the byte-compile-file command from within Emacs and specifying the name of the web-mode source le as the name of the le to compile. If you decide that you like having certain WEB commands highlighted but do not wish to have all six categories of commands highlighted you may turn o highlighting of any of the six categories of WEB commands. To disable highlight of a WEB command category insert the lines of LISP code into your.emacs le which disable colorization for that category of WEB commands. The following Emacs LISP code turns o highlighting for all six categories of WEB commands: (defvar web-hilit-section-reference nil "*Determines if section references are hilited under web-mode.") (defvar web-hilit-section-defintion nil "*Determines if section definitions are hilited under web-mode.") (defvar web-hilit-chapter nil "*Determines if chapters (@*) are hilited under web-mode.") (defvar web-hilit-index-entry nil "*Determines if index entries are hilited under web-mode.") (defvar web-hilit-control-codes nil "*Determines if WEB control codes are hilited under web-mode.") (defvar web-hilit-preprocessor-commands nil "*Determines if WEB preprocessor etc.) are hilited under web-mode.") 13.2 Colorization of the web-mode Index To add colorization to the web-mode index only requires that the following two lines of Emacs LISP code appear in your.emacs le: (defvar web-color-index t "*Determines if the WEB index is to be colored under web-mode.") 30