diff --git a/Makefile b/Makefile index 0ba0e7bd..9604aa08 100644 --- a/Makefile +++ b/Makefile @@ -37,7 +37,7 @@ DOC = info _info_ sysdoc sysnet syshst kshack _teco_ emacs emacs1 c kcc \ combat pdl minits mits_s chaos hal -pics- imlac maint BIN = sys1 sys2 emacs _teco_ lisp liblsp alan inquir sail comlap c decsys \ graphs draw datdrw fonts fonts1 fonts2 games macsym maint imlac \ - _www_ gt40 llogo bawden sysbin -pics- lmman + _www_ gt40 llogo bawden sysbin -pics- lmman r MINSRC = midas system $(DDT) $(SALV) $(KSFEDR) $(DUMP) # These are not included on the tape. diff --git a/bin/r/ts.r42 b/bin/r/ts.r42 new file mode 100755 index 00000000..20445eed Binary files /dev/null and b/bin/r/ts.r42 differ diff --git a/build/misc.tcl b/build/misc.tcl index 07d256b7..3fc9018b 100644 --- a/build/misc.tcl +++ b/build/misc.tcl @@ -1425,6 +1425,15 @@ expect ":KILL" respond "*" ":testc\r" expect "Done." +# R, text formatter. +respond "*" ":link sys3; ts r, r; ts r42\r" +# sys2; ts rr -> r; ts rr +# .info.; r info -> r; r info +# .info.; r recent -> r; r recent +# r; r macros -> r; r30 rmac +# r; rmacro 1 -> r; r macros +# sys3; ts itype -> r; ts itype + # C library for drawing on a TV display. respond "*" ":cwd clib\r" respond "*" ":cc tv.>\r" diff --git a/doc/info/rguide.info b/doc/info/rguide.info new file mode 100755 index 00000000..a0135785 --- /dev/null +++ b/doc/info/rguide.info @@ -0,0 +1,4855 @@ +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. diff --git a/doc/programs.md b/doc/programs.md index 785c75e6..9c373295 100644 --- a/doc/programs.md +++ b/doc/programs.md @@ -261,6 +261,7 @@ - PWORD, replacement for ATSIGN HACTRN that requires registered logins. - QB, the game of Qubic. - QUOTE, prints out a random quote. +- R, typesetting software. - REATTA, reattaches disowned jobs to terminal. - RECORD, save TV display contents as text file. - REDRCT, redirect IP routing.