This is the file containing the INFO-ized documentation on using R with its standard macro package.  File: RGUIDE, Node: Top, Up: (DIR), Next: Generalities This file describes how to use R with its standard macro package, and contains information on essentially all features available. The earlier sections of this file deal with general topics of using R, and explain some of the common things that most R users need to understand (at least a little) to use R effectively. We have tried to write all parts so that the beginning user can glean enough information to get started, but also so that the advanced user can get help on all but the most arcane things. Whereas the goal of the R Reference Manual (see node Documentation for pointers to documentation) is to explain precisely everything in R, the goal of this file is describe how to use things effectively. Another difference is that the reference manual describes "raw" R, that is, R minus the macro package, but it is the macro package that provides most of the "friendly" features users exploit. Here we desire to explain the use of the macro package as it is, and also how to tailor it to do slightly different things. We also give some guidance and lore on how to debug documents, and hints on writing your own macros. However, to do all this, we must explain a lot of things, many of which need not be understood by novices. Therefore, the sections are usually written so that they start with simple cases, with simple examples that can be used almost like recipes. Then they progress to explanations of what is really going on and more advanced examples. Novices should start at the beginning -- Generalities, since this gives a brief orientation, and tells you about a number of simple mechanical things. If just starting, you should also go through the first four or five sections at least. Do not worry if there are things you do not understand on first reading; they should become clear as you start actually preparing documents. Comments and suggestions on the form and content of this guide would be appreciated. Send them to EBM@XX. * Menu: * Generalities:: This node contains such information as where to find documentation, conventions used in this file, the place of R in the document preparation process, etc. Also, how to report bugs, how to get on the mailing list, etc. * Setup:: How to set up the beginning of your file to use the standard macro package. * Input:: How R scans a file. In particular, how to get 'funny' characters to work right, etc. * Registers:: How string and number registers work. This knowledge is necessary for you to get anything other than the default actions of the macro package. * Expressions:: How to write down numerical expressions, including more complicated horizontal and vertical measurements, such as "twice the current indentation", etc. * Backslash:: The various roles of \ in R. * Justification:: A review of how filling and adjusting work in R. The role of the space character. * Fonts:: The various facilities for switching fonts are described here. * Macro Invocation:: How to call macros. This describes how to deal with getting special characters into macro arguments, etc. * Page Layout:: How the standard macro package lays out the page into vertical sections (top margin, text area, bottom margin, etc.) * Line Spacing:: How R determines the distance between lines, and how you can control it. * Line Layout:: How R lays out each output line, and macro package facilities for setting line margins. * Horizontal Positioning:: How to control fine positioning of items on the output line. * Text Features:: This discusses a raft of little, useful things, such as super- and subscripting, underscoring, overstriking, output translation, and hyphenation. * Alignment:: How to get things on different lines to line up vertically in various ways. * Sectioning:: The macros available for organizing a document into chapters, sections, appendices, etc. * Footnotes:: How to use the footnote facility. * Figures:: How to use the figure and table facility. * Lists:: The facility for lists of things, e.g.: 1. This is the first item in a list. 2. This is the second item, and is a bit longer, so it takes up more than one line. The list facility is quite flexible and powerful. * Table of contents:: How to get a table of contents, and how to control its appearance. * Keeping:: How to keep things on a single line or a single page. * Setoff Things:: Here we describe the facilities available for setting things off in the text. Examples of this kind of thing are quotations, equations, program text, and various kinds of pictures and tables. * Math:: Here we describe the facilities available for doing mathematical equations and formulae, and give some hints on how to go beyond what is standardly available. * Columnar tables:: Introduction to methods of making tables that consist of vertical columns that must be aligned in a particular way. * References:: Introduction to the packages available for producing bibliographies and keyed references in running text. * Writing Macros:: Conventions and hints on macro writing in general. Specific hints are given in other places. * Debugging:: Some hints on how to debug problems encountered. * Miscellaneous:: Some comments on things not discussed elsewhere.  File: RGUIDE, Node: Generalities, Up: Top, Previous: Top, Next: Setup Here we give you some orientation as to what R does and to get started using it. The next node, Setup, gives you tips on organizing your input file. * Menu: * What R does:: R's place in the document preparation process. * Documentation:: What is available and where to find it. How to report bugs. How to get on the mailing list. * Filenames:: Things you should know about how R deals with filenames. * Output Devices:: Things you should know about using the various output devices available with R. * Invoking R:: How to run R.  File: RGUIDE, Node: What R does, Up: Generalities, Next: Documentation R is a text formatting program. Its place in the process of preparing documents is illustrated by the following picture: you -> editor -> input file -> R -> output file -> output program -> document | +--> error messages The above picture means that the common way of preparing a document involves these steps, in order: 1. You prepare an INPUT FILE using your favorite editing program. A FILE is a repository of data in the computer system. The way most of out editors work, you simply type the text in to the editor, and then when you think it is ready, to give the editor a special command, telling it to write what you have typed in, to a file on the computer system. You can also edit files you have made before, to correct mistakes, add new text, etc. The most commonly used editors are EMACS, RMODE, and TED. 2. You then run R, telling it to process the input file you created with the editor. The term "invoking" means the same as "running" in this context. People will say "Run R" or "Invoke R" just about as readily. R then produces an OUTPUT FILE, and possibly some error messages and other information. 3. If there are no errors, then you invoke the appropriate program to send the output file to the output device. Here are the programs you would use for the most common situations: Device on ITS on TOPS-20 (XX) PRESS (Dover) DOVER, DOVR DOVERSEND (and DOVER, coming soon) XGP XGP XGPSEND LPT TPL If there are error messages, or the document does not have the desired appearance, you back back to step 1, and create a new input file that you think will work better. It may take doing this half a dozen times to get rid of the "bugs" in a new version of a document. R normally prints its error messages on your terminal as it runs. However, it is often better to save them in a file, so that you don't have to write down what is on your screen to avoid losing the messages. See the section on invoking R for information on how to do this. Some of the other text formatters available are: (Opinions expressed are mine, but I have found many experienced users to agree with most of these statements.) SCRIBE - has approximately the same capabilities as R, and about the same strong and weak points. Easier for the novice to use than R, but maybe harder for the expert to get what s/he wants. Can do single or multiple pass processing. Not available on ITS at this time, maybe never. TJ6 - a very simple minded, easy to use formatter, with superficial similarities to R. Most people find TJ6 too simple: there are too many things it cannot do. Available only on ITS. PUB - a powerful but often arcane formatter. Slower than R, but it can do a few more things than R can. Available only on ITS. TEX - Good for mathematical things like equations and tables, but not as easy to use as some of the other formatters. Not as convenient as other formatters on non-mathematical documents. Available only on ITS In sum, R may not be for you. But you should know that R is the only text formatter we have that runs under all our computer systems. The diagram of the document preparation process that we drew above is overly simple: sometimes one processes the input text some before giving it to R, and sometimes one processes the output file some before printing it out. An example of the first situation is this: you can run a spelling checking and correcting program (e.g., ISPELL) to find spelling errors before running R. Some examples of the second situation are: you may use a program that extracts only the pages that have changed between versions of a document (e.g., @ or XGPDIFF), or you may have to run RALP on line printer output (see node Devices).  File: RGUIDE, Node: Documentation, Up: Generalities, Previous: What R does, Next: Filenames The documentation on R itself consists of the R Reference Manual. That document is pretty good for the experienced and/or sophisticated user, but is tough going for the novice (sort of like reading an encyclopedia!) The manual exists in online readable form (suitable to read into a text editor, etc.) as R;RDOC LPT on ITS, and DOC:R20.MANUAL on XX. To acquire a nice looking copy, send MC:R;MANUAL PRESS to the Dover. If you don't know how, talk to somebody who does. There is an R Primer in preparation by another person (Judi Jones). That document should complement this one, in that the Primer is something you can sit down and read all at once. This guide goes farther, and is therefore longer. We recommend that most parts be skimmed on first reading. Having two different explanations of the same thing should help; we have tried hard to make sure that the two documents do not say contradictory or wrong things. Documentation on the macro package consists of this file, and also R;RMACRO INFO (RMACRO.INFO on XX -- from now on, assume the XX name is the one corresponding to the ITS name unless told otherwise). Either file may be printed on your terminal or a line printer. (This file is INFO;RMACRO INFO.) The other file may be retired if this one works out. The macro package itself comes in two parts. By special dispensation, the larger part, R;R30M RMAC, is pre-loaded into R when you get it. The smaller part, R;R30 RMAC, is inserted by R;R MACROS, and must be read every time. It activates the larger package, and helps in option selection. However, if you desire to inspect these file, you should look at these versions: R;R30M RML and R;R30 RML. (RML = R Macro Language.) The difference is that the RML files are nicely indented and have comments, whereas the RMAC files have been compacted by throwing away the indentation and comments. If you want to write things in the "R Macro Language" yourself, you should realize that R will not accept them as they are, because the // comment form is not understood by R. You can use ^K instead of //, or you can convert your RML file to an RMAC file using the TECO macro in R;RML >. For XX users, there is a program in RML.EXE that will do the job; just type RML file-name, and it will create a new file, with second name RMAC, with the compacted version in it. Documentation on auxiliary macro packages is usually included as comments in the beginning of the file containing the extra macros. There is a mailing list, INFO-R, to which messages concerning changes to R and the standard macro package are sent. If you wish to be added or removed from that list, send mail to the R maintainer (currently EBM@XX). The file R;R ARCHIV contains a record of all changes made to R in recent history (it goes back several years), except the most recent changes, which are described in R;R RECENT. R;RMACRO RECENT contains information about recent changes to the standard macro package. R;R STATS gives a summary of R usage from the time R began, by user, in order of amount of stuff processed. The primary home of all R files and documentation is XX; ITS and other versions are updated from there. Complaints, suggestions, and problems may be referred to the maintainer (EBM@XX), by sending mail directly, or by using :BUG R on ITS (which is the same as :MAIL BUG-R@AI). Please do what you can on your own first! See the node on Debugging for hints.  File: RGUIDE, Node: Filenames, Up: Generalities, Previous: Documentation, Next: Output Devices Read the section pertinent to your system, and then read the note at the end. On ITS: Full filenames on ITS have the form: device:directory;name1 name2 In the .so command of R, you may omit device: if it is DSK: omit directory; if it is your directory, or R; omit name2 if it is >, R, or RMAC In the .fo command of R, you may omit device: if it is DSK: omit directory; if it is your directory, FONTS;, FONTS1;, FONTS2;, XFONT;, or R; omit name2 if it is KST NOTE: In the command line, filenames may NOT have spaces in them. Thus, ':r foo >' will NOT do what you might expect! However, the second name need not be given if it is R, RMAC, or >. If you must supply a second name, there are two ways: :r "foo bar" -- put the file name in double quotes The other way involves a different format of filenames, and is explained in the reference manual. On TOPS-20: Full filenames on TOPS20 have the form: device:name1.name2.version In the .so command of R, you may omit device: if it is DSK: omit if it is your directory or PS: omit name2 if it is R or RMAC omit version it is the most recent one (0) In the .fo command of R, you may omit device: if it is DSK: omit directory; if it is your directory, PS:, PS:, PS:, PS:, or PS: omit name2 if it is KST omit version if it is the most recent one NOTE: To make files more easily portable from system to system, you should try to arrange things so that you can omit the device, directory and name2 fields in as many cases as possible. R was purposely designed to make this easy in most cases. For example, unless you made up a font file yourself and gave it a funny name, you never need to state the device or directory for a font. Similarly, it is conventional to set your input file's name2 to be > on ITS (R on XX), and to use a name2 of >, R, or RMAC for auxiliary input files. If you do so, then you will not have to state the name2 to R. Since almost all files will be in your directory or the R directory, this means that most of the time you need only state the name1 of the desired file. In the cases where you need name2, writing the filename as name1.name2 works on all systems. There is no nice way to include a directory or device that can be read on all systems with no changes. Therefore, we suggest that you omit as many of the filename fields as you can.  File: RGUIDE, Node: Output Devices, Up: Generalities, Previous: Filenames, Next: Invoking R R can produce output for several different printing devices. These devices are distinguished mainly because to get the same appearance of an input file on different devices requires different instructions in the output file which is sent to the device. Another reason for distinguishing the devices is their different capabilities. For example, the XGP, Dover, and Varian all support multiple fonts with characters of varying widths. The Diablo supports a single font, but can do relatively fine grained positioning on the page, and line printers have a single, coarsely positioned font. (Font means typeface.) R is designed so that it is comparatively easy to make up a single file that can be output on several different devices by just telling R what device you want. Of course, R can't do anything about some devices not having the special characters you may want, but with a little care, on can often get reasonable drafts from less fancy devices. When R produces output for a given device, the name2 of the output file is set to the device name. For example, if your input file is called FOO.R, and you produce output for the XGP device, the output file will be called FOO.XGP. The only exceptions to this rule are the Diablo device and 12 pitch line printer output; see the reference manual for details. Below is a list of the devices and their interesting properties. See also the Setup node and the Invoking R node. LPT - line printer. A single font, fixed character width device. Generally, files produced for the LPT are also suitable for inspection with a text editor. This is often helpful in debugging. Although you only get one output font, you can have R mark things supposed to be in different fonts by underscoring them, printing the characters several times (to darken their appearance), or capitalizing them. See .FO in the reference manual for details on that. NOTE: the macro package assumes that LPT files will be printed by a program on the operating system, and makes certain adjustments not described in the reference manual. If this is a problem, set the number register LPT_HACK to 0 before loading the macro package. NOTE: if you use superscripts, subscripts, or related things, R will give you a message "postprocessing needed". In such cases you should run RALP (random access line printer). Just type :RALP FOO where FOO is the name of your input file (RALP FOO on TOPS-20, etc.). PRESS - press file. This is the format accepted by a number of devices constructed by Xerox Corp., including our Dover (but NOT the XGP, also made by Xerox). This supports multiple fonts and very fine positioning (units of 10 millionths of a meter in theory, 384 dots to the inch on the Dover). Press fonts are those available on a special list (see FONTS;DOVER FONTS). There may be a complete catalog of these available sometime; a few copies of a limited catalog might still be available from Anne Rubin in Room 529. Unfortunately, the fonts available for the XGP and the Dover are different, even similar ones have different names. The first 1/3 of an inch (at the top of the page) cannot be used (hardware limitation). XGP - Xerox Graphics Printer. Capabilities similar to the Dover. Output quality is not as good, and printing is much slower on the XGP, but many more fonts are available, and it is easier to make up new ones than for the Dover (it is almost impossible for the Dover). Each font comes from a different file, so the fonts are specified by giving the name of the file containing the font. Most of these fonts live in FONTS, FONTS1, and XFONT, with some "personal" ones in FONTS2 and elsewhere. The old catalog is out of print. A new catalog will be available after the ongoing font reorganization is complete. The XGP device cannot go up the page; all other devices can, more or less. VARIAN - Varian printer/plotter. This has almost exactly the same properties as the XGP, including the available fonts. It is connected to the 4th floor 11/70 UNIX system. You should talk to them for more information. DIABLO - Xerox 1700 terminal (Diablo mechanism) - This is similar to a line printer in that is has only one, fixed width, typeface, but it can do fine positioning both horizontally and vertically. Output is very sharp with a carbon ribbon. See the file R;DIABLO INFO for more information on using the Xerox 1700 on the 5th floor.  File: RGUIDE, Node: Invoking R, Up: Generalities, Previous: Output Devices In this node, we discuss the command line in general, list the specific options and flags available, and, at the end, give some special notes for ITS and TOPS-20 users. Using the command line. When you run R, you do it by typing the name of R (e.g., "R") followed by the name of your input file. For example: (ITS) :r foo (TOPS-20) r20 foo This handles many common situations, but there are a number of options you can specify. Most options are FLAGs. A flag is one or two letters, preceded by a dash (-), with the whole thing separated from anything else on the line by spaces. For example: :r foo -x -s The flags are discussed in three groups below. In addition to the filename and flags, there are two other things that may appear on the command line. One is a request to send the error messages to a file instead of the terminal screen. To send error message to the file foo.bar, put >foo.bar at the END of the command line. For example: :r foo -x -t >foo.err The other kind of thing that may appear on the command line, is an initial setting of a number register, like this: reg=value. Here is an example: :r foo -x figure_debug=1 Device options: You can override any .dv in your file and get R to produce output for a particular device by putting the right flag in the command line. Here are the flags for each device: -p Press -x XGP -l LPT -di DIABLO -v VARIAN Miscellaneous options: -s prints extra statistics -t does a TRACE of the execution (see node Debugging) -d debug -- causes some extra output regarding figures, footnotes, etc. (see node Debugging) Pitch and Lines per inch options: You can override the default pitch and/or lines per inch, or any .pi or .lp commands in your file, by putting the right flag in the command line. This is useful mainly for the Diablo device, but pitch applies to to the LPT device as well. -10p use 10 pitch (10 characters to the inch; Pica) -12p use 12 pitch (12 characters to the inch; Elite) -6l use 6 lines per inch as single spacing -8l use 8 lines per inch as single spacing Special things to know on ITS. Don't forget that filenames in the command line cannot contain spaces! This includes both the input filename and the name of the file to receive error messages, if any. If this is a problem, see node Filenames for a way around it. Special things to know on TOPS-20. Because "R" is a command on TOPS-20 (meaning "run the program whose name follows"), R is called R20 on TOPS-20. So, you might invoke R this way: R20 foo -p >foo.errors  File: RGUIDE, Node: Setup, Up: Top, Previous: Generalities, Next: Input If you are new to R, I suggest you put the lines shown below at the beginning of your file, until you understand better what it all means. (It is explained below, but it may take using R for a while until you will understand it.) .dv press .if press . fo 0 TimesRoman12 . fo 1 TimesRoman12b . fo 2 TimesRoman12i . fo 3 TimesRoman18 .else . fo 0 times.12rom . fo 1 times.12bold . fo 2 times.12ital . fo 3 times.18rom . end if .tr @ .so r.macros The .DV line means that your default device will be the Dover (Press file format). The ".if press" says if the device really is PRESS (you can override it in the command line; see node Invoking R) then continue with the immediately following .FO's; otherwise, continue from the .ELSE. This used to get one set of font definitions when you use the Dover, and another set when using the XGP (or any other device). This is really the only way to do it. The .FO lines define four fonts: font 0 - a normal text font, I have given you Times Roman, 12 point (1 point = 1/72 inch; points are a standard unit of measurement in typesetting). font 1 - a bold font, set to match the normal font font 2 - an italic font, also matching the normal font font 3 - a big font, for chapter headings, etc. You may use any fonts you like, of course, and you may define more, to get special symbols, greek characters, etc. But the standard macro package always assumes that font 0 is a normal font, font 1 is a bold font, font 2 is an italic font, and font 3 is a big font. For the diablo or lpt, it does not matter at all what fonts you put down, but you must put something down for these 4 fonts. For more about fonts, see node Fonts. The .TR command sets things up so that the character '@' will print as a space instead of an @. Now that may not sound useful, but it is, because the space character, ' ', does not exactly print as a space, but usually means "put some white space here, or, if you are close to the end of a line, start a new line". The node Input starts to explain the difference, and node Justification explains this particular case in detail. The .SO command activates the standard macro package. It turns out that most of the macro package is loaded into the R that you run, since it takes a while to read it into R, and people use R all the time. BUT! you must still turn it on by reading a smaller file that starts things off. You must have no text or blank lines before this .SO. The above setup gives you the standard macro package with its default options. If you decide there are things you don't like about some feature or other, consult the appropriate section, to understand what things can be adjusted, and how. Then, you may wish to insert some lines to override the default options. These lines should go just before the .SO above. You will most likely have to read up on string and number registers (next node) and possibly input processing (Input) to understand how to get what you want.  File: RGUIDE, Node: Input, Up: Top, Previous: Setup, Next: Registers This node describes things you should know about how R processes your input file. At all times, R reads a character at a time from some place, until it reaches the end of your file. The various places R can be reading from include: Files String and number registers Macro bodies Macro arguments and a few other internal sorts of things For example, when R reads the setup described in the previous node, it is reading from your input file, from the beginning to the end. However, when it sees the .SO, it starts reading from the named file (R.MACROS). Then, when it reaches the end of that file, it returns to where it left off in your file. This process can be carried to MANY levels (about 20-30 in the current R). The reference manual refers to this changing of where R reads from as "input stream switching". The next thing to understand is that except for stream switching commands, which effectively disappear, the characters read are grouped into lines, which are processed one at a time. Normally each line that you type becomes a single input line; if you find yourself typing a lot of long lines, read up on the line continuation feature in node Continuation lines. There are two different kinds of input lines: Requests and macro invocations, and Text Requests and macro invocations are readily recognizable: they are the lines that start with "." or "'". For example, the line .dv press is a request line. The request is the thing following the "." (dv in this case), and the rest of the line forms the ARGUMENTS to the request. Of course, the meaning of these arguments depends on the request. Macro invocations LOOK exactly like request lines. The only distinction is that requests are built-in, and macros are written in terms of requests. This distinction is not very important, but it may help you to know the two terms. Here is an example macro invocation: .chapter "Title of Chapter One." Text lines are line that do not start with "." or "'", and most, but not all, characters on a text line will appear in the output. Let us examine the situation here in more detail, since you may need to know most of this to construct good input files. Assume R encounters an ordinary character, say "D". What R will do is put something in the output file that tells the output device to print whatever corresponds to a "D" in the current font. We phrased the previous sentence in a somewhat awkward way to make a point: just because you have a "D" in your input file does not mean that the appearance of the character will be that of a "D". In fact, R knows nothing about the actual appearance of characters at all! R only knows how big they are, so it can figure out where to put them on the page. Some characters that appear in the running text are used to tell R to change what it is doing in some way. These characters are the CONTROL CHARACTERS. They are called control characters both because they control R's behavior and because most of the particular characters in question are normally typed as ASCII control characters. An example is ^F (pronounced "control F"), which is used to change the current font. NOTE: we write control characters as two characters in this document (an "^" followed by a letter) to avoid certain mechanical difficulties, but "^" followed by "F" is NOT the same as control-F. Control characters bring us straight into a thorny problem, however. Fonts can have characters associated with ANY of the ASCII characters, including the ASCII control characters -- how can we possibly get the symbol corresponding to a ^F if ^F means change fonts? What we do is this. Inside R there are two kinds of control characters, which we will call the R CONTROL CHARACTERS and the TEXT CONTROL CHARACTERS. An R control character performs a special function, such as ^F changing the font. A text control character causes a character to be added to the text output. When a control character is written by itself, it is taken as an R control character, i.e., it performs its special function. However, the R control character ^Q has the particular function of taking the next character, no matter what that character is, and turning it into a text control character. In sum, ^F means change fonts, and ^Q^F means output the character corresponding to ^F in the current font. ^Q^Q, therefore, is the way to get a text control-Q, etc. NOTE: most editors require a special command for you to get a control character into your file, and that command is usually ^Q. For example, to get a ^F into your buffer, you must type ^Q^F in most of our editors. Further, to get ^Q^F into your buffer, you must type ^Q^Q^Q^F, etc. To get a ^_ or ^Z into your buffer on ITS requires more devious means -- ask somebody. (The same holds for getting ^C into your buffer on TOPS-20.) Fortunately, these characters are almost never used. NOTE: for some help on techniques to ease problems with characters that are hard to type, or hard to get R to accept (e.g., ^J, ^M, and ^L) see the discussion of escape characters in node Backslash. For completeness here is a list of the R control characters: ^A, ^B, ^C, ..., ^Z the ASCII control characters \ space that is, " " . and ' when appearing at the beginning of a line (So, to get a . at a beginning of a line, write "^Q.".) Most of these are explained fairly well in the R manual. You should definitely read about the control characters ^A through ^Z. You already know that control-. and control-' are used in request and macro invocation lines. Control-\ is explained in node Backslash, and Control-space is explained in node Justification. Additional Features: Normally control characters in the input turn into the corresponding R control characters. You may use the .CC and .NC requests to change the exact mapping, however. .cc c p - causes the input character "p" to become an R control "c" .nc p - causes the input character "p" to become a text "p" You might also be interested in reading the description of escape characters in node Backslash.  File: RGUIDE, Node: Registers, Up: Top, Previous: Input, Next: Expressions R has NUMBER REGISTERS and STRING REGISTERS, which are very useful. It is hard to give an easy to understand explanation of exactly how they work, but they turn out to be easy to use in the common situations. Let us consider an example. Say that you find you are typing ^F5^Q^N^F... quite a lot, because it is a special character used many times in your document. Let us say that it is a summation sign (capital sigma). You can define a string register to give you a handy abbreviation for that: .sr sum ^F5^Q^N^F* Then, wherever you want the summation sign to appear, just write "^Ssum". The .SR command ("string register") has two ARGUMENTS, a name for the string register ("sum" in this case), and the stuff to put in it. The name begins after the space after the .SR, and continues to the next space. Register names (this holds for number registers, too) can have only these characters in them: A through Z, 0 through 9, and _. Case (upper or lower) is ignored. The stuff that goes into a string register starts with the first non-space, non-tab character and continues to the end of the line. If you need the first character of the stuff in a string register to be a space or a tab, precede it by a backslash. For example: .sr foo \ abc The above puts space, a, b, c into the string register FOO. If you want to set a string register so that it has nothing in it, then just put nothing after its name, e.g.: .sr foo Whereas as string registers hold strings (a technical name for a bunch of characters), number registers hold numbers. Number registers hold whole numbers (integers) only, and positive and negative numbers are allowed. The biggest number you can put into a number register depends upon what computer system you are using, but is always at least 15000. As we saw before, the contents of a string register can be made to appear by typing ^S followed by the string register name. To get the value of a number register to appear, we use ^N followed by the number registers name. Similarly, we use .nr to set a number register. Here is a simple example: .nr foo 105 The serial number of the stolen item was ^Nfoo. What will appear in the output is: The serial number of the stolen item was 105. The particular example above could have been done with a string register. The important thing about number registers is that you can use them to make calculations, to count things, etc. A simple example is that the macro package has a number register named chapter that always holds the number of the current chapter. This is nice because it lets us write down once the format for the header line of a new chapter: ^Nchapter. ^Schapter_title Instead of writing that down in each place, we do this: .sr chapter_form \^Nchapter. \^Schapter_title The exact meaning of the backslashes is made clear in node Backslash, but suffice it to say that if you leave them out, you will certainly not get what you want. Anyway, when we want the line to come out, we can just do: ^Schapter_form and the chapter number and title will come out. Number registers can also be inserted as Roman numerals (upper or lower case), or alphabetics (1 => A, 2 => B, 3 => C, etc.) by putting a special character just after the ^N. See the reference manual's description of ^N for a list of these. Similarly, string registers may be inserted in upper case, lower case, or capitalized (first letter upper case, rest lower) by putting a special character just after the ^S. Again, we refer you to the reference manual for details. IMPORTANT: Remember how we describes R as reading a character at a time in node Input? Well, when a ^N or ^S is encountered, R reads along until it finds a character that cannot be part of a register name. All the characters is has read between the ^N or ^S and that point are grouped together to make a register name, and then the value of the register is looked up. There are some problems you might encounter because of the way this works. For example: .nr foo 100 10 times 10 times 10 equals ^Nfoo0. In this example, R will try to look up a number register called foo0, and will NOT try to find foo. The way out of this problem is to write the second line like this: 10 times 10 times 10 equals ^Nfoo!0. We say that the ! TERMINATES (ends) the register name. By special dispensation, the ! is thrown away. Therefore, .sr foo BAR And I say FOO ^Sfoo! will print as: And I say FOO BAR Whereas And I say FOO ^Sfoo!! will print as And I say FOO BAR! One final situation should be mentioned, which is less common, but you might need to know about it. It is possible to read part of the name of a register from another register: .sr b bar .nr foobar 1000 10*10*10 = ^Nfoo^Sb. will print as: 10*10*10 = 1000. You may need to use ! in such situations. Here is a hairy example for you to think about: .sr b bar .sr f foo .sr foobar form R is a text ^S^Sf!^Sb!!atter.  File: RGUIDE, Node: Expressions, Up: Top, Previous, Registers, Next: Backslash An expression is a way of writing down a little computation for R to perform. Expressions are used in many requests. Some of these requests, for example, .NR, are looking for just a number, and others are looking for a description of a horizontal or vertical distance. (Horizontal and vertical distances are distinguished mainly because they involve different actions on the part of output devices.) The simplest thing you can put in an expression is a number, such as 1, or 2.5, or .001, etc. If the situation calls for a whole number, R will round the expression to the nearest whole number for you; halves round down. The next simplest thing you can put in an expression is the name of a number register. It will be treated as if you put a ^N in front of it. Note that there are occasions where you must put an ! after the number register name to show R where it ends (see node Registers for more information on this use of !). Beyond simple numbers and number registers, you can compute and combine expressions into larger expressions using the various OPERATORS. The reference manual has complete details, but here are some of the highlights. +, -, *, / stand for addition, subtraction, multiplication, and division +, - may also be used in the sense of +1, -1, -n, etc. parentheses, ( and ). may be used to group parts of an expression, e.g., (a+b)/(c+d) No spaces should appear in an expression. Besides computing numbers, expressions can be used in the sense of logical or truth values; 0 means false, and not 0 means true. For example, .if press says go on if "press" is true, namely, if the number register press is not 0, which happens only when the output device is Press. Here are some of the operators used this way: ==, ~= return 1 (true) if the left-hand and right-hand expressions are equal (==) or not equal (~=), and return 0 otherwise. <, <=, >=, > return 1 if the left-hand expression is less than, less than or equal, greater than or equal, or greater than the right-hand expression. &, | returns 1 only when both (&) or at least one (|) of the left- and right-hand expressions is true ~ returns the opposite truth value, i.e., it means "not", as in ~(a&b) Here are some examples taken from the macro package: .nr chapter chapter+1 .if toc_level>0 .if ~ignore_level (a trick; the same as .if ignore_level==0) .if table_of_figures&~ignore_level .if (last_fig_pos~=vpos)|(last_fig_page~=page) .nv one_line ls*fheight/100 Horizontal and Vertical Expressions: These consist of a regular expression, possibly followed by a letter to indicate some measurement unit, e.g., c indicates centimeters. See nodes Page Layout and Line Layout for more details on these units. Here are some examples to show what you can do: .sp (fheight+100)m .hp ll-rindent!m ^V(+delta1!m) .hs -(wid1+wid2)/2m  File: RGUIDE, Node: Backslash, Up: Top, Previous: Expressions, Next: Justification This node may (and perhaps should) be omitted on first reading. The \ characters turns into R control-\ when read, unless quoted with ^Q (see node Input for that discussion). The purpose of the R control-\ character has not been made clear, however. It turns out that there are four distinct uses of \ in R: as a text character (when quoted with ^Q) to indicate ESCAPE CHARACTERS to PROTECT R control characters to indicate continuation lines * Menu: * Escape characters:: How to make a convenient abbreviation for a hard to type character; how to get a text ^J, ^M, or ^L. * Protecting:: A discussion of protected control characters; essential for advanced work. * Continuation lines:: How to get continuation lines -- a real convenience feature.  File: RGUIDE, Node: Escape characters, Up: Backslash, Next: Protecting Escape characters provide a convenient way of writing down characters that are otherwise hard to type. There are 26 escape characters, called escape-A, escape-B, ..., escape-Z. They are written \a, \b, ..., \z (you can use upper case letters if you like, but they mean the same as the lower case letter). The .EC command is used to say what character you want a particular escape character to really be. For example: .ec c ^C will cause \c to mean ^C (that is, R control-C) whenever it is seen in the input. Most escape characters mean nothing when R starts, and it will print an error message if you use them. However, the following are pre-defined, because it is impossible to get them otherwise: \n as text ^J (n for newline) \r as text ^M (r for return (carriage return)) \p as text ^L (p for page (form feed)) It is not recommended that you try to get these characters any other way -- it may work on some systems and not others, because different combinations of these are used to indicate line boundaries.  File: RGUIDE, Node: Protecting, Up: Backslash, Previous: Escape characters, Next: Continuation lines Here we describe the primary use of \ in macros and string registers, which is to "protect" control characters, i.e., prevent the control character's action from being performed until the right time. This is best explained by means of some examples that illustrate the problem that \ is intended to solve. We take our first example straight from the standard macro package. There is a string register named center_heading that is inserted (using ^S) in the middle of the top of the page, to print a heading. Normally it prints: - page - where page is the current page number. Now, consider how we might DEFINE center_heading originally. Here is a try: .sr center_heading - ^Npage - This is a good try, and shows some understanding of how string and number registers work. However, it will result in this being printed at the top of every page: - 1 - The problem is that the value of the number register "page" is sampled at the time the string register "center_heading" is defined, so center_heading's contents turn out to be "- 1 -" instead of "- ^Npage -". What we need is a way of saying "I want to put a ^N into the string register, not look up the number register right now". That is exactly the function of \. Here is the correct way to set center_heading to get the desired effect: .sr center_heading - \^Npage - Now you may be able to understand an earlier word of wisdom that we asked you to take on faith, namely: .sr foo \ abc puts a space, a, b, and c into string register foo. What you are getting is a protected control space. A protected control space is clearly not the same as a control space, and it is control spaces that are skipped between the arguments to a .SR. So now you should understand both why the \ is required, and why it works. Backslashes can be used to protect ANY R control character from being INTERPRETED (interpreted means being gobbled and causing a special action), however it is needed only in the cases where the control character would be interpreted anyway. The reference manual explains the exact situation in more detail, but the only control characters that commonly require protection are ^N, ^S, and ^A. Sometimes you might have to protect a control-., control-', control-space, control-I (tab), control-J (newline), ^Q, or ^K, but those situations tend to be more rare. Multiple backslashes. Occasionally it is required to put more than one \ in front of a control character. Here is an example: .sr heading ^Sleft_heading^C^Scenter_heading^R^Sright_heading This is supposed to set up a single string register so that when inserted with ^S it will print the left heading on the left, the center heading centered (the ^C centers stuff), and the right heading flush against the right edge (^R does that). But those headings are each defined separately in different string registers. Once again we run into the problem that if we do: .sr center_heading - \^Npage - we will not get nice headers. The reason is that although center_heading has "- ^Npage -" in it, when we put center_heading into heading, the characters are read again, and the ^N will be interpreted, resulting in heading containing this: ...^C- 1 -^R... which is not what we wanted. One solution is to define center_heading this way: .sr center_heading - \\^Npage - We say that the ^N is protected TWICE in this case. R is willing to let you protect a control character many times (at least 9, anyway). In general, something may be read many times if it is moved from register to register, and it is necessary to know how many times it is moved in order to get the number of \'s right. Because this is inconvenient to do, and makes changes hard, another feature was introduced to make doing this kind of thing easier. If the ^S used to insert a string register is followed immediately by a ":", then every control character in the string has an extra \ put in front of it before it is inserted in the input stream. This prevents interpretation of any control characters in the string, and means that the initial setup requires just one backslash. Here is the example above reworked with this ":" feature: .sr center_heading - \^Npage - .sr heading ^S:left_heading^C^S:center_heading^R^S:right_heading You should know that there are cases where multiple backslashes are still needed; however, these generally occur in more sophisticated things, such as macros that define macros, etc.  File: RGUIDE, Node: Continuation lines, Up: Backslash, Previous: Protecting If you put "\!" at the end of a line, then the \, !, and the newline all disappear from R's input, as if they were never there. This is convenient when you have long request lines, or long lines in nofill mode, etc., where it is important that R THINK that the input is all on one line. However, when R tells you a line number, as in an error message, the number is the real line number in the file. This makes it easy to find the relevant place in your file. \! can be used to throw away ANY immediately following character, but I have never thought of anything that is useful for except continuation lines.  File: RGUIDE, Node: Justification, Up: Top, Previous: Backslash, Next: Fonts There are several sub-topics here, indicated in the menu below: * Menu: * Filling:: Fill vs. Nofill mode This describes how R decides what to put on each output line. * Breaking:: What happens when R decides it is time to start a new output line in fill mode. * Adjusting:: This describes what R does with the stuff on an output line once it has accumulated it. The most interesting part is the process commonly known as justification, in which spaces are widened to give straight edges for text on both the right and the left.  File: RGUIDE, Node: Filling, Up: Justification, Next: Breaking In NOFILL mode, each output line corresponds to exactly one input line (except for continuation lines; see node Continuation Lines). That is, lines are not FILLED out with words from succeeding lines to try to make them reach to the right margin. Nofill mode is appropriate for tables, program code, diagrams, etc. It is often used for title page information as well. In FILL mode, words from more than one input line are accumulated so as to fill out the space from the left margin to the right margin, as closely as possible without overflowing. Fill mode is used for normal text. The newlines at the end of each input line are turned into justifiable spaces (R control-spaces, that is). If you have a period, question mark, or exclamation point at the end of an input line, an extra space is inserted, because it is accepted style to separate sentences by two spaces instead of one. You should not leave spaces at the end of input lines unless you really want them in the output, because they will not be thrown away unless the line just happens to break there. If an input line starts with a space, tab, or ^P in fill mode, then any partial line is output before that input line is processed. The same holds for a blank line. So, for items indented by hand with spaces, tabs, etc., you do not have to go to nofill mode or put in .BR's to suppress filling from line to line. To get rid of the line break caused by putting a space or tab at the beginning of a line, you may do one of three things: Rearrange the input so that none of the affected lines starts with a space, tab, etc. Use continuation lines to make the lines look like a single input line to R (see node Continuation Lines). Use ^G to glue the two lines together. The ^G may be placed at the end of the line preceding the one that starts with spaces, or at the very beginning of the line starting with spaces (before the spaces). Details of what happens when a line is broken are presented in the next node, Breaking. To get into fill (nofill) mode, the .FI (.NF) request is used. These requests permit you to set the adjustment mode at the same time (see node Adjusting). Another way to control filling is the FILL number register. In many cases the number register is the appropriate thing to use when writing a macro (see Writing Macros).  File: RGUIDE, Node: Breaking, Up: Justification, Next: Adjusting, Previous: Filling, Next: Breaks happen in two ways: 1. when a line gets too much text on it in fill mode, and must be broken to start a new line; and 2. when any partial line is requested to be output, so that the next line will start fresh. The second kind of break happens as a "side-effect" of a number of requests. Such requests are said to "break". For example, the .SP request, which is used to generate white space, is a breaking request. The idea here, as with most breaking requests, is that you probably want any partial line output BEFORE the space rather than AFTER it. All requests that break, cause the break before they do anything else. To suppress the break, precede the request with ' instead of ".". For example, 'SP will not break, where .SP will. It is considered good style to use "." everywhere, except those places where you really need to suppress a break. The second kind of break also happens when a blank line, or a line starting with a space, tab, or ^P is encountered. Again, it was done this way because it is usually what you want. Node Filling mentions ways of suppressing this. The first kind of break, the kind caused by overflowing a line in fill mode, is different from the second kind of break in two main ways. First, it is determined implicitly by R, as it computes how big each letter, etc., is. Second, after deciding where to break the line, the text on the line to be output is justified according to the current adjustment mode (see the next node, Adjusting). About spaces: R will not break a line in the middle of a text word, but will break it almost anywhere else. In particular, R will break at a control-space (which is what the space character normally turns into -- see node Input). One way to prevent a break at a bad place is to use a text space instead of a control space. This can be done by writing "^Q ", but most people use .TR to TRANSLATE some other character to a text space when output. Node Setup suggests that you include the line ".tr @" in your setup, which will cause @ to be translated into a text space on output. That way you can write @ wherever you want a space that will not be broken. For example, "foo bar" may be broken in the middle, but "foo@bar" will not. However, you should know that it is control spaces that are widened during adjustment (see node Adjusting), and text spaces will not be widened. If you need more sophisticated behavior, see nodes "Math", and "Writing Macros", for techniques that may be used to build up formulae or expressions that you do not want broken in the middle.  File: RGUIDE, Node: Adjusting, Up: Justification, Previous: Filling Once R has determined what items will go on a particular output line, that line may be JUSTIFIED before being output. There are several different ways this can be done, and they are controlled by the current ADJUSTMENT MODE. Let us first discuss the effects of the different adjustment modes, and when adjustment will and will not be done, and then describe how to set the adjustment mode. R has four distinct adjustment modes: LEFT adjusted - The line is output against the left margin, and spaces are not widened. This leads to a ragged right edge. RIGHT adjusted - The line is output against the right margin, and spaces are not widened. This leads to a ragged left edge. CENTERED - The line is output centered between the margins; both edges will be ragged. BOTH - Spaces in the line are widened so that the edges of the line come just to the margins. This is what most people refer to as justification. NOTE: only control-spaces are widened; text spaces are considered to be part of words are not disturbed. The adjustment modes are entirely independent of fill vs. nofill mode: all eight combinations of fill and adjust modes are legal, though some are not very useful. Here are the most useful ones: fill both - used for most text nofill left - the usual usage of nofill mode, for diagrams, programs, equations, etc. nofill center - often used to center one or a few lines for a header, title page, etc. Fill left is sometimes useful for things that look better with a ragged right edge than with big spaces between the words. Bibliographies have a tendency to look better in fill left than in fill both. The other four combinations, nofill left, nofill both, fill center, and fill right, just do not seem to be very useful. R performs adjustment of every output line except those output in fill both mode by an explicit break. (An explicit break is the type of break labelled by a 2 in node Breaking.) Adjustment is suppressed in this case so that the last lines of paragraphs will not be stretched out across the whole line. If you use center or right adjustment in combination with tabs, ^P, or other absolute positioning requests, the result you get is hard to describe, and probably not what you want. So, you should simply avoid doing that. The ^C and ^R characters provide a more powerful way to center and right-flush items, even within columns in a line. See node Line Layout for more details. Setting the Adjustment mode. R actually remembers the last adjustment mode used with fill mode, and the last one used with nofill mode, separately. If you use .FI or .NF with no argument, or set the FILL number register, the adjustment mode changes automatically to the last adjustment mode you used with whatever fill moe you are going to. On the other hand, you may give an argument to .FI (.NF) to have to the fill adjust mode (nofill adjust mode) set explicitly. That argument consists of a single letter, one of L, R, C, and B. For example: .nf c .fi B .nf L .fi l and so on. The best style is probably to set the adjust mode every time, so you don't have to remember what is was before, but it is a matter of personal taste. The fill adjustment mode starts as "both", and the nofill adjustment mode starts as "left", on the grounds that these are the most common settings. In addition to the .FI and .NF requests, the adjust mode may be examined and changed via three number registers: ADJUST, ADJUST_FILL, and ADJUST_NOFILL. See the reference and node Writing Macros for more details.  File: RGUIDE, Node: Fonts, Up: Top, Previous: Justification, Next: Macro Invocation There are a number of different aspects of this subject: * Menu: * .FO:: How to tell R what fonts you want, and what fonts are. * Switching Fonts:: How to change what font R is using. * Selecting Fonts:: How to control what fonts the macro package will use for various things.  File: RGUIDE, Node: .FO, Up: Fonts, Next: Switching Fonts R permits you to use many different typefaces, called fonts, in a single document. Typically one chooses a font for normal text, and italic and boldface fonts that go well with it. Also, it is common (and the macro package assumes it) to define a larger font for section headers, titles, etc. Beyond that, it is usually a question of fonts with special characters, such as Greek letters and mathematical symbols, smaller or larger fonts for special use (such as a small font for footnotes), and fixed width fonts for diagrams and programs. R permits up to sixteen fonts to be defined. Each is defined using the .FO command. You might think that we would number them 1 through 16, but we wanted to be able to designate a font with a single letter. So, we "number" them 0 through 9 and A through F. You cannot change fonts in the middle of a document; you are limited to 16 fonts overall. The .FO line has these parts: .FO The part consists of a FONT DESIGNATOR, namely, one of 0 through 9 or A through F. The says what font to associate with that font number. The treatment of this field depends on the output device: XGP - you should supply the name of a KST file describing the font VARIAN - you should supply the name of a VFT file PRESS - you should supply the name of a Dover font LPT, DIABLO - the field is ignored, and may be blank For more information on the fonts available and how to specify them, read the following nodes, or consult the reference manual: Filenames, Output Devices, Setup The part of the .FO line is usually omitted. However, you can do some useful things with it. One is to separately control what file the XGP will use for a font versus what file R uses to see how big it is. See the reference manual for details. The other thing you can do is to have R highlight text that is supposed to appear in a different font when you are producing output for a single font device (LPT or DIABLO). For each font, R is willing to do one of four things: Nothing - Output the text with no modification. Overprint - Print the text several times, to make it look bold. The number register NOVER controls how many times each letter will be typed; it starts set to 2 (print twice). Underscore - Underscore all characters output in the given font. Capitalize - Capitalize all lowercase letter in the given font. By default, R does font 0 normally (no special highlighting), and all other fonts are underscored. You can change this, for each font individually, by putting a letter in parentheses as the for a given font. The letters are: n = nothing, o = overprint, c = capitalize, u = underscore Examples: .fo 0 25fg (u) .fo 1 25fgb (O) .fo 2 25fgi (n) .fo 3 37vrb (C)  File: RGUIDE, Node: Switching Fonts, Up: Fonts, Previous: .FO, Next: Selecting Fonts The most common case of changing fonts is to one or a few words in another font. For example, a single word or expression in italics or boldface, or a special character, such as a Greek letter or mathematical symbol. R provides a very easy way to do that. You just put ^Fx where you want to change to the different font, where "x" is the font designator character for the font you want. If that sounds confusing, and example should make it clear. Say that your Greek letter font is font 6. To get a sigma, just put ^F6s... (the ... will be filled in in a moment). Similarly, to switch to font A, just write ^FA, etc. In most cases it is possible to do all font switching explicitly like this, so the ... above might be filled in with ^F0 to switch back to the normal font: ^F6s^F0. However, there is a better way -- the special expression ^F* means go back to whatever font you had before the last ^F setting. Thus, ^F6s^F* means "go to font 6; output an s (sigma); go back to the font you had before". R remembers a whole bunch (10) of these previous fonts, so you can do things like: ^F2Here is some bold text with one ^F1italic^F* word.^F* It is considered good style to use the ^F* feature wherever you can, because it leads to fewer errors. Note also that R will produce a warning message if enough ^F*'s are done so that it would have to back up more than 10 fonts' worth. That situation is called "font ring-buffer underflow". Hint: When you have a special symbol that is in a different font, and you use it in many places, you may find it helps to define a string register abbreviation. For example: .sr sig ^F6s^F* Here is where ^F* is a MUST, so that you will not switch back to the wrong font. Using a string register this way has two strong advantages. First, when you see a use in the text, it is easier to tell what you are dealing with: ^Ssig conveys more information that ^F6s^F*, and results in a little less clutter on your screen. The other advantage is that if you change the number of the font, or decide to switch to another character, you need only change the string register definition line, instead of every use of a sigma in your file. So, give string registers a try! It you have a large amount of stuff to do in another font, you can use the .FS request. For example: .fs 2 ... several lines in italics ... .fs .FS takes a font designator character as its argument, so to switch to font C, you can write: .fs c (or .fs C). A .fs with no letter after it, such as the second one in the example, works like ^F* -- it means to go back to the previous font. The standard macro package provides several features to aid you in font switching; see the next node, Selecting Fonts, for more details. There is a fine point of difference between ^F and .FS, that usually does not make any difference. However, we mention it here so you will know about it. Besides the idea of the CURRENT FONT, which is the font R uses at any given time for outputting characters, there is also something called the PRINCIPAL FONT. The height of the principal font governs line separation calculations, along with a number of other factors. (The details are in node Line Spacing.) The principal font also determines the with of a control-space character. The point here is that ^F changes only the current font, but .FS changes both the current font and the principal font. The number registers FONT and PFONT control the current and principal font, respectively. They provide an alternate mechanism for font switching that is often the most appropriate one for use in macros. In cases where you desire to change both the current and principal fonts to be a particular font, and you do not wish to use .FS because it uses the font stack, you may use the SET_FONT macro. It takes one argument, a numerical expression (number register names allowed), and sets FONT and PFONT to that number. Here are some examples: .set_font italic_font .set_font 3 .set_font 13  File: RGUIDE, Node: Selecting Fonts, Up: Fonts, Previous: Switching Fonts The macro package provides a number of features related to fonts that should be of assistance to you in document preparation. First, it provides two ways of switching to fonts that do not require you to remember which number corresponds to which font. Method 1: There are several string registers defined that contain a ^F and a font designator, to switch to a particular font. These string registers are: NF - switch to the normal font BF - switch to the bold font IF - switch to the italic font These start with the right values in them for the macro package's normal assignment of fonts: normal = 0; bold = 1; italic = 2; big = 3. Naturally you can change the contents of the string registers as you please. Perhaps even more useful, you can convince the macro package to use different names for the string registers in question, if the above names are inappropriate. These string registers contain the NAMES to use for the string registers mentioned above: nf_reg -- name of string register for the normal font; starts as NF bf_reg -- same for bold font; starts as BF if_reg -- same for italic font; starts as IF However, any changes to these last three must be done BEFORE you insert the standard macro package (i.e., before you do the .SO of the file R.MACROS), and can never be changed later. This feature is introduced so that you can use the names NF, BF, or IF for something else without screwing up the macro package or yourself. Method 2: The macro package provides several macros for outputting text in a selected font: NORM - outputs its arguments in the normal font BOLD - outputs its arguments in the bold font ITAL - outputs its arguments in the italic font BIG - outputs its arguments in the big font These macros are intended to be invoked inline with ^X (see node Macro Invocation for further discussion). Here is an example use: ^Xbold(Most of this is bold, but this ^Xital(word) is italic.) You may define more such macros in a very simple way: .def_font_macro foo num will define a macro with name "foo" that outputs its arguments in whatever font the number register "num" contains. Here is an example: .fo 7 hippo .nr greek_font 7 .def_font_macro greek greek_font and then later: ^Xgreek(a b g d) will print alpha, beta, gamma, delta. For flexibility, the macro package permits you to control what font it considers to be the normal font, italic font, bold font, and big font in the above two methods. As we have said in several places, these start as follows: NORMAL_FONT - 0 BOLD_FONT - 1 ITALIC_FONT - 2 BIG_FONT - 3 However, by setting the number registers mentioned above, you will change what the macro package will use. For example, if you type ".nr bold_font 6" then ^Sbf and ^Xbold will use font 6 instead of font 1. You can change the bold_font number register, or any of the others, as often as you wish. In fact, the macro package will automatically change the definitions of NORMAL_FONT, etc., in certain special cases. One of those cases is footnotes. Within a footnote, normal_font, italic_font, and bold_font are temporarily set to footnote_font, footnote_italic_font and footnote_bold_font. This is because many people like to have footnotes printed in a smaller font. Here is how you might do that: First, put these lines in your setup, i.e., before the line with ".so r.macros": .fo 4 timesroman8 .fo 5 timesroman8b .fo 6 timesroman8i .nr footnote_font 4 .nr footnote_bold_font 5 .nr footnote_ital_font 6 Of course you can use any fonts you like, and they don't have to be 4, 5, and 6, or in order, or anything. The important thing is that the number for footnote_font be the number of the font you want for normal text in footnotes, etc. One thing you should realize is that if your font is one of A through F, you must use the letter in the .FO, but the corresponding number (10 through 15) in the .NR. For example: .fo A timesroman8 .nr footnote_font 10 If you are using a setup as described in node Setup, with one set of fonts for the Dover, and another set for the XGP and otehr devices, you will have to do 2 .FO's, one for each case. The .NR need only be done once, just before the .SO, provided you used the same font numbers for the different devices, which you probably should do, or you will just confuse yourself. If you ever need to convert a font NUMBER to a font DESIGNATOR, there are some pre-defined string registers that do it. The string register _font_n (where n ranges from 0 to 15) contains the font designator for the font with number n. For example: .fs ^S_font_^Nital_font Here is a list of the things for which you can separately control what font will be used. The names are the names of number registers that you can set to select the font you want for the given thing. They all have "reasonable" defaults. Below, toc = table of contents. headings: heading_font footings: footing_font footnotes: fnfont for the superscript number, footnote_font, footnote_bold_font, and footnote_ital_font for the body figures and tables: figure_font and table_font for the bodies; figure_title_font and table_title_font for the title lines; figtab_toc_font for the toc entries. chapters: chapter_font for the header line; chapter_toc_font for the toc line. sections: section_font for the header line; section_toc_font for the toc line. appendices use the chapter fonts. subsections, subsubsections, subsubsubsections, and achapters use the section fonts. In addition, there are a number of places where the macro package will use big_font, etc., itself. These are mentioned in the appropriate sections later. The default values for the registers listed above are set when you read in R.MACROS, but only if you have not previously set them. Further, the default values are set according to the values of normal_font, bold_font, etc., in effect at the time you read in R.MACROS.  File: RGUIDE, Node: Macro Invocation, Up: Top, Previous: Fonts, Next: Page Layout This node describes how to type in arguments to macros. Both normal macro invocation (with "." and ' at the beginning of a line), and inline macro invocation (with ^X) are discussed. Note that most of the nice features of the macro package come to you as macros, so it is important to know how to use them. General information: All macro invocations consist of the NAME of the macro to invoke, and zero or more MACRO ARGUMENTS, supplied after the macro name, in order. The effect of a macro invocation is to cause some previously defined sequence of R commands to be processed, very similar to .SO or ^S or ^N. The macro arguments are available to these commands (via the ^A control character). Further discussion of exactly how it all works appears in node Writing Macros. Normal Macro Invocation: A normal macro invocation takes one of two forms: .macro-name arg0 arg1 arg2 ... argN or 'macro-name arg0 arg1 arg2 ... argN There may be any number of spaces and tabs between the "." or ' and the macro name. Then zero or more arguments follow. There are several forms that may be used to express an individual argument: Form 1: The argument is simply written down. This is the easiest form to use, and the most common. However, it has some limitations. You cannot have an unprotected control-space or control-tab in this form of argument (because spaces and tabs are used to separate arguments), or an unprotected control-J (newline) (because newlines terminate the whole macro invocation line). So, you must either protect such characters with backslash (see node Backslash), or, in the case of spaces, you could use a text space or a character that translates to text space. Nodes Input and Justification explain this in more detail. Form 2: The argument is surrounded by double quote characters ("). This form of macro argument may control unprotected spaces and tabs, but cannot contain an unprotected control-J (newline). Also, to get a " character in as part of the argument, you must write two quote marks in a row. For example, .foo """" invokes foo with a single argument consisting of the single character ". Here is another example of a form 2 argument: .chapter "Effects of Swapping on System Performance." Form 3: The argument is surrounded by { and }. This form of macro argument may contain unprotected spaces, tabs, and control-J's, and is therefore the only form of argument that can extend over more than one input line without special care. Its only limitation is that the curly brackets, { and }, must be BALANCED inside the argument. If an argument of this form extends over too many lines, an error message is printed (to help you find unmatched curly brackets). See the reference manual for details. Here is an example of this form of macro argument: .chapter {Effects of Swapping on System Performance.} Inline Macro Invocation. An inline macro invocation one of these forms: ^Xmacro-name or ^Xmacro-name! or ^Xmacro-name(arg0 arg1 ... argN) The first and second kinds are used when the macro is to be supplied no arguments at all. The ! can be used all the time, and must be used in cases where the next character read might be included in the macro name. See node registers for further discussion and example of this use of !. The last form is used when the macro has 1 or more arguments. The forms the arguments may take are essentially the same as the forms for normal macro invocation, which are listed above. There is only one difference: you may not have unbalanced parentheses in an argument of form 1. What actually happens is that every time an open parenthesis is seen, the argument scanning continues at least until the matching close parenthesis. This permits nested use of ^X, as shown here: ^Xdiv(a+b ^Xdiv(c d*e)) The arguments to the first invocation are "a+b" and "^Xdiv(c d*e)", and the arguments to the second invocation are "c" and "d*e". Differences between the two kinds of macro invocation. The main difference between the two forms is that normal macro invocation may be used anywhere, and takes effect immediately, whereas inline macro invocation only takes effect when the ^X is seen when scanning text (as opposed to reading request lines). Another important difference is that any text produced by inline macro invocations is automatically glued to surrounding words (assuming they are adjacent). Most of the macro in the macro package are designed to be invoked using normal macro invocation. Others are intended to be invoked inline, and explanations of them will mention that fact. Do not expect good results if you invoke a macro in a fashion other from that intended for it, because the principles of design of the two kinds of macros are a bit different.  File: RGUIDE, Node: Page Layout, Up: Top, Previous: Macro Invocation, Next: Line Layout The standard macro package splits each output page up into a number of regions, from top to bottom. These are: the header area the text area the footer area We describe each in turn, and at the end, introduce some convenient macros used for setting up margins, and explain R's notation(s) for vertical distances and their meanings. We also mention miscellaneous requests used for vertical positioning. Headers: Headers are things like the page number, etc., printed at the top of each page. The default is to print "- page# -" centered at the top of the page. The string registers left_heading, center_heading, and right_heading contain the actual headings, so you can change them freely. The number register section_headings, if set to 1 (it is normally 0) will set left_heading to the contents of section_title, and right_heading to the contents of section_number_title, for each page. See node Sectioning for details of what those registers contain. (Section_title is the title of the current section, and section_number_title is something like "Section 1.3".) The number register both_sides controls whether to swap the headers on pages with even numbers. It is defaultly off (0), but you should set it to 1 for documents to be reproduces by printing on both sides of the paper. Headers are normally suppressed on the first page (page 1), but if you set the number register print_page1_headings to 1, then they will be printed. If you want no headings at all, set the number register print_headings to 0. The number register heading_font control what font will be used to print the headings (defaultly normal_font). The number register heading_pos contains the vertical position at which to print the headings (if any). This is expressed in mils (thousandths of inches), measured from the top of the page. Thus, the default value, 500, print the headings 1/2 inch from the top of the page. If it makes a difference, the distance is from the top of the page to the baseline of the header line. Text area: The text area starts below the headers. The exact position is controlled by the number register top_margin_size. Thus, according to R, the headers are printed in the margin. The default value for top_margin_size is 1000, and its units and meaning are like those of heading_pos, so text normally starts one inch from the top of the page. The text area end just above the footers. The distance from the end of the text area to the end of the page is defined by the number register bottom_margin_size, and is defaultly 1000 (i.e., one inch). Note that figures, tables, and footnotes are always printed in the text area, even when printed at the bottom of the page. For more details on them, see the relevant node. Footers: Footers are like headers, except they are printed at the bottom of the page. Their appearance is controlled by number and string registers analogous to the ones for headings; we simply list them below, and indicate the default values: print_footings - 0 (i.e., normally NOT printed) footing_font - normal_font left_footing, center_footing, right_footing - string registers, all normally empty footing_pos - 500 (mils, measured from top of bottom margin, i.e., end of text area) footing_height - 167 (mils, increase it if you use a large font; its purpose is too obscure to go into here) The number register both_sides controls swapping of footers as well as headers. Footers will be printed on page 1 (if print_footings is on (1)). Setting margins: You could set up all the margins yourself, and for complicated things, you maybe required to do that. But there are two macros available that handle most of the common cases. The old macro: MARGIN This macro takes four arguments, each suitable for a .VX (see description of vertical units and requests, below), in this order: top margin size, bottom margin size, left margin size, and right margin size. Note that headers are printed WITHIN the top margin, and footers within the bottom margin. Also, this macro does NOT change heading_pos or footing_pos, or take both_sides into account. The macro described below is probably better -- MARGIN is being retained for compatibility. This example sets the margins to the way they start: .margin 1i 1i 1i 1i The better macro: SMARGINS This macro takes four to six arguments. The first four arguments are the top, bottom, left, and right margin sizes, in that order, however, the top and bottom margin sizes indicate the amount of white space desired. That is, headers and footers will not be printed in these margins. The fifth argument, which is optional, allows you to specify the distance between the headers and the start of the text area (defaultly 1/2 inch) and the sixth argument (also optional), can be used to specify the distance from the end of the text area to the footers. This macro takes the settings of print_headings and print_footings into account, so as to provide the maximum text area that is consistent with the margins requested. That is, if you do not print headers (footers), then the space that would otherwise be used for them will be used for text. SMARGINS also takes both_sides into account when setting up the left and right margins. This example sets the margins to the way they start: .smargins .5i .5i 1i 1i .5i .5i Vertical expressions: A vertical expression consists of a whole number, or a number with a decimal fraction, optionally followed by a letter. here are the different meanings for the letters; assume the number was "n": no letter - n times the default line height; the default line height is directly related to the height of the principal font. For details see node Line Spacing. a - n micas. One mica = 10 microns = .01 centimeters = 1/2540 inch. Because a mica is less than a mil, conversions to/from micas may not be exact. c - n centimeters. i - n inches. l - n lines. This is like n with no letter, except that it is additionally multiplies by the line spacing factor, LS. See node Line Spacing for more details. m - n mils. 1 mil = 1/1000 inch = 2.54 micas. u - n units, where a unit is the smallest distance by which the output device can position text vertically. This should be avoided because it introduces dependencies on particular devices. It is included because it is sometimes necessary. In situations calling for a vertical expression, you may use any of these freely. For example, the .SP request takes a single argument, a vertical expression, so all of the following are legal: .sp 1 .sp 1l .sp 2.5c .sp 135u .sp .5i .sp 150m .sp 650a More complicated expressions are permitted, too. See node Expressions for details and examples. Relevant requests: .VX n v1 v2 v3 ... vK - set the number register n to be the number of mils in the sum of the distances given by the vertical expressions v1, v2, ..., vK. For example, .vx vpos vpos!m 10l .VV n v1 v2 v3 ... vK - equivalent to: .NV n n .VX n v1 v2 v3 ... vk .SP v - leave an amount of white space equal to the vertical distance specified by the vertical expression v. A blank line is equivalent to a .SP with no arguments, which is equivalent to .SP 1 .VP v - go to position v on the page. 0 means the top, 1i means one inch from the top, etc. Some other relevant requests are described in Line Spacing. Also, ^V(+v) and ^V(-v) are described in Line layout. The reference manual section on line spacing discusses this in more detail, including the VPOS and LVPU number registers. NOTE: 1i in a vertical expression is not equivalent to 1i in a horizontal expression, because horizontal items (e.g., HPOS) and vertical items (e.g., VPOS) are stored internally in different units.  File: RGUIDE, Node: Line Spacing, Up: Top, Previous: Page Layout, Next: Line Layout There are several factors that control the space between lines in R. They are: the height of the principal font the leading the line spacing factor (LS) and the actual height of the line The nominal spacing between consecutive output lines is the DEFAULT LINE HEIGHT times the line spacing factor LS. That is, the distance between the baselines of two lines will be: default line height * ls / 100 The division by 100 is there because LS is in units of hundredths of line heights. In vertical expressions, the number n means n times the default line height, whereas nl (n lines) means n times the default line height times the line spacing factor. The default line height is defined this way: default line height = fheight * (100 + leading) / 100 where fheight is the height of the principal font (the distance from the bottom of the character that goes the farthest below the baseline to the top of the character that goes the farthest above the baseline). FHEIGHT is available in the number register of the same name, as is LS. The number register LEADING gives the default percent white space between lines, and starts as 20. This choice is governed by long established aesthetic principles of the printing industry, so you should not change it lightly. The appropriate place to make an adjustment is usually LS, and R provides the .LS request for that purpose. Note that .LS takes the line spacing factor "straight", so that the value of the LS number register is 100 times the value you write in a .LS. For example, .ls 2 will give you double spaced output. R starts with LS equal to 100 (single spacing). Historical note: Leading is pronounced "ledding", and refers to the fact that in printing the space between lines in filled with thin strips made of lead. The above discussion concerns the NOMINAL spacing of lines. R calculates the exact height of each line above and below the baseline (the HABOVE and HBELOW built-in number registers provide access to this information), and R will move a line down to make sure that it does not overlap the previous line. This happens more often if LEADING is set to a smaller value, or if you use a lot of subscripts, superscripts, or characters from a large font. If you do not like it, your only recourse is to increase the line spacing, or get rid of the offending tall character(s).  File: RGUIDE, Node: Line Layout, Up: Top, Previous: Line Spacing, Next: Horizontal Positioning R divides the space across the output page into a number of regions, from left to right: the left margin the indentation the text area the right indent the right margin The sizes of these are defined by the values in various number registers, and can be controlled by setting the number registers or using some R requests. Below is a description of the interesting things in left to right order. At the end is a description of horizontal expressions. Left margin - Defined by what is called the OFFSET, which may be different for even and odd numbered pages, so that document to be reproduced on both sides of the paper can be handled nicely. This can be examined via the EO, OO, and POFF number registers, but can be set only via the .EO and .OO requests. The default is one inch for both even and odd offsets. For more details on changing margins, see the discussion near the end of node Page Layout. NOTE: The offset defines the origin of horizontal position calculations, specifically, HPOS is 0 when you are at a distance from the left edge of the paper equal to the offset. Also, the horizontal position is never permitted to be less than 0. Indentation - The indentation is defined by the value of the INDENT number register, and is the distance from the offset to where the current text line should start. The indentation is typically 0, but it is not unusual to indent a group a text lines, as in the case of a quotation, for example. If you want a number of indented items, you may find the list macros convenient; see node Lists for more information about them. The indentation can be changed "manually" with the .IN request. This takes three forms, illustrated below: .in 1i set the indentation to one inch .in +1i increase the indentation by one inch .in -1i decrease the indentation by one inch Usually a matched pair of the last two forms is better than setting the indentation explicitly, because it allows something to be moved around, etc., with fewer errors. Node Alignment discusses a very safe and easy to use method changing the indentation, which you should read about. In addition to the indentation, which is used for indenting a group of lines, there is also a feature called the TEMPORARY INDENTATION, which takes effect for just the next line. It can be set only via the .TI request, which has three forms just like those for .IN. Note that a relative temporary indentation is relative to the indentation. This request is often used for making paragraphs, e.g.: .de para define a macro for starting a paragraph . sp 1l it will first leave a blank line . ti +5 and then indent the first line by 5 characters . em Text area - The text area extends from the indentation, plus any temporary indentation, to the right indentation. Thus, the actual length of the text area is defined implicitly. Right indentation - The right indentation is the distance from the right margin to the end of the text area. Increasing the right indentation makes the text area smaller; that is, the indentation and the right indentation are both measured toward to center of the page. The right indentation is controlled by the number register RINDENT, which may be set directly, or via the .IR request, which works just like the .IN request. The right indentation starts as 0. Right margin - The right margin is defined implicitly by the offset and line length. That is, the right margin starts at that place which is the offset plus the line length from the left edge of the paper. For 8.5 inch wide paper, and the default offset (1 inch) and default line length (6.5 inches), the right margin will be 1 inch. See node Page Layout for descriptions of two macros to assist in setting up margins. The line length is defined by the number register LL, and can be set directly or via the .LL request. Horizontal expressions: Horizontal expression are very similar to vertical expressions. A horizontal expression consists of an expression (see node Expressions), possibly followed by a letter to indicate a unit of measurement. Here are the possibilities, assuming the value of the expression is n: no letter - n times the average character width. The average character width is the width of the "0" character, unless it is less than the width of a space (in which case the width of the space is used), or greater then the width of two spaces (in which case the width of two spaces is used). The font used for this is the principal font, NOT the current font. a - n micas c - n centimeters i - n inches m - n mils There are .HX and .HV requests that are analogous to the .VX and .VV requests discussed in node Page Layout. You should NEVER use .HX or .HV to compute a vertical distance, or .VX or .VV to compute a horizontal distance, because the internal units may be different. For example, on the XGP the units are XGP dots, and there are 192 per inch horizontally, but 200 per inch vertically. Even though R gives you the measurements in mils, it uses these units internally, so you must not confuse the two directions.  File: RGUIDE, Node: Horizontal Positioning, Up: Top, Previous: Line Layout, Next: Text Features There are several sub-topics here; you should definitely read the first two. Also, you should have read node Line Layout first. * Menu: * Absolute Positioning:: How to get to a particular place across the page. * Relative Positioning:: When to use .HS instead of .HP. * Tabs:: Using ^I (tab) and tab stops. * Centering and Righting:: ^C and ^R in the general case.  File: RGUIDE, Node: Absolute Positioning, Up: Horizontal Positioning, Next: Relative Positioning The current horizontal position is determined by the value in the number register HPOS. It is measured from the offset (the right edge of the left margin), and increases to the right. Outputting text and spaces or tabs increases the horizontal position by the width of the characters output. (For details on tabs, see node Tabs.) There are three ways to set the horizontal position to a particular value: set HPOS, with .HX or .NR use ^P use .HP Setting number registers should be familiar to you (see node Registers). .HP h will set the horizontal position to h (h is a horizontal expression; see nodes Line Layout and Expressions.) You may also say: .HP +h .HP -h to increment or decrement the horizontal position by h. However, if you are thinking of doing that, you probably should be using relative positioning (see node Relative Positioning). ^P(h) also goes to position h (h is a horizontal expression here), with a difference, though. It always moves right by at least the width of a space, and gives an error message if the position you asked for is to the left of where it ends up. Thus, it prevents overprinting, and cannot be used for going backwards. If you are trying to get things on different lines to line up, read node Alignment. Some details: Any absolute positioning command (tab, ^P, .HP, or setting HPOS) suppresses BOTH mode adjustment on its left. The main implication of this is that absolute positioning is usually inappropriate in the middle of a line in fill mode. The value of HPOS corresponds to where you are now, not where you would be after the line is adjusted. (The latter would require predicting the future.) Therefore, the value of HPOS is not necessarily useful when the adjustment mode is anything but LEFT mode.  File: RGUIDE, Node: Relative Positioning, Up: Horizontal Positioning, Previous: Absolute Positioning, Next: Tabs The .HS request (HS = horizontal space) is used for relative positioning. .HS h goes forward (or backward if h is negative) the amount specified by the horizontal expression h. Unlike .HP and friends, this works in fill mode. Further, although R may break a line at an absolute position command, it will never break a line at a .HS. So, .HS is the method of choice for building up formulae and expressions like this: |A| U a i=1 i However, before embarking on doing such things by hand, read node Math -- it will tell you about the macros already there to help with this sort of thing.  File: RGUIDE, Node: Tabs, Up: Horizontal Positioning, Previous: Relative Positioning, Next: Centering and Righting R has a built-in tab stop mechanism that lets you set a large number of tab stops. The R control character control-I (tab) goes to the next tab stop, if any. (It always moves over at least one space width.) These are the requests available for manipulating tabs: .ta h1 h2 ... hn - Removes all existing tab stops, and sets stops at the positions specified by the horizontal expressions h1, h2, ..., hn. R starts with a dozen or so stops set at intervals of 8 characters. That is, .ta 8 16 24 ... .tg name exp - Number register "name" is set to the position of the exp'th tab stop. .tu h - "Unset" (clear) any tab at position h. .ts h - Set a tab stop at position h. See the reference manual for more details. Note: The normal tab stops are set by character positions, which, if you remember, are defined by the nominal width of the principal font, which may not be the current font. So do not expect a tab to be 8 spaces in the current font unless you do this: .fs n -- makes the font both the principal and current font .rtabs -- does a .ta 8 16 24 .... Of course, even this will not work if you are using a variable width font. If this is a problem, read node Alignment.  File: RGUIDE, Node: Centering and Righting, Up: Horizontal Positioning, Previous: Tabs The actual action caused by ^C and ^R is to center or right-flush the following text between the first absolute positioning command on the left and the first one on the right. For this purpose, the margins constitute absolute positioning commands. In this case, the margins include any indentation, temporary indentation, or right indentation. Thus, the position of centered text will be different for different values of INDENT. Between any adjacent pair of absolute positioning commands, you may have centered items, right-flushed items, or both. The way you write it down goes like this: pos1 left adjusted items^Ccentered items^Rright-flushed items pos2 Before trying to make up fancy tables by hand, you should read node Columnar Tables. It describes macro packages that make it a lot easier for you.  File: RGUIDE, Node: Text Features, Up: Top, Previous: Horizontal Positioning, Next: Alignment There are many interesting things you can do in text. We have gathered together here the ones that are not discussed elsewhere. * Menu: * Superscripts and Subscripts:: How to do simple superscripts and subscripts, and also more fine vertical adjustment of characters on a line. * Underscoring:: How to underscore text; how to control whether white space is also underscored; all the other details of underscoring. * Overstriking:: How to create new characters and special symbols by printing more than one character in the same position. * Hyphenation:: A description of the minimal assistance R provides in this regard. * Substitution:: How an arbitrary string can be substituted for a character in the output. (More useful than it sounds!)  File: RGUIDE, Node: Superscripts and Subscripts, Up: Text Features, Next: Underscoring Superscripting and subscripting are special cases of changes to what is called the VERTICAL OFFSET. The vertical offset is controlled by the number register VOFF, and is the distance above the baseline at which output characters are to be placed. It is normally 0, meaning characters will be placed on the baseline. Making VOFF greater than 0 causes subsequent output to be above the baseline, and making VOFF negative, outputs characters below the baseline. Although it may be a little confusing, VPOS, the current vertical position (which determines where the baseline is) increases DOWN the page, whereas VOFF increases UP the page. Here are the methods available for adjusting the vertical offset: setting VOFF - generally used only in macros ^U - up: increase VOFF by a device dependent amount (set so that it looks good for superscripts) ^D - down: decrease VOFF by the same amount that ^U increases it; good for subscripts. ^V(v) - Change the vertical offset by v; v is a vertical expression (see nodes Page Layout and Expressions). The change may be positive or negative. ^Z - set the vertical offset to 0. Here are some examples: a^Di^U - a subscript i x^Un^D - x superscript n m^Di^Dj^U^U - appears something like this: m i j ^U and ^D should always be used in matched pairs. If the vertical offset is not 0 at the end of an output line, R will print a warning message, going something like this: "unterminated superscripts" (or subscripts). Likewise, ^V should be used in matched pairs of ^V(+...) and ^V(-...) to avoid the same error. When setting VOFF directly you must remember to set if back. Also, you should keep in mind that relative adjustments (e.g., .nr voff voff+10) can more easily be included in larger formulae than absolute ones. Hence, we do not recommend the use of ^Z. In addition to using the control characters directly, there is a (possibly somewhat more convenient) pair of macros for doing superscripts and subscripts. Here is how to use them: ^Xsub(item1 item2 ... itemN) - will output the N items shifted down by one ^D, and automatically shift back up when done. Further, it guarantees that there will be no line breaks in between the items. ^Xsup(item1 item2 ... itemN) - works exactly the same way, except that it output the items shifted up. Here are some little examples: a^Xsub(i) -- a i a^Xsub(i^Xsub(j)) -- a i j n x^Xsup(n) -- x 2 (n ) x^Xsup((n^Xsup(2))) -- x (These would look better on the XGP or Dover.) If you are trying to think of ways to build up more complicated mathematical formulae, you should read node Math for a detailed discussion.  File: RGUIDE, Node: Underscoring, Up: Text Features, Previous: Superscripts and Subscripts, Next: Overstriking Here is a list of the various things about underscoring thAt are under your control: whether underscoring is being done whether white space is to be underscored or just text characters the position of the underscoring with respect to the baseline the thickness of the underscore The number register UL controls whether underscoring is currently being done (0 means no underscoring, 1 means underscoring). However, the most common way of doing underscoring is with control characters: ^B - begin: start underscoring (set UL to 1) ^E - end: stop underscoring (set UL to 0) For example: The third ^Bword^E in this sentence will be underscored. The number register UL_SPACE controls whether white space will be underscored, or just text characters. If it is 0, only text will be underscored; if it is 1, white space will be, too. Note: if a text character prints as white space (e.g., a text space usually does), then it will be underscored in any case. Remember: R does not know anything about the appearance of text characters. UL_SPACE starts set to 0, so white space is normally NOT underscored. The position of underscoring with respect to the baseline is determined by the underscore offset, which is kept in the number register UOFF. It is measured in the same fashion as VOFF (see node Superscripting and Subscripting). It starts with a device dependent value that gives underscoring with a pleasing appearance. You may change the underscore offset by setting UOFF directly, or by using the .UO request, documented in the reference manual. Generally the only good reason for changing the underscore offset is to draw a horizontal line, as in the DIV macro (see node Math). Naturally the fineness with which UOFF can be adjusted depends on the capabilities of the output device. The thickness of underscoring is initially set to a pleasing value (device dependent). You may change it with the .UT request, documented in the reference manual. Of course, not all output devices support this feature.  File: RGUIDE, Node: Overstriking, Up: Text Features, Previous: Underscoring, Next: Hyphenation R provides the ability to print more than one character in the same position, and thus overstrike. This can be used to create new symbols (similar to the way APL overstrikes, for those of you familiar with that), and also permits you to add diacritical marks such as the French accent ague, accent grave, and circumflex ("hat"). Here is a description of the feature. As R accumulates a word, character by character, you can think of there being a row of boxes. Normally R places one character in each box, from left to right. However, the control character ^H (backspace) directs R to back up one box. By backing up and then adding more characters, more than one character may be placed in each box. When it comes time to print the word, R examines each box in turn, and prints its contents. The exact method of printing the contents of one of the boxes is to print each of the characters of the box centered in a space equal to the width of the widest character. Hence, even if you back up several boxes by using more than one ^H, the characters in that box will still line up. NOTE: ^H works only WITHIN a single text word; you cannot back up over (control) spaces, or positioning commands, etc. If you are considering using ^H for multiple characters, you should probably be thinking of using .HS (see nodes Horizontal Positioning and Alignment) or some of the convenient macros for mathematical formulae (see node Math). HINT: A string register is a convenient way of "abbreviating" a special symbol that requires several characters to print. For example: .sr ne =^H/ .sr ahat a^H^ This method has the additional advantage that if you later change your mind about how to make the special symbol (e.g., you find a font that has it), you need change only yhr register definition. Further, string registers are the only way to go when the symbol must be constructed in different ways for different output devices: .if lpt . sr ne =^H/ .else . sr ne ^F6^Q^R^F* . end if  File: RGUIDE, Node: Hyphenation, Up: Text Features, Previous: Overstriking, Next: Substitution R does not provide an automatic hyphenation facility. However, it does provide two control characters to assist in manual hyphenation: ^Y - Insert an invisible hyphen here ^W - A word break is legal here An INVISIBLE HYPHEN produces no output unless R break the output line at the ^Y, in which case it prints as a hyphen ("-"). Thus, it can be inserted in a word that you wish to have broken to improve the appearance of a given output line. Using ^Y is better than inserting a hyphen by hand because ^Y will continue to do the right thing even if you change the document around later such that the word in question no longer falls at the end of an output line. Here is an example use: hyphen^Yation ^W is similar, but is intended for words that already have a hyphen in them: ambassador-^Wat-large Generally people do not use ^Y and ^W much, but insert them only in places where they are really needed. Of course, you usually cannot tell that a break is needed until you have printed your document.  File: RGUIDE, Node: Substitution, Up: Text Features, Previous: Hyphenation R provides a very general and powerful facility for substituting arbitrary strings for single characters in the output. This can be used to do a number of things; here are some examples: You can have a convenient to type character translated into one that is inconvenient to type, and thus make your typing easier. You can "fix" a character, e.g., move it up or down a little before printing it, or substitute a character from another font. You can have a character turn into an inline macro invocation that generates exactly what you want; similarly, you could have the character insert a string register, or directly come several characters. A specific example might be translating something to =^H/ so it looks like a "not equal" sign. You can translate a character into a control character, to avoid any special meaning of the control character until it is actually output. (We present a specific, very useful example below.) We now describe what is available, and give some examples. Substitution, also known as OUTPUT TRANSLATION is controlled by the .TR and .TC requests: .tr c s .tc f c s Each causes occurrences of a TEXT character "c" to be replaced by the string "s". .TR does it for all fonts; .TC does it only for the font "f". ("f" is a single character font designator.) .TR translations are performed first, and then .TC ones. In a .TR, if the string "s" is omitted, it is assumed to consist of a single character: a text space. Thus, the line .tr @ that occurs in the example setup file in node Setup, causes occurrences of @ in text to be changed to text spaces. That particular use of .TR is the most common. Output translation does not occur until just before the character would be assembled into a text word. In particular, it does not happen to anything on a request line. This fact can be used to advantage. For example: .tr ` \ (Translate backquote to control-space) can be useful in that it makes expression of macro arguments and other things easier by giving you a character that eventually becomes a text space, but does not appear as a text space when macro arguments are being scanned. Here is an example used: .chapter Suggestions`for`Further`Research. I have found this particular translation to be useful in case where I do not want my text editor to break a line (I usually have it set in a mode that breaks long lines as I type them). For example: ^Xital(This`is`some`text`in`italics.) This is useful because inline macro invocations (^X) cannot span more than one input line. Suppressing Translation: Doing ".tr @" is all well and good, but how can I ever print a real @ character? You could turn the translation off and back on: .tr @ @ ....@..... .tr @ Note that .TR and .TC special case the translation of a character to itself to mean to remove any translation of the character in question. There is an easier way to suppress translation in particular instances, however. The control character ^O suppresses any translation of the next text character. Thus, "^O@" will cause a real @ to be printed when you have done ".tr @". NOTE: The characters substituted in an output translation are themselves subject to further translation. (Translation is implemented by gobbling the output character and making it look as if you had really typed the substituted string.) So, if you did this: .tc 5 $ ^V(-10m)$^V(+10m) in an attempt to shift the $ character of font 5 down 10 mils, you would bomb out, because the new $ will be translated, too. What you should say is: .tc 5 $ ^V(-10m)^O$^V(+10m) Input translation: R does not have a complete input translation facility. For what is available, see node Input, or read up on the .CC, .NC, and .EC requests in the reference manual, as well as the discussion of the input mapping, etc.  File: RGUIDE, Node: Alignment, Up: Top, Previous: Text Features, Next: Sectioning This node discusses how to get things on different lines to line up vertically. We assume that you are familiar with the material in nodes Line Layout and Horizontal Positioning. There are several different methods you can use; we outline them below, calling attention to their advantages and disadvantages for particular situations. We suggest that you read about all of them, because each is good in different cases. Method 1: Guessing. Sometimes just putting in spaces and tabs, or "eyeballing" a distance can produce reasonable results, but don't count on it. In particular, when using spaces and tabs, items on different lines will line up only if you are using a fixed width font, and you set the tab stops to 8, 16, 24, ..., while the font in question is the principal font. For example: .fs n -- make the font both the principal and current font .rtabs -- a macro in the standard package that sets a lot of tabs at the requisite intervals (8, 16, 24, ...) In the case of a fixed width font this method works well because the "guessing" has become exact. Method 2: Logical Tab Stops. In addition to the built-in tab mechanism of R, the macro package provide a somewhat different mechanism, which, unfortunately, also goes by the name of tabs and tab stops. To tell the two apart, we have introduced the term "logical tab stop" for the kind of tab stop implemented in the macro package. A logical tab stop is name for a place across the page. Here are the main macros involved (we illustrate how you invoke them): ^Xs(name) - sets the logical tab stop called "name" so that it "remembers" the current horizontal position. This is implemented like this: .de s . nr tab_pos\^A0 hpos . em ^Xt(name) - Go to the place remembered by the logical tab stop called "name". ^Xp(name) - Just like ^Xt(name), except that it uses ^P, so it never goes backwards, and prints an error message if you try. ^Xbtab(name) - Just like ^Xt(name), except that it does a line break first (i.e., it starts a new line). Here is an example. Say that you want your output to look like this: foobar (arg1, arg2, arg3) Here are two ways to do it with the macros given above: foobar (^Xs(1)arg1, ^Xt(1)arg2, ^Xt(1)arg3) foobar (^Xs(1)arg1, ^Xbtab(1)arg2, ^Xbtab(1)arg3) Here are some things you should notice: When using ^Xp or ^Xt at the beginning of a line, it is a good idea to precede them by a space. This forces a line break. Otherwise the tabbing may be attempted on the previous line. ^Xbtab solves this problem. The argument to the ^Xs, ^Xt, etc., macros can be any string of characters so long as it can be part of a register name. (These characters are A through Z (case not distinguished), 0 through 9, and _; for more information, see node Registers.) Method 3: Indentation. If the kind of alignment you desire is to have several lines all start at the same place, the indentation may be the most convenient thing for you to use. Node Line Layout has a detailed explanation of the indentation and how to change it. However, the macro package provides some macros that can help you: .align name - Set the indentation to the position remembered by logical tab stop "name". .unalign - Return to the previous indentation. ^Xa(name) - Has the same effect as doing ^Xs(name) and then ".align name", but happens all at once, and can be used in-line. The earlier example could be expressed with these macros as follows: foobar (^Xa(1)arg1, arg2, arg3) .unalign This should be done in nofill mode; or else you could put a .BR after each line, to force it out. The ^Xa and .align macros can be nested, as illustrated here: foobar (^Xa(1)arg1, ralph (^Xa(2)inner-arg1, inner-arg2), .unalign arg3) .unalign Additional Features: For fancier alignment, such as different parts of formulae, expressions, or equations, see node Math. For outputting column oriented tables, see node Columnar Tables. ^Xc(name item1 item2 ... itemn) - will output the items, separated by spaces, centered about the logical tab position called "name". Naturally you must do a ^Xs(name) sometime before doing this.  File: RGUIDE, Node: Sectioning, Up: Top, Previous: Alignment, Next: Footnotes The standard macro package provides considerable assistance in structuring a document into sections such as chapter, sections, and appendices. For processing a large document in separate pieces, see the macro package in R;SECT RMAC (it has its own instructions at the beginning of the file). The kinds of sections supported by the standard macro package are: chapters sections subsections subsubsections subsubsubsections appendices achapters (chapters within appendices) These have the following nesting relationships: subsubsubsections are part of subsubsections subsubsections are part of subsections subsection are part of sections sections are part of chapters, achapters, or appendices achapters are part of appendices Note: There is a flag (number register) called achapters, which says whether to use achapters or not (0 means no achapters, 1 means achapters are all right). If achapters is 1, then sections may not be part of appendices, but may be part of achapters. If achapters is 0, then achapters should not be used at all. Here are the available macros: .chapter .section .subsection .subsubsection .subsubsubsection .appendix .achapter Each of these starts a section of the indicated kind. Each of the macros takes a single argument, the name of the section. For example: .chapter "Suggestions for Future Research." The current chapter number, section number, etc., are managed automatically. They are available in these number registers: chapter, section, subsection, subsubsection, subsubsubsection, appendix. In every case these are the numbers of the CURRENT section, and are incremented when you define a new section of that kind. For example, before any .chapter's, the chapter number register will be 0; the first .chapter increments it to 1, etc. Also, when a sectioning macro is invoked, the counter for the next smaller kind of section is set to 0. For example, .chapter sets section to 0. In sum, the numbering is done the "right way", with numbers always starting at 1. Of course, you can change the numbers freely. For example, if for some reason you want the first section in some chapter to be numbered 0, just set section to -1 after the .chapter and before the first .section. Note: The chapter number register is used to number the achapters in an appendix, if you are using achapters. The sectioning macros have two main effects: A header line is produced. A line may be added to the table of contents. For details about the table of contents, see node Table of Contents. The different things you can control about the header line are: The space produced before the line; the amount of the .NE before the line; the font used for the line; the form of the header line itself; the space produced after the line. Most of these are controlled by string registers, and in most cases there is one register chapter_... that controls the value used for chapters, appendices, and achapters, and one register section_... that controls it for sections, subsections, etc. Here are the various STRING registers, and their default values: chapter_space_before 1 (.sp ...) section_space_before 1 (.sp ...) chapter_need 5l (.ne ...) section_need 4l (.ne ...) chapter_space_after 1 (.sp ...) section_space_after 1 (.sp ...) chapter_form \^Ssection_number. \^Ssection_title section_form \^Ssection_number \^Ssection_title subsection_form same as section_form subsubsection_form same as section_form subsubsubsection_form same as section_form appendix_form ^C\^Ssection_number_title - \^Ssection_title achapter_form same as chapter_form The string register section_title is always set to the title of the section, namely, the argument to the sectioning macro. The string registers section_number and section_number_title are a bit more complicated, and we will talk about them in a minute. The font used for the header line is controlled by a NUMBER register: chapter_font big_font section_font normal_font Now, here is how the section_number string register is set by the various macros: chapter - \^Nchapter section - \^Schapter_number.\^Nsection subsection - \^Schapter_number.\^Nsection.\^Nsubsection subsubsection, subsubsubsection - similarly appendix - \^Schapter_number achapter - \^Schapter_number And here is how the chapter_number string register is set by the relevant macros: chapter - \^Nchapter appendix - \^N:appendix (Roman numerals: I, II, III, ...) achapter - \^N:appendix.\^Nchapter Lastly, here is how section_number_title is set by the relevant macros: all except appendix - Section \^Ssection_number appendix - Appendix \^Ssection_number Other details: Chapters normally start on a new page, but this is controlled by the number register chapter_starts_page. If it is 0, then a new page will not be started for each chapter; if it is 1 (it starts as 1), then a new page will be started. Part of this process is the forcing out of any figures, footnotes, etc., for the previous chapter. Appendices always start on a new page, and achapters never do. The appropriate way to start a new section at the top of a page is to do: .top_of_page If you want any pending figures, etc., output first, do a .force_out before the .top_of_page. These macros interface more smoothly with the macro package than .BP, for example. Before going on, here are a few comments about .BP, .PN, and the PAGE and NEXT_PAGE number registers. PAGE always contains the number of the current page, and NEXT_PAGE always contains the number of the next page to be output. Setting NEXT_PAGE does not affect PAGE, but any time PAGE is set, NEXT_PAGE is set to one plus the new value of PAGE. For example, .NR PAGE 103 will set NEXT_PAGE to 104. If for some reason you stack and unstack PAGE with .NV, both the stacking and unstacking operations set PAGE, and therefore change NEXT_PAGE. .BP sets NEXT_PAGE to its argument, if any; then it sets PAGE to NEXT_PAGE; finally it causes a new page to be started. .PN merely sets NEXT_PAGE; .NR NEXT_PAGE works just as well. As mentioned above, it is suggested that you use .top_of_page instead of .BP; but .PN is all right. Normally, page numbers increase throughout the document. However, you can optionally number them on a per-chapter basis, which causes the page number to be reset to 1 at the start of each chapter. This feature is controlled by the number register pages_per_chapter: if it is 0, pages are numbered normally; if it is 1, pages are numbered per-chapter. Almost all places in the macro package print the page number by inserting the string register page_number, which is set as follows: normal page numbering: \^Npage per-chapter numbering: \^Schapter_number-\^Npage Of course you can change it if you wish. Note that when per-chapter numbering is used, pages before the first chapter will have page numbers like 0-1, 0-2, etc. Similarly, figure and table numbers increase throughout the document, unless you set figures_per_chapter to 1, and then they will be numbered per chapter (0 means use normal numbering). The way the number of a figure or table is printed is controlled by the contents of the string registers shown below, with their setting in each case: figure_number_form normal: \^Ncurrent_figure (1, 2, 3, ...) per-chapter: \^Schapter_number.\^Ncurrent_figure table_number_form normal: \^N:current_table (A, B, C, ...) per-chapter: \^Schapter_number.\^N:current_table When the figures_per_chapter number register is set to 1, the footnote number will also be reset at the first opportunity in each chapter. See node Footnotes for more details.  File: RGUIDE, Node: Footnotes, Up: Top, Previous: Sectioning, Next: Figures The standard macro package has a fairly good footnote facility. Here we describe what it does, and how to use it in the normal case, and then describe what parts of it you may change, and how to do it. The normal way of constructing a footnote when in fill mode is like this (for instructions about how to do it when in nofill mode, read on): .foot ... body of the footnote ... .efoot This text should be placed at exactly the point where you want the superscript footnote number to appear. The body of the footnote will be output at the bottom of the page. Footnotes are output before any figures or tables that will appear at the bottom of the page, and footnotes always come out in order. The footnotes will be separated from the text by a short horizontal line, and from the figures below them (if there are any), by a long horizontal line. Each footnote will be preceded by its number, the same number that appeared where you did the .foot. If you omit or misspell EFOOT, then R will throw everything up to the next .efoot (if any) into the footnote. Typically the results of this are disastrous, and result in error message like "macro fn_xxx getting big" and possibly even "STORAGE FULL". If you do the above when in nofill mode, you will probably not get what you want. Here is the recommended method for doing a footnote when you are in nofill mode (the footnote itself will be in fill mode, unless you do a .nf inside its body): Here is the first part of the line^Sfn ^G .sfoot ... the footnote .efoot and here is the rest of the line. If you really wanted the footnote number at the end of a line, then omit the space and ^G. There are other ways that will sort of work, but all I have tested have one flaw or another. If the footnote is too large to fit in the space remaining on the current page, you can do one of two things: leave the space blank, and move the current line and the footnote to the next page; or move the footnote to the next page, but continue with text on the current page until it is full. The choice is controlled by the short_page number register: if it is 0, then R will fill up the current page; if it is 1, then the rest of the current page will be blank. The short_page register starts set to 1. R cannot split a footnote into two pieces. The primitives available in R make it somewhere between extremely difficult and impossible to do that, so don't ask for it - there is no easy fix. Normally R will start numbering footnotes on each page with 1. However, the number register reset_per_page controls this behavior. If it is set to 1, as it normally is, then the numbers will start with 1 each time. But if you set reset_per_page to 0, then the numbers will increase from page to page. The number register figures_per_chapter controls whether the footnote numbers are reset at the beginning of each chapter; see node Sectioning for further information. Special care is exercised in the macro package so that footnotes within figures (and other kept things) will work right. However, do not expect it to work for any but the simplest situations. Here are the other things about footnotes that you can adjust (N means a number register, S means a string register), and their default values: fn - S - ^U\^Ncfn^D in font fnfont; This is what is output at the .foot. fnfont - N - normal_font - the font used to print the superscript footnote number at the .foot. footnote_font - N - normal_font footnote_bold_font - N - bold_font footnote_italic_font - N - italic_font These control the settings of normal_font, italic_font, and bold_font in the footnote body. The font in the footnote body starts set to footnote_font. footnote_spacing - S - 1 (.ls ...) The value for the line spacing to be used in the footnote body. footnote_starter - S - ^Q \^Ncfn.^Q ^Q The string printed at the beginning of the footnote body. The number register cfn contains the the number of the current footnote. footnote_sep_width - S - 2.5i The width of the line separating the footnotes from the text (at the bottom of the page). footnote_space_before - S - 1 The space to output (.sp ...) before the footnote separator line. footnote_space_after - S - 1 The space to output after the footnote separator line. NOTE: footnote_space_before and footnote_space_after should be set before loading the macro package -- they are sampled once and ignored thereafter. They are evaluated in the header environment with the principal font set to heading_font. Let us say that you wanted your footnote references to be with special symbols instead of numbers. For example, suppose that you wanted to use *, **, ***, etc. Here is one way you could do it: .sr star1 * .sr star2 ** .sr star3 *** ... as many as you think are necessary ... .sr footnote_starter ^Q \^Sstar\^Ncfn^Q ^Q .sr fn ^F\^S_font_\^Nfnfont!!^U\^Sstar\^Ncfn^D^F* If you had a more complicated set of special symbols, you might want to use a macro to compute the right one to use: .sr fn ^F\^S_font_\^Nfnfont!!^U^Xfnsym(\^Ncfn)^D^F* .sr footnote_starter ^Q ^Xfnsym(\^Ncfn)^Q ^Q .de fnsym . for count 1 \^A0 *^G . end for . em (or any other macro in the place of the little one above). Hint: If R complains about undefined number or string registers in a footnote, you may have done something like this: .foot ... .nr foo 5 ... ...^Nfoo... ... .efoot The above will not work because the body of a footnote is always stuffed into a macro. The problem is that the .NR will not be executed until the macro is expanded, but interpretation of the ^N will be attempted while the macro is being defined. The solution is to put a backslash before the ^N.  File: RGUIDE, Node: Figures, Up: Top, Previous: Footnotes, Next: Lists The standard macro package provides a reasonably good figure and table facility. We will describe the simplest way to use it, and then explain the different options and how you can set them up to tailor the facility to your preference. It should be noted that the tables we are talking about here are no the same as what the macro package calls "inline tables" (see node Setoff Things), or highly structured tables with rows and columns (see node Columnar Tables for more on them). It turns out that the kind of tables we describe here are almost exactly the same as figures: they are just called tables. Below we will use the term figure to mean both tables and figures unless we explicitly indicate otherwise. The concept of figure supported by the macro package is bunch of text, space, etc., of arbitrary size. The macro package will keep it on a single page, unless it is bigger than one page. Further, figures will be produced in order. The additional distinction between figures and other kept things (see node Keeping) is that figures are automatically numbered and labelled, and they may have table of contents lines automatically created. Special care is used in the macro package to ensure that figures within kept things will work right. However, do not expect it to work for any but the simplest cases. There are two kinds of figures: normal figures, and page figures. Page figures always come out on a separate page, and always start at the top of the page. Page figures are more efficient to produce than normal figures, because they do not have to be expanded an extra time to discover their size; but the placing of normal figures in the output is more flexible. Here is the way to define a figure: .begin_figure "the title of the figure" ... the body of the figure ... .finish_figure The body of a figure is always made into a macro, so the hint at the end of node Footnotes applies for figures, too. If you want a page figure, just substitute .begin_page_figure for .begin_figure; the .finish_figure remains the same. Defining tables works exactly the same way, except that the macro names are different: .begin_table, .begin_page_table, and .finish_table Output Appearance and Options: Figures and tables are always output in order of definition. As previously mentioned, page figures are always output on separate pages. Normally, regular figures and table will be output at the bottom of the current page, after any footnotes, if there is room. If there is not room, figures and tables will be output at the top of the next page. The macro package will output as many figures, tables, and footnotes as it can on each page, and (with the exception of page figures) any "extra" space on a page will be filled with text, if there is any. If you want the macro package to output figures (tables) where they appear, provided they fit, then you should set the number register immediate_figure (immediate_table) to 1; it is normally 0. Regular figures will be separated from any text or footnotes above them by a FIGURE SEPARATOR. A figure separator will also appear between adjacent figures, and after a figure, if it might have text under it. A figure separator consists of a horizontal line, of width figure_sep_width, preceded by space of size figure_space_before and followed by space of size figure_space_after. These three are all string registers, with the default values indicated below: figure_sep_width - ll-indent!m (across the whole page) figure_space_before - 1 figure_space_after - 1 NOTE: figure_space_before and figure_space_after should be set before loading the standard macro package, because they are sampled once and ignored thereafter. They are evaluated in the header environment with the principal font set to heading_font. Getting the Current Figure Number: The number registers current_figure and current_table contain the number of the NEXT figure, but this will be just the per-chapter number if per_chapter is set (see node Sectioning). The string registers figure_number_form and table_number_form are better, because they are adjusted when per_chapter is set. So, you could refer to a figure in the text like this: ... are shown in Figure ^Sfigure_number_form. .begin_figure ... ... .finish_figure To refer to the figure AFTER it is defined, you should sample the value of figure_number_form and stick it in a string register. For example: .sr prog1_figure Figure ^Sfigure_number_form .begin_figure "The first program:" ... .finish_figure .... See ^Sprog1_figure for details. The Title Line: The form of the title line in a figure (table) is controlled by a string register, figure_title_form (table_title_form). The default value is: figure_title_form - \^Sfigure_name_form. \^Sfigure_title table_title_form - \^Stable_name_form. \^Stable_title Both of these actually have a ^F to switch to another font, and a ^F* to switch back at the end. The fonts used are controlled by these number registers, with the indicated default values: figure_title_font - bold_font table_title_font - bold_font The string registers figure_title and table_title are always set to the argument to the begin_xxx macro, that is, the title that you supplied. The string registers xxx_name_form have these default values: figure_name_form - Fig. \^Sfigure_number_form table_name_form - Table \^Stable_number_form The arrangement of figure_number_form and table_number_form depends on the setting of per_chapter. Node Sectioning explains this in detail. The title is normally printed at the top of the figure, before the body. To have it printed at the bottom, after the body of the figure, set the number register print_figure_title_top (print_table_title_top) to 0; it is normally set to 1. To suppress printing of a title line completely, set the number register print_figure_title (print_table_title) to 0; it is also normally set to 1. Options in the Body: There are several things you can control about the setting up of the figure body; defaults will be listed below. First, the string register figtab_spacing controls the initial setting of the line spacing factor (.ls ...). The number registers figure_font and table_font control the initial setting of the principal and current font. The string register figure_before (table_before) is inserted just before the body; it will always appear on a separate line if it contains anything. The string register figure_after (table_after) will be inserted after the body of the figure (and after the title line, if it is printed at the bottom of the figure). Here are the default values for these registers: figtab_spacing - 1 figure_font - normal_font table_font - normal_font figure_before, table_before, figure_after, table_after: all empty Each figure always start in nofill mode, with left adjustment (.nf l). Table of Contents Information: For information on this, see node Table of Contents.  File: RGUIDE, Node: Lists, Up: Top, Previous: Figures, Next: Table of contents The standard macro package has a convenient and highly flexible facility for producing lists of items, such as this: 1. The first item of the list, which exntds over two output lines. 2. The second, which uses just one line. 3. The third, which also uses just one line. The basic idea is straightforward, but there are a whole raft of things you can adjust about lists, so we will have to get more detailed about it. Also, there is a facility permitting you to define other things that act like lists, but either set up the parameters in a particular, unusual way, or need some special capability not provided. We defer discussion of this latter facility until the end of this node. We will call the different parts of a list, as in the text that follows 1, 2, and 3, above, ELEMENTS of the list. There are two kinds of lists: NORMAL LISTS and INVERTED LISTS. They are distinguished by whether the first line of each element is indented to the right or to the left of the rest of the lines of that element. Normal lists indent to the right, as in typical paragraphs; inverted lists indent to the left. The example list above is a normal list, here is an inverted one: 1. This is the first line of a list element that covers more than one line. As you can see, the first line sticks out to the left. 2. ... 3. ... You may think that the terminology itself is inverted! (But that's the way it was done originally, so we will not change it.) Additionally, the elements of a list may be produced in fill mode or nofill mode. We thus have four different list macros: .list normal, filled .ilist inverted, filled .nofill_list normal, not filled .nofill_ilist inverted, not filled To actually use these macros, you proceed as follows: .list ... text for first element ... .next ... text for second element ... .next . . . .next ... text for last element ... .end_list All four list macros use the SAME .next and .end_list macros in this structure. Now here are the various things you can control (default values for registers are indicated below). The position of the first line of each element, and of succeeding lines, is controlled by the string registers list_left_margin and list_indent, as follows: normal list first line at: list_left_margin plus list_indent others at: list_left_margin inverted list first line at: list_left_margin others at: list_left_margin plus list_indent These two (list_left_margin and list_indent) are string registers containing horizontal expressions. You should know that list_left_margin is not an absolute position, but rather the amount by which the indentation is to be increased within a list. If you have a list inside a list, the indentation will be increased twice. The string register list_right_margin controls the amount by which the right indentation is increased in each list, in similar fashion. The rest of the options are a little bit simpler. The string register list_begin_space is the amount to .SP before the first list element; the string register list_after_space is the amount to .SP after the last element; and the string register list_space is the amount to .SP between list elements. Lastly, the string register list_spacing is used to set .LS for each element, and list_keep is the amount to .NE before each element. Here are the default values for all of these registers: list_left_margin - 800m list_right_margin - 800m list_indent - 0 list_begin_space - 1 list_after_space - 1l list_space - 1 list_spacing - 1 list_keep - 3 The lists we wrote down in the examples at the beginning of this node would NOT be produced by the default values. In particular, list_indent would have to be set to something like 8 to get an appearance similar to the examples (which were done by hand). Some other useful things to know: Lists may be used within lists with no difficulties; it was specifically designed so that this would work and thus permit lists to be used for making outlines, etc. The number register list_count contains the number of the current element in the current list at all times, going 1, 2, 3, etc. This can be used to number the elements of a list automatically, and is particularly effect when used in combination with the list_start string register. List_start is inserted at the beginning of each list element. It is normally empty, but if you do the following, you will get automatically numbered list elements with no effort on your part: .sr list_start \^Nlist_count. (There are two spaces at the end of the above line, so you will get two spaces between the number and the list element text. One other nice feature is that a tab stop is set at the position list_left_margin plus list_indent, that is, at the farther right of the places where the first line of each element starts and the succeeding lines start. This permits the text of an inverted list to be all lined up, with a number on the left, and so forth. For example, setting list_start to be list_count followed by a tab (instead of two spaces as above) will produce output like this when used with inverted lists and a non-zero list_indent (about 4 or 5 tends to be nice): 1. Here is the first element. Note how the second line comes right under the first. 2. The second element Although we did not tell you before, list_indent and list_space may be set to specific values for a single call of a list macro by passing the value(s) as arguments to the list macro. For example: .list 6 - set indent to 6 for this list only .ilist 4 2.5 - set indent to 4 and space to 2.5 for this list only Making your own list macros: Besides the very flexible list facility presented above, it is possible to construct your own set of list macros in a very simple way. In fact, there are two different things you can do. If you want to have something that works exactly like lists, but sets up the string and number registers a particular way, you can do this: .de foo . begin standard_list -- use this name . nv list_... ... -- set up the registers your way . ... -- use .nv and .sv . _list_ . em You use it like this: .foo ... first element .next ... second element, etc. .next ... .end_list The name "foo" can be anything you like. The four things in brackets should be filled in by you so that you get normal or inverted lists (0 = normal, 1= inverted), and fill or nofill lists (0 = nofill, 1 = fill). The last two arguments, opt-indent and opt-space, are the same as the optional arguments to .list, etc., and you can fill them in or not, as you please. It may interest you to know that .list, .ilist, etc., are built just this way, to call _list_ as above. The other way to make your own list macros is somewhat different. Here you get three new macros, to play the roles of .list, .next, and .end_list. The idea is that you can take advantage of the macro package writer's expertise and cleverness to do the hard-to-figure-out part. You supply four macros defining what to do at the beginning and end of each item, and the beginning and end of the list as a whole, and then use a special macro to make up the three ADDITIONAL macros, which play the role of .list, .next, and .end_list. The advantage is that the three macros automatically nest (in the send that .list can be used inside a list) and the correct environment switching and initialization is done for you. Here are the details: Step 1. Define four little macros, having names not used before. We will assume you called them "before", "before_each", "after_each", and "after". The idea is that "before" will be called before the first element, "before_each" before each element, "after_each" after each element, and "after" after the last element. For your information, the entire list is in a begin block, and each element (including the invocations of before_each and after_each) is in an additional nested begin block. This simplifies writing your macros (see node Writing Macros for more information). Step 2. Decide on the name you want for the three macros that will take the place of .list, .next, and .end_list. These names MUST be different from any other macros, including the ones you defined in step 1. We will assume you called them "first", "middle", and "last", for explanatory purposes. Step 3. Invoke def_list_macro: .def_list_macro first middle last before before_each after_each after The def_list_macro invocation will DEFINE three new macros called "first", "middle", and "last"; those are the macros you use in the body of your document: .first ... first element ... .middle ... .middle ... .last More Details: Any arguments to "first" will be passed through, unchanged, to "before"; similarly, any arguments to "last" will be passed through to "after". Any arguments to "middle" will be ignored. All processing is done in a temporary environment that is initialized from the environment at the time of the call to "first". If you like, you can supply an additional argument to def_list_macro: the name of an environment to use for initializing the temporary environment each time. The advantage of doing it this way is that many things you may wish to set (current and principal font, line spacing, tab stops, etc.) will be done automatically when the temporary environment is created. All you need do is setup one environment once at the beginning, and give that environment's name to def_list_macro. The macros defined (e.g., "first", "middle", and "last") will nest correctly, just as lists do, and will nest nicely in other similar structures, too. There is an empty macro, called NULL, that you can use for those macros that you wish to do nothing. For example, if everything you want to do in your lists can be set up by just initializing the environment, then the following will do: .ev newenv ... set things up ... .ev text .def_list_macro first middle last null null null null newenv A similar "roll your own feature" is presented for setoff things in node Setoff Things. You may wish to examine that, too.  File: RGUIDE, Node: Table of contents, Up: Top, Previous: Lists, Next: Keeping Here we describe the table of contents feature of the standard macro package, including the various options and the format control available to you. The macro package accumulates a table of contents through the document, and prints it at the end, with the correct page numbers. For this method (printing at the end) to work, you are required to tell R where the table of contents is to appear, and how many pages long it will be. If you request a table of contents, it will be produced automatically. To indicate the placement and size of the table of contents, you do this at the place you want the table of contents to appear: .begin_table_of_contents n where "n" is the number of pages in the table of contents. If you get this number wrong, an error message will be printed when the table of contents is actually generated. From the information it supplies, you can correct "n" and run the document off again to get a document with correct page numbers. Options: You may control which of chapters, sections, subsections, etc., appendices, and achapters will have entries in the table of contents by setting the toc_level number register. Here is how it works. Each kind of sectioning macro has a level number: chapter - 1 section - 2 subsection - 3 subsubsection - 4 subsubsubsection - 5 appendix - 1 achapter - 2 When toc_level is set to "n", then only those kinds of sections with level numbers less than or equal to "n" will have entries in the table of contents. The default setting is 2, which means that chapters, sections, appendices, and achapters will all be entered, but none of the others. You may have lines printed on your terminal as each section is encountered, indicating page numbers, etc. To get this, set the tty_table_of_contents number register to 1 (it is normally 0). You may have a table of figures and/or table of tables in the table of contents if you wish. The number registers table_of_figures and table_of_tables will cause such tables to be produced, if they are set to 1. They are normally set to 0. No table of figures will be produced if there are no figures; likewise for tables, so it does not hurt to set the number registers to 1 even when you have no figures or tables. R normally assumes that the table of figures and table of tables, if any, will consume one page, together. If this is incorrect, set the number register tof_size to the number of pages actually needed by the table of figures, and tot_size to number of pages actually needed by the table of tables. For tof_size, round fractions of pages DOWN; for tot_size, round fractions of pages UP. This permits R to know on which page the table of tables actually starts. Note that the table of figures and table of tables are considered to be part of the table of contents for .begin_table_of_contents' purposes, so the number you supply should be the sum of the number pages used by the table of contents proper and the number of pages used by the table of figures and table of tables, if any. The only other options are whether the include a line for each of the tables (table of contents, table of figures, and table of tables) in the table of contents itself. The number registers print_toc_toc_entry, print_tof_toc_entry, and print_tot_toc_entry control each of these separately. When set to 1, a line will appear in the table of contents for the corresponding thing (unless no table of figures (table of tables) is to be produced, in which case the line for table of figures (table of tables) is suppressed). These numbers registers are all normally 0 (meaning these lines are not normally produced). Format Control: The detailed format of almost everything in the table of contents is under your control. This leads to a whole bunch of string and number registers, but we will try to sort them out into easy to understand categories below. The FORM registers: These string registers contain what is actually added to the table of contents by the different macros (.chapter, .section, .begin_figure, etc.). Here they are, with their default values. To get details on the string registers they use, you may have to refer to node Sectioning or node Figures. chapter_toc_form - \^Ssection_number. \^Ssection_title ^T.^R \^Spage_number section_toc_form - \^Ssection_number \^Ssection_title ^T.^R \^Spage_number subsection_toc_form, subsubsection_toc_form, subsubsubsection_toc_form: all just like section_toc_form appendix_toc_form - \^Ssection_number_title. \^Ssection_title ^T.^R \^Spage_number achapter_toc_form - just like chapter_toc_form figure_toc_form - \^Sfigure_name_form. \^Sfigure_title ^T.^R \\^Spage_number table_toc_form - \^Stable_name_form. \^Stable_title ^T.^R \\^Spage_number Note that the page_number string register insert is quoted twice. This is because figures and tables are produced as macros and cause another reading of the xxx_toc_form. The double quotation is needed so that the table of contents entry reflects the page on which the figure (table) is inserted, rather than where the macro was made. (TAR) toc_toc_form - Table of Contents ^T.^R \^Ntoc_start_page tof_toc_form - Table of Figures ^T.^R \^Ntof_start_page tot_toc_form - Table of Tables ^T.^R \^Ntot_start_page Note: the xxx_start_page number registers are set up by begin_table_of_contents, automatically. The INDENT and FONT registers: There are a number of string registers that control the indentation of the various form lines described above, and also a several number registers describing what font to use for the lines. Here is a list of them with their default values: chapter_toc_indent - 0 section_toc_indent - 8 subsection_toc_indent - 8 subsubsection_toc_indent - 8 subsubsubsection_toc_indent - 8 appendix_toc_indent - 0 achapter_toc_indent - 0 figtab_toc_indent - 0 chapter_toc_font - big_font also used for appendix and achapter section_toc_font - normal_font also used for subsection, subsubsection, and subsubsubsection. figtab_toc_font - normal_font Registers controlling spacing: There are some string registers that control how much to .SP before a given kind of table of contents entry, how much to .SP after it, and how much to .NE before it. Here they are with their defaults: chapter_toc_space_before - 1 chapter_toc_space_after - 1 chapter_toc_need - 5l the above are used for appendix and achapter, too section_space_before - 1 section_space_after - 1 section_need - 4l the above are used for subsection, subsubsection, and subsubsubsection, too. figtab_toc_need - 5l The Table of Contents, Table of Figures, and Table of Tables announcements: The beginning of each of these is normally announced with a header line. (This is not the same as the entries for these in the table of contents itself.) Naturally, the announcement is inserted only if there is a corresponding table to output. The string registers below control the form and spacing of these announcement lines: toc_blurb - ^C^F\^S_font_\^Nbig_font!!CONTENTS^F* tof_blurb - ^C^F\^S_font_\^Nbig_font!!FIGURES^F* tot_blurb - ^C^F\^S_font_\^Nbig_font!!TABLES^F* toc_title - Table of Contents tof_title - Table of Figures tot_title - Table of Tables toc_before_space - 4 toc_between_space - 2 tof_before_space - 2 tof_between_space - 2 tot_need - 5l tot_before_space - 2 tot_between_space - 2 Some of these need a little more description. The xxx_blurb lines are the announcement lines themselves. The xxx_before_space registers give the amount to .SP before the corresponding announcement line. The xxx_between_space registers give the amount to .SP after the announcement and before the corresponding table. The tot_need register gives the amount to .NE before the table of tables announcement. It is needed because it is the only one of the the three that might not start at the beginning of a new page. The title string registers are used to set the section titles. The only effect they might have is on the headings of the pages in the table of contents, if you set the headings according to the section title.  File: RGUIDE, Node: Keeping, Up: Top, Previous, Table of Contents, Next: Setoff Things The term "keeping" (in this context) is used to mean keeping some body of text on a single line or a single page. Line keeping: There are several ways you can keep something on one line. Often the easiest is to make sure that it has no spaces, tabs, or absolute horizontal position commands (^P, .hp, etc.; see node Horizontal Positioning) in it. Note that the spaces of concern are R control-spaces, and text spaces are no problem. The ".tr @" line of the example set up file in node Setup gives you a simple way of typing text spaces -- use @. See nodes Input and Substitution for more details on that kind of mechanism. When building complicated formulae, not only must you be careful not to use spaces, etc., you must remember to use relative positioning (.HS) instead of absolute positioning. The macros described in node Math all work that way. Another slightly tricky point: if you write your own macros, don't forget to put a ^G at the end any text outputting lines. The ^G will prevent the newline at the end of the line in the macro from turning into a space in fill mode (or, worse, causing a line break in nofill mode). Your last alternative, which works for anything, is to use the LKEEP macro. It works best when used inline: ^Xlkeep(Here are some words to keep on one line.) This macro works by using the WIDTH macro (see node Writing Macros) to find out how big its arguments are (there can be any number of arguments to LKEEP), and then either sticking them in, if there is room, or doing a .BJ first if there is not. See the reference manual for information on .BJ, if you need it. Page Keeping: The simplest and cheapest way to keep something on a single page is to use .NE. The .NE request takes a single argument, a vertical expression, and if there is not that much space on the current page, it causes a new page to be started. Note: the macro package redefines .NE, so that it will take into account the space used by any footnotes, figures, etc, that will be coming out at the bottom of the current page; but the meaning of .NE is essentially unchanged from the standard request. Another method is to put the text in question into a figure or table, which are always kept on a single page. But that is not always appropriate. In such cases you may use the KEEP macro to keep the text on one page. It works like this: .keep ... stuff to keep on one page ... .end_keep This works by first stuffing the text between the .keep and .end_keep into a macro, and then finding out how big it is with the SIZE macro (see node Writing Macros). Then it does a .NE of the required amount, and lastly, outputs the actual text. Sometimes you will have to remember that the body of a keep becomes a macro first. The reason is that certain things will require an extra backslash to make them work right. For example: .keep .nr foo 5 ..... ^Nfoo ... .end_keep will not work, because the .NR will NOT have been done at the time the ^N will attempt to evaluate number register FOO. You will get an error message like "undefined number register". The solution is to but a backslash in front of the ^N, or to move the .NR to before the .KEEP. Another kind of thing that will not work in a .keep is: .nr foo foo+1 This will not do what you expect, because the macro is expanded twice -- once to find its size, and once to produce the output. Any things like that can be made to work right by making them conditional: .if ~ignore_level . nr foo foo+1 . end if (The ignore_level number register is non-zero when we are expanding something to determine its size.) Special care is taken in the macro package to make this work right when you have a figure or footnote in a kept thing. It is done by having the figure and footnote macros do most of their normal work when we are just finding out the sizes of things, but the figure and footnote macros suppress the actual queueing for output. It is conceivable that there are complicated situations for which the methods used will not work. Node Setoff Things describes some macros that do keeping for you. It also describes how to build your own macros that do so. If none of the things we have described suits your needs, you should read up on macros (node Writing Macros), and read R;KEEP DOC for details on using .keep in your own macros.  File: RGUIDE, Node: Setoff Things, Up: Top, Previous: Keeping, Next: Math By "setoff things", we mean blocks of text that are set off from the normal flow of text. Examples of such things are quotations, program examples, big equations, diagrams, etc. The figure mechanism provides one form of setoff things, but it is not appropriate for everything. In particular, figures will tend to entered in the table of contents, and have an automatic naming and numbering scheme, which you may not want to use for everything. Of course, tables give you another set of these names and numbers, but there are still many cases where you might want "anonymous" set off items. The list macros, discussed in node List, explain how to get a list of set off items, and how to tailor the list facility. However, that mechanism is also inappropriate for items that do not appear in lists. To handle these situations, the macro package provides some macros for you to use, which can be tailored somewhat. In addition, it provides a way for you to build more macros that work in a similar way. This second facility is nice when you have several or many items that must all be done in a similar, and is essential when you have several different types of things, each of which has many occurrences. We will describe the macros that are provided automatically first, and then tell you how to build your own macros for different kinds of things. The simplest set of macros provided are .table and .end_table. The "tables" produced by these are NOT the same as the tables made by .begin_table and .finish_table. The coincidence of names is unfortunate, but historical. The table macros work like this: .table 3i ... stuff to set off ... .end_table You can specify any size you like in the .table line; it is used to do a .NE. If you leave it blank, 5 is used. The only options you can set are three string registers: table_begin_space - 1 - amount to .SP before body table_end_space - 1l - amount to .SP after bofy table_spacing - 1 - setting for .LS in body There are two other sets of macros provided initially, which are more flexible than the table macros shown above. One set does a .keep of its body, to make sure it stays on a single page, and the other set does not. Otherwise they function the same way. The keeping form is considerably more expensive, so we suggest that you use it only when necessary. See node Keeping for more discussion on how to keep things on one page. Here we illustrate how you would use the two sets of macros: .example ... setoff stuff ... .end_example .kept_example ... setoff stuff, to be kept on one page ... .end_kept_example Note that "example", etc., are the REAL names of these macros! (That is, we wrote .example because it is actually the name of the macro, not because we were writing an example.) That's all there is to it. There are a number of options you can control about how the set off text will be produced. Here is a list of the registers you can set, their default values, and their effects. The number registers are presented first, and then the string registers: example_font - normal_font - sets the principal and current font example_fill - 0 - fill nor nofill? (1 = fill) example_adjust - 0 - adjustment mode (0 = left, 3 = both) example_tabs - 16 - number of tab stops to set example_left_margin - 500m - amount to increase indent example_right_margin - 500m - amount to increase rindent example_spacing - 1 - .ls ... example_begin_space - 1l - amount to .sp before body example_end_space - 1l - amount to .sp after body example_tab_width - 8 - distance between tab stops All other things are initialized from the current environment. The body itself is produced in a temporary environment, and is always inside a begin block. Of course, in a kept_example, the body will be stored in a macro, its size determined, and then it will be output, as in .keep. See node Keeping for details on problems you might run into because of that. The tab stops are set starting at the indentation, so if you have example_font set to select a fixed width font, things will line up the way they do on the screen in your editor. Examples of either kind may be nested in the other, with no problems, EXCEPT: don't put a kept_example inside a kept_example. There is no need to do so, anyway. Making your own setoff macros: There are two kinds of things you can do in terms of making macros tailored to what you want to do: 1 - Have a macro set up the example options, and then use the table or example macros essentially unchanged, or 2 - Construct an analogous set of macros where you set up things yourself. In the first case, you write macros according to these skeletons: .de new_table -- or any other NEW macro name . begin standard_table . nv .... -- use .NV and .SV to set options . table1 \^A0 -- pass argument through . em Used as: .new_table ... body ... .end_table -- same as before .de new_example -- analogous to new_table . begin standard_example . nv ... . example1 . em Used as: .new_example ... body ... .end_example .de new_kept_example -- analogous to new_table . begin standard_example . nv ... . kept_example1 . em Used as: .new_kept_example ... body ... .end_kept_example Note: .table and .end_table, .example and .end_example, and .kept_example and .end_kept_example are defined in terms of table1, end_table1, example1, end_example1, kept_example1, and end_kept_example1 just to make it easy for you to do what is shown above. If the above method do not meet your needs, perhaps method 2 will. In this second method, you write two macros: one to set up and do what needs to be done before the body of the things you are defining, and one to be done after. Then you use a special macro to create two NEW macros, which call upon your macros, but have these additional features: They nest properly; They switch environments correctly; They set up an extra begin block for you. Here are the details: Step 1 - Define two little macros, one to be invoked before the setoff stuff, to set things up, and one to do anything needed at the end. We will assume for the sake of argument that you called them "before" and "after". Step 2 - Pick two previously unused names. If they are "first" and "last", then they "fill in the blanks" in this way when you use them: .first ... setoff stuff ... .last Step 3 - Use .def_setoff_macro to actually construct the macros "first" and "last" in terms of "before" and "after", like this: .def_setoff_macro first last before after If you want either of the "before" or "after" macros to do nothing, you can use the NULL macro, which does nothing. For example: .def_setoff_macro foo bar setup null There is also a macro called .def_kept_setoff_macro that works in exactly the same way as .det_setoff_macro, except that it does a .keep of the body of the setoff stuff. It may interest you to know that the table and example macros are actually constructed this way with def_setoff_macro and def_kept_setoff_macro. More details you should know: The macros constructed by def_setoff_macro and def_kept_setoff_macro will call your "before" and "after" macros in a temporary environment in a begin block. The body of any particular use will be expanded in this same environment and begin block. Any arguments given to "first" will be passed directly to "before", and any arguments to "last" will be passed to "after". That is how itable gets the size of the table in a .table, for example. In a kept setoff macro, the "before" and "after" macros are invoked inside the .keep, inside an extra begin block, if this makes any difference to you. The temporary environment created by your "first" macro is normally initialized from the environment current at the time "first" is invoked, but if you give def_setoff_macro or def_kept_setoff_macro one more argument, it will use it as the name of an environment, and initialize the temporary environment from that environment. If everything of interest to you can be expressed in an environment, then this provides a very simple and efficient way to tailor a macro. For example, say that you have set up the "foo" environment to be what you need. Then the following will create two macros that "do the right thing": .def_setoff_macro first last null null foo  File: RGUIDE, Node: Math, Up: Top, Previous: Setoff Things, Next: Columnar Tables There are a number of little macros in the standard macro package for assisting you in writing mathematical formulae, equations, and the like. They have been made up to work well together, and you should read node Writing Macros before attempting to write your own macros for this sort of thing. These macros are setup so that if you place surrounding things directly adjacent on both sides (no control-spaces, that is), then whole formulae will move as a unit. Features provided: Some of these features have been described elsewhere, but we will give you a complete list, anyway: superscripting and subscripting -- Simple situations are handled as described in node Superscripting and Subscripting, but some of the more common complicated cases are described below. aligning items -- Node Alignment has a complete discussion; see also node Columnar Tables. The rest of the list is a macro by macro description: arg1 ^Xdiv(arg1 arg2) generates: ---- arg2 Notes: Works for any arguments, including other invocations of div. The line will be as long as the longer of the two arguments. ___ ^Xsqroot(arg) generates: \/arg Notes: The string register SQROOT can be set to a nice square root symbol in some font, if you like; it starts set to a backslash followed by a slash, as above. The line at the top is drawn from the beginning to the end of arg, one line up. The string register SQVOFF can be set to change the vertical position of the line; it is the distance from the baseline of "arg" to the position where you want the line. It is normally set to "fheight!m". The string register SQHOFF can be set to the amount by which you want the line to extend to the left beyond "arg". It may be positive or negative; it starts at 0. The idea is to set it so that the line just joins up with your chosen square root sign. Only one size of square root is supported, but you could easily write a macro that sets the SQROOT, SQHOFF, and SQVOFF string registers for a variety of different square root symbols, and get different sizes that way. You may have to put ^V adjustments into the string register SQROOT to get a pleasing appearance (see node Supscripting and Subscripting). item1 ^Xabove(item1 item2) - generates: item2 That is, item1 centered above item2; item2 on the baseline. The string register ABOVE_SEP controls the amount of white space between item1 and item2; it is a vertical expression, normally "20m". ^Xbelow(item1 item2) - generates: item2 item1 That is, item1 centered below item2; item2 on the baseline. The string register BELOW_SEP controls the amount of white space between the two; it is a vertical expression, normally "20m". item3 ^Xbottop(item1 item2 item3) - generates: item1 item2 That is, item1 with item2 centered below it, and item3 centered above it. This is goos for summations, unions, etc. For example, ^Xbottop(U n=1 |a|)^b^Xsub(n) becomes: |a| U a n=1 n The string registers BOTTOP_TOP_SEP and BOTTOP_BOT_SEP control the amount amount of white space between item1 and item3 and item2 (respectively). They are normally both set to "20m". item2 ^Xsubsup(item1 item2) generates: item1 (But closer together vertically.) This can be used to give something both superscripts and subscripts simultaneously. For example, a^Xsubsup(j i) produces this: i a j The top and bottom items are normally done with a single ^U or ^D. If your formulae overlap when output that way, you should include extra vertical adjustment in the items themselves, e.g.: a^Xsubsup(^Di^Xsup(j)^U ^Um^Xsub(n)^D) to produce this: m n a j i and so forth. Well, that's it. But with care, you should be able to build similar macros or special cases readily; and the above handle a lot of things anyway. Node Writing Macros gives some hints on writing your own macros for this kind of thing.  File: RGUIDE, Node: Columnar Tables, Up: Top, Previous: Math, Next: References There is not too much we can do here except describe some general principals, and point you to available macro packages. R can do pretty good horizontal positioning, and draw horizontal lines, but its notion of the page is a bit primitive, and it would be non-trivial to try to draw vertical lines. So don't expect to be able to draw boxes around stuff, etc., very easily. It is not too hard to get straight columns, even with optional centering and right flushing of items in columns (using ^C and ^R), but you get multiple columns of FILLED text very easily (it requires writing macros to do the justification - ugh!). If you want the width of a column determined by the widest element in it, then the text will have to be scanned three times, at least: once to put it in a macro, a second time to find the sizes, and a third time to actually output it. The WIDTH and SIZE macros do just that kind of thing. They are described in more detail in node Writing Macros. You can get a simple columnar table in this fashion: 1.1^P(pos2)1.2^P(pos3)...^P(posK-1)1.K 2.1^P(pos2)2.2^P(pos3)...^P(posK-1)2.K ... N.1^P(pos2)N.2^P(pos3)...^P(posK-1)N.K Naturally, you can change indent to adjust the position of the first column, or even precede it with ^P's. You can use ^C or ^R before an item to center or right flush it in its column, etc. All the column macro packages generate output like this when done, but they may do a lot of work first to figure out the ^P positions, and possibly rearrange the items from the way you supplied them. A technique even easier than the above is to use a fixed width font, and line things uyp in your text editor. Of course, it is not as flexible, and fixed width fonts don't look as good, typically. You can also try it with variable width fonts, but you will probably have to adjust it some to get the desired appearance. The package in R;TAB RMAC is simple to use, and may save you a lot of trouble over the above, by-hand methods. It has good instructions at the beginning of the file. The package in R;COLUMN RMAC can do more than the TAB package, and is only slightly harder to use. It also has instructions at the beginning. If you plan to do any amount of tabular work, you should read up on these -- they can save you a lot of grief.  File: RGUIDE, Node: References, Up: Top, Previous: Columnar Tables, Next: Writing Macros There are several packages available for assisting you with constructing bibliographies and references. They are: R;REF RMAC R;REF1 RMAC R;REF2 RMAC R;REF3 RMAC The general method of use for each is the same: 1. At the beginning of your file, you define the references, in the order in which you wish them to appear in the bibliography. (The bibliography itself will be remembered and produced later.) Each reference is defined this way: .ref Foo67 Foobar, John, Hacking at M.I.T., April, 1967. .em 2. To refer to any of these in the text, you insert the string register of the name given in the .ref line: ... and so was Foobar's work [^SFoo67]. ... 3. At the place where you want the bibliography to appear, do this: .insert_refs If you need something different, just take one of these packages (they are all very much the same), and make a private copy, modified as you see fit. You should be able to inspect them and see what they do fairly readily by now. Here are the details on the four packages provided: In each, the number registers ref_margin and ref_indent are used to set up the margins when the bibliography is output. The INDENT is set to the sum of ref_margin and ref_indent, and the RINDENT is set to ref_margin. The first line of each reference will begin at ref_margin, and hence will stick out to the left of succeeding lines for the same reference. The bodies of the references, as opposed to the reference numbers or codes, will always start at ref_margin plus ref_indent. The bibliography is produced in fill mode, with the principal and current fonts both 0. There is a ".ne 3l" before each reference. Note: The beauty of these files is that you can change the format used by just changing which file you .SO, because they all use exactly the same initial set up (.ref) the same referencing scheme (the string registers) and the same inserting technique (.insert_refs). If there were sufficient call for some other flavor, it could easily be added. REF - The references are numbered, in the order you originally gave them. So, ^SFoo67 might turn out to be "8", or something. The bibliography lines start with the reference number followed by a period, e.g., "1.". The default values for ref_margin and ref_indent are both 500 (i.e., 500 mils). REF1 - The references come out as the keyword string you used in the .ref line; e.g., ^SFoo67 will print as "Foo67". The bibliography line would start with "[Foo67]". The defaults for ref_margin and ref_indent are 500 and 1000, respectively. (The 100 is to leave room for the [Foo67].) REF2 - CACM format: The references should be entered in alphabetical order. When referred to in the text, the reference will print as number. The bibliography lines use the same number, followed by a period, both in boldface (according to the setting of bold_font when the REF2 package is read). That is followed only by a space before the rest of the line appears. When you do .insert_refs, it will output a header line, "References", in boldface, followed by the references. The ref_indent number register is ignored; ref_margin is normally 500. Single spacing is used. REF3 - This differs from REF2 only slightly. The "References" line will be centered, and there will be one blank line before each reference.  File: RGUIDE, Node: Writing Macros, Up: Top, Previous: References, Next: Debugging There are many topics that could be covered here; we will not attempt to make you expert in anything, but try to give you some hints and references. First, there are some mechanisms of R that you should understand before attempting write anything except simple macros. We will introduce you to the subjects listed below, and give you some hints. Beyond that, you should read the reference manual, and perhaps look at the macro package itself, to get ideas of more sophisticated techniques and tricks. * Menu: * Macro Definition:: How to define a macro, and how macro expansion works. * Environments:: What you should know about them, and a guide to which things depend on the current environment, and which do not. * Variables and the Stack:: How to use R variables (as opposed to registers), and the control structures. * Macro Writer's Hints:: A collection of little suggestions and techniques.  File: RGUIDE, Node: Macro Definition, Up: Writing Macros, Next: Environments Defining a macro is quite simple (although getting it RIGHT is another matter!) You just use the .DE request: .de ... body of macro ... . em The macro definition continues until the first line with .EM. If, for some reason, you need a line with .EM on it in the macro itself, you must write it this way: .de ... \. em ... . em The \ PROTECTS the "." (which is actually a control-.) from being interpreted until later. The .DE request is actually a little more flexible: .de defines a macro that is terminated with "." instead of ".EM". Further, after the macro is defined, the . line will be executed as a normal request line, so you may have to define a little macro named , which does nothing: .de . em You may in fact define permit a macro to be terminated by one of a set of terminators: .de ... This would be useful in a kept form of the LIST macros, where aech item is accumulated into the body of a macro, but the terminator may be "next" or "end_list", and you cannot tell in advance which it will be. Thus, .list and .next could have in them a .DE line like this: .de foo next end_list It is considered good style to indent everything in the body of macro that you can, by a space or two, to make it more readable. (See also node Variables and the Stack for more suggestions on this.) The .KEEP and .END_KEEP macros (see node Keeping) use the optional terminator feature, something like this: .de keep ... . de keep_holder end_keep . em .de end_keep ... . em That is, when .KEEP is run, it will cause the definition of a new macro, KEEP_HOLDER, which will hold your kept stuff, up through the next .END_KEEP. The .END_KEEP is also invoked, which has the effect of doing an appropriate .NE, and then invoking the recently defined KEEP_HOLDER to actually produce your kept item. (The actual macros are more complicated, to take care of other problems, but this is the essence of the scheme used.) When a macro is DEFINED with .DE, nothing in its body is "evaluated", EXCEPT any unprotected ^N's, ^S's, or ^A's. These are evaluated so that the mechanism will be powerful enough that you can write macros that define macros, etc. If you are NOT defining a macro in a macro, then the general rule is that every ^N, ^S, and ^A should have one backslash in front of it to protect it. That way it will not be evaluated when the macro is defined, but rather when the macro is invoked. If you define a macro in a macro, then most of the ^N's, ^S's and ^A's will need TWO backslashes, etc. The macro .def_setoff_macro is good example of this sort of thing. Control-A: The R control character, control-A, is the method by which macros gain access to their arguments. (Node Macro Invocation describes how the argument are defined for each invocation; perhaps you should review it if you do not feel comfortable with the subject.) The arguments are referred to by position, the first one begin numbered 0, the second argument 1, etc. To get argument N, you write ^AN (or, more likely, \^AN). Actually, that works only if N is between 0 and 9. ^A(exp) can be used for an arbitrary expression, including ones bigger than 9. The number register NARGS contains the number of arguments supplied to the current macro. For example: . for n 0 nargs-1 . ... \^A(n) ... . end for Macros can even distinguish whether they are called with a control-. or control-', with "^A.", which yields "1" if the macro was called with control-., and "0" otherwise. "0" is also the result if the macro was called with ^X. One way of thinking of macros is as if they are like string registers. In fact, they work almost exactly the same way. Of course they are defined differently, and different things trigger their insertion, but both are essentially a text substitution mechanism. What that means is, that the insertion of a string register, or invocation of a macro, are little more than just the substitution of the contents of the string register (the body of the macro) in the place of the call, in the input stream. That is in fact how they are implemented. So, although macros are like programs, there are ways in which they are NOT like programs, too. For example, besides grouping together requests in order to perform a specific function, macros are also used to hold text to be printed later. That is how table of contents, references, keeping, etc., are implemented. For these things, it is often convenient to add a little bit to the macro each time; the .AM request does that. It is also possible to access a macro body as a string. See the reference manual for details on these features, and also for information on the string processing available.  File: RGUIDE, Node: Environments, Up: Writing Macros, Previous: Macro Definition, Next: Variables and the Stack In R, certain properties controlling the appearance of the output are part of an ENVIRONMENT. The interesting thing about this is that if you change to another environment, all those properties change, "magically" and instantaneously. Environments have names, and the name of the current environment is always available in the string register ENV. In fact, on way to change to other environments is to change ENV. The other relevant requests are: .EV e - Change to environment "e". If it does not exist, then create it, initialized in a standard way. .ES e - Save all parameters of the current environment, INCLUDING ANY PARTIAL OUTPUT LINE, in environment "e". A new environment is created if "e" does not exist. .XE e - Expunge (throw away) environment "e". If "e" is the current environment, it will not be thrown away until another environment is selected. The initial environment is called TEXT. Some other environments used in the macro package are CONTENTS (table of contents), TABLES (figures and tables), FOOTNOTES (footnotes), HEADER (headers and footers), IGNORExxx (in IGNORE), LISTENVxxx (in lists), and SETOFFENVxxx (in setoff things). In general, things are done in other environments to prevent irrevocable side-effects, such as a line break that would force out a partial line in the wrong place. Here is a list of the things that are kept with each environment: the partial output line principal and current font, and a font stack for ^F and .FS (FONT, PFONT) line spacing (LS) fill and adjust modes (FILL, ADJUST, ADJUST_FILL, ADJUST_NOFILL) vertical offset (VOFF) indentation (INDENT, RINDENT, and temporary indent) tab stops (.TA, etc.) underscoring (UL, UL_SPACE, and UOFF) Everything else is common to everything is R, so care must be used to change such things back if you want to change a value temporarily. See node Variables and the Stack for some hints about that.  File: RGUIDE, Node: Variables and the Stack, Up: Writing Macros, Previous: Environments, Next: Macro Writer's Hints To make saving and restoration of values easier, and reduce problems arising from unwittingly using the same register name in two or more places, R provides what we call a STACK of values for string and number registers. This stack work in conjunction with the flow control requests, .BE, .IF, .EF, .WH, and .FR. We will explain the meaning of the control structures in a moment. For now, all you need to know is that we will call the lines read between a .BE, .IF, .EF, .WH, or .FR and the next .EN a BLOCK, and say that we are in a BLOCK during the time those lines are read. When you are in a block, the .NV and .SV requests may be used to save the previous value of a number or string register, and set the register to a new value. The register need not have a previous value. Here is an example: .be bar . nv foo 10 .... . en The nice thing about this is that when the .EN comes by, all the .NV's and .SV's done since the .BE will be undone. In this way we can use FOO in the block above temporarily without caring whether FOO was being used somewhere else. This feature is convenient a lot of the time, but becomes essential when writing macros such as .LIST, which can be nested inside themselves. Stylistic note: The macro package is set up so that the following long names are equivalent to the short names given in the R manual. It is considered good style to use the long names, and we will do so from now on: .begin .be .else .ef -- use the appropriate one of these two .elseif .ef -- .for .fr .while .wh .end .en .lbegin .if -- when used just to introduce a new block It is also customary to put the name of the kind of thing ended after .END, e.g.: .for n 1 nargs ... . end for Further, it is good style to indent one or two spaces for each level of blocks you are in. For example: .de foo . lbegin . nv foo 0 . for n 1 nargs . nr foo foo+n . end for . end lbegin . em [The above is a useless macro!] In addition to .NV and .SV, there are two requests, .HV and .VV that make it easier to do calculations in blocks. .HV and .VV work exactly like .HX and .VX, except that they save the number register that they will be changing. The saving is done after the new value is computed, but before it is stored, which is true of .NV and .SV, too, so the following works: .hv indent indent!m 1i An obscurity: In some cases care must be used about the order in which things are saved and restored, but it usually does not make too much difference. Here is a case where it does: .nv fill 0 .nv adjust 0 The problem here comes if someone change FILL later. Say a .FI is done. Then when the .END is encountered, ADJUST will be restored. BUT, it will be the fill mode adjust that is restored, not the nofill mode adjust. Therefore, when you wish to save and restore FILL and ADJUST safely, you can either do this: .nv fill 0 .nv adjust_nofill 0 (or similarly for fill mode), or this, which works when you do not know in advance what the new fill mode will be: .nv fill \^A0 .nv adjust 0 .nv fill \^A0 This works because FILL is restored before ADJUST, so that the correct adjust mode is restored. If you thought of just swapping the order of saving fill and adjust, that won't work because then the wrong adjust mode may be set up, etc. It is possible that you might run into other situations like the one shown above, but we believe not. Control Structure: The reference manual discusses this in detail, but here are a few tips: .FOR and .WHILE can be used only in macros (because they involve going backwards, so the text must be handy) Only .BEGIN can be put in a macro without a matching .END in the same macro. The LIST, EXAMPLE, KEEP, and other macros provide examples of its use. .LBEGIN is a convenient way to start a new block for saving and restoring some registers. Sometimes you have to introduce a variable before you have a value for it, so that it will not be lost. For example: .if ... . nv foo exp1 .else . nv foo exp2 . end if will not work. You should do this instead: .nv foo 0 .if ... . nr foo exp1 .else . nr foo exp2 . endif One last hint: Don't forget that every time around a loop (.FOR or .WHILE), and every macro invocation involves scanning a potentially large amount of text, and R's speed in limited by its character processing rate.  File: RGUIDE, Node: Macro Writer's Hints, Up: Writing Macros, Previous: Variables and the Stack Below is a list of little hints, in no particular order, that may help you in writing your own macros. Finding sizes of things: The macro package provides two very useful macros for this, .SIZE and .WIDTH. They work like this: .width arg - Finds out the width of "arg", and saves it in the number register WIDTH (in mils). It also saves its height above the baseline in the number register HA, and its height below the baseline in HB. .size name - Finds of the vertical size of the macro "name", when expanded. The number register SIZE will contain the size in mils. Both macros work by expanding their arguments in a temporary environment set up specially so as to cause no side-effects. The macro .IGNORE provides that environment. If you feel the need to write other size finding macros, make sure you understand the operation of WIDTH and SIZE, first; read the macro package! If you are not very careful you can cause weird things to happen to your output. Gluing: When writing macros that output little pieces of text, don't forget that usually you want to follow each text line in the macro with a ^G, so that the newline will not be output as a space, or cause a line break. Note that you can put ^G's at the start of a line, to eat the PREVIOUS newline, provided there has not been a breaking request in between. However, macros that are invoked inline have an implicit ^G both before an after them. So, generally a ^G is necessary only at the end of each text line in a macro. Mathematical Macros: The crucial things to remember are: Don't forget ^G's. Use the variable stack, so your expressions will nest. Use .WIDTH to find widths and heights of expressions; in particular, this kind of construction will not work in every case: .nr temp hpos ... output something ... .hs temp-hpos!m It fails because the outputting might force a line break, which makes the second measurement of hpos bogus compared to the first one. Use .HS, never ^P, .HP, or setting HPOS. Use relative adjustments to VOFF (^U, ^D, ^V(+...), ^V(-...)). When drawing a line with underscores, be careful that the states of UL, UL_SPACE, and UOFF will be restored correctly. For example: .lbegin . nv ul 1 . nv ul_space 1 . nv uoff voff . hs ... . end lbegin Passing Arguments: If you wish to pass the arguments of one macro through to another macro, you can use the following lines: . sr args \^A:0 . for n 1 nargs-1 . sr args \^S:args \^A:(n) . end for . foo \^S:args The ":"'s are required if you want to make sure that control characters in the arguments are not interpreted too soon. Naturally this works with any number of arguments. A slight variation will "glue" all the arguments together into one argument, with spaces in between: ... . foo {\^S:args} There are other useful variations on this trick.  File: RGUIDE, Node: Debugging, Up: Top, Previous: Writing Macros, Next: Miscellaneous This node is organized as a collection of minor hints and techniques, in no particular order. Debug and friends: R supports a number register called DEBUG, which is normally 0, but is set to 1 if you put a -D in the command line (see node Invoking R for details on the command line). There is no other way to set DEBUG. DEBUG is tested at various places int he macro package, and if it is set, additional information will be printed on your terminal (or in your error message file). In addition, there are number registers called HEADER_DEBUG, FOOTER_DEBUG, FIGURE_DEBUG, and FOOTNOTE_DEBUG, which give extra information concerning the feature they name. They are normally off (0); setting them to 1 turns them on. They maybe turned on and off at your whim. This information can be very helpful is figuring out problems such mysterious blank pages near a figure or footnote, etc. [Note: a common cause of that kind of misbehavior is something that changes size between the time its size is measured and it is actually printed. Naturally figures, footnotes, etc., are not SUPPOSED to change size, but sometimes they do, if you put "funny" stuff in them.] Tracing: R has a very useful trace feature, controlled by the TRACE number register. Normally it is 0 (off); setting it to 1 turns tracing on. Another way to turn tracing on is to put -T in the command line (see node Invoking R), but it is often more useful to turn tracing on just in the region of the problem. For example: .nr trace 1 ... .nr trace 0 You can turn tracing on and off as much as you like. What you get when tracing is on is two extra files describing what R actually saw. If the first name of your input file is FOO, they will be called FOO RTA and FOO RTB (for R Trace A and R Trace B). The A file shows every character scanned. For example, if you have written: .sr foo ^Sralph!or then the A file will show both scanning of the string register name "ralph", and the characters that come out of it, etc. The B file is a "higher level" trace, often easier to wade through to find the problem. The B trace shows only the actual values seen by each request. For example, in a .nr, all it will show is ".NR FOO 1045" where 1045 was the value of what might have been a quite involved expression. Other things are made briefer and standardized in similar ways. Tracing can be very useful, but the output can be HUGE, because of all the extra stuff that happens behind your back in the macro package. That is why we suggest you be selective in the region that you trace. About the only thing tracing cannot do is show you what you output looks like. For debugging a document, you can often figure things out by examining in your text editor output for the LPT device. But sometimes the problem only shows up on a particular device, and then you must apply your deductive powers. Some Common Mistakes: Forgetting a ^F* to switch fonts back. Forgetting a matching .END, .FINISH_FIGURE, .EFOOT, .END_LIST, etc. Some of these will cause R to attempt to put large parts of your file into a macro, and say "macro getting big", or even STORAGE OVERFLOW. (On the larger computers, these mistakes are the main causes of STORAGE OVERFLOW.) Causing a line break by forgetting a ^G, or inserting a space or newline in the inappropriate place. Not getting a line break, because you are not in nofill mode, or you omitted a space somewhere. Omitting a backslash where you need it. This often results in an "undefined register" message.  File: RGUIDE, Node: Miscellaneous, Up: Top, Previous: Debugging, Next: Top Here are some of the things that we did not discuss. You are on your own (see the reference manual, etc.) Indexing, .II, .ID. Traps, .ST, .CT, .RT Writing to files, .WF, .WS, .WM, .WL, .WA, .WE Terminal I/O, .RL, .TM Miscellaneous Requests: .PN, .BJ, .ND, .SD, .XN, .XS, .SB, .SI, .SC, .SL, .RM, .EQ, .MS, .NX, .RD, .EX, .XC, .PR, .PW, .PL Other control characters: ^K Other built-in registers: DAY, ENABLED, END_OF_SENTENCE, EVEN, FHEIGHT, FWIDTH, HABOVE, HBELOW, INTERACTIVE, LPI, LVPU, MACRO_ARG_LIMIT, MACRO_LIMIT, MARGIN_LIMIT, MAXHPOS, MONTH, PAGE_EMPTY, PBOTTOM, PL, PLEFT, PRIGHT, PRINTING, PTOP, RUNTIME, SPACING, STATS, VERSION, VPLOST, VTRAP, YEAR, CFDATE, CFILENAME, CFTIME, DATE, DEVICE, FDATE, FILENAME, FTIME, LINENO, MACRO, SDATE, TIME, USER Not to mention many things internal to the macro package.