Redtohtml

Go back to top

REDTOHTML

REDTOHTML

FUNCTION

RedToHtml is a modification of GCG's program Red to convert documentation source files into HTML documents.

RedToHtml 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 laser printer. PostScript is a powerful page description language that can make publication-quality output on laser printers equipped with a PostScript interpreter, such as the Apple LaserWriter. RedToHtml is designed to extend the philosophy of RUNOFF to support some of PostScript's features. Most EGCG documentation is formatted using RedToHtml

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 laser printer must be attached to the port to which the logical name LPrintPort has been assigned.

You can include a figure from a Wisconsin Sequence Analysis Package(TM) graphics program within the text of a Red document.

AUTHOR

This GCG program was modified by Peter Rice (E-mail: pmr@sanger.ac.uk Post: Informatics Division, The Sanger Centre, Hinxton Hall, Cambridge, CB10 1RQ, UK).

All EGCG programs are supported by the EGCG Support Team, who can be contacted by E-mail (egcg@embnet.org).

EXAMPLES

Here is a session using RedToHtml to format the document red.red and send the output to an HTML file

  
  
  % redtohtml -html=redtohtml.html
  
   RED format what file(s)?  EProgram_Manual:redtohtml.red
  
   First page (*    1 *) ?
    Last page (* 9999 *) ?
  
  %

OUTPUT

You, gentle user, are reading the output from this session with RedToHtml

RELATED PROGRAMS

Red is a text formatter that creates publication-quality documents on a PostScript laser 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 GCG graphics program within the text of the document. Most GCG documentation, correspondence, and publication is done with Red. Figure makes figures and posters by drawing graphics and text together. You can include output from other GCG graphics programs as part of a figure. You can include output from the Figure program (or from any other Wisconsin Package(TM) graphics program) within the text of a Red document with the .PSInclude command.

RESTRICTIONS

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

COMMANDS

Any line of the input file that starts with a period is interpreted by RedToHtml 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 (box)

draws a box around this page showing the part of the platen that lies within the current margin settings (.lm, .rm, .tm, and .ps). The box includes enough space for the running title, subtitle, and page number. Note, however, that the left and right margins for the running titles are set whenever the .nm, .nmr, .t, or .st commands are interpreted. Subsequent margin calls do not change the horizontal position of the titles unless one of these commands follows them. The file GenDocData:redtest.red makes a little test pattern that exercises this command. If paragraphs have a negative indenting value, the box is drawn around the filled part of the text, and the topic sentence will start outside the box.

.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.

.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 laser 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 n1 n2 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. You can define 10-point font groups for fonts n1-n4 with the .SchoolBook, .Courier, and .AvantGarde commands.

.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 of string1 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 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; 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 ^|VMS|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).

.NewStuff String OffSet Font Scale (emphasize new stuff)

issues a break and starts a region of the file that prints extra characters outside the margins to add emphasis. We use this to show the parts of our document that are new. The optional arguments can be used to specify the String to print beside each column, the distance from the margin, the font and the scale. If you use any optional argument, you must use all the arguments that precede it so the parser knows which parameter you are setting.

.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 n1 (numbering)

sets Red to put a page number in the upper-right corner of each page. If you provide a number (n1), 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 appear as the running titles at the same height as the number. (See also .nnm, .nmr, .Section, .st, .t, and .tf.)

.nmr n1 (numbering in Roman)(+)

sets Red to put the page number as a lowercase Roman numeral in the upper-right corner of each page. If you provide a number (n1), Red puts that number on the current page and start numbering from that number upward. If you have defined a title or a subtitle these appear as the running titles at the same height as the number. If your command is uppercase (.NMR), Red displays the numeral in uppercase. (See also .nm, .nnm, .Section, .st, .t, and .tf.)

.nnm (no numbering)

turns off numbering 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 titles to appear with the title on the left and the subtitle and page number on the right. (See also .TwoSided.)

.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 laser 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, add the optional parameter !odd. This parameter makes Red print out a blank page if the current page is odd. If you do not want the next page numbered, use the optional parameter !new. If you want Red to print two pages on each page, use the optional parameter !double. If you want Red to print the text of the next page along the long dimension of the page, use the optional parameter !landscape. If you want Red to number the first page of your document, use the optional parameter !old. (Use this with !odd to make Red number the first page of the following chapter.)

