diff options
Diffstat (limited to 'src/preproc/tbl/tbl.man')
| -rw-r--r-- | src/preproc/tbl/tbl.man | 332 |
1 files changed, 296 insertions, 36 deletions
diff --git a/src/preproc/tbl/tbl.man b/src/preproc/tbl/tbl.man index 42dac252..058d6009 100644 --- a/src/preproc/tbl/tbl.man +++ b/src/preproc/tbl/tbl.man @@ -19,6 +19,8 @@ the original English. .TH @G@TBL @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" .SH NAME @g@tbl \- format tables for troff +. +. .SH SYNOPSIS .B @g@tbl [ @@ -27,6 +29,8 @@ the original English. [ .IR files \|.\|.\|. ] +. +. .SH DESCRIPTION This manual page describes the GNU version of .BR tbl , @@ -53,6 +57,8 @@ will be read. A filename of .B \- will cause the standard input to be read. +. +. .SH OPTIONS .TP .B \-C @@ -64,47 +70,291 @@ even when followed by a character other than space or newline. .TP .B \-v Print the version number. +. +. .SH USAGE -Only the differences between GNU .B tbl -and Unix -.B tbl -are described here. -.LP +expects to find table descriptions wrapped in the +.B .TS +(table start) and +.B .TE +(table end) macros. +The line immediately following the +.B .TS +macro may contain any of the following global options: +. +.TP +.B center +Centers the table (default is left-justified). +The alternative keyword name +.B centre +is also recognized. +. +.TP +.BI delim( xy ) +Use +.I x +and +.I y +as start and end delimiters for +.BR @g@eqn (@MAN1EXT@). +. +.TP +.B expand +Makes the table as wide as the current line length. +. +.TP +.B box +Encloses the table in a box. +. +.TP +.B doublebox +Encloses the table in a double box. +. +.TP +.B allbox +Encloses each item of the table in a box. +. +.TP +.B frame +Same as box (GNU tbl only). +. +.TP +.B doubleframe +Same as doublebox (GNU tbl only). +. +.TP +.BI tab( x ) +Uses the character +.I x +instead of a tab to separate items in a line of input data. +. +.TP +.BI linesize( n ) +Sets lines or rules (e.g. from +.BR box ) +in +.IR n -point +type. +. +.TP +.B nokeep +Don't use diversions to prevent page breaks (GNU tbl only). Normally .B tbl attempts to prevent undesirable breaks in the table by using diversions. -This can sometimes interact badly with macro packages' own use of diversions, -when footnotes, for example, are used. -The -.B nokeep -option tells -.B tbl -not to try and prevent breaks in this way. +This can sometimes interact badly with macro packages' own use of +diversions, when footnotes, for example, are used. +. +.TP +.BI decimalpoint( c ) +Set the character to be recognized as the decimal point in numeric +columns (GNU tbl only). +. .LP -The -.B decimalpoint -option specifies the character to be recognized as the decimal -point character in place of the default period. -It takes an argument in parentheses, which must be a single -character, as for the +The global options must end with a semicolon. +There might be whitespace after the option and its argument in parentheses. +.LP +After global options come lines describing the format of each line of +the table. +Each such format line describes one line of the table itself, except that +the last format line (which you must end with a period) describes all +remaining lines of the table. +A single key character describes each column of each line of the table. +You may run format specs for multiple lines together on the same line by +separating them with commas. +.LP +You may follow each key character with specifiers that determine the font +and point size of the corresponding item, that determine column width, +inter-column spacing, etc. +.LP +The longest format line defines the number of columns in the table; missing +format descriptors at the end of format lines are assumed to be `L'. +Extra columns in the data (which have no corresponding format entry) are +ignored. +.LP +The available key characters are: +. +.TP +c,C +Centers item within the column. +. +.TP +r,R +Right-justifies item within the column. +. +.TP +l,L +Left-justifies item within the column. +. +.TP +n,N +Numerically justifies item in the column: Units positions of numbers are +aligned vertically. +. +.TP +s,S +Spans previous item on the left into this column. +. +.TP +a,A +Centers longest line in this column and then left-justifies all other lines +in this column with respect to that centered line. +. +.TP +^ +Spans down entry from previous row in this column. +. +.TP +_,- +Replaces this entry with a horizontal line. +. +.TP += +. +Replaces this entry with a double horizontal line. +. +.TP +| +The corresponding column becomes a vertical rule (if two of these are +adjacent, a double vertical rule). +. +.LP +A vertical bar to the left of the first key-letter or to the right of the +last one produces a line at the edge of the table. +.LP +Here are the specifiers that can appear in suffixes to column key letters: +. +.TP +b,B +Short form of fB (make affected entries bold). +. +.TP +i,I +Short form of fI (make affected entries italic). +. +.TP +t,T +Start an item vertically spanning rows at the top of its range rather than +vertically centering it. +. +.TP +d,D +Start an item vertically spanning rows at the bottom of its range rather +than vertically centering it (GNU tbl only). +. +.TP +v,V +Followed by a number, this indicates the vertical line spacing to be used in +a multi-line table entry. +If signed, the current vertical line spacing is incremented or decremented +(using a signed number instead of a signed digit is a GNU tbl extension). +A vertical line spacing specifier followed by a column separation number +must be separated by one or more blanks. +No effect if the corresponding table entry isn't a text block. +. +.TP +f,F +Either of these specifiers may be followed by a font name (either one or two +characters long), font number (a single digit), or long name in parentheses +(the last form is a GNU tbl extension). +A one-letter font name must be separated by one or more blanks from whatever +follows. +. +.TP +p,P +Followed by a number, this does a point size change for the affected fields. +If signed, the current point size is incremented or decremented (using a +signed number instead of a signed digit is a GNU tbl extension). +A point size specifier followed by a column separation number must be +separated by one or more blanks. +. +.TP +w,W +Minimal column width value. +Must be followed either by a +.BR @g@troff (@MAN1EXT@) +width expression in parentheses or a unitless integer. +If no unit is given, en units are used. +Also used as the default line length for included text blocks. +If used multiple times, the last entry takes effect. +. +.TP +e,E +Make equally-spaced columns. +. +.TP +u,U +Move the corresponding column up one half-line. +. +.TP +z,Z +Ignore the corresponding column for width-calculation purposes. +. +.LP +A number suffix on a key character is interpreted as a column +separation in ens (multiplied in proportion if the +.B expand +option is on). +Default separation is 3n. +.LP +The format lines are followed by lines containing the actual data for the +table, followed finally by +.BR .TE . +Within such data lines, items are normally separated by tab characters (or +the character specified with the .B tab -option. +option). +Long input lines can be broken across multiple lines if the last character +on the line is `\e' (which vanishes after concatenation). .LP -The -.B f -format modifier can be followed by an arbitrary length -font name in parentheses. -.LP -There is a -.B d -format modifier which means that a vertically spanning entry -should be aligned at the bottom of its range. -.LP -There is no limit on the number of columns in a table, nor any limit -on the number of text blocks. -All the lines of a table are considered in deciding column -widths, not just the first 200. +A dot starting a line, followed by anything but a digit is handled as a +troff command, passed through without changes. +The table position is unchanged in this case. +.LP +If a data line consists of only `_' or `=', a single or double line, +respectively, is drawn across the table at that point; if a single item in a +data line consists of only `_' or `=', then that item is replaced by a +single or double line, joining its neighbours. +If a data item consists only of `\e_' or `\e=', a single or double line, +respectively, is drawn across the field at that point which does not join +its neighbours. +.LP +A data item consisting only of `\eRx' (`x' any character) is replaced by +repetitions of character `x' as wide as the column (not joining its +neighbours). +.LP +A data item consisting only of `\e^' indicates that the field immediately +above spans downward over this row. +.LP +A text block can be used to enter data as a single entry which would be +too long as a simple string between tabs. +It is started with `T{' and closed with `T}'. +The latter must start a line, probably followed by other data columns +(separated with tabs). +.LP +To change the data format within a table, use the +.B .T& +command (at the start of a line). +It is followed by format and data lines (but no global options) similar to +the +.B .TS +request. +. +. +.SH "INTERACTION WITH @G@EQN" +.BR @g@tbl (@MAN1EXT@) +should always be called before +.BR @g@eqn (@MAN1EXT@) +.RB ( groff (@MAN1EXT@) +automatically takes care of the correct order of preprocessors). +. +. +.SH "GNU TBL ENHANCEMENTS" +There is no limit on the number of columns in a table, nor any limit on the +number of text blocks. +All the lines of a table are considered in deciding column widths, not just +the first 200. Table continuation .RB ( .T& ) lines are not restricted to the first 200 lines. @@ -113,13 +363,15 @@ Numeric and alphabetic items may appear in the same column. .LP Numeric and alphabetic items may span horizontally. .LP -.B tbl +.B @g@tbl uses register, string, macro and diversion names beginning with .BR 3 . When using -.B tbl +.B @g@tbl you should avoid using any names beginning with a .BR 3 . +. +. .SH BUGS You should use .BR .TS\ H / .TH @@ -157,7 +409,7 @@ instead of .BR bp . .LP Using \ea directly in a table to get leaders will not work. -This is correct behaviour: \ea is a +This is correct behaviour: \ea is an .B uninterpreted leader. To get leaders use a real leader, either by using a control A or like @@ -173,6 +425,14 @@ A\e*a;B \&.TE .ft .fi +. +. +.SH REFERENCE +Lesk, M.E.: "TBL -- A Program to Format Tables". +For copyright reasons it cannot be included in the groff distribution, +but copies can be found with a title search on the World Wide Web. +. +. .SH "SEE ALSO" .BR groff (@MAN1EXT@), .BR @g@troff (@MAN1EXT@) |