back2roots/padua

home *** CD-ROM | disk | FTP | other *** search

/ back2roots/padua / padua.7z / padua / misc / nroff.lzh / NRO / MAN < prev next >

Wrap

Text File | 1989-03-28 | 36.2 KB | 727 lines

NRO(1) AM*GA Programmer's Manual NRO(1) ¢1mNAME ¢0mnro - text formatter ¢1mSYNOPSIS nroáá¢0m[-¢1mn¢0m] [+¢1mn¢0m] [-¢1mpxx¢0m] [-¢1mv¢0m] [-¢1mbx¢0m] [-¢1mrnx¢0m] [-¢1mrdx¢0m] [-¢1mrpx¢0m] [-¢1mmmfile¢0m] ¢1mifile ¢0m... [>¢1mofile¢0m] ¢1mDESCRIPTION ¢0m¢4mNRO¢0m is a text processor and formatter based on the design provided in "¢1mSoftware Tools¢0m" by Kernighan and Plauger. The text and commands found in the ¢4mifile(s)¢0m are processed to generate formatted text. The output may be directed into a file or to the printer, otherwise, the output will appear at the user console. The +¢4mn¢0m option causes the output to start with page ¢4mn¢0m. The -¢4mn¢0m option causes the output to stop after page ¢4mn¢0m. The -¢4mv¢0m option prints the version number to the console. Specifying a higher numerical argument makes ¢1mNRO ¢0mmore and more verbose. The -¢4mp¢0m option causes the output to be shifted to the right by ¢4mxx¢0m spaces. This has the same effect as the .¢1mpo ¢0mcommand. The -¢4mb¢0m option with argument ¢4mx¢0m controls if backspaces appear in the output text when underlining or overstriking. This has the same effect as the .¢1mbs ¢0mcommand with the same argument. The -¢4mr¢0m options allow you to specify how much memory is allocated for macro definitions and related things. The -¢4mrn¢0m option lets you specify how many macros you may define while your text is being formatted. Default is 512. The -¢4mrd¢0m option lets you specify how much memory is reserved for keeping the contents of your macro definitions. Default is 20480 characters. The -¢4mrp¢0m option lets you specify how much characters may be pushed back into the input, when processing a macro evaluation. Default is 1024 characters. If any of these options is present they must be located before the first file to be processed to have any effect. The -¢4mm¢0m option processes the file ¢4mmfile¢0m for macro definitions. Note that files processed in this way should contain only macro definitions, no immediate output should be generated from this file. Commands typically are distinguished by a period in column one of the input followed by a two character abbreviation for the command funtion. The abbreviation may then be followed by an optional numeric or character argument. The numeric argument may be an absolute value such as setting the right margin to a particular column, or the argument may be preceded by an operator to indicate that the parameter should be modified relative to a previous setting. You may use the operators +, -, /, *, % (mod), | KosmoSoft -1- Version 1.5 NRO(1) AM*GA Programmer's Manual NRO(1) (bitwise or), & (bitwise and), = (equal), < (less than) and > (greater than) to calculate values. ¢4mNo¢0m normal operator precedence is taken into account; the expression is evaluated strictly from left to right. You may use parentheses to group sub-expressions together. Note that all operators are dyadic, even the -. To generate a negative value, use a form like 0-5. A leading operator in an expression is not used in the evaluation. Instead, it has the effect of altering a previously set value. The + operator increases the set value with the given value, the - operator decreases the set value with the given value, the * operator multiplies the set value with the given value, and the / operator divides the set value by the given value. A leading operator within parentheses is ignored. Commands that have effect on a given number of input lines, can also take a text argument, if it is preceded by a double quote character `"'. This behaves exactly as if you gave the number 1, and followed the command with the given text argument. More text or commands may follow a command if they are seperated by a semicolon `;', unless the first command must be the last one on an input line. The following commands are recognized: .¢1mboá¢0mácauses the following lines of text to appear in boldface. The optional argument specifies the number of lines to be typed in boldface. An argument of zero explicitly turns boldface off, while a negative argument turns it on indefinitely. When overstrike is being used to produce the boldface, boldface and underlining are mutually exclusive features, and the appearance of a boldface command will cause any underlining to cease. .¢1mbpá¢0mácauses succeeding text to appear at the top of a new page. The optional argument specifies the page number for the new page. The initial value is one and the default value is one more than the previous page number. .¢1mbrá¢0mácauses succeeding text to start on a new line at the current left margin. There is no argument for this command. .¢1mbsá¢0máenables or disables the appearance of backspaces in the output text. A value of ¢4mzero¢0m doesn't use backspaces at all, but utilizes standard ISO printer codes. The Commodore Amiga console and printer devices support these directly, but on other systems you need a post-processor to convert these standard ISO codes into, for example, Epson printer codes. If you don't want this, underlining and boldface can be done by inserting character - backspace - character combinations into the output. This is fine for devices which properly recognize the backspace character. Many printers, however, do not recognize backspaces, so the KosmoSoft -2- Version 1.5 NRO(1) AM*GA Programmer's Manual NRO(1) option is provided to overprint one line buffer with another. The first line buffer is terminated with just a carriage return rather than the carriage return - linefeed combination. An argument of ¢4m2¢0m to the backspace command removes backspaces from the output. Even with printers which do recognize backspaces, this usually is faster. An argument of ¢4m1¢0m puts them into the output. The default is to use Commodore Amiga (ISO) control sequences. .¢1mccá¢0máchanges the ¢4mNRO¢0m command character to that specified by the character argument. If no argument is provided, the default is a period. .¢1mceá¢0mácauses the next line of text to appear centered on the output. This automatically generates a break. The optional argument specifies if more than one line is to be centered. An argument of zero explicitly turns centering off, while a negative argument turns it on indefinitely. .¢1mcuá¢0mácauses the next line(s) of text to be continuously underlined. Unlike the underline command (see .¢1mul¢0m) which underlines only alphanumerics, continuous underlining underlines all printable characters. The optional argument specifies the number of lines of text to underlined. An argument of zero explicitly turns continuous underline off, while a negative argument turns it on indefinitely. Any normal underlining command currently in effect will be terminated. .¢1mdeá¢0mácauses all text and commands following to be used to define a macro. The definition is terminated by a line with .¢1men ¢0mas the first three characters. The rest of that line is ignored. The first argument following the .¢1mde ¢0mcommand becomes the name of the new command. It should be noted that upper and lower case arguments are considered different. Thus, the commands .¢1mPP ¢0mand .¢1mpp ¢0mcould define two different macros. Care should be exercised since existing commands and macros may be redefined. A macro may contain up to ten arguments. In the macro definition, the placement of arguments is designated by the two character sequences, $0, $1, ... $9. When the macro is invoked, each argument of the macro command line is substituted for its corresponding designator in the expansion. The first argument of the macro command is substituted for the $0 in the expansion, the second argument for the $1, and so forth. Arguments are typically strings which do not contain blanks or tabs. If an argument is to contain blanks, then it should be surrounded by either single or double quotes. A macro name may be at most ten characters long. If more are supplied, the results are unpredictable. To get things like $4 in the macro text, use a double $$, i.e. $$4. KosmoSoft -3- Version 1.5 NRO(1) AM*GA Programmer's Manual NRO(1) .¢1mefá¢0máspecifies the text for the footer on even numbered pages. The format is the same as for the footer command (see .¢1mfo¢0m). .¢1mehá¢0máspecifies the text for the header on even numbered pages. The format is the same as for the footer command (see .¢1mfo¢0m). .¢1melá¢0máSee .¢1mif ¢0mand .¢1mie¢0m. The .¢1mel ¢0mcommand reverses the truth of the condition remembered by the last .¢1mie¢0m. command, and if the result is true, it accepts the input on the remainder of the line, just like the .¢1mif ¢0mcommand. Multi-line else-parts are thus also possible. You may have multiple .¢1mel ¢0mrequest following a single .¢1mie ¢0mcommand. Since every .¢1mel ¢0mreverses the remembered condition, you have if effect multiple 'then-' and 'else-parts', just divided into bits and pieces. .¢1mevá¢0máenvironment switch. If a numerical argument is given, the number of the current environment is pushed on a special environment number stack, and the named environment is made current. If no argument is supplied, the previous environment number that was in effect will be restored. As a variation of this, the command .¢1mev ¢0m- will restore the previous environment and ¢4mdiscard¢0m the current environment. This is useful if you don't need the particular environment anymore. At a new invocation of this environment it will have default values again. The environment is the set of values that determine the appearance of formatted output. There are ten environments available, and up to nineteen environment numbers can be pushed. Because a stack of previous environment numbers is maintained, always return to a previous environment by a .¢1mev ¢0mcommand without numeric argument. The following commands affect values that are in the environment: .¢1mls ¢0m.¢1mti ¢0m.¢1min ¢0m.¢1mrm ¢0m.¢1mce ¢0m.¢1mul ¢0m.¢1mcu ¢0m.¢1mit ¢0m.¢1mta ¢0m.¢1mju ¢0m.¢1mnj ¢0m.¢1mbo ¢0m.¢1mfi ¢0m.¢1mnf ¢0m.¢1mpn ¢0m.¢1mpc ¢0m.¢1mcc and ¢0m.¢1mc2¢0m. Also in the environment are the last remembered conditional, .¢1mie¢0m, and collected partial output lines. .¢1mená¢0mádesignates the end of a macro definition. .¢1mfiá¢0mácauses the input text to be rearranged or filled to obtain the maximum word count possible between the previously set left and right margins. No argument is expected. .¢1mfoá¢0máspecifies text to be used for a footer. The footer text contains three strings seperated by a delimiter character. The first non-blank character following the command is designated as the delimiter. The first text string is left justified to the current indentation value (specified by .¢1min¢0m). The second string is centered between the current indentation value and the current right margin value (specified by .¢1mrm¢0m). The third string is right justified to the current right KosmoSoft -4- Version 1.5 NRO(1) AM*GA Programmer's Manual NRO(1) margin value. The absence of footer text will result in the footer being printed as one blank line. The presence of the page number character (set by .¢1mpc¢0m) in the footer text results in the current page number being inserted at that position. Multiple occurrances of the page number character are allowed. This command must be the last command on an input line. .¢1mheá¢0máspecifies text to be used for a header. The for mat is the same as for the footer (see .¢1mfo¢0m). .¢1mieá¢0máSame as .¢1mif¢0m, but remembers the resulting condition, that can be used by subsequent .¢1mel ¢0mrequests. Only one level of conditions is remembered: they cannot be nested. Every occurrence of a .¢1mie ¢0mrequest overrides the result as remembered by the previous one. .¢1mifá¢0máConditional acceptance of input. The request is followed by a conditional, which may take several forms. Depending on the condition, subsequent input may be accepted or ignored. The following forms of condition are valid: .¢1mif ¢0m[!]<¢1mletter¢0m> anything .¢1mif ¢0m[!]<¢1mexpression¢0m> anything .¢1mif ¢0m[!]<¢1mdelimiter¢0m> <¢1mstring1¢0m> <¢1mdelimiter¢0m> <¢1mstring2¢0m> <¢1mdelimiter¢0m> anything The following <letter>s may be used: ¢1mo¢0m: Current page number is odd; ¢1me¢0m: Current page number is even; ¢1mn¢0m: Formatter is ¢4mNRO¢0m, which is always true; ¢1mt¢0m: Formatter is TRO(FF), which is always false. An <expression> is said to be true if it is > 0. The last form is a string comparison, which is true if <string1> and <string2> are exactly equal. Any <delimiter> may be used as long as it doesn't make the conditional look like one of the other forms. A not-symbol `!' may immediately precede the condition to reverse its truth. Normally, the accepted or ignored input affected is only the rest of the current input line. A multi-line `then-part' must begin with the opening delimiter @{ and the last line must end with the closing delimiter @}. It may also be useful to conceal the newline following the opening delimiter if it is at the end of an input line. Because the delimiters are deleted from the input, make sure that the line is not empty without them, because this would cause a break. It is sufficient to place them on a line with a comment command to avoid this. .¢1miná¢0máindents the left margin to the column value specified by the argument. The default left margin is set to zero. This command performs a break. .¢1mitá¢0mácauses the following lines of text to appear in italics. The optional argument specifies the number of lines to be typed in italics. An argument of zero explicitly turns italics off, while a negative argument turns it on indefinitely. This command is ¢1mnot ¢0m KosmoSoft -5- Version 1.5 NRO(1) AM*GA Programmer's Manual NRO(1) ¢1m¢0mfunctional when the Commodore Amiga (ISO) command sequences are not being used, since it can't be emulated by overstriking printlines. .¢1mjuá¢0mácauses blanks to be inserted between words in a line of output in order to align or justify the right margin. The default is to justify. No argument is expected. .¢1mlsá¢0másets the line spacing to the value specified by the argument. The default is for single spacing. .¢1mm1á¢0máspecifies the number of lines in the header margin. This is the space from the physical top of page to and including the header text. A value of zero causes the header to not be printed. A value of one causes the header to appear at the physical top of page. Larger argument values cause the appropriate number of blank lines to appear before the header is printed. .¢1mm2á¢0máspecifies the number of blank lines to be printed between the header line and the first line of the processed text. .¢1mm3á¢0máspecifies the number of blank lines to be printed between the last line of processed text and the footer line. .¢1mm4á¢0máspecifies the number of lines in the footer margin. This command affects the footer the same way the .¢1mm1 ¢0mcommand affects the header. .¢1mneá¢0máspecifies a number of lines which should not be broken across a page boundary. If the number of lines remaining on a page is less than the value needed, then a new output page is started. .¢1mnfá¢0máspecifies that succeeding text should be printed without rearrangement, or with no fill. The default is to justify. No argument is expected. .¢1mnjá¢0máspecifies that no attempt should be made to align or justify the right margin. No argument is expected. .¢1mnrá¢0mácauses the value of a number register to be set or modified. A total of twenty-six number registers are available designated @na through @nz (either upper or lower case is allowed). When the sequence @nc is imbedded in the text, the current value of number register c replaces the sequence, thus, such things as paragraph numbering can be accomplished with relative ease. .¢1mofá¢0máspecifies the text for the footer on odd numbered pages. The format is the same as the footer command (see .¢1mfo¢0m). .¢1mohá¢0máspecifies the text for the header on odd numbered pages. The format is the same as the footer command KosmoSoft -6- Version 1.5 NRO(1) AM*GA Programmer's Manual NRO(1) (see .¢1mfo¢0m). .¢1mpcá¢0máspecifies the page number character to be used in headers and footers. The occurrance of this character in the header or footer text results in the current page number being printed. The default for this character is the hash mark `#'. .¢1mplá¢0máspecifies the page lenght or the number of lines per output page. The default is 66. .¢1mpná¢0máspecifies the way page numbering is done. You may specify the following values: 0 uses normal arabic page numbers, 1 generates lowercase roman numbers, and 2 specifies uppercase roman numbers. Default is arabic page numbering. .¢1mpoá¢0máspecifies a page offset value. This allows the formatted text to be shifted to the right by the number of spaces specified. This feature may also be invoked by a switch on the command line. All horizontal positions (like tabstops, indentations) are adjusted accordingly. .¢1mrmá¢0másets the column value for the right margin. The default is 80. .¢1msoá¢0mácauses input to be retrieved from the file specified by the command's character string argument. The contents of the new file are inserted into the output stream until an EOF is detected. Processing of the original file is then resumed. File nesting is allowed up to a reasonable level (four). .¢1mspá¢0máspecifies a number of blank lines to be output before printing the next line of text. This automatically generates a break. You cannot move upwards. .¢1mtaá¢0mátab settings. This command allows you to set tabstops. It may have optional numeric arguments. When issued without arguments, all tabstops are removed. When issued with one or more numeric arguments, tabstops are set at the specified number of spaces from the left hand side of the paper. An argument may optionally be preceded with a `+' to indicate that a distance from the previously mentioned tab is meant instead of an absolute position. A `+' sign before the first argument indicates a distance from the current indent. .¢1mtiá¢0mátemporarily alters the indentation or left margin value for a single succeeding line of output text. This command performs a break. If an input line starts with spaces, this has the effect that a break is generated, and a temporary indent for the number of spaces is set. KosmoSoft -7- Version 1.5 NRO(1) AM*GA Programmer's Manual NRO(1) .¢1mtmá¢0máwrites a message to the standard error output, so you see it in your console window. This command must be the last one on an input line. When used with the no-break command character, this `no-break' gets another meaning: don't break the formatted output if it also is printed on the console. The command is ignored instead. .¢1mulá¢0máunderlines the alphanumeric text in the following line(s). The optional argument specifies the number of lines to be underlined. An argument of zero explicitly turns underlining off, while a negative argument turns it on indefinitely. When overstrike is being used to produce the underline, underlining and boldface are mutually exclusive features, and the appearance of an underline command cancels any existing boldface operations. .¢1muná¢0máundefines a previously defined macro, and all macros that were defined later. If this macro was a redefinition of an older macro with the same name, the old definition will be available again. Thus, macros are defined in a stack-like fashion. .* ."áááBoth of these serve as a way to insert comments in the input text. They have absolutely no effect on the output. Instead of having the command immediately at the beginning of a line, you may also begin a line with a command character, then some blanks, and then again a command character, this time followed immediately by the command. There exists even a second command character, called the ¢1mno break command character¢0m, `'', which suppresses the break normally generated by some commands. This no break command character can only be used in this way. If the first non-blank character is ¢4mnot¢0m a command character, it is considered to be text. An example illustrates this. . .sp @" This is a space command, . this is some normal text, . 'sp 3 @" and this spaces without a break. When a line does not begin with the command character, its words are placed one by one on an output line. As soon as a word doesn't fit, the collected line is printed, possibly after justification. The word is then placed on the next output line. If a line is about to be printed at the top of a page, the page header, if any, is printed first. If a line is on the last usable line of a page, the page footer, if any, is printed next, and the page is ejected. If you want to begin an input text line with an instance of the command character, you may precede it with the escape character. KosmoSoft -8- Version 1.5 NRO(1) AM*GA Programmer's Manual NRO(1) A number of translations can be performed on the input, even before it is interpreted as either text or commands. Such a translation takes place where an escape character `@' is seen in the input text. The single charachter following the escape character determines the effect. The following functions are currently implemented: @@áááis a single @. @¢1meá¢0mááis replaced by the current value of the escape character. Currently, there is no way to change it. @¢1mná¢0mááfollowed by a single letter, is replaced by the contents of the designated number register. @¢1mtá¢0mááis replaced with a tab character, to be used in conjunction with the .¢1mta ¢0mcommand. You may also use a normal tab character if you wish. If a tab is encountered, the necessary space is generated by non-breakable spaces. Any spaces on the output line before the tab are also made non-breakable. This is to avoid justification spoiling the tab. Tabs beyond the current right margin or beyond the last tab stop are ignored, except that they separate words. @¢1mX¢0m(¢1mexpression¢0m)áis replaced with the character with character code value `expression'. @(¢1mspace¢0m)áis replaced by a non-breakable space. It behaves just like any printable character, you just don't see it. This space won't be modified by justification, and it will be underlined by continous underline. @(¢1mnewline¢0m)áis deleted from the input. If a @ is placed at the end of an input line, it will appear as if the next input line actually is following the contents of the current line. This is called `concealing the newline'. @.áááwhere . stands for the current command character, produces the command character. It will, however, not be recognized as such. This provides a way to start your input line with a command character that in fact is a text line. This only works if the command character is different from any other valid character following the escape character, and does not work for .¢1men ¢0mcommands that end a macro definition. @{ @}áááThese two delimiters were already mentioned in the section about the .¢1mif ¢0mand .¢1mel ¢0mcommands. They serve to delimit the lines you want to be affected by these commands. Normally, when the condition is false, the .¢1mif ¢0mskips input until it finds the end of the current line. If it sees the @{ following the condition, it sets a flag to indicate to the low-level file reader, that it must count these delimiters. All input is then KosmoSoft -9- Version 1.5 NRO(1) AM*GA Programmer's Manual NRO(1) skipped until the matching closing delimiter @} is found. So, the .¢1mif ¢0mcommand never 'sees' anything of it. Also in this case, the .¢1mif ¢0mcommand skips the rest of the line remaining after the closing @}. On the other hand, if the condition evaluates to be true, all and any opening and closing delimiters are ignored completely. The command following the condition is executed, and also of course any commands on following lines. Since a command (or text) is expected on the same line as the .¢1mif ¢0mcommand, omission of a command makes it look like there is an empty line, and this generates an unexpected break. Therefore, you should conceal the newline at the end of such a line. (See @(newline).) @"áááThis is yet another way to insert a comment. Note that text may precede the comment function. All text from the comment function until the end of the line will be ignored. Note that spaces between the last word on a line and the comment are not deleted, and this may effect your layout in some (as of yet unimplemented) cirumstances. Any unrecognized character that follows the @ will be left in the input. Macro expansion is accomplished in the following way. There exists an input push-back buffer. If any input is needed, this push-back buffer is examined first. If a character is present, the request is satisfied by taking the last pushed back character. Only if the push back buffer is empty, a character is read from the input file. At any time that ¢4mNRO¢0m reads a character that is unexpected, it is pushed back, in the hope that it can be used later. When a macro is to be expanded, its body is pushed back, while at the same time subsituting the arguments. Normally when an instance of the escape character is to be pushed back, it is `guarded' against re-substitution when it is read back, by doubling it, so anything pushed back will be read back exactly the same. This is not done ¢4monly¢0m for macro bodies, to allow resubstitution to occur in them. This means that the body of a macro is interpreted twice, once at definition time, and once at application time. The macro arguments are interpreted only once, so that a double escape character in an argument will show up in the resulting text as a single escape character, instead of disappearing. This seems to be the most intuitive approach. It will disallow some more complex applications but avoids needing four @'s in an argument if you want only one. ¢1mEXAMPLES ¢0mMacros: You may even define a macro that defines a macro, in the following way: .de keep .de $0 $1 $2 $3 $4 $5 $6 $7 $8 $9 @@.en KosmoSoft -10- Version 1.5 NRO(1) AM*GA Programmer's Manual NRO(1) .en This macro defines a macro with a name designated by the first argument, and containing the text designated by the remaining arguments. Remember that you can always enclose an argument with quotes. Note that you must use two escape characters to make the .¢1men ¢0mpart of the macro body. This is because macro definitions are handled slightly different from normal input lines. In the definition of `keep' there will be a line with @.¢1men¢0m, and at the time of definition of the inner macro the second escape character will be stripped off, so that the end of the inner macro definition is recognized. Another way to to it, is to change the command character temporarily while defining the outer macro. Conditionals: Here are a few examples of correct use of the .¢1mif¢0m, .¢1mie ¢0mand .¢1mel ¢0mcommands: .if @na Register A is greater than zero! .if @na @{.firstcommand . .secondcommand . .lastcommand @} .if @na @{@ . .firstcommand . .secondcommand . .lastcommand @} .ie @na @{.firstcommand . .secondcommand . .lastcommand @} .el Register A is NOT greater than zero!! .el Maybe a bit late, but register A IS greater than zero!! ¢1mUNDOCUMENTED FEATURES ¢0m<censored> KosmoSoft -11- Version 1.5