RED

Red is a text formatter that creates publication-quality documents on a PostScript printer such as the Apple LaserWriter. You can use 13 different fonts, scaling each font to any size. You can also include figures and graphics from any Wisconsin Package graphics program within the text of the document.

DESCRIPTION [ Previous | Top | Next ]

Red is a text formatter somewhat like RUNOFF. You supply a file with text and embedded formatting commands, and Red formats your document and prints it out on a PostScript printer. PostScript is a powerful page description language that can make publication-quality output on printers equipped with a PostScript interpreter, such as the Apple LaserWriter. Red is designed to extend the philosophy of RUNOFF to support some of PostScript's features. Most Wisconsin Package^(TM) documentation and correspondence is printed using Red.

Formatting is controlled by two basic entities: commands and flags. Commands appear by themselves on a line that starts with a period; flags are special characters that occur within regular text. Typical commands move the carriage or reset the margins; typical flags change the font, move the carriage for subscripts and superscripts, or insert the current date. A complete list of commands and flags appears below.

If you only want part of a document, you can specify the first and last pages to print. The PostScript printer must be attached to the port to which the logical name LPrintPort has been assigned.

You can include a figure from a Wisconsin Package graphics program within the text of a Red document.

EXAMPLES [ Previous | Top | Next ]

Here is a session using Red to format the document red.red and send the output to a PostScript printer attached to LPrintPort:


% red

 RED format what file(s)?  Program_Manual:red.red

 First page (*    1 *) ?
  Last page (* 9999 *) ?

%

OUTPUT [ Previous | Top | Next ]

You are reading the output from this session with Red.

Figure makes figures and posters by drawing graphics and text together. You can include output from other Wisconsin Package graphics programs as part of a figure. You can include output from the Figure program (or from any other Wisconsin Package program that produces graphics output) within the text of a Red document with the.PSInclude command, if your graphics configuration was set to produce PostScript output, or .GIFInclude, if your graphics configuration was set to produce GIF output (HTML only).

You can also include output from graphics producing Wisconsin Package programs with the .PNGInclude command if your graphics configuration was set to produce PNG output (HTML only).

RESTRICTIONS [ Previous | Top | Next ]

Red directs its output to LPrintPort so this logical name must be assigned to the correct port or queue before you run Red.

COMMANDS [ Previous | Top | Next ]

Any line of the input file that starts with a period is interpreted by Red as a command. Commands are shown below as they would appear on a line in the input file. The word in parentheses is the mnemonic for the command. A plus sign (+) following the parenthesis indicates that RUNOFF does not support the command.

Numbers like n1 following commands are integers such as 0, 1, 2. Numbers like f1 and numbers with a decimal point following commands are real numbers such as 1.0, 2.5. All carriage-control parameters (for example, right margin, left margin, spacing) are shown with a decimal point to imply that they can be fractional -- you can skip 1.5 lines.

Points are 1/72 inch. There are 12 points per line (vertical space). The vertical space is the unit used with the top margin, page size, skip, and test page commands. There are six points per character (horizontal space ). The horizontal space is the unit used with the left margin, right margin, and set paragraph commands. The horizontal space is constant regardless of the font and scaling being used.

Commands can be in either upper- or lowercase. If there are numbers following the command, there should be a space between the command and the numbers. If more than one number is used, the numbers can be separated from each other by a comma and/or a space.

.BeginSkip (begin a skip)⁽⁺⁾

starts a section that is skipped over when -ASCii is on the command line. There are often sections of a document (such as figures) that cannot be included in an ASCII output file. This command, together with the .EndSkip command, lets you skip over such sections.

.box +5.0 -5.0 +0.0 +0.0 (box)

draws a box relative to the current margins settings. The first and second numeric values are the amount to add or subtract to the left and right margins (in 1/12 inch increments). The third and fourth values are the amount to add or subtract to the current carriage position (in 1/6 inch increments).

If the third and fourth values are both +0.0 the box will look like a horizontal line, that is, the box will have no height. If the first and second values are both +0.0 the box will look like a vertical line, that is, the box will have no width.

If the values do not start with a plus or a minus, the box will drawn in the absolute position you specify on the page, regardless of the current carriage position and margin settings.

This command does not move the carriage.

If you do include any parameter values at all, this command draws a box around the current text area. This area is defined by the most recent left margin, right margin, top margin, page size, and shift over commands (.lm, .rm,.tm, .ps, and .so). We use this box to make sure the text is centered on the page or shifted away from the binding sides of each page appropriately.

Before version 9.0, this box extended around the area where the running titles were displayed. In version 9, however, running titles can be anywhere on the page (See .nmfp, .tfp, and.stfp.)

If paragraphs are negatively indented, the box is drawn around the filled part of the text, and the first line of each paragraph will start outside the box.

The file GenDocData:redtest.red makes a little test pattern that exercises this command.

.br (break)

stops filling and prints all of the words in the last line as a line of uncertain length, when text is being filled. (Many commands issue a break command before carrying out the rest of their purpose.)

.c (center)

centers the text on the next line of the input file between the current left and right margins. If the text being centered will not fit between the current margins, Red centers as much of it as it can and centers the rest on additional lines.

