03/04/85 format_document_ The format_document_ subroutine is used to fill and adjust text. The subroutine arguments control the formatting, some of which can be overridden by optional control lines in the text. See the "Notes" section below for a discussion of those control lines. Entry points in format_document_: (List is generated by the help command) :Entry: format_document_: 03/03/85 format_document_ Function: The format_document_ entry point uses directory names and entrynames. The entrynames can reference segments, links, or multisegment files. Syntax: declare format_document_ entry (char(*), char(*), char(*), char(*), ptr, fixed bin(35)); call format_document_ (dir_name_in, entry_name_in, dir_name_out, entry_name_out, options_ptr, code); Arguments: dir_name_in is the pathname of the containing directory of the input. (Input) entry_name_in is the entryname of the input segment, link or multisegment file. (Input) dir_name_out is the pathname of the containing directory of the output. (Input) entry_name_out is the entryname of the output segment, link or multisegment file. (Input) If the entry does not exist, it will be created. options_ptr is a pointer to the structure in which options are specified. (Input) See "Notes" below. code is a standard status code. (Output) It may be one of the following: error_table_$fatal_error if the input file cannot be processed. error_table_$recoverable_error if an error occurs but processing is completed. :Entry: string: 03/04/85 format_document_$string Function: This entry point uses char (*) variables as input and output. Syntax: declare format_document_$string entry (char (*), char(*), fixed bin(21), ptr, fixed bin(35)); call format_document_$string (instring, outstring, outlen, options_ptr, code); Arguments: instring is the input string. (Input) outstring is the output string. (Input) outlen is the length in bytes of the output string. (Output) options_ptr is a pointer to the structure in which options are specified. (Input) code is a standard status code. (Output) It can be one of the following: error_table_$smallarg if the size of the output exceeds that of the output string. error_table_$fatal_error if the input file cannot be processed. error_table_$recoverable_error if an error occurs but processing is completed. :Entry: switch: 03/04/85 format_document_$switch Function: This entry point uses a directory name and entryname for input and writes its output to an I/O switch. The entryname can reference a segment, link or multisegment file. Syntax: declare format_document_$switch entry (char(*), char(*), ptr, ptr, fixed bin(35)); call format_document_$switch (dir_name_in, entry_name_in, iocbptr, options_ptr, code); Arguments: dir_name_in is the pathname of the containing directory of the input. (Input) entry_name_in is the entryname of the input segment, link or multisegment file. (Input) iocbptr is a pointer to the control block for the output I/O switch. (Input) options_ptr is a pointer to the structure in which options are specified. (Input) See "Notes" below. code is a standard status code. (Output) It can one of the following: error_table_$fatal_error if the input file cannot be processed. error_table_$recoverable_error if an error occurs but processing is completed. Notes: The argument options_ptr points to the format_document_options structure (defined in include file format_document_options.incl.pl1). dcl 1 format_document_options aligned based (format_document_options_ptr), 2 version_number fixed bin, 2 indentation fixed bin, 2 line_length fixed bin, 2 switches, 3 pgno_sw bit (1) unaligned, 3 adj_sw bit (1) unaligned, 3 galley_sw bit (1) unaligned, 3 error_sw bit (1) unaligned, 3 literal_sw bit (1) unaligned, 3 file_sw bit (1) unaligned, 3 dont_compress_sw bit (1) unaligned, 3 break_word_sw bit (1) unaligned, 3 max_line_length_sw bit (1) unaligned, 3 dont_break_indented_lines_sw bit (1) unaligned, 3 sub_err_sw bit (1) unaligned, 3 dont_fill_sw bit (1) unaligned, 3 hyphenation_sw bit (1) unaligned, 3 mbz bit (23) unaligned 2 syllable_size fixed bin; Structure elements: version_number is the version number of this structure. (Input) It must have the value 2. indentation indentation value, causing indentation from the left margin. (Input) This space is in addition to any indentation established by the usage of the indent control in the text. line_length is the initial line length value. (Input) It is the equivalent of the ".pdw" control in the text, and can be overridden in the text. pgno_sw (Input) "1"b enables page numbering. If galley_sw is off, then each page is to end with a centered page number. "0"b indicates that no page numbering is requested. adj_sw (Input) "1"b causes adjust mode to be on initially. This is the equivalent of a ".alb" in the text. It can be overridden in the text. "0"b causes adjust mode to be off initially. This is the equivalent of a ".all" in the text. It is only meaningful if dont_fill_sw = "0"b. galley_sw (Input) "1"b suppresses vertical margins and page breaks. "0"b enables vertical margins and page breaks. error_sw (Input) "1"b causes diagnostic error messages to be written to error_output. "0"b suppresses diagnostic error messages. literal_sw (Input) "1"b causes all input to be treated as text. "0"b enables format_document_ controls. A line that begins with a period is treated as a control line. file_sw (Output) "1"b indicates that a non-zero storage system status code refers to the output file. "0"b indicates that a non-zero storage system status code refers to the input file. dont_compress_sw (Input) "1"b causes no compression of adjacent spaces and tab characters, nor enforcement of the convention of ending a sentence with 2 spaces. "0"b causes adjacent spaces and tab characters that do not begin a line to be converted to a single space, and enforces the convention that a sentence ends with 2 spaces. A sentence is any string that terminates with one of the following character sequences: ". "; "? "; " "; ": "; ".) "; "?) "; or " ) ". This switch may be overridden by dont_break_indented_lines for certain input lines. break_word_sw (Input) "1"b causes the line to be broken in the middle of a word if the line exceeds the line length and there are no spaces or tab characters available at which to do so. "0"b causes an overlength line to be returned and error_table_$recoverable_error to be returned if the line exceeds the linelength and there are no spaces or tab characters at which to break it. max_line_length_sw (Input) "1"b causes the line to be re-adjusted to the line_length given in this structure and error_table_$recoverable_error to be returned if controls in the text cause the calculated line length to be greater than the line_length given in this structure. "0"b allows the controls in the text to adjust the calculated line length to a value greater than the line_length given in this structure. dont_break_indented_lines_sw (Input) "1"b indicates that if an input line exceeds the specified line length and begins with a blank or horizontal tab, it is not to be broken if a) it is the last line of input, b) it is followed a line that begins with a blank or horizontal tab, or c) it is followed by a blank line. In addition, such lines will not have space compression or sentence formatting performed on them, no matter what value dont_compress_sw has. "0"b indicates that overlength lines are broken regardless of indentation, and that dont_compress will always control space compression and sentence formatting. sub_err_sw (Input) "1"b indicates that diagnostic errors are to be communicated via calls to sub_err_. The info structure used to communicate information about the error is format_document_error.incl.pl1. "0"b indicates that no calls to sub_err_ are to be made. dont_fill_sw (Input) "1"b causes fill mode to be off initially. This is the equivalent of a ".fif" in the text. It can be overridden in the text. "0"b causes fill mode to be on initially. This is the equivalent of a ".fin" in the text. hyphenation_sw (Input) "1"b causes hyphenation mode to be on initially. Hyphenation can be turned on in the text via the "hyn" control and off via the ".hyf" control. The ".hy" control returns hyphenation mode to the initial value, i.e. the state of this switch. "0"b causes hyphenation mode to be off initially. mbz must be zero. syllable_size (Input) indicates the smallest number of characters to be contained in a syllable that is to be separated from the rest of a word by hyphenation. This value can be adjusted in the text via the ".hyn" control. The ".hy" control returns the syllable size to the value of this argument. set hyphenation mode and syllable size to the defaults as specified by format_document_options.hyphenation_sw and format_document_options.syllable_size. hyf set hyphenation mode off. See the discussion of .hyn for details. hyn {N} set hyphenation mode on and set the syllable size according to the given parameter. the parameter is given as an unsigned integer and specifies the number of characters in the smallest allowed hyphenated syllable. If the parameter is not given, then the default syllable size is used. The default syllable size is the value given in format_document_options.syllable_size. Control lines: The following is a discussion of each of the control lines. .alb align the text at both the left and right margins according to the current value of the left indentation and undentation. Text is padded by insertion of uniformly distributed white space. The fill mode must be on for this mode to operate. If the fill mode is off, this control is mapped into the align-left (.all) control. This is the default alignment mode. .all align the text on the left margin according to the current values of left indentation and undentation leaving the right margin ragged. .brf finish the current output line by formatting any pending texts as a short line. .brp finish the current page, formatting any pending texts as a short line. .fif set the fill mode off. See the discussion of .fin for details. .fin set the fill mode on. In fill mode, text words are moved from line to line in such a way that the last word does not extend past the right margin. The default for this mode is on. .in, .inl {+/-N} if N is given without the optional sign, plus (+) or minus (-), then set the left indentation point to N columns to the right of the left margin. If N is given with the optional sign, then change the current left indentation point by N columns. Positive values for N cause movement to the right. The default value for N is 0. Any value that results in a zero or negative effective line length will produce an error diagnostic message. The left indentation point is never set to the left of the left margin. The left margin is determined by the -indent control argument. .pdl {+/-N} if N is given without the optional sign, (+ or -), then set the page length to N lines. If N is given with the optional sign, then change the current page length by N. If the resulting page length is zero or negative, an error diagnostic message is produced. The default value for N is 66. .pdw {+/-N} if N is given without the optional sign, then set the page width to N columns. If N is given with the optional sign, then change the current page width by N. If the resulting page width is zero or negative, an error diagnostic message is produced. The default value for N is 65. .spf {N} finish the current output line and then add N blank lines. If N is not given, then add 1 blank line. .un, .unl {+/-N} adjust the indentation point for only the next output line. If N is unsigned or has the + sign the indentation point is moved n columns to the left. If N has the - sign, the indentation point is moved n columns to the right. The default value for N is the value of the indentation value. Specialized Error Handling: If format_document_options.sub_err_sw is set and errors occur in formatting, the sub_err_ subroutine will be called to signal them rather than aborting the program. The caller of format_document_ can set up a handler for the sub_error_ condition and use the information in the format_document_error structure to make decisions about how to proceed. See the sub_err_ subroutine for an example of how to establish a handler for the sub_error_ condition. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved