|
pltab
SYNOPSISpltab tablefile [-small|-medium|-large|-landscape] [detail options]DESCRIPTIONpltab is a table and list renderer. It can beautify plain ASCII tables and place graphs using a table-based model. The basic options are -small, -medium, -large, -landscape. Many other detail options are also available. Command line options may be embedded in the table file using the #pltaboptions operator (see below).pltab takes as its input a plain ascii tablefile containing a table or tabular listing (for example, the output produced by a program). It produces an attractive equivalent with optional embellishments and ploticus graphs. Basic results can usually be obtained without the need for any embedded formatting codes in the input.
pltab parses tablefile using a set of rules (see TABLE PARSING RULES below).
In addition, pltab understands
certain operators that may be embedded within table text.
FEATURESpltab can produce tables that span multiple pages, and includes features such as embedded data plots, images, graphical symbols, background shaded regions, horizontal and vertical rulings, and user control over font and size of title, column headers, section headings, and color of shaded regions.EXAMPLESSee the tables gallery examples![]() ![]() OUTPUTThis tool is most often used to produce printed copy, thus the default behaviour is for PostScript to be written to standard output, where it may be piped to the print spooler or placed into a file for previewing using ghostview (see simple example below). For other output modes, see NON-POSTSCRIPT OUTPUT MODES, below.
The output mode can be changed using certain of the
pl options
TABLE STRUCTURETables do not need to include any embedded formatting codes in order to achieve basic results. There are two rules that tables must generally follow to be usable with pltab: 1) there should be at least two blank lines below the title; and 2) columns and column headers should be separated horizontally from each other by at least two spaces. (Rule 1 is waived if an #header embedded operator is used or if -notitle is used).SIMPLE EXAMPLEHere is a small example table that pltab can render nicely: Completion of Audit Procedures 08-31-98 No. No. (%) Group Eligible Audited ------- -------- -------- A (1 yr) 40 23 ( 57) A (2 yr) 18 14 ( 78) B 80 60 ( 75) C 37 16 ( 43) D 44 28 ( 64) Total 219 141 ( 64) To render this table so that it fills a standard page, this command could be used (assume the table text is located in a file called table1): pltab -small table1 > out.ps
The file out.ps will then contain
PostScript and may be printed (lp out.ps)
or previewed.
BASIC OPTIONSThese basic options are for convenience and provide settings to suit many purposes. Try one of these first before delving into the detail options. If a basic option is used, it must appear to the left of other command line options. Also, only one of them can be used; combinations don't work. If none of these basic options are given, the overall default behavior is like -large except that lines will not be spaced vertically to fill the page.-small
-medium
-large
-landscape
TABLE EMBELLISHMENT OPTIONS-chartmode
-chartmode2
-shade
-shademode1
-shademode2
-shadesize n
-shadecolor color
PL OPTIONS
The
pl command line options
are generally supported by pltab, for purposes such as
selecting output format, setting graphics defaults, etc.
DETAIL OPTIONSThese are additional command line options to control various details, and should appear on the command line to the right of any basic option, so that they override basic option settings.Geometry options: -top h
-midline x
-width w
-height h
-multipage
-singlepage
-linesperpage n
-notitle
-noid
-diag
Font and text size options. In these descriptions the following indicate variations on the base font: B=bold, I=italic, BI=bold italic, R=regular. -bodysize p
-font font
-title p style
-header p style
-sectionheading p style
-continue mode
-delimchars charlist|none
COLUMN HEADERSTable column headers usually include text and ruling characters. Text headers are centered, however not always perfectly. Ruling characters are dash (-), equals sign (=), and underscore (_). pltab renders groups of these characters as standard lines, heavy lines, or thin lines, respectively.
When using some of the embellishment modes such as -chartmode, pltab needs
to find where the column headers end and the table body begins.
It can do this automatically if the last line of the column headers
is mostly comprised of horizontal ruling
characters (dashes (-), equals signs (=), or underscores (_)).
Otherwise, an embedded #body operator must be used.
MULTI-PAGE LISTS AND PAGE BREAKSpltab attempts to make longer tables overflow automatically onto multiple pages. To have more control over page breaks, the -linesperpage command line option may be used, or #pagebreak operators may be embedded within the table text. When a page break occurs, table title and headers are replicated at top of the next page. Page numbers (for pages 2 and up) are displayed in the upper right corner. Alternating shading will reset at page boundary.SECTIONS AND SECTION HEADINGSA table body may be divided into "sections". No special formatting is needed except that the first line of each "section" must start immediately at the beginning of the line and subsequent lines within the section must be indented by one or more spaces. If this is done, the first line of a section (called section heading) may be set off by bolding, larger type size, or shading using certain command line options.TABLES HAVING MULTIPLE PANELSTables having multiple panels generally work well (see ./example/table3 & 4 for instance). The panels do not need to have like structure. There is no way to have more than one title per page however. An alternate approach is to render several tables separately (using appropriate -top, etc.) using -eps and then combine the PostScript output so that all tables are together on one page.EMBEDDED PLOTS AND GRAPHSAn important use of pltab is to render graphs using its table-based model. As opposed to pl, where plotting areas must be layed out at specific page locations, when using pltab, plots are tied to table stubs, which "float" up or down, or even overflow onto the following page, depending on the content. This make possible quite rich data displays with minimal set up and coding.There are two key operators embedded in the table input when working with graphs: #plotbegin and #plotend. The row locations of #plotbegin and #plotend control the top and bottom of the plotting area. The column location of the # in #plotbegin determines the plot area's left, and the standalone # off to the right determines the plot area's right. After the word #plotbegin a ploticus script file name is given; this script is executed when pltab is finished with each page.
The ploticus script must have a #proc areadef with this setting:
yscaletype: pltab
#proc catslide may be used to adjust placement up or down relative to the row stubs, to do plotted pairs, for example. The $nextstub() function may be used to get successive stub entries. Usage is $nextstub(len) where len is the maximum desired length of the result. For an example see caselist
More table-based graph examples are
MORE COMPLICATED EXAMPLESSee ./examples for a number of test tables and pltab command examples. The following example: pltab table8 -height 10 -header 2 BI -shademode2 -sectionheading 1 BI > postscript would take the table located in ascii file table8, render it into an area 10 inches high. The table will be centered on the page, and width will be determined by the input. Column headers will be rendered 2 pts larger than table body in bold italic. Section headings within the table (lines that are not indented) are rendered using a shaded rectangle background in helvetica bold italic 1 pt larger than table body. The following example: pltab longtable -width 7 -chartmode > postscript
would take the table located in ascii file longtable, and
render it onto multiple pages, scaled to a width of 7 inches.
Each page will have approximately the same number of lines.
Each line will have a horizontal ruling (chart mode).
OPTIONAL EMBEDDED OPERATORSThese operators may optionally be embedded within table text. Each should appear at the beginning of a line. Also note that these operators will occupy one line in the output, sometimes resulting in blank lines or gaps.#body [vrule format]
#buttvr
#center text
#font f
#header [vrule format]
#hr [vrule format]
#hr-light
#pagebreak
#plotbegin scriptfile #
#plotend
#pltaboptions opt1 opt2 .. optN
#shadeblocks-on
#shadeblocks-off
#shade-on
#shade-off
#stopvr
#textsize n
#vr vrule format
EMBEDDED VARIABLESThe table input text is processed using the same script interpreter as ploticus scripts. Hence, @VARIABLES and #operators may be included. For more information, see scriptsEMBEDDED OPERATOR EXAMPLEHere is an example showing how vertical rulings may be done using #vr. Also, #header and #body are used since the table structure does not conform to pltab's requirements.PERSONNEL CERTIFICATION STATUS 7/22/98 #header Full-scale Equipment Trial ----------- --------- #vr | | | | | | | Photographer F N L H N,B #body 01 - Atlanta 0181-Linn Ward x x x x 0182-Jim Harman x x x x 0183-Wendy Ott x x x x etc. TABLE PARSING RULESThe following rules are applied when parsing the table text.1. Title is everything from the beginning of the file to the first occurance of two consecutive blank lines. (The #header embedded operator overrides this rule.) 2. Column headers begin just below the title. Column headers end at the lowest line having mostly ruling characters such as dash(-), underscore(_), or equals(=). pltab assumes the headers will end somewhere in the first 20 lines. (The #body embedded operator overrides this rule and may be used when this rule fails.) 3. Body is everything else. 4. Column headers must be separated horizontally at least two spaces. 5. Column headings (such as in the example above) often contain groups of ruling characters such as dashes (-), underscores (_), or equals signs (=). A dash gives a standard-weight ruling; equals sign gives a double ruling; underscore gives a light-weight ruling. Within the table body: 6. The first non-whitespace text found within 8 characters of the beginning of a line is considered a row label and will be placed flush-left. 7. Columns must be separated horizontally by at least two spaces. 8. Integers are placed flush-right. Numbers may begin with +/-. Decimal numbers are aligned on decimal point. 9. Parentheses () and brackets ([] and <>) are by default considered independent from nearby numbers or text in the table body. This may be overriden using the -delimchars option.
10. Cells which are determined not to be numbers, row labels, or rulings will
be centered in the column.
NON-POSTSCRIPT OUTPUT MODESIf PNG output is being produced, results are placed into file out.png unless -o is specified on command line. (Pages 2 and up of multi-page PNG output are always named outp2.png, outp3.png and so on.) If GIF output is being produced, results are placed into file out.gif unless -o is specified on command line. (Pages 2 and up of multi-page GIF output are always named outp2.gif, outp3.gif and so on.)
If EPS output is being produced, results are placed into file
out.eps unless -o is specified on command line.
(Pages 2 and up of multi-page EPS output are always named outp2.eps, outp3.eps
and so on.)
COLORSColor may be specified by gray(N) where N is 0.0 (black) to 1.0 (white), or by rgb(R,G,B) where R, G, and B are each 0.0 to 1.0. No embedded spaces are allowed in either specification.ENVIRONMENTSee pl environmentBUGSpltab's heuristics have been developed in an environment where particular types of tables are used. Other unanticipated table structures may give less satisfactory results. Use of larger fonts for title, section headings etc. does not increase vertical line spacing in these areas.
Operators such as #font result in blank lines (gaps) in the output.
AUTHORStephen C. GrubbSEE ALSOploticus(1), pl(1), www.sgpr.net |
![]() data display engine Copyright Steve Grubb ![]() |