.cp 25.0 (carriage position)

issues a break and sets the carriage to start printing at line 25. (Lines are measured in 1/6 inch units from the top of the page.) It is probably not a good idea, but you can, at least in principal, move the carriage backwards to an absolute line with this command. (See .tm.)

.DefineStyle name (define a style)⁽⁺⁾

begins defining a style with the given name. Styles are discussed in detail below.

.EndNew (end a section of new emphasis)⁽⁺⁾

issues a break and then ends the section that is being emphasized. (See also.NewStuff.)

.EndSkip (end a skip)⁽⁺⁾

ends a section that is skipped over when -ASCii is on the command line. (See also .BeginSkip.)

.EndStyle (end a style definition)⁽⁺⁾

terminates the current style definition. Styles are discussed in detail below.

.EPSInclude FileSpec 1.0 (Encapsulated PostScript Include)⁽⁺⁾

This command includes a figure at the current carriage position by naming a file of encapsulated PostScript instructions to be sent to the printer.

.f (fill)

sets Red to fill all of the free-format text in your input file. Within filled text, Red will skip two spaces instead of one after periods, colons, exclamation marks, question marks, semicolons, or right parentheses. Filling may be part of a style, explained below. (See also .nf and .j.)

.fgd 10.0 (figure deferred)

inserts a blank space of 10.0 lines (for a figure). If a space of this size will not fit on the current page, Red leaves the blank space at the top of the next page. Such a pending figure is said to be deferred. You can have up to 32 simultaneously deferred figures. (See also .PSInclude.)

.followon (follow on)

Normally Red tests the page to see if there is enough room whenever you start a paragraph. However if you have multiple topic lines, as we often do in the documentation for the Procedure Library, you will often start a multi-heading paragraph only to have the page turn before all the headings are shown. This feature will suppress the test page service whenever a paragraph follows a paragraph that is only one line long. (See also .spr and .tp.)

.Font n1n2 n3 n4 n5 n6 n7 n8 (define font groups)⁽⁺⁾

Fonts come in groups of up to eight different fonts. Normally Red uses the first font you have chosen (n1). The number of each available font is shown in the list below. When you use a font flag to begin printing in italics, bold, or bold italics, Red switches to font numbers n2, n3, and n4 respectively. A switch-font-group flag can be used to make a second group of four fonts (n5-n8) work like fonts n1-n4. If you specify only one font (n1), Red uses fonts n1+1 through n1+7 for fonts n2-n8. Tables showing each character in each font appear at the end of this document. Here are the fonts we currently support, scaled to 13 points:

1. New Century Schoolbook
2. New Century Schoolbook Italic
3. New Century Schoolbook Bold
4. New Century Schoolbook Bold-Italic
5. Courier
6. Courier Oblique
7. Courier Bold
8. Courier Bold-Oblique
9. Avant Garde Book
10. Avant Garde Oblique
11. Avant Garde Demi
12. Avant Garde Demi Oblique
13. Symbol

You can define 10-point font groups for fonts n1-n4 with the .SchoolBook, .Courier, and .AvantGarde commands.

.GIFInclude ImageFileSpec [width [height]] (include a Graphics Interchange Format file, HTML

only)

This command interrupts executation of the current input file and generates HTML content to display the specified GIF image file. If you include the optional width and height values, the image will be displayed to those size constraints. (See also .PNGInclude.)

.GoTo Below (skip ahead to a (particular) target line)⁽⁺⁾

Sometimes, such as when you are modifying a big document, you temporarily want to skip over sections. This command sets Red to skip everything in the current input file until it finds a line that starts with .!Below. This target line must occur in the same input file as the.GoTo command -- all included files between the GoTo and its target are ignored. The pagination and absolute position on the page of the text following the target is disrupted.

.If Symbol .AnyCommand (if)⁽⁺⁾

tests the value of Symbol and executes any valid Red command if it is true. (See the .Set and .Unset commands to find out how to set a symbol value.)

.Include FileSpec [string1 string2] (include a file)⁽⁺⁾

This command interrupts execution of the current input file and starts reading text and formatting instructions from an included file until that file is exhausted. Included files can include other files and these can include others to a total depth of 25 files.

If you include the two optional strings, every instance ofstring1 in the included file is replaced with string2. String1 and string2 cannot contain spaces, but they may contain flags. The scope of the substitution only extends through the included file (and any files that it can, in turn, include).

.j (justify)

sets Red to stretch filled lines so that they extend all the way from the current left margin to the current right margin. This is done by widening the intervening spaces appropriately. The last line of each paragraph is not justified. Justification can be part of a style, explained below. The text in this document is justified. (See also .f and .nj.)

.Letter 1 2 (letter tray1 tray2)⁽⁺⁾

sets Red to print the first page on the paper in tray 1 (see .tray) and continue all subsequent pages from tray 2. If numbering is enabled, the running titles appear at the upper left with the name of the addressee, the date, and page shown on three separate lines.

You should set title font and position with a command like .tfp 1 0.9 4 0 in order to leave enough room.

