1 1976-11-10 columns, col
2
3 Syntax as a command: col path -control_args
4
5
6 Function: reformats the lines of a segment so that they form
7 columns that read vertically down the page, thereby greatly
8 decreasing the amount of paper required to print a segment
9 containing many short lines.
10
11
12 Arguments:
13 path
14 is the pathname of the segment to reformat.
15
16
17 Control arguments:
18 -segment, -sm
19 specifies that the reformatted segment is to be placed in
20 another segment in the working directory with the
21 same name as the original plus the suffix col. Default, if this
22 argument is not specified, is to print the segment on
23 user_output, which is normally connected to the terminal.
24 -line_length n, -ll n
25 specifies the line length to be used for output. The default is
26 136 when segment is specified, and the terminal line length when
27 segment is not specified. If the line length cannot be determined,
28 as when file_output is being used, the default is 136.
29
30
31 -page_length n, -pl n
32 specifies the page length to be used for output. This is the
33 number of printable lines on the page. The default is 60.
34 -top_margin n, -tmg n
35 specifies the number of blank lines that are to appear at the top
36 of each page, in addition to the page_length printable lines.
37 For segment output, this value must be at least 3. Default is 3,
38 except when output is to the terminal and no_pagination is
39 specified, in which case the default is 0.
40 -bottom_margin n, -bmg n
41 specifes the number of blank lines to appear at the bottom of each
42 page. This control argument may not appear if segment is specified.
43 Default is 3, except when output is to the terminal and
44 no_pagination is specified, in which case the default is 0.
45
46
47 -margin n, -mg n
48 sets both the top and bottom margins at the same time. This value
49 must be at least 3 if segment is specified. The default values of
50 the top and bottom margins are specified above. This control
51 argument may not be specified if top_margin or bottom_margin are
52 specified.
53 -no_pagination, -npgn
54 specifies that the page_length is assumed to be infinite. In
55 this case the vertical length of the output will be the minimum
56 required to contain all the columns of the entire segment. The
57 column lengths will all be equal, except for the last column,
58 which may contain unused positions. This control argument is
59 incompatible with the use of the page_length argument.
60
61
62 -indent n, -in n
63 specifies the left margin. The default is 0. The use of this
64 control argument effectively reduces the available line length
65 specified by the line_length control argument.
66 -minimize, -mn
67 If this control argument is not specified, all columns in the
68 reformatted segment will be the same width, which is determined
69 from the values of additional control arguments described below.
70 If this argument is specified, each column will only be as wide as
71 the longest line in that column, thereby minimizing the amount of
72 space required to print the reformatted segment. Thus, for
73 example, if one column happens to contain only short lines, that
74 column will be narrower than columns containing longer lines.
75
76
77 -column_width n, -cw n
78 If minimize is not specified, this control argument specifies the
79 width of each column. The default is to use the longest line in
80 the segment as the column width except when number_columns is
81 specified. If minimize is specified, this is the maximum width
82 of any column. Lines in a column exceeding this width are either
83 truncated, folded, or extended into adjacent columns depending on
84 other control arguments discussed below. The default maximum
85 column width when minimize is specified is the available line
86 length.
87
88
89 -number_columns n, -nc n
90 specifies the number of columns to print on each page. This
91 control argument is not permitted when minimize is specified. The
92 default is to put as many columns as possible across the page,
93 subject to the column_width and other restrictions specified by
94 additional control arguments.
95 -space n, -sp n
96 specifies the width of the blank space between each column. The
97 default is one blank space. Note that if minimize is not
98 specified the actual number of blanks between the longest line in
99 any particular column and the next column may be greater than this
100 amount if that line is shorter than the column_width.
101
102
103 -adjust, -ad
104 specifies that the space between the columns is to be adjusted so
105 that the rightmost column is as far to the right as possible
106 within the line_length. This control argument can effectively
107 increase the value of space. The space will always be equal
108 between columns, so that the rightmost column may not necessarily
109 end up at the right margin. This control argument is incompatible
110 with the specification of minimize. The default is not to adjust.
111 -truncate, -tc
112 specifies that a line longer than the default column_width is
113 truncated at the column_width.
114
115
116 -full, -fl
117 specifies that lines longer than the column_width are to be
118 extended into the inter-column space and possibly into adjacent
119 columns for the full length of the line. When a line extends into
120 other columns, the spot taken up by the extended line in those
121 columns will be skipped over. This argument is useful when a few
122 lines in a segment are longer than most of the others. It can
123 produce strange but perfectly correct results if many lines
124 overflow the column_width.
125
126
127 When minimize is specified, the length of the overflowing lines
128 is not used in determining the width of the column. Thus, if the
129 maximum column_width is specified as 20, and one line in a
130 column of 10 character lines is 30 characters long, the actual
131 width of that column will only be 10. If the column_width were
132 equal to or greater than 30, that column would be 30 characters
133 wide. This control argument may not be specified unless a
134 column_width is also specified.
135
136
137 -fold n, -fd n
138 specifies that lines longer than the column_width are to be folded
139 at the column_width and subsequent portions of the line are to be
140 continued below the first part of the line in the same column,
141 indented n spaces from the column's left border.
142
143
144 -blocks, -bk
145 The columns command normally interprets the vertical tab character
146 octal 013 as a "tab" to the top of the next column. The current
147 column may end before the bottom of the page, and a new column
148 will be started. If the blocks control argument is specified,
149 columns treats the input segment as if it were a series of blocks
150 of lines separated by the vertical tab character. The vertical
151 tab, in this case, does not cause a tab to the next column, except
152 when such a tab is required to make the block fit totally within
153 one column. Thus, a block of lines will never be split between
154 two columns, unless that block of lines is longer than the
155 page_length. If a block of lines is too long to fit on the
156 current column, and it did not begin the column, a new column will
157 be started.
158
159
160 The vertical tab character is only recognized if it appears as the
161 first character of a line. This control argument may not be
162 specified when the no_pagination argument is used. If
163 no_pagination is specified, vertical tabs in the first position of
164 a line are ignored.
165
166
167 -full_last_page, -flp
168 Normally, if the last page of output is not completely full,
169 columns tries to minimize the number of printed lines on that page
170 by shortening the page_length. This tends to spread the output
171 more across the page, maximizing the number of columns used and
172 minimizing their lengths. As an example, assume that the last
173 page contains 15 entries, where n_columns is 4 and page_length is
174 6. The last page would then have the following format:
175
176 x x x x
177 x x x x
178 x x x x
179 x x x
180
181
182 Note that the page_length of 6 is not used, since only 4 lines are
183 required to contain the 15 entries. The full_last_page control
184 argument specifies that the last page minimization not be done.
185 This results in columns that may reach down to the bottom of the
186 page, even though subsequent columns are empty. In this same
187 example, the last page would look as follows:
188
189 x x x
190 x x x
191 x x
192 x x
193 x x
194 x x
195
196 The last page in this case uses all 6 lines.
197
198
199 Notes:
200 The defaults are such that if no control arguments are
201 specified, columns searches for the longest line in the segment
202 and uses its length as the column_width. All columns are this
203 same width. The segment is printed on the terminal paged, with 60
204 lines per page and three lines of top and bottom margin on each
205 page.
206
207 The longest line in the segment is always used as the
208 column_width when neither column_width nor n_columns is specified.
209 If the column_width is longer than the line_length minus any
210 indent, and neither fold nor truncate are specified, an error
211 message is printed. Note that only one of the three control
212 arguments full, truncate, or fold may be specified.
213
214
215 This command handles the following control characters
216 properly: newline, backspace, and tab. In addition, newpage
217 characters in the original segment are ignored, and vertical tab
218 characters appearing in the first position of a line are treated
219 as described above for the blocks control argument. All other
220 characters are assumed to occupy one horizontal printing position.
221 The columns may not line up properly if non-printing or escape
222 sequences appear in the output.
223
224
225 The segment produced by columns contains a newpage character
226 at the top of each page, except the first. It is assumed that the
227 first printing position after the newpage is line 4. Thus, a top
228 margin of 4 would result in one extra blank line after each
229 newpage. Bottom margins do not appear on segment output. Note
230 that if the page_length plus top_margin is greater than 62 the
231 defaults result in 63 the user must specify -no_endpage when
232 dprinting the segment, or extra blank lines may be inserted into
233 the output.
234
235
236 The following combinations of control arguments are
237 inconsistent:
238
239 minimize & n_columns
240 minimize & adjust
241 blocks & no_pagination
242 full & ^column_width & ^n_columns
243 margin & top_margin | bottom_margin
244 fold & truncate | full
245 truncate & full
246 full_last_page & no_pagination
247 page_length & no_pagination
248
249
250 The use of the no_pagination control argument or specifying
251 a very large value of page_length, together with minimize, full,
252 or fold, considerably increases the execution time of this
253 command. It is recommended that no_pagination only be used to
254 print relatively short segments on the terminal. Little paper is
255 saved by specifying no_pagination when the output is to be
256 dprinted. There is no significant additional cost in using
257 no_pagination, however, when neither minimize, full, nor fold are
258 specified.