.Require "filename" (include a file)

This is equivalent to .Include. It is supported to let files being used with RUNOFF work with Red. Please do not use it.

.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 f1 f2 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.

.Section 1- (section)(+)

You can associate the number on each page with a section or chapter by defining a string that prints just to the left of the number. In this case the string 1- would make the numbering of page three look like 1-3. (See also .nm, .nmr, .st, .t, and .tf.)

.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 parameters 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 and string2 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 Red (subtitle)

defines a running title (in this case Red) that is justified against the right margin when numbering is enabled. The right margin used is the margin that is current when either the subtitle or title command is issued. The font for the running titles and the numbering is set with .tf. The line for the running titles and the numbering is set with .tm. (See also .nm, .nmr, .Section, .t, and .TwoSided.)

.t Program Manual (title)

defines a running title that appears justified against the left margin when numbering is enabled (see .nm). The left margin used is the margin that is current when either the subtitle or title command is issued. The font for the running titles and the numbering is set with .tf. The line for the running titles and the numbering is set with .tm. (See also .nm, .nmr, .Section, .st, and .TwoSided.)

.tf n1 f1 (title font)(+)

sets the font and the scale used for the running title and the numbering. (See also .Font, .nm, .nmr, .scale, .Section, .st, .t, and .tm.)

.tm 5.0 2.0 (top margin)(+)

The first top margin parameter sets the number of lines to skip before printing the line with the numbering and the running title. The second parameter sets the number of lines between the title line and the first line of regular text. The unit of vertical carriage movement is 1/6 inch. For this example, therefore, the first line of regular text would be on line 8 -- 1.33 inches from the top. (See also .nm, .nmr, .Section, .st, .t, and .tf.)

.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 laser 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 f1 f2 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 in the middle of even-numbered pages while titles are in the middle and subtitles and numbers are on the right of odd-numbered pages (see .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

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 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: April 22, 1996. 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

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 ^|VMS|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

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

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 option -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

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

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

ACKNOWLEDGEMENTS

Red was written by Philip Delaquess and John Devereux.

COMMAND-LINE SUMMARY

All parameters for this program may be put on the command line. Use the option -CHEck to see the summary below and to have a chance to add things to the command line before the program executes. In the summary below, the capitalized letters in the qualifier names are the letters that you must type in order to use the parameter. Square brackets ([ and ]) enclose qualifiers or parameter values that are optional. For more information, see "Using Program Parameters" in Chapter 3, Basic Concepts: Using Programs in the User's Guide.

  
  
  Minimal Syntax: % red [-INfile=]Program_Manual:red.red -Default
  
  Prompted Parameters:
  
  -BEGin=1             first page
  -END=9999            last page
  
  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 the paper
  -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 upppercase
  -CARdimage=FileName  writes line-by-line text file instead of PostScript
  -ASCii=FileName      writes a formatted text file instead of PostScript
  -CTRLD               adds D at the end of the output

LOCAL DATA FILES

None.

OPTIONAL PARAMETERS

The parameters and switches listed below can be set from the command line. For more information, see "Using Program Parameters" in Chapter 3, Basic Concepts: Using Programs in the User's Guide.

-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.

-COPies=2

makes Red print extra copies of your document.

-MONitor

shows the page that is printing.

-HTML=filename

makes an HTML marked up file instead of writing output to a PostScript laser printer. We use this option to make formatted HTML pages for the EGCG Web documents. Some features of RedToHtml such as font modulation, font scaling, page size, titles, subtitles, and numbering are not supported for HTML 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 provided by the browser. Superscripting and subscripting are supported by putting parentheses around offset material. Bold can be supported with the option -BOLDtoupper.

-ASCii=filename

makes a text file instead of writing output to a PostScript laser printer. We use this option to make formatted ASCII files for the GCG 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 option -BOLDtoupper.

-BOLDtoupper

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

-CARdimage=filename

makes a text file instead of writing output to the laser printer. We use this option to quickly make files that show the paging that would have occurred on the laser 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.

-TRAy=1

sets Red to use a paper tray other than the default tray. On PostScript laser 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).