Red finds out the name of the addressee in one of two ways: 1) you put the name of the addressee on the first line, following a comment line that looks like .Address; or 2) you define the name of the addressee with the title command (.t).

.ListItem 1 (list item)⁽⁺⁾

Red formats a single member of a list of alternatives when your source file contains a string like ^|OpenVMS|UNIX\|. This feature is normally disabled, unless you use the .ListItem or.fl list command. If there has been no call to .ListItem, but the .fl list command has enabled the list flag, Red prints the first item of the list. You can have up to 10 items in a list. You can have more than one list of items on a line, but all of the items in any list must occur on the same line. The items may contain other flags and spaces.

.lm 5.0 (left margin)

sets the left margin (the carriage position to the right of which text is printed). The units of horizontal carriage movement are 1/12 inch -- the same as a typewriter using elite type. These units are the same no matter what font and scaling you are using. Usually margins are set at the top of a document and only relative margin adjustments are made within the document. Make relative margin adjustments by using a signed number such as +5.0 or -10.0. For example, your text is centered on a page that is 8.5 by 11 inches when you use margins of 5.0-90.0 or 10.0-85.0. The left margin can be part of a style, explained below. (See also .rm).

Here is approximately what the horizontal carriage ruler looks like:



        10        20        30        40        50        60        70        80        90
....:....|....:....|....:....|....:....|....:....|....:....|....:....|....:....|....:....|....:

.NewStuff 2.0 (emphasize new stuff)

identifies new features by adding a dark line to the right of the text from the line where this command occurs down to the point where the next .endnew command occurs. We use these lines to add emphasis to the parts of our document that are new in the current release. The optional value tells how many margin units outside the margin the emphasis line should appear. If you have used .TwoSided then the line appears on the left on even-numbered pages. (See .endnew.)

.nf (no fill)

sets Red to not fill all of the free format text in your input file. (See also .f and.j.)

.nj (no justify)

sets Red to stop justifying filled lines. (See also.j.)

.nm 1 (enable numbering and titling)

sets Red to show page numbers and running titles and subtitles. If you provide a number with this command, Red puts that number on the current page and starts numbering from that number upwards. If you have defined a title or a subtitle, these will also appear. (See also .nnm, .nmr, .Section, .st, .t,.nmfp, .tfp, and .stfp.)

NOTE: When you issue this command, Red resets the title, subtitle, and number positions using the current settings for top margin, page size, left margin, and right margin. (See.tm, .ps, .lm, and .rm.)

.nmr n1 (numbering in Roman)⁽⁺⁾

works like .nm, but pages are numbered with Roman numerals. If your command is uppercase (.NMR), Red displays the numerals in uppercase. (See .nm.)

.nmfp 1 1.0 2.0 0.0 (number font and position)⁽⁺⁾

Red will number pages on the right of every page either above or below the main text. When .TwoSided is used, these numbers appear on the left for for even-numbered pages. The first two numbers are the font and scale of these running numbers. The third number is the number of lines above the top or below the bottom line of the text where these numbers should appear. If the third number is positive the number will be above the main text, if negative below.

The fourth number sets the number of margin units outside or inside the outer text margins where the page number will appear. If the fourth number is zero, page numbers are justified at the text margin. If the fourth number is positive, the page number appears outside the margin, if negative inside.

Whenever the subtitle and page number are set to appear together on the same line, the subtitle is justified against the page number with the page number on the outside.

.nnm (no numbering or titling)

turns off the display of page numbers and running titles. (See also .nm.)

.nofollowon (follow on)

reverses the .followon command. (See .followon.)

.NoSubstitute string1 (nosubstitute)⁽⁺⁾

stops substitution of string1.String1 is any pattern of ASCII printing characters that have been used with a previous .Substitute command. The substitution stops until you use the.Substitute command again to turn it back on.

.OneSided (one sided)⁽⁺⁾

sets running titles to appear with titles on the left and subtitles and page numbers on the right. (See .TwoSided.)

.PNGInclude PNGImageFileSpec [width [height]] (include a Portable Network Graphics file, HTML only)

This command interrupts executation of the current input file and generates HTML content to display the specified PNG image file. If you include the optional width and height values, the image will be displayed to those size constraints. (See also .GIFInclude.)

.ps 55.0 (page size)⁽⁺⁾

sets the bottom margin for a page -- the lowest carriage position on which text can be displayed. When text or skipped lines bring the carriage below this position, Red issues a new page command and continues on the next page. (See also .tm.)

.PSInclude FileSpec 1.0 (PostScript Include)⁽⁺⁾

This command includes a figure at the current carriage position by naming a file of PostScript instructions to be sent to the printer (see the FIGURES topic below).

.pg (new page)⁽⁺⁾

ends the current page and prints any additional text on subsequent pages. If the current page has nothing on it, nothing happens. Therefore, this command can appear in the heading at the beginning of an input file.

If you want chapters to start on odd pages, addodd to the parameter. This parameter makes Red print out a blank page if the current page is odd.

If you do not want the next page numbered, usenew.

If you want Red to print two pages on each page, use double.

If you want Red to print the text of the next page along the long dimension of the page, use the landscape.

If you want Red to number the first page of your document, use old. (Use this with odd to make Red number the first page of the following chapter.)

.rm 90.0 (right margin)

sets the right margin, which is the carriage position beyond which text will not be printed. (See the .lm command for a discussion of margin control.) The right margin can be part of a style, explained below.

.s 1.0 (skip)

issues a break command and skips 1.0 lines (a line is 1/6 inch). If filling is turned on and if spacing is set to 2.0, the break skips a line and this skip command skips an additional line. The number of lines skipped can be negative. (See also .sp, .sd, and.br.)

.Scale f1f2 f3 f4 f5 f6 f7 f8 (scale)⁽⁺⁾

Each font in a font group (see .Font) can be scaled independently. The scales are decimal numbers such as 1.0, 1.1. A scale is a factor by which the standard 10-point font is multiplied to make it bigger or smaller. You can specify just one scale factor if you want all eight fonts to be printed with the same scaling. Here is what the New Century Schoolbook font (Font 1) looks like at several different scalings:

0.8 prints each font at 8 points

0.9 prints each font at 9 points

1.0 prints each font at 10 points

1.1 prints each font at 11 points

1.2 prints each font at 12 points

1.3 prints each font at 13 points

1.4 prints each font at 14 points

1.5 prints each font at 15 points

.Section A- (section)⁽⁺⁾

You can associate page numbers with a section or chapter by defining a string that prints just to the left of the number. In this case the stringA- would make the numbering of page three look like A-3. (See also .nm and .nmr.)

.sd 1.0 (skip if dirty)⁽⁺⁾

It is often desirable to skip two lines before starting a figure or a table. On a fresh page, these two lines are wasted. Skip if dirty is a conditional skip that deals with this problem. It issues a break and then skips a line only if something has already been printed on the current page. (A line is 1/6 inch.) The number of lines skipped can be negative.

.Set Symbol (set)⁽⁺⁾

sets the value of a symbol to true. The symbol may be new or may have already been set by previous calls to .Set or .Unset. (See also .Unset and .If.)

.so 2.0 (shift over)⁽⁺⁾

When binding double-sided copies of a manuscript, the binding uses up some of the left margin on odd pages and some of the right margin on even pages. The shift over command staggers the left and right margins depending on the page number. A shift over of 2.0 staggers the odd pages two character widths (2/12 inch) to the right and the even pages two character widths to the left. The difference between odd and even pages is 4.0 character widths (4/12 inch).

.sp 1.5 (spacing)

sets the number of lines the carriage advances after each line when filling is turned on.

.spr 5.0 1.0 5.0 (set paragraph)

The set paragraph command describes how you want filled paragraphs to be formatted. When filling is turned on, any line that starts with a space is taken to be the start of a new paragraph. The three numeric values for set paragraph determine the amount of indentation (positive or negative), the number of lines to skip between paragraphs, and the number of lines of text that must be left on the page (see.tp). If there are not enough lines of text available, a new page command is issued before the paragraph is printed. The paragraph setting can be part of a style, explained below.

Use a fractional negative indent and turn off justification to make perfect bibliographies. (See also .nj.)

Notice that the units of vertical carriage movement are different in the two parameters for test page and skip. Test page measures the number of lines of text left on this page at the current setting of spacing while skip uses the standard unit of carriage movement, which is 1/6 inch. (See also .tp and.s.)

.Style name (use a style)⁽⁺⁾

start using the previously defined style. Styles are discussed in detail below.

.Subscale 0.5 (subscript scale)⁽⁺⁾

adjusts the size of subscripts in relation to normal text. To print subscripts at the same size as normal text, use .Subscale 1.0. The default setting (.Subscale 0.5), prints subscripts at half the size of normal text. (See the flags @[ and @].)

.Substitute string1 string2 (substitute)⁽⁺⁾

substitutes string2 for every instance of string1. String1 andstring2 are any pattern of ASCII printing characters -- they may not contain spaces. String1 and string2 may contain flags. The substitution continues until you use the .nosubstitute command.

.Superscale 0.5 (superscript scale)⁽⁺⁾

adjusts the size of superscripts in relation to normal text. To print superscripts at the same size as normal text, use .Superscale 1.0. The default setting (.Superscale 0.5), prints superscripts at half the size of normal text. (See the flags @[ and @].)

.st ChapterName (subtitle)

defines a running subtitle that appears when numbering is enabled. The font and position of the running subtitles is set with .stfp. (See also .stfp, .tfp, .nm, and.TwoSided.)

.stfp 1 1.0 2.0 0.0 (subtitle font and position)⁽⁺⁾

Red will show a running subtitle on the right of every page either above or below the main text. When .TwoSided is used, these titles appear on the left for for even-numbered pages. The first two numbers are the font and scale of these running titles. The third number is the number of lines above the top or below the bottom of the text where the title should appear. If the third number is positive, the title will be above the main text; if negative, below.

The fourth number is the number of margin units outside the outer margin of the page. If this fourth number is positive, the title is outside the margin; if negative, inside.

Whenever the subtitle and page number are set to appear together on the same line, the subtitle is justified against the page number with the page number on the outside (effectively ignoring the fourth parameter of this command).

.t BookName (title)

defines a running title that appears when numbering is enabled (see .nm). The font and position of the running titles is set with .tfp. (See also .st, .tfp, .stfp, .nm, and .TwoSided.)

.tf n1 f1 (title font)⁽⁺⁾

This command has been replaced by .tfp. Do not use it and remove it from any Red files you have.

.tfp 1 1.0 2.0 0.0 (title font and position)⁽⁺⁾

Red will show a running title on the left of every page either above or below the main text. When .TwoSided is used, these titles appear on the right for for even-numbered pages. The first two numbers are the font and scale of these running titles. The third number is the number of lines above the top or below the bottom of the text where the title should appear. If the third number is positive, the title will be above the main text; if negative, below. The fourth number is the number of margin units outside the margin of the page. If this fourth number is zero, the titles are justified to the margin. If this fourth number is positive, the title is outside the margin (toward the binding); if negative, inside.

.tm 6.0 (top margin)⁽⁺⁾

This command sets the number of lines below the top of the page where the first line of text should appear. The unit of vertical carriage movement is 1/6 inch. For this example, therefore, the first line of regular text would be on line six, one inch below the top of the page. The bottom of each character in the first line of text touches this line. (See also .tfp, .nmfp, .stfp, .ps)

NOTE: Before version 9, this command took two parameters. The first was distance in lines (1/6 inch) from the top of the page to the running titles. The second was the distance from the running titles to the main text area. Red can still interpret these old-format .tm commands. If Red sees two parameters, it infers that you want your titles in the old format and puts the number, title and subtitle all on the line above your main text. The title positions are all reset to this height when such an old-format .tm command is appears in your document.

.tp 5.0 (test page)

issues a break and tests the number of lines of text that can be formatted onto this page (at the current spacing). If you have set spacing to 2.0, then a test page of 3.0 would make sure that 6.0 lines were left on this page. The unit of vertical carriage movement, referred to as a line, is 1/6 inch. ( See also .s .sp .tm, and .ps.)

.Tray 1 (set paper tray)⁽⁺⁾

sets Red to use a paper tray other than the default tray. On PostScript printers, such as the LZR1200 series from Dataproducts Corporation, the paper trays are numbered as follows: 0 is the main cassette (the default), 1 is the upper cassette of the multi-cassette sheet feeder, 2 is the lower cassette of the multi-cassette sheet feeder, and 3 is the envelope feeder.

.ts f1f2 f3 f4 ... (tab stops)

sets tab stops. If you have set up tab stops, put tabs into a line and if filling is not turned on, Red skips ahead to the next tab column if the line has not already printed beyond it. (See .lm for more information about the horizontal carriage movement.)

.TwoSided (two sided)⁽⁺⁾

sets titles, subtitles, and numbering to be mirrored between odd- and even-numbered pages. Numbers and subtitles are on the left and titles are on the right of even-numbered pages while titles are on the left and subtitles and numbers are on the right of odd-numbered pages. (See .nm and .OneSided.)

.Unset Symbol (unset)⁽⁺⁾

sets the value of a symbol to false. The symbol may be new or may have already been set or unset by previous calls to .Set or .Unset. (See also .Set and .If.)

FLAGS [ Previous | Top | Next ]

Flags occur within text. They are used to change fonts, to make superscripts or subscripts, or to substitute the current time, date, or input filename. Flags are composed of the infrequently used characters: @, ^, \, _, #, =, [, ], *, &, %, |, and $.

You can get flag characters to print in one of two ways: 1) precede any flag character with an underscore (_) to cause Red to print the flag character instead of interpreting it as a flag; or 2) disable the interpretation of any flag with an .nfl command.

Flags are usually composed of two infrequently used characters. They are shown in the list below exactly as they would appear in your input file. The word in parentheses following the flag is the mnemonic for the flag.

^* (switch font to bold)

changes the font to bold. If italics are currently being used, this flag changes the font to bold-italic.

\* (stop printing in bold)

reverses the action of the switch-font-to-bold flag.

^& (switch font to italic)

changes the font to italic. If text is currently being printed in bold, this flag changes the font to bold-italic.

\& (stop italics)

reverses the action of the switch-font-to-italic flag.

^+ (switch from VMS to Unix case convention)

changes the case from mixed upper and lower to all lower.

\+ (switch to VMS case convention)

reverses the action of the switch-case-to-Unix flag.

^% (switch to alternate font group)

changes the font group (see.Font). Four alternate fonts become available for regular, bold, italic, and bold-italic printing.

\% (switch to regular font group)

reverses the action of the switch-to-alternate-font-group flag.

@[ (move carriage up 1/2 line)

moves the carriage up 1/2 line to start a superscript or end a subscript.

@] (move carriage down 1/2 line)

moves the carriage down 1/2 line to start a subscript or end a superscript.

_ (accept)

If you want to print a character normally interpreted as a flag, precede it with an accept flag.

# (space)

