1 03/04/85 format_document_
2
3
4 The format_document_ subroutine is used to fill and adjust text. The
5 subroutine arguments control the formatting, some of which can be
6 overridden by optional control lines in the text. See the "Notes"
7 section below for a discussion of those control lines.
8
9
10 Entry points in format_document_:
11 List is generated by the help command
12
13
14
15 :Entry: format_document_: 03/03/85 format_document_
16
17
18 Function:
19 The format_document_ entry point uses directory names and entrynames.
20 The entrynames can reference segments, links, or multisegment files.
21
22
23 Syntax:
24 declare format_document_ entry char* char* char* char*
25 ptr fixed bin35;
26 call format_document_ dir_name_in entry_name_in dir_name_out
27 entry_name_out options_ptr code;
28
29
30 Arguments:
31 dir_name_in
32 is the pathname of the containing directory of the input. Input
33 entry_name_in
34 is the entryname of the input segment, link or multisegment file.
35 Input
36 dir_name_out
37 is the pathname of the containing directory of the output. Input
38 entry_name_out
39 is the entryname of the output segment, link or multisegment file.
40 Input If the entry does not exist, it will be created.
41
42
43 options_ptr
44 is a pointer to the structure in which options are specified.
45 Input See "Notes" below.
46 code
47 is a standard status code. Output It may be one of the following:
48 error_table_$fatal_error
49 if the input file cannot be processed.
50 error_table_$recoverable_error
51 if an error occurs but processing is completed.
52
53
54 :Entry: string: 03/04/85 format_document_$string
55
56
57 Function: This entry point uses char * variables as input and
58 output.
59
60
61 Syntax:
62 declare format_document_$string entry char * char* fixed
63 bin21 ptr fixed bin35;
64 call format_document_$string instring outstring outlen options_ptr
65 code;
66
67
68 Arguments:
69 instring
70 is the input string. Input
71 outstring
72 is the output string. Input
73 outlen
74 is the length in bytes of the output string. Output
75 options_ptr
76 is a pointer to the structure in which options are specified.
77 Input
78
79
80 code
81 is a standard status code. Output It can be one of the following:
82 error_table_$smallarg
83 if the size of the output exceeds that of the output string.
84 error_table_$fatal_error
85 if the input file cannot be processed.
86 error_table_$recoverable_error
87 if an error occurs but processing is completed.
88
89
90 :Entry: switch: 03/04/85 format_document_$switch
91
92
93 Function: This entry point uses a directory name and entryname for
94 input and writes its output to an I/O switch. The entryname can
95 reference a segment, link or multisegment file.
96
97
98 Syntax:
99 declare format_document_$switch entry char* char* ptr ptr
100 fixed bin35;
101 call format_document_$switch dir_name_in entry_name_in iocbptr
102 options_ptr code;
103
104
105 Arguments:
106 dir_name_in
107 is the pathname of the containing directory of the input. Input
108 entry_name_in
109 is the entryname of the input segment, link or multisegment file.
110 Input
111 iocbptr
112 is a pointer to the control block for the output I/O switch.
113 Input
114 options_ptr
115 is a pointer to the structure in which options are specified.
116 Input See "Notes" below.
117
118
119 code
120 is a standard status code. Output It can one of the following:
121 error_table_$fatal_error
122 if the input file cannot be processed.
123 error_table_$recoverable_error
124 if an error occurs but processing is completed.
125
126
127 Notes: The argument options_ptr points to the format_document_options
128 structure defined in include file format_document_options.incl.pl1.
129
130 dcl 1 format_document_options aligned based
131 format_document_options_ptr,
132 2 version_number fixed bin,
133 2 indentation fixed bin,
134 2 line_length fixed bin,
135 2 switches,
136 3 pgno_sw bit 1 unaligned,
137 3 adj_sw bit 1 unaligned,
138 3 galley_sw bit 1 unaligned,
139 3 error_sw bit 1 unaligned,
140 3 literal_sw bit 1 unaligned,
141 3 file_sw bit 1 unaligned,
142 3 dont_compress_sw bit 1 unaligned,
143
144
145 3 break_word_sw bit 1 unaligned,
146 3 max_line_length_sw bit 1 unaligned,
147 3 dont_break_indented_lines_sw
148 bit 1 unaligned,
149 3 sub_err_sw bit 1 unaligned,
150 3 dont_fill_sw bit 1 unaligned,
151 3 hyphenation_sw bit 1 unaligned,
152 3 mbz bit 23 unaligned
153 2 syllable_size fixed bin;
154
155
156
157 Structure elements:
158 version_number
159 is the version number of this structure. Input It must have
160 the value 2.
161 indentation
162 indentation value, causing indentation from the left margin.
163 Input This space is in addition to any indentation established
164 by the usage of the indent control in the text.
165 line_length
166 is the initial line length value. Input It is the equivalent
167 of the ".pdw" control in the text, and can be overridden in the
168 text.
169
170
171 pgno_sw
172 Input
173 "1"b enables page numbering. If galley_sw is off, then each page
174 is to end with a centered page number.
175 "0"b indicates that no page numbering is requested.
176 adj_sw
177 Input
178 "1"b causes adjust mode to be on initially. This is the
179 equivalent of a ".alb" in the text. It can be overridden in
180 the text.
181 "0"b causes adjust mode to be off initially. This is the
182 equivalent of a ".all" in the text. It is only meaningful
183 if dont_fill_sw = "0"b.
184
185
186 galley_sw
187 Input
188 "1"b suppresses vertical margins and page breaks.
189 "0"b enables vertical margins and page breaks.
190 error_sw
191 Input
192 "1"b causes diagnostic error messages to be written to
193 error_output.
194 "0"b suppresses diagnostic error messages.
195 literal_sw
196 Input
197 "1"b causes all input to be treated as text.
198 "0"b enables format_document_ controls. A line that begins with
199 a period is treated as a control line.
200
201
202 file_sw
203 Output
204 "1"b indicates that a non-zero storage system status code refers
205 to the output file.
206 "0"b indicates that a non-zero storage system status code refers
207 to the input file.
208 dont_compress_sw
209 Input
210 "1"b causes no compression of adjacent spaces and tab characters,
211 nor enforcement of the convention of ending a sentence with
212 2 spaces.
213 "0"b causes adjacent spaces and tab characters that do not begin
214 a line to be converted to a single space, and enforces the
215 convention that a sentence ends with 2 spaces. A sentence
216 is any string that terminates with one of the following
217 character sequences: ". "; "? "; " "; ": "; ".) ";
218 "?) "; or " ) ". This switch may be overridden by
219 dont_break_indented_lines for certain input lines.
220
221
222 break_word_sw
223 Input
224 "1"b causes the line to be broken in the middle of a word if the
225 line exceeds the line length and there are no spaces or tab
226 characters available at which to do so.
227 "0"b causes an overlength line to be returned and
228 error_table_$recoverable_error to be returned if the line
229 exceeds the linelength and there are no spaces or tab
230 characters at which to break it.
231
232
233 max_line_length_sw
234 Input
235 "1"b causes the line to be re-adjusted to the line_length given
236 in this structure and error_table_$recoverable_error to be
237 returned if controls in the text cause the calculated line
238 length to be greater than the line_length given in this
239 structure.
240 "0"b allows the controls in the text to adjust the calculated
241 line length to a value greater than the line_length given in
242 this structure.
243
244
245 dont_break_indented_lines_sw
246 Input
247 "1"b indicates that if an input line exceeds the specified line
248 length and begins with a blank or horizontal tab, it is not
249 to be broken if a) it is the last line of input, b) it is
250 followed a line that begins with a blank or horizontal tab,
251 or c) it is followed by a blank line. In addition, such
252 lines will not have space compression or sentence formatting
253 performed on them, no matter what value dont_compress_sw
254 has.
255 "0"b indicates that overlength lines are broken regardless of
256 indentation, and that dont_compress will always control
257 space compression and sentence formatting.
258
259
260 sub_err_sw
261 Input
262 "1"b indicates that diagnostic errors are to be communicated via
263 calls to sub_err_. The info structure used to communicate
264 information about the error is
265 format_document_error.incl.pl1.
266 "0"b indicates that no calls to sub_err_ are to be made.
267 dont_fill_sw
268 Input
269 "1"b causes fill mode to be off initially. This is the
270 equivalent of a ".fif" in the text. It can be overridden in
271 the text.
272 "0"b causes fill mode to be on initially. This is the equivalent
273 of a ".fin" in the text.
274
275
276 hyphenation_sw
277 Input
278 "1"b causes hyphenation mode to be on initially. Hyphenation can
279 be turned on in the text via the "hyn" control and off via
280 the ".hyf" control. The ".hy" control returns hyphenation
281 mode to the initial value, i.e. the state of this switch.
282 "0"b causes hyphenation mode to be off initially.
283 mbz
284 must be zero.
285
286
287 syllable_size
288 Input
289 indicates the smallest number of characters to be contained in a
290 syllable that is to be separated from the rest of a word by
291 hyphenation. This value can be adjusted in the text via the
292 ".hyn" control. The ".hy" control returns the syllable size to
293 the value of this argument.
294 set hyphenation mode and syllable size to the defaults as
295 specified by format_document_options.hyphenation_sw and
296 format_document_options.syllable_size.
297
298
299 hyf
300 set hyphenation mode off. See the discussion of .hyn for
301 details.
302 hyn N
303 set hyphenation mode on and set the syllable size according
304 to the given parameter. the parameter is given as an
305 unsigned integer and specifies the number of characters in
306 the smallest allowed hyphenated syllable. If the parameter
307 is not given, then the default syllable size is used. The
308 default syllable size is the value given in
309 format_document_options.syllable_size.
310
311
312 Control lines:
313 The following is a discussion of each of the control lines.
314 .alb
315 align the text at both the left and right margins according to the
316 current value of the left indentation and undentation. Text is
317 padded by insertion of uniformly distributed white space. The fill
318 mode must be on for this mode to operate. If the fill mode is off,
319 this control is mapped into the align-left .all control. This is
320 the default alignment mode.
321 .all
322 align the text on the left margin according to the current values of
323 left indentation and undentation leaving the right margin ragged.
324 .brf
325 finish the current output line by formatting any pending texts as a
326 short line.
327
328
329 .brp
330 finish the current page, formatting any pending texts as a short
331 line.
332 .fif
333 set the fill mode off. See the discussion of .fin for details.
334 .fin
335 set the fill mode on. In fill mode, text words are moved from line
336 to line in such a way that the last word does not extend past the
337 right margin. The default for this mode is on.
338
339
340 .in, .inl +/-N
341 if N is given without the optional sign, plus + or minus -, then
342 set the left indentation point to N columns to the right of the left
343 margin. If N is given with the optional sign, then change the
344 current left indentation point by N columns. Positive values for N
345 cause movement to the right. The default value for N is 0. Any
346 value that results in a zero or negative effective line length will
347 produce an error diagnostic message. The left indentation point is
348 never set to the left of the left margin. The left margin is
349 determined by the -indent control argument.
350 .pdl +/-N
351 if N is given without the optional sign, + or -, then set the page
352 length to N lines. If N is given with the optional sign, then
353 change the current page length by N. If the resulting page length
354 is zero or negative, an error diagnostic message is produced. The
355 default value for N is 66.
356
357
358 .pdw +/-N
359 if N is given without the optional sign, then set the page width to
360 N columns. If N is given with the optional sign, then change the
361 current page width by N. If the resulting page width is zero or
362 negative, an error diagnostic message is produced. The default
363 value for N is 65.
364 .spf N
365 finish the current output line and then add N blank lines. If N is
366 not given, then add 1 blank line.
367 .un, .unl +/-N
368 adjust the indentation point for only the next output line. If N is
369 unsigned or has the + sign the indentation point is moved n columns
370 to the left. If N has the - sign, the indentation point is moved n
371 columns to the right. The default value for N is the value of the
372 indentation value.
373
374
375 Specialized Error Handling:
376 If format_document_options.sub_err_sw is set and errors occur in
377 formatting, the sub_err_ subroutine will be called to signal them
378 rather than aborting the program. The caller of format_document_ can
379 set up a handler for the sub_error_ condition and use the information
380 in the format_document_error structure to make decisions about how to
381 proceed. See the sub_err_ subroutine for an example of how to
382 establish a handler for the sub_error_ condition.