1 Prose Instruction Manual 27 May 86 _____ ___________ ______ + Prose Instruction Manual John P. Strait Copyright 1978, 1984, 1985, 1986 Academic Computing Services and Systems University of Minnesota ________ +Abstract Preparation and editing of prose (such as computer-oriented documentation) is a tedious process. This process can be made somewhat easier through the use of computerized text processing tools such as text editors and formatters. This writeup describes a text formatting program named Prose. Prose and this instruction manual are oriented toward the preparation of computer oriented documentation, and so this writeup assumes basic knowledge of computer-related text processing tools. Differences from the previous version of this manual are indicated by | change bars in the right margin. | - i - 1 Prose Instruction Manual 27 May 86 ________ +Contents 1 . . . . . Historical Notes 1 . . . . . Philosophy, Goals, and Abilities 2 . . . . . Prose and Cons 3 . . . . . Basic Units of Text 5 . . . . . A General Look at Directives 6 . . . . . Controlling the Formatting Environment 8 . . . . . Short Directive Table Descriptions of the Directives: 9 . . . . . Break, Change, Comment | 10 . . . . . Count, Form 11 . . . . . Indent 12 . . . . . Input 14 . . . . . Inx, Literal 15 . . . . . Margin 16 . . . . . Option 19 . . . . . Output 21 . . . . . Page, Paragraph 22 . . . . . Reset 23 . . . . . Select, Skip 24 . . . . . Sortindex, Subtitle, Title 25 . . . . . Undent, Weos Hardware and Operating System Dependant Information: 26 . . . . . CDC KRONOS and NOS Control statement call Character set Prose writeup ********** The text examples in this manual have been extracted from _______ __________ __ __________ +Alice's Adventures in Wonderland by Lewis Carroll. ********** - ii - 1 Prose Instruction Manual 27 May 86 __________ _____ +Historical Notes Most of the text formatting programs available today descend from one of several original programs. Among these is RUNOFF which was developed on the Dartmouth Time-Sharing System in the 1960s. Later, the Call-a-Computer system provided a RUNOFF version called EDIT RUNOFF as a text editor command. In 1972, Michael Huck, working on the University of Minnesota's MERITSS system (a CDC 6400 running the KRONOS operating system), began to develop a version of EDIT RUNOFF that he called TYPESET. TYPESET went through many developmental changes, and stabilized somewhat in early 1977 at version 5.0, which is written in CDC COMPASS assembly language. Prose is written in the programming language Pascal, and was developed over a year's time starting in the spring of 1977. The design of Prose was influenced heavily by TYPESET and so Prose is one of the many descendants of RUNOFF. ___________ ______ ___ _________ +Philosophy, Goals, and Abilities Prose is intended primarily for the preparation of machine retrievable documentation, and this has influenced the choice of its repertoire of abilities. TYPESET was intended as a "versatile text information processor commonly used to typeset theme papers, term papers, essays, letters, reports, external documentation ..., and _______ ___ ___________ +almost any other typewritten text" [Typeset 5.0 Information, Copyright 1977 by Michael Huck]. In spite of these aspirations, no program can be all things to all people, and so it is with Prose. It was intended that Prose be able to do most of the things that are needed to produce high quality computerized text. The design of Prose was influenced by several goals. First, it should be possible to produce high quality results, with a minimum number of directives. Prose should have about 90: of the abilities that you think are useful, and the 10: it doesn't have should be the ones that are so esoteric that they are non-essential. Some text formatters take the approach of providing a minimum set of built-in abilities, along with a "general and powerful" feature such as macros. The idea is that you can accomplish anything you want (no matter how much effort it will take) by defining appropriate macros. The problem with this approach is that the user is forced to learn a complicated feature in order to produce any but the most trivial results. Prose's philosophy is that the user should not be overwhelmed by a large number of complicated directives. That the syntax of the directives should be consistent. That the text should stand out, not the directives. Because of this desire for simplicity, Prose may or may not be the tool for a given application. The following two tables should aid in deciding whether or not to use Prose. - 1 - 1 Prose Instruction Manual 27 May 86 _____ +Prose ... a. Prose has a small number of commands, which provide a learnable set of basic formatting abilities. b. Prose can do underlining and discretionary hyphenation. c. Prose can remember and restore the text processing environment. d. Prose can produce mixed-case or upper-case-only output from either mixed-case or upper-case-only input. e. Prose can accumulate and produce a sorted index, refer- ring to page numbers. f. Prose can print selected pages on request. g. Prose can format text in pages with headers, footers, and other frills. h. Prose can fill and justify text to specified margins. i. Prose is an extremely portable program, written in standard Pascal, and it uses ASCII as its internal character code. It is written to encourage transporta- tion between computers with different hardware and dif- ferent operating systems. ___ ____ +... and Cons a. Prose cannot control photo-typesetting machines. b. Prose cannot do graphics. c. Prose does not have multi-column ability. d. Prose does not have macros, variables, or other program- ming language-like features. e. Prose does not have the ability to store text and retrieve it later, with the exception of the special purpose indexing ability. f. Prose does not have tabs. g. Prose does not have directives to do everything you always wanted to. - 2 - 1 Prose Instruction Manual 27 May 86 _____ _____ __ ____ +Basic Units of Text Some of the basic units of natural language are the word, the phrase, the sentence, and the paragraph. In text formatting, the ____ +word, the line, and the paragraph are the basic units. A word is defined as any non-blank string of characters, with a blank on either side. Thus, for the purposes of formatting, a punctuation character is part of the word it is next to. By default, Prose reformats its _____ +input by filling words into lines, adding blanks to justify the lines to left and right margins, and printing lines together to make __________ +paragraphs. In filling lines, Prose does not pay attention to the original positions of the words, but instead fills as many words as possible into the output lines, preserving the original order. The following example illustrates this process of filling and justifying. Input to Prose: "When we were little," the Mock Turtle went on at last, more calmly, though still sobbing a little now and then, "we went to school in the sea. The master was an old Turtle--we used to call him Tortoise--" "Why did you call him Tortoise, if he wasn't one?" Alice asked. "We called him Tortoise because he taught us," said the Mock Turtle angrily. "Really you are very dull!" "You ought to be ashamed of yourself for asking such a simple question," added the Gryphon; and then they both sat silent and looked at Alice, who felt ready to sink into the earth. Output from Prose: "When we were little," the Mock Turtle went on at last, more calmly, though still sobbing a little now and then, "we went to school in the sea. The master was an old Turtle--we used to call him Tortoise--" "Why did you call him Tortoise, if he wasn't one?" Alice asked. "We called him Tortoise because he taught us," said the Mock Turtle angrily. "Really you are very dull!" "You ought to be ashamed of yourself for asking such a simple question," added the Gryphon; and then they both sat silent and looked at Alice, who felt ready to sink into the earth. _______ ___ __________ + Most of text formatting is filling and justifying. In the __________ +absence of special instructions to Prose (called directives), it will fill all of the input words into output lines, and justify all of those lines. - 3 - 1 Prose Instruction Manual 27 May 86 The distinction between one paragraph and the next is defined by _____________ _____ +a justification break, which causes Prose to stop filling the current _____ +output line, and print it without justifying. Since the break is one of the most frequently used instructions (as well as one of the simplest), it can be indicated in many ways. Paragraphs can be separated (broken) by one or more blank lines, by leading blanks typed ______ +on an input line (a paragraph indentation), or by the Prose ".BREAK" directive. The following example demonstrates these three methods. Input to Prose At last the Gryphon said to the Mock Turtle "Drive on, old fellow! Don't be all day about it!" and he went on in these words:-- "Yes, we went to school in the sea, though you mayn't believe it--" .BREAK "I never said I didn't!" interrupted Alice. .BREAK "You did," said the Mock Turtle. "Hold your tongue!" added the Gryphon, before Alice could speak again. Output from Prose: At last the Gryphon said to the Mock Turtle "Drive on, old fellow! Don't be all day about it!" and he went on in these words:-- "Yes, we went to school in the sea, though you mayn't believe it--" "I never said I didn't!" interrupted Alice. "You did," said the Mock Turtle. "Hold your tongue!" added the Gryphon, before Alice could speak again. When you use one of these methods to create a paragraph, Prose only does a justification break. That is, Prose will not skip lines or indent unless blank lines or indentations explicitly appear on the input file. There is a way to do fancier things by using the ".PARAGRAPH" directive, but that will be introduced later. - 4 - 1 Prose Instruction Manual 27 May 86 _ _______ ____ __ __________ +A General Look at Directives In its default mode, Prose automatically fills and justifies output lines, and formats the output in pages. Directives are needed to instruct Prose to do anything more fancy. There are directives to change the margins, to control options, and to define the type of output device you intend to use. A line of directives is indicated by typing the directive escape character in the first column of an input line. The period was chosen as the default directive escape character (although you can change it if you wish) because it seems very unlikely that anyone would want to type a period in the first column of a line of text. The entire line is scanned for directives. Several directives can be typed on the same line, provided that they are separated by the directive escape character. For example: .BREAK.SKIP 2.MARGIN( L5 R65 ) Some directives, however, take the remainder of the line as their parameter, and so no other directives can follow these. Long directives may extend to several lines. Continuation lines are indicated by a plus sign ( + ) typed in column one. The continuation may be made anywhere that a blank is allowed. For example: .FORM( [ /// L58 // #73 'PAGE' P /// ] + [ /// L58 // 'PAGE' P /// ] ) Although the examples in this writeup will usually show directives typed entirely in upper case, upper and lower case letters may be intermixed. Every directive begins with the name of the command, for instance "MARGIN". The name can always be abbreviated to three letters, and in fact, only the first three letters are examined by Prose. The name may be followed by a parameter, but in the absence of a parameter, default values are used. There are four forms for the parameter: 1) The absence of any parameter. 2) A single numeric value. 3) The remainder of the directive line. 4) A specification enclosed in parentheses, which consists of descriptors defined by the directive itself. - 5 - 1 Prose Instruction Manual 27 May 86 When a numeric value is required (for a parameter or as part of a descriptor), an explicit positive integer may be given. In many directives, a relative value may be used. This is indicated by a plus or minus sign before the integer, and indicates that the old value should be incremented or decremented by a certain amount. In the following example, the left margin is set to 10 and the right margin to 70. Then, the margins are squeezed together by 5 characters on both sides. .MARGIN( L10 R70 ) .MARGIN( L+5 R-5 ) ___________ ___ __________ ___________ +Controlling the Formatting Environment The formatting environment is defined to be all the options and specifications that direct Prose as it produces formatted output from unformatted input. The concepts that make up the formatting environ- ment can be loosely grouped into six areas, and there are directives to control each one: 1) INPUT controls the meaning and treatment of characters on the input file. 2) OUTPUT describes the type of output device for which the formatted result is intended. 3) FORM specifies the format of the page into which the running text will be inserted. This includes where to print titles, footers, and the like. 4) MARGIN sets the left and right margins. 5) PARAGRAPH describes special actions for the beginning of each paragraph. 6) OPTION controls the rest of the miscellaneous options that affect the text formatting process. Of these six groups, the INPUT, MARGIN, OPTION, and PARAGRAPH settings are likely to be changed often throughout the text. There will probably be a small number of different settings, and it will be convenient to be able to resume old settings. To accomodate these needs, a simple device is available for these four directives. When setting the options controlled by these directives, the following syntax is used: .directivename( parameters ) where the parameters consist of a key letter followed by option settings. For instance: .MARGIN( L5 R60 ) sets the left margin to 5 and the right to 60. Each time one of these ____ +four directives is processed, Prose saves the new values in a keep - 6 - 1 Prose Instruction Manual 27 May 86 ______ +buffer. There are ten keep buffers (numbered 0 through 9) associated with each of these directives. A keep parameter may be used to specify which buffer to use, but if not specified, the values are saved in the numerically next buffer. Old values may be recalled by using the following form: .directivename number For example: .MARGIN 5 sets the margins to the values that were stored in keep buffer 5. If no parameter is specified, the values are set to those that were stored in the numerically previous keep buffer. Since the keep number is automatically incremented when the parenthesis form is used and automatically decremented when no parameter is given, the keep buffers can be used as a stack. .MARGIN( L0 R70 ) ... .MARGIN( L10 R60 ) ... .MARGIN In the previous example, the last MARGIN directive resets the margins to their previous values: left 0 and right 70. - 7 - 1 Prose Instruction Manual 27 May 86 _____ _________ _____ +Short Directive Table _________ ________________ _____ ______________ +Directive Meaning (action) Break Parameter type BREAK break justification * -none- CHANGE control change bars ( ... ) or numeric | COMMENT no action remainder of line COUNT set page count numeric FORM define page format * ( ... ) INDENT indent following line * numeric INPUT set input parameters * ( ... ) or numeric INX store index entry remainder of line LITERAL print literal text remainder of line MARGIN set margins * ( ... ) or numeric OPTION set options * ( ... ) or numeric OUTPUT set output parameters ( ... ) PAGE eject to top of page * numeric PARAGRAPH set paragraphing params ( ... ) or numeric RESET reset directive defaults * ( ... ) SELECT select pages to print * ( ... ) SKIP skip output lines * numeric SORTINDEX sort and print index * ( ... ) SUBTITLE set the subtitle remainder of line TITLE set the main title remainder of line UNDENT undent following line * numeric WEOS write end of section * -none- The directives marked with an asterisk ( * ) cause a justifica- tion break before they are processed, since they affect the filling and justifying environment. ( ... ) indicates that the parameter is enclosed in parentheses and is described in detail along with the description of the directive itself. - 8 - 1 Prose Instruction Manual 27 May 86 _____ +BREAK Causes a justification break. ______ +CHANGE ( parameters ) | ______ +CHANGE number | ______ +CHANGE | | Defines the "change character". The current change character is | printed in the "change-character position" (see the OUTPUT directive) | of each non-blank line. By setting the change character to a vertical | bar ("|"), change bars are produced. Resetting the change character | to nul suppresses the change bar. | | __________ _______ ____ _______ ________ +key letter meaning type default relative | C change character character nul | K keep number next no | | If a specification is not given, its value is not changed. The | default value is the one that will be set if the key letter is given | by itself, and is also the value that is assigned when Prose begins | processing. | | | ______ _________ +C: The change character is the character to be printed in the in the | change-character position (normally past the right margin). | | | ____ +K: The keep parameter explicitly specifies which keep buffer should be | used to store the new paragraph options. The default is to use the | numerically next buffer. | _______ +COMMENT Prose treats the remainder of the directive line as a comment, i.e. it is ignored. The COMMENT directive allows you to include in the source of your document information that will not be printed on the formatted copy. - 9 - 1 Prose Instruction Manual 27 May 86 _____ +COUNT number _____ +COUNT Sets the page counter. The numeric parameter can be relative. For example, ".COUNT +1" increments the page number by one. In the absence of a parameter the default is to set the page number to one. ____ +FORM ( parameters ) ____ +FORM Defines the page format, including titles, footers, date/time, and the top and bottom of the page. The argument consists of parameters, followed by (if appropriate) an optional field width. For example "T:30" prints the title in a field of 30 characters. Text lines are built by the FORM directive from left to right, starting in the first printable column, although the tabbing specification may be used to alter that. The following table describes the FORM specifi- cations that are available. ________ _______ ___________________ +key char meaning default field width C 24 hour clock as hh.mm.ss (15.37.58) 8 D raw date as yy/mm/dd (78/02/13) 8 E nice date as dd Mmm yy (13 Feb 78) 9 Ln fill in n lines of running text Pf current page number, f selects the form 3 N or n arabic numerals (default) [the field L upper case letter width will l lower case letter be expanded R upper case roman numerals if needed] r lower case roman numerals S subtitle its length T main title its length W wall clock as hh:mm AM ( 3:37 PM) 8 or hh:mm PM #n tab forward or backward to absolute column n "..." print literal text '...' print literal text / print an end of line /n print -n- ends of lines [ define top of page ] define bottom of page default form: .FORM( [ // T #62 E /// L56 // #33 '- ' PN:1 ' -' /// ] ) The FORM directive is processed interpretively. This means that the format is re-scanned as each page of output is produced, so changing one of the title buffers with the TITLE or SUBTITLE directives will change the title or subtitle on the next page. - 10 - 1 Prose Instruction Manual 27 May 86 The top of page definition is used for several things. By using the OUTPUT directive, you can request Prose to send a page eject to the output device when it reaches the top of a page. You can also request Prose to pause at the top of each page to allow you to change paper. At the end of the document, Prose does one last page eject, interpreting the FORM specification until it reaches the top of page. The bottom of page specification is where Prose increments the page number, so if you print the page number both before and after the bottom of page definition, you will get two different numbers. It is easy (once you understand the FORM directive) to produce fancy page formats. For example, you can design a FORM that will print the page number at the right of odd numbered pages, and at the left of even pages. This is done with a FORM that defines two pages with two "["s and two "]"s: .FORM( [ // T #62 E /// L56 // #63 'PAGE' P /// ] + [ // T #62 E /// L56 // 'PAGE' P /// ] ) In the absence of a parameter, no special page formatting is done. This is similar to a FORM consisting of a single L specifi- cation defining an infinite number of lines per page. In this mode, the PAGE directive acts as though there are 5 lines left on the page. ______ +INDENT number ______ +INDENT Indents the following line by a certain number of spaces. In the absence of a parameter, the default is 5. - 11 - 1 Prose Instruction Manual 27 May 86 _____ +INPUT ( parameters ) _____ +INPUT number _____ +INPUT The INPUT directive is used to define the input environment, that is, the interpretation of characters on the input file. The param- eters can be given in any order, and consist of a key letter followed by a value. The following table summarizes the parameters. __________ _______ ____ _______ ________ +key letter meaning type default relative B explicit blank character character nul C case shift character character nul D directive escape character character . H hyphenation character character nul K keep number next no U underline character character nul W input width number 150 no If a specification is not given, its value is not changed. The default value is the one that will be set if the key letter is given by itself, and is also the value that is assigned when Prose begins processing. ________ _____ _________ +B: The explicit blank character indicates a blank that Prose should not tamper with. Thus, if the cross hatch ( # ) is specified as the explicit blank: .INPUT( B# ) then two words that are separated by an explicit blank: Mr.#Smith will never be split from one line to the next, and Prose will never fill blanks in between the words to justify a line. ____ _____ _________ +C: The case shift character must be used to create mixed-case output from upper-case-only input. When a case shift character is specified, Prose automatically shifts all upper case letters to lower case. To specify an upper case letter, one of two methods may be used. The first method is to surround letters with the case shift characters, causing a shift-up and shift-down. Since most upper case letters are at the beginning of a word (following a blank), the second method, called stuttering, is to double the first character of the word. The following example demonstrates the production of mixed-case output from upper-case-only input. - 12 - 1 Prose Instruction Manual 27 May 86 Input to Prose: .INPUT( C^ ) TTHE MMOCK TTURTLE WENT ON. "^W^E HAD THE BEST OF EDUCATIONS--IN FACT, WE WENT TO SCHOOL EVERY DAY--" ^"I'VE^ BEEN TO A DAY-SCHOOL, TOO," SAID AALICE. "^Y^OU NEEDN'T BE SO PROUD AS ALL THAT." "^W^ITH EXTRAS?" ASKED THE MMOCK TTURTLE, A LITTLE ANXIOUSLY. "^Y^ES," SAID AALICE: "WE LEARNED FFRENCH AND MUSIC." "^A^ND WASHING?" SAID THE MMOCK TTURTLE. "^C^ERTAINLY NOT" SAID AALICE, INDIGNANTLY. "^A^H TTHEN YOURS WASN'T A REALLY GOOD SCHOOL," SAID THE MMOCK TTURTLE IN A TONE OF GREAT RELIEF. "^N^OW, AT ^OURS^, THEY HAD, AT THE END OF THE BILL, '^F^RENCH, MUSIC, ^AND WASHING--^ EXTRA.'" Output from Prose: The Mock Turtle went on. "We had the best of educations--in fact, we went to school every day--" "I'VE been to a day-school, too," said Alice. "You needn't be so proud as all that." "With extras?" asked the Mock Turtle, a little anxiously. "Yes," said Alice: "we learned French and music." "And washing?" said the Mock Turtle. "Certainly not" said Alice, indignantly. "Ah Then yours wasn't a really good school," said the Mock Turtle in a tone of great relief. "Now, at OURS, they had, at the end of the bill, 'French, music, AND WASHING-- extra.'" At first glance, the stuttering method may seem clumsy, but experience shows that it is reasonably easy to get used to. To enter words that already have a double letter at the beginning (like llama and oops), merely precede the word with two case shift characters, causing a shift-up/shift-down (^^LLAMA and ^^OOPS). Keep in mind that the case shift character does not need to be used unless you want to create mixed-case output from upper-case-only input. It is recommended that if possible, you use mixed-case input to create mixed-case output. _________ ______ _________ +D: The directive escape character is the character you type in the first column of an input line to flag it as a directive line. ___________ _________ +H: The hyphenation character is used to define hyphenation points within words. Sometimes a long word will cause many blanks to be inserted to justify the preceding line. Prose will hyphenate such - 13 - 1 Prose Instruction Manual 27 May 86 a word if you have defined the syllable boundries within that word. Of course, not all the syllable boundries need be specified, only those where you want Prose to be able to split a word. For example, if the hyphenation character is set to the slash ( / ), you might type "syncopation" as "syn/co/pa/tion". Prose will insert a hyphen ( - ) only when the characters on both sides of the hyphenation point are letters. You might type "hyper-active" as "hyper-/active", and Prose will split the word, if necessary, without adding a superfluous hyphen. If Prose is forced to insert more blanks than a certain threshold (set with the OPTION direc- tive), it will issue a message suggesting that you insert hyphen- ation characters. ____ +K: The keep parameter explicitly specifies which keep buffer should be used to store the new input options. The default is to use the numerically next buffer. _________ _________ +U: Text surrounded by the underline character will be underlined. Blanks are not underlined, but explicit blanks are. _____ _____ +W: The input width is used to specify how many characters will be read from each input line. If your input lines have sequencing information at the right of each line, you will need to set the width to an appropriate value. ___ +INX text Enters the remainder of the line together with the current page number as an index entry. This means that as the formatted text migrates from page to page, the resulting index will always be correct. _______ +LITERAL text Prints the remainder of the line on the output file. The special processing for upper/lower case, underlining, and literal blanks is performed on the text of the parameter, and then it is printed as a single output line. This output line is printed independently of filling and justifying and page formatting processes; it is trans- parent to the usual Prose formatting and is not counted as an output line. The LITERAL directive is useful for producing special printer control characters. For example, .LITERAL T - 14 - 1 Prose Instruction Manual 27 May 86 sets a print density of 8 lines per inch on some CDC line printers. ______ +MARGIN ( parameters ) ______ +MARGIN number ______ +MARGIN The margin directive is used to set the left and right margins ____ ______ +for filling and justifying. The left margin is the number of leading _____ ______ +spaces before the first printed character, and the right margin is the column number of the last printed character. Thus subtracting the left margin from the right margin gives the number of printed columns. The parameters may be given in any order, and consist of a key letter followed by a value. The following table lists the parameters. __________ _______ ____ _______ ________________ +key letter meaning type default relative allowed K keep number next no L left margin number 0 yes R right margin number 70 yes If a specification is not given, its value is not changed. The default value is the one that will be set if the key letter is given by itself, and is also the value that is assigned when Prose begins processing. ____ + The keep parameter explicitly specifies which keep buffer should be used to store the new margins. The default is to use the numerically next buffer. - 15 - 1 Prose Instruction Manual 27 May 86 ______ +OPTION ( parameters ) ______ +OPTION number ______ +OPTION All the miscellaneous options that affect the text formatting process are gathered together in the OPTION directive. These options are summarized in the following table. For switch options, "+" is on and "-" is off. __________ _______ ____ _______ ________________ +key letter meaning type default relative allowed E print error messages switch + F fill output lines switch + J justification limit numeric 3 no K keep numeric next no L left justify switch + M multiple blanks switch + P 2 blanks after periods switch + R right justify switch + S spacing numeric 1 no U shift to upper case switch - If a specification is not given, its value is not changed. The default value is the one that will be set if the key letter is given by itself, and is also the value that is assigned when Prose begins processing. E: Error messages are printed on the main output file, interspersed in the formatted text. These may be entirely suppressed by setting the E option to "E-". F: Output lines are automatically filled and justified as described in ____ ______ + the section "Basic Units of Text". If the fill switch is turned off, Prose will print the input lines as they are, without reformatting to fill up the output lines. In effect, a justifica- tion break is done after each input line. J: In justifying the left and right margins of an output line, Prose has to insert blanks that are not explicitly on the input file. _____________ _____ + The justification limit controls the point at which Prose will attempt to hyphenate a word. If, for instance, the justification limit is three, then the hyphenation process will be invoked when Prose inserts enough blanks to bring the number between any adjacent words to three. If hyphenation is not possible, or Prose is not able to bring the number of inserted blanks below the limit, an error message is printed. ____ +K: The keep parameter explicitly specifies which keep buffer should be used to store the new options. The default is to use the numerically next buffer. - 16 - 1 Prose Instruction Manual 27 May 86 L: ____ ___ _____ _______ ________ +R: The left and right justify switches work together to determine what kind of justification is done. If both switches are on, output lines are justified to both the left and right margins. If both switches are off, lines are centered between the two margins. If one is on and one is off, the result is one straight margin (either left or right) and one ragged margin. The following demonstrates these four options. .OPTION( L+ R+ ) : "You couldn't have wanted it much," said Alice; "living at the bottom of the sea." "I couldn't afford to learn it," said the Mock Turtle with a sigh. "I only took the regular course." "What was that?" inquired Alice. "Reeling and Writhing, of course, to begin with," the Mock Turtle replied; "and then the different branches of Arithmetic--Ambition, Distraction, Uglification, and Derision." "I never heard of 'Uglification,'" Alice ventured to say. "What is it?" The Gryphon lifted up both its paws in surprise. "Never heard of uglifying!" it exclaimed. "You know what to beautify is, I suppose?" .OPTION( L- R- ) : "Yes," said Alice doubtfully: "it means--to--make--anything--prettier." "Well, then," the Gryphon went on, "if you don't know ___ + what to uglify is, you are a simpleton." Alice did not feel encouraged to ask any more questions about it: so she turned to the Mock Turtle, and said "What else had you to learn?" "Well, there was Mystery," the Mock Turtle replied, counting off the subjects on his flappers--"Mystery, ancient and modern, with Seaography: then Drawling--the Drawling-master was an old conger-eel, that used to come __ + once a week: he taught us Drawling, Stretching, and Fainting in Coils." - 17 - 1 Prose Instruction Manual 27 May 86 .OPTION( L+ R- ) : ____ + "What was that like?" said Alice. "Well, I ca'n't show it you, myself," the Mock Turtle said "I'm too stiff. And the Gryphon never learnt it." "Hadn't time," said the Gryphon: "I went to the Classical __ + master, though. He was an old crab, he was." "I never went to him," the Mock Turtle said with a sigh. "He taught Laughing and Grief, they used to say." "So he did, so he did," said the Gryphon, sighing in turn; and both creatures hid their faces in their paws. "And how many hours a day did you do lessons?" said Alice, in a hurry to change the subject. .OPTION( L- R+ ) "Ten hours the first day," said the Mock Turtle: "nine the next, and so on." "What a curious plan!" exclaimed Alice. "That's the reason they're called lessons," the Gryphon remarked: "because they lessen from day to day." This was quite a new idea to Alice, and she thought it over a little before she made her next remark. "Then the eleventh day must have been a holiday?" "Of course it was," said the Mock Turtle. "And how did you manage on the twelfth?" Alice went on eagerly. "That's enough about lessons," the Gryphon interrupted in a very decided tone. "Tell her something about the games now." ________ ______ ______ +M: If the multiple blanks switch is on, multiple blanks on the input file are considered to be significant. That is, if there are several blanks between two words on the input file, there will be at least that many on the output file, but Prose may add more blanks during the justification process. If the switch is off, multiple blanks will be changed into a single blank. _ ______ _____ _______ +P: If the 2 blanks after periods option is selected, then Prose will make sure that each period which is already followed by at least one blank will be followed by at least two blanks. Prose will not add blanks before justifying if there are already two. This makes - 18 - 1 Prose Instruction Manual 27 May 86 it easy to have sentences separated by two blanks without requiring you to be extremely careful about typing the original text. _______ +S: By setting the spacing option, you can easily produce single, double, or triple spaced output. Simply set the spacing option to 1, 2, or 3. U: Since some output devices are not able to handle mixed-case files, you can cause Prose to shift all lower case letters to upper case _____ __ _____ ____ + by selecting the shift to upper case option. This is of particular interest to CDC users for whom lower case letters are interpreted as two characters when sent to certain output devices. This option is also handy for printing large sections, such as sample programs, all in upper case. ______ +OUTPUT ( terminal-type parameters ) The OUTPUT directive defines important aspects of the output device that is the destination of the formatted text. The OUTPUT directive may be used only once, and must appear before any lines are printed on the output device or immediately following the directive ".RESET( OUTPUT )". _____________ +Terminal-type may be one of the following; the default is ASC: ASC ASCII terminal, using carriage return for overprinting and form feed for page eject. A teletype is called an ASC terminal although the form feed will not cause a page eject. This is not a problem if the eject option (see below) is not selected. LPT Line printer, using "+" for overprinting and "1" for page eject. Carriage control is supplied automatically by Prose, and so like any other terminal, column 1 is the first printing column. AJ Anderson/Jacobson terminal, using 1/60th of inch incre- ments for justification. ASC may be specified for an AJ terminal, but the result will not have as high quality. If AJ is selected, however, the output will be printed more slowly. For this reason, it is recommended that ASC be used for drafts, and AJ only for the final version. The AJ may be followed by a number specifying the desired pitch (in characters per inch), e.g. "AJ 10". - 19 - 1 Prose Instruction Manual 27 May 86 The parameters define further characteristics of the output device, and several global output options. The parameters may be given in any order, and are selected from the following table. __________ _______ ____ _______ +key letter meaning type default C change-character position number 72 | E page eject at top of page switch - ( "[" in FORM description) P pause at top of page switch - S shift output lines to the right numeric 0 U underlining is available switch + ________________ ________ +C: The change-character position specifies the output column in which | the current change bar character is printed (see the CHANGE | directive). If the right margin is changed (with the MARGIN | directive), then the change-character position should be modified | accordingly. | ____ _____ +E: If the page eject option is selected, a form feed or "1" will be printed every time the "[" is encountered in the FORM specifica- tion. _____ +P: If the pause option is selected, every time the "[" is encountered in the FORM specification, Prose will stop printing and wait for some operator acknowledgement. On an ASC or AJ terminal, Prose will sound the bell, and wait for a carriage return to be entered. For an LPT terminal, the processing is dependent on the operating system. This option is handy for using an AJ terminal with non-fan-fold paper, allowing you to roll paper in for each page. For the CDC version, any single character (not just carriage return) will cause Prose to resume printing on an ASC or AJ terminal. For a CDC LPT terminal, Prose will print a PM message containing the Prose control statement. _______ __ ___ _____ +S: All output that Prose produces can be shifted to the right by any number of spaces up to 50. This makes it easy to center the output on a wide printer page. U: If the destination terminal does not have underlining ability and ___________ _________ + your input does underlining, the underlining available option should be turned off to prevent Prose from trying to generate overprinted underlines. - 20 - 1 Prose Instruction Manual 27 May 86 ____ +PAGE number ____ +PAGE Causes a page eject if there are fewer than the specified number of lines remaining on the current page. If no parameter is given, PAGE does an unconditional page eject. _________ +PARAGRAPH ( parameters ) _________ +PARAGRAPH number _________ +PARAGRAPH Paragraphs can be indicated by any of the methods introduced in the section "Basic Units of Text". The PARAGRAPH directive provides a more versatile method of creating paragraphs. The PARAGRAPH directive specifies what is done when a new paragraph is signalled by typing a special character (called the paragraph flag character) in the first column of an input line. An automatic indent or undent can be selected, an automatic skip and/or automatic page eject can be specified, and you can even have Prose automatically number the paragraphs. __________ _______ ____ _______ ________ +key letter meaning type default relative F paragraph character character nul I automatic indent number 0 no K keep number next no N number generator none P automatic page eject number 0 no S automatic skip number 0 no U automatic undent number 0 no If a specification is not given, its value is not changed. The default value is the one that will be set if the key letter is given by itself, and is also the value that is assigned when Prose begins processing. _________ ____ _________ +F: The paragraph flag character is used to invoke this collection of paragraphing actions by typing it in the first column of an input line. Note that this character should be set in at least one PARAGRAPH directive, or none of these actions will work. I: _________ ______ _________ ______ +U: The automatic indent or automatic undent is applied to the first ______ ______ + line of the paragraph (see the description of INDENT and UNDENT). If the number generator is used, the indent or undent is applied after the number is generated. - 21 - 1 Prose Instruction Manual 27 May 86 ______ _________ +N: If the number generator is specified, a new number (or letter) will be generated for each occurrance of the paragraph flag character. The number generator is initialized to 1 each time new PARAGRAPH settings go into effect, but resuming an old setting will also resume the old numbering. The number replaces the paragraph flag character when the line is formatted. The number generator parameter has the form: Nfn . f selects the numeric form: -blank- no numbering N or n arabic numerals L upper case letter l lower case letter R upper case roman r lower case roman n is the field width, which will be expanded if needed. _________ ____ _____ +P: The automatic page eject is used to simulate the effect of the directive .PAGE number before the first line of the paragraph. If this parameter is set to 4, for instance, it will ensure that at least four lines are left on the page. If there are fewer lines than specified, a page eject is done. This is applied after the automatic skip. _________ ____ +S: The automatic skip is done before the first line of the paragraph, and functions the same as a SKIP directive. ____ +K: The keep parameter explicitly specifies which keep buffer should be used to store the new paragraph options. The default is to use the numerically next buffer. _____ +RESET _____ +RESET ( parameters ) _____ +RESET ( EXCEPT parameters ) The RESET directive is used to set directives to their default values. If you have changed the values of many directives (such as FORM, MARGIN, or OPTION), the simple command .RESET resets the values of all directives to their defaults. Directives may be reset selectively by using the second form of the command. For example, - 22 - 1 Prose Instruction Manual 27 May 86 .RESET( MARGIN OPTION ) only resets the MARGIN and OPTION directives. Directives may also be excluded selectively. For example, .RESET( EXCEPT FORM OUTPUT ) resets all directives with the exception of FORM and OUTPUT. Parameters for RESET are selected from the following list of directive names. COUNT FORM INPUT INX MARGIN OPTION OUTPUT PAGE PARAGRAPH SELECT SUBTITLE TITLE The values of parameters for most directives are set to their defaults (which are listed with the description of each directive) with the ____ +exception of the keep parameters which are set to "K0". For the COUNT, INX, and PAGE directives, however, the action is different. Resetting COUNT sets the page counter to 1, resetting INX deletes all index entries that have been accumulated, and resetting PAGE causes a page eject. In addition, since resetting FORM or OUTPUT directly affects the printed result, resetting either of these directives also causes a page eject. ______ +SELECT ( parameters ) As documentation is revised, not every page changes. The SELECT directive may be used to print only certain pages. The entire text will be formatted, but only selected pages will be printed. Thus the central processor time used will not be reduced very much, but printing time will be. The descriptor consists simply of page numbers separated by spaces. To select a span of pages, two numbers are typed together, separated by a colon ( : ). The second page number may be specified relative to the first. The following example selects pages 3, 5, 10 through 15, and 20 through 25 to be printed. .SELECT( 3 5 10:15 20:+5 ) The default is to select all pages to be printed. ____ +SKIP number ____ +SKIP Skips a certain number of output lines, i.e. prints blank lines. SKIP will never print blank lines at the top of a page, so to skip - 23 - 1 Prose Instruction Manual 27 May 86 lines at the top of a page, at least one actual blank line must precede the SKIP directive. In the absence of a parameter, 5 lines are skipped. _________ +SORTINDEX ( parameters ) _________ +SORTINDEX The index entries that are accumulated by INX directives can be sorted either alphabetically or by page number, and then printed in a fairly flexible manner. The SORTINDEX directive allows you to specify what column is to be considered the first significant column for alphabetical sorting, how many leading blanks to print at the left of each index line, where to insert the page number in each line, and how to format the page number. The parameters may be given in any order, and are selected from the following. __________ _______ _______ +key letter default meaning L 2 left width of page number (field width for number) M 0 margin (left margin before index line) P 0 column (in index entry) to insert page number R 2 right width of page number (blanks printed after) S 1 sorting option. if this is numeric, it is the first significant column for alphabetical sorting. if it is the letter "P", it selects sorting by page number. In the absence of parameters, the defaults are used. ________ +SUBTITLE text Enters the remainder of the directive line into the subtitle buffer. The subtitle buffer is used by the FORM directive. _____ +TITLE text Enters the remainder of the directive line into the main title buffer. The title buffer is used by the FORM directive. - 24 - 1 Prose Instruction Manual 27 May 86 ______ +UNDENT number ______ +UNDENT Undents the following line a certain number of spaces. The undent is sometimes known by the name "outdent" or "hanging indent". A line can never be undented past the leftmost column of the printer page, and so a large number is adjusted to a smaller value. In the absence of a parameter, the default is to undent to the leftmost printable column. ____ +WEOS Write an end-of-section on the output file. This directive is useful for creating multiple section writeups under systems with utilities that manipulate multiple section files. In the CDC version of Prose, WEOS writes a CDC end-of-record mark. Specifically, this directive is used to create indexed writeups at the University of Minnesota. - 25 - 1 Prose Instruction Manual 27 May 86 ___ ______ ___ ___ +CDC KRONOS and NOS At the University of Minnesota, Prose is available through the PROSE control statement, which has three order-dependant file parame- ters. The prototype call (which includes the default file names) is: PROSE(INFILE,OUTPUT,INPUT) INFILE - file containing text in Prose form. OUTPUT - file to receive the formatted result. INPUT - file used for the pause option of the OUTPUT directive. The following control statement will format a file named DOC and write the result to OUTPUT: PROSE(DOC) and to format the same file but write the result to LIST: PROSE(DOC,LIST) This version of Prose is compatible with the CDC full-ASCII character set under KRONOS and NOS. This means that if you are using Prose from an interactive terminal, you should have terminal type TTY (the default) and either use the full-ASCII character set by typing the ASCII command or follow the guidelines for batch use. If you are using Prose from batch entry, you are able to use only a subset of the full-ASCII character set. This is equivalent to terminal type TTY in NORMAL mode at an interactive terminal. Both in NORMAL TTY mode and from batch, you should avoid using the 'commercial at' (@) and 'caret' (^) characters since their representations differ between the ASCII and NORMAL character sets. Prose will interpret these two characters as the ASCII mode escape codes. This Prose writeup is available at the University of Minnesota through the WRITEUP control statement. Since this writeup was prepared in full ASCII, we recommend that you list it on a printer that has the entire ASCII character set. Furthermore, the Prose writeup was designed to be listed on a line-printer with underlining available, and so the paging and underlining will be incorrect if it is listed on an interactive terminal. The following examples demon- strate how to list the writeup. For a listing on a high-speed line-printer: WRITEUP(PROSE/L=LIST,PT=AS) ROUTE(LIST,DC=LP,EC=A9,BIN=*sc) where 'sc' is the site code of your high-speed terminal if you are not at Lauderdale (for example, BIN=*EA for Experimental Engineering). - 26 - 1 Prose Instruction Manual 27 May 86 From an interactive terminal (such as a Decwriter): WRITEUP(PROSE) If you wish, you may make a listing of the Prose writeup on a line-printer that has only upper case by using the following WRITEUP statement: WRITEUP(PROSE) The upper-case result, however, will obscure some important distinc- - 27 -