If you want two words to always print on the same line (such as Appendix I), put a space flag between them (Appendix#I). You can also add extra space to centered or filled text with the space flag.

When filling, Red skips two spaces after periods, exclamation points, and question marks. If you use a period in an abbreviation (for instance, Dr. Devereux), the extra skipped space is inappropriate. Use a space flag between the period and the next word to avoid the extra skipped space.

$$ (substitute)

You can include the current year, month, day, hour, minute, or filename in a document with the substitute flag. The expression$$Month#$$Day,#$$Year will print the current date: December 9, 1998. You can include the name of the file being formatted. Here is the syntax of each supported substitution: $$Year, $$Month,$$Day, $$Hours, $$Minutes, $$File.

^| (begin a list of string items)

starts a list of strings, one of which may be selected for output with the.ListItem command. Each string in the list is referred to as an item.

| (list separator)

separates one list item from the next within a list.

\| (end the string list)

signifies the end of a list of string items.

DISABLING FLAGS [ Previous | Top | Next ]

If you include a vanilla text file within your document, flag characters within it will not print correctly. You can disable each kind of flag or all the flags at once with the.nfl command. You can enable any disabled flag with a corresponding.fl command. Within a style definition (see below) you may enable all flags, or disable all flags, but there is no way for a style definition to enable or disable particular flags.

.nfl all (disable all flags)

disables all flags and prints all the flag characters in your input file. Tabs are not interpreted according to the settings made with the .ts command when all flags are disabled. When you reenable the flags with .fl all, any flags that were individually disabled remain disabled. This command can be part of a style definition.

.nfl accept (disable accept flag)

prints and does not interpret underscore characters (_).

.nfl alternate (disable alternate font flag)⁽⁺⁾

prints and does not interpret the two-character patterns ^% or \%.

.nfl bold (disable bold flag)

prints and does not interpret the two-character patterns ^* or \*.

.nfl hyphenate (disable hyphenation flag)

prints and does not interpret equal signs (=). (Red does not currently support hyphenation, but this flag is maintained for compatibility with RUNOFF.)

.nfl list (disable list flag)⁽⁺⁾

prints and does not interpret the list flags ^| and \|. Red formats a single member of a list of alternatives when your source file contains a string like ^|OpenVMS|UNIX\|. This feature is normally disabled, unless you use the .ListItem command or the.fl list command. If there is no call to .ListItem and the flag is enabled, Red prints the first item in the list.

.nfl space (disable space flag)

prints and does not interpret pound characters (#).

.nfl substitute (disable substitution flag)

prints and does not interpret the two-character pattern $$.

.nfl superscript (disable superscript flag)⁽⁺⁾

prints and does not interpret the two-character patterns @[ or @].

.nfl underline (disable italic flag)

prints and does not interpret the two-character patterns ^& or \&.

STYLES [ Previous | Top | Next ]

Starting with Version 8.0, Red supports style definitions. A style is a set of formatting commands grouped together and given a name. Once a style is defined, all of its component formatting commands can be recalled at any time by giving a single command. For example:


       .DefineStyle Typewriter
       .lm 10
       .mono
       .nf
       .EndStyle

       .DefineStyle Normal
       .lm 5
       .rm 90
       .spr 0, 1, 5
       .f
       .prop
       .nofollowon
       .EndStyle

The above defines a style named Typewriter which uses a left margin of 10, monospaced, and no filling; and a style named Normal with left margin 5, right margin 90, proportional, filling, and doesn't suppress the test page service. With these definitions made, Red can easily switch back and forth between the two styles, like this:


 .style normal

This part of the document is formatted in the "normal" style, with proportional font, filling, and so forth.


 .style typewriter

But this part is formatted in the typewriter style.

 .style normal

Now we're back to normal again...

There are two good reasons for using styles in your documents. First, they reduce noise and clutter by replacing several lines of cryptic format commands by single lines with meaningful style names. Second, they facilitate global format changes. Once you have determined which parts of your document should be in typewriter style, you can then change the style definition, a different left margin for instance, and have the change take effect everywhere the style is used. This is much easier than searching for left margin commands, figuring out which ones are there to effect typewriter styling, and changing only those.

A good practice is to identify those styles commonly required by the documents you usually write, define them in a common header file, and include this file in all your document sources. In this way, you can easily change your mind about the particulars of a style and have the changes affect all of your documents.

Here is a list of the formatting commands that have meaning inside a style definition.


       .f
       .fl all
       .j
       .lm
       .mono
       .nf
       .nfl all
       .nj
       .prop
       .rm
       .spr
       .followon

FIGURES [ Previous | Top | Next ]

You can include a figure from any Wisconsin Package graphics program within a Red document. This section tells you how.

Setting the Package to Plot With PostScript

First set up the Wisconsin Package to create graphics using PostScript with the SetPlot utility or a command like

% postscript LaserWriter LPrintPort

Creating a File of PostScript Instructions

Run any Wisconsin Package graphics program with the command-line parameter -PSINClude=myfile.ps. The program creates a file (in this case called myfile.ps) with your plot described using PostScript instructions. This file is created instead of the plot that the program would normally create .

Including the PostScript Instruction File Within Your Document

Within your Red input file, insert commands that tell Red to include the file of PostScript instructions you have just created. First test the page to see if there is enough room for your figure and its heading and/or legend, then insert any heading you want. Next, move the carriage down to position the figure and include the PostScript instruction file with the.PSInclude command. Last, move the carriage down so that the legend or the text following the figure prints below the figure. The source file

.sd 1
.tp 29
.scale 1.4
.c
Figure 1
.s 14
.PSInclude myfile.ps 1.0
.s 14

creates a figure that looks like this

Figure 1

Red rotates the plot (from landscape to portrait), scales it down, and moves the plot up or down so that it is centered at the current carriage position between the current left and right margins.

Positioning the Figure Horizontally

You can adjust the left-right position (if the original figure was not perfectly centered) by resetting the left and right margins before the .PSInclude statement. (Remember to reset the margins after the .PSInclude command.)

Positioning the Figure Vertically

You always have to adjust the vertical position of a figure and the text following it with two separate skip (.s) commands. The skip command preceding the.PSInclude command positions the plot on the page (by moving the carriage to the middle of the plot). The skip command following the .PSInclude command, moves the carriage down so that the legend and the rest of the document continues below the figure.

Start out by skipping 14.0 lines, then issue the .PSInclude command and end by skipping 14.0 more lines. Then continue the text of the rest of the document. When you print the first draft, if the figure is too low, skip fewer lines initially; if it is too high, skip more. If the text following the figure collides with the figure, skip more lines after the.PSInclude command.

Scaling the Figure

The number after the file specification in the .PSInclude command is a scaling factor that you can set to some number other than 1.0 if you want to expand or contract the plot.

Full Size Figures

GCG graphics usually occupy the whole page in landscape orientation. The.PSInclude command rotates them 90 degrees to portrait orientation, moves them up or down to line up with the current vertical carriage position, and reduces their linear size to about 70 percent of the original in each dimension. If you want to maintain the original orientation, scale, and position of the plot, add the word exact after the file specification on the same line as the.PSInclude command. If you want to maintain the original scale and position of the plot, but rotate it 180 degrees on the page, add the word rotate after the file specification on the same line as the .PSInclude command.

DRIVERS [ Previous | Top | Next ]

You can print many different files together in sequence by making up a driver file that contains nothing but .Include statements. Drivers are a good way to create consistent pagination across a large document. Here is the driver file we use to print the Appendices to the Program Manual:


 .Include DriverHeader
 .Include GenDocContents:Appendices.Contents
 .Include Program_Manual:Appendix_I.Red
 .Include Program_Manual:Appendix_II.Red
 .Include Program_Manual:Appendix_III.Red
 .Include Program_Manual:Appendix_IV.Red
 .Include Program_Manual:Appendix_V.Red
 .Include Program_Manual:Appendix_VI.Red
 .Include Program_Manual:Appendix_VII.Red

ACKNOWLEDGEMENTS [ Previous | Top | Next ]

Red was written by Philip Delaquess and John Devereux.

COMMAND-LINE SUMMARY [ Previous | Top | Next ]

All parameters for this program may be added to the command line. Use -CHEck to view the summary below and to specify parameters before the program executes. In the summary below, the capitalized letters in the parameter names are the letters that you must type in order to use the parameter. Square brackets ([ and ]) enclose parameter values that are optional. For more information, see "Using Program Parameters" in Chapter 3, Using Programs in the User's Guide.


Minimal Syntax: % red [-INfile=]Program_Manual:red.red -Default

Prompted Parameters:

-BEGin=1 -END=9999   sets the page range of interest

Local Data Files:    None

Optional Parameters:

-COPies=2            prints more than one copy
-MONitor             shows what page is printing on your terminal screen
-TRAy=1              prints document from paper in tray number one
-LETter              prints first page from tray 1, the rest from tray 2
-DOUble              prints two pages on each LaserWriter sheet
-LANDscape           rotates text to long dimension of 8.5 x 11 inch paper
-A4                  moves text field to center text on A4 paper
-UP=2.0              moves the whole text field up 2.0/6 inches
-OVEr=2.0            moves text field to the right 2.0/12 inches
-NOJUStify           doesn't justify
-RMLimit=75.0        limits right margin to 75
-LMLimit=5.0         limits left margin to 5
-NOPSINClude         makes RED ignore all .PSInclude commands
-NOEPSINClude        makes RED ignore all .EPSInclude commands
-OUTfile=temp.ps     directs the output to a PostScript file
-BOLDtoupper         changes characters within bold flags to uppercase
-CARdimage=FileName  writes line-by-line text file instead of PostScript
-ASCii=FileName      writes a formatted text file instead of PostScript
-HTML=FileName       writes an HTML file instead of PostScript
-MEDia               sets -BEGin and -END to refer to pages formatted
-CTRLD               adds <Ctrl>D at the end of the output

LOCAL DATA FILES [ Previous | Top | Next ]

None.

PARAMETER REFERENCE [ Previous | Top | Next ]

You can set the parameters listed below from the command line. For more information, see "Using Program Parameters" in Chapter 3, Using Programs in the User's Guide.

-COPies=2

makes Red print extra copies of your document.

-MONitor

shows the page that is printing.

-TRAy=1

sets Red to use a paper tray other than the default tray. On PostScript printers, such as the LZR1200 series from Dataproducts Corporation, the paper trays are numbered as follows: tray 0 is the main cassette, tray 1 is the upper cassette of the multi-cassette sheet feeder, tray 2 is the lower cassette of the multi-cassette sheet feeder, and tray 3 is the envelope feeder.

-LETter

sets Red to print the first page using the paper in tray 1 (see -TRAy) and print all subsequent pages using tray 2. If numbering is enabled, the running titles appear in the upper left with the name of the addressee, the date, and page shown on three separate lines. You should set the top margin with a command like.tm 6 6 in order to leave enough room. Red finds out the name of the addressee in one of two ways: 1) you put the name of the addressee on the first line, following a comment line that looks like .address; and 2) you define the name of the addressee with the title command (.t).

-DOUble

prints two pages on each sheet of paper.

-LANDscape

rotates the text to the vertical (long) dimension of the paper.

-A4

moves all left margins to the left 9/72 inch and raises all top and bottom margins up by 24/72 inch. This command will center documents on A4 paper without changing their pagination or filling in any way.

-UP=2

raises both the top and bottom margins up by 2/6 of an inch. (1/6 of an inch is the standard unit for the top margin and page size settings.)

-OVEr=2

moves both the left and right margins to the right by 2/12 of an inch. (1/12 of an inch is the standard unit for left and right margin settings.)

-NOJUStify

never justify regardless of what appears in the document. (See .j.)

-RMLimit=70

limit the right margin to never be more than 70 regardless of what appears in the document. (See .rm.)

-LMLimit=5

limit the left margin to never be more than five regardless of what appears in the document. (See .lm.)

-NOPSINClude

makes Red ignore all .PSInclude commands. Included PostScript plots can take a long time to print. You can use this parameter when you want to check the layout and don't need to see the included plots.

-NOEPSINClude

makes Red ignore all .EPSInclude commands. Included encapsulated PostScript plots can take a long time to print. You can use this parameter when you want to check the layout and don't need to see the included plots.

-OUTfile=LPrintPort2

lets you direct output to a different port, queue, or disk file. Usually, Red directs its output to a port or queue to which the logical name LPrintPort has been assigned.

-BOLDtoupper

changes all the alphabetic characters between the bold flags (^* and \*) to uppercase. Where alternative fonts are not available, this parameter adds emphasis where the original document called for a bold font.

-CARdimage=filename

makes a text file instead of writing output to the printer. We use this parameter to quickly make files that show the paging that would have occurred on the printer. The lines are not justified in the card image, but each token appears on the line where it occurs in the fully formatted document.

-ASCii=filename

makes a text file instead of writing output to a PostScript printer. We use this parameter to make formatted ASCII files for the Wisconsin Package on-line help documents. Some features of Red, such as font modulation, font scaling, page size, titles, subtitles, and numbering are not supported for ASCII output. The margins are absolute character columns; for example,.lm 0 starts printing in column 1 and .rm 75 puts the last character in column 75. Justification is simulated by randomly adding whole spaces between the words on each justified line. Superscripting and subscripting are supported by putting parentheses around offset material. Bold can be supported with the parameter -BOLDtoupper.

-HTML=filename

makes an HTML-formatted file instead of writing output to a PostScript printer. We use this parameter to make formatted HTML files for the Wisconsin Package on-line help documents. Some features of Red, such as font modulation, font scaling, page size, titles, subtitles, and numbering are not supported nor relevant for HTML output. Superscripting and subscripting are supported by putting parentheses around offset material, and by using the appropriate HTML flag (this is in order to allow text-based HTML viewers to read produced documents).

-MEDia

When you limit Red to print only part of your document, the first page and last page settings you choose refer to the pages as they are actually numbered. However, in a complex document the numbering may start over several times as it would if there were a title page, a table of contents, and a preface before the main body of a book. Printing pages three to six in such a document will cause Red to start printing as soon as a page number three is found and stop at the first page number six.

With this parameter the first page and last pages you choose refer to the number of pages actually formatted regardless of what pages numbers are printed on them. If Red leaves a blank page so that a new chapter will start on an odd-numbered page, that blank page counts as a face.

WARNING. Do not use this parameter with -CARD or-ASCII parameters.

-CTRLD

sends a <Ctrl>D (^D, ASCII 4) at the end of the stream of PostScript instructions (some terminal servers require this in order to liberate the terminal for use by others).

Printed: December 9, 1998 16:30 (1162)

[ Program Manual | User's Guide | Data Files | Databases ]

Documentation Comments: doc-comments@gcg.com
Technical Support: help@gcg.com

Licenses and Trademarks Wisconsin Package is a trademark of Genetics Computer Group, Inc. GCG and the GCG logo are registered trademarks of Genetics Computer Group, Inc.

All other product names mentioned in this documentation may be trademarks, and if so, are trademarks or registered trademarks of their respective holders and are used in this documentation for identification purposes only.