#set TITLE = "The pltab program #include top

NAME
pltab

SYNOPSIS
pltab tablefile [-small|-medium|-large|-landscape] [detail options] #include space

DESCRIPTION
pltab is a table and list renderer. It can beautify plain ASCII tables and place #set FILE = "#plots" #set TAG = graphs #include link 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. #include space

FEATURES
pltab 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. #include space

EXAMPLES
See the tables gallery examples #include space

OUTPUT
This 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 #set FILE = "pl.1.html#options" #set TAG = "pl options" #include link #include space

TABLE STRUCTURE
Tables 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). #include space

SIMPLE EXAMPLE

Here 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. #include space

BASIC OPTIONS
These 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

    Render a small table in fairly large type using portrait orientation.

-medium

    Render a medium-sized table in medium type using portrait orientation.

-large

    Render a large table in smaller type using portrait orientation. If not enough content to require more than one page, table lines will be spaced vertically to fill the page.

-landscape

    Render a wide table in smaller type using landscape paper orientation. #include space

TABLE EMBELLISHMENT OPTIONS

-chartmode

    do a horizontal ruling on every line of the table body (to make a chart or log).

-chartmode2

    do a horizontal ruling on every line of the table body that does not begin with a space, to set of table sections (see SECTIONS below).

-shade

    do automatic alternating shaded background zones within table body to make tables easier for the eye. By default the shaded zones have a size of 3 lines.

-shademode1

    shaded zone boundary at any line that does not begin with a space. Allows shaded zones to follow table sections (see SECTIONS below). Implies -shade.

-shademode2

    shade any line that does not begin with a space; other lines are not shaded. Allows a shaded bar to mark section headings. Implies -shade.

-shadesize n

    size of shaded zones to be n lines (3). Implies -shade

-shadecolor color

    color for shaded zones. Default is gray(0.98). See colors for list of available color names. #include space

PL OPTIONS

The #set FILE = "pl.1.html#options" #set TAG = "pl command line options" #include link are generally supported by pltab, for purposes such as selecting output format, setting graphics defaults, etc. #include space

DETAIL OPTIONS
These 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

    top of title to be h inches below top of page (1.2)

-midline x

    table to be centered horizontally about an imaginary line x inches from left of page (4.4)

-width w

    table width to be w inches (scaled to input by default)

-height h

    table height to be h inches (scaled to input by default).

-multipage

    Explicitly have pltab produce a listing that spans multiple pages. This may be used when you wish to override default behavior.

-singlepage

    Explicitly have pltab produce a listing where everything is displayed on one page. May be used when you wish to override default behavior. Should be used along with -large or one of the other size options, unless you don't mind output scrolling off the bottom of the page.

-linesperpage n

    set the maximum number of table body lines that will appear on each page of a multi-page table (default is 40). Any group of lines greater than this will be broken across pages. Implies -multipage.

-notitle

    no title; process tablefile as body only

-noid

    suppress the identifier/timestamp at bottom of table

-diag

    display informational messages and table parameters to stderr.

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

    point size of body text to be p (default is 12). This, along with -height, determines the overall vertical line spacing of the page.

-font font

    use this PostScript font as the base font for the table (default is /Helvetica) when rendering in PostScript. Usually these fonts are available: /Helvetica /Helvica-Oblique /Helvetica-Bold /Helvetica-BoldOblique /Times-Roman /Times-Bold

-title p style

    adjust point size and set font of title text (default is: 3 B) p is relative to body size, e.g. 2 = 2 pt sizes larger than body. style may be one of B, I, BI, R.

-header p style

    adjust point size and set font of column header text (default is: 2 B). p is relative to body size, e.g. 2 = 2 pt sizes larger than body. style may be one of B, I, BI, R.

-sectionheading p style

    Adjust point size and set font of section heading lines (see SECTIONS below). p is relative to body size, e.g. 2 = 2 pt sizes larger than body. style may be one of B, I, BI, R.

-continue mode

    Control the (Continued..) label that appears at the bottom of all pages but the last with multipage output. mode may be one of C (centered), L (left adjusted), R (right adjusted), or omit. Default is C.

-delimchars charlist|none

    Normally pltab uses spaces and parentheses to delimit column entries. However this is not always desired, such as when text column entries contain one or more of them. This option allows you to specify the list of characters that you want to be considered as column delimiters, or none. You could also use this option to delimit on other characters.
    Example: -delimchars "()/"
    Example: -delimchars none #include space

COLUMN HEADERS
Table 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. #include space

MULTI-PAGE LISTS AND PAGE BREAKS
pltab 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. #include space

SECTIONS AND SECTION HEADINGS
A 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. #include space

TABLES HAVING MULTIPLE PANELS
Tables 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. #include space

EMBEDDED PLOTS AND GRAPHS
An 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 This essentially sets up categories scaling, where each row stub in the table becomes the category name. The page setup and geometry of the plotting area is done automatically by pltab; therefore the ploticus script should not invoke #proc page, nor should it attempt to define the plotting area rectangle.

#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 #include space

MORE COMPLICATED EXAMPLES

See ./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). #include space

OPTIONAL EMBEDDED OPERATORS
These 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]

    explicitly define where column headers end and table body begins (normally a heuristic is used to determine this; see TABLE PARSING RULES below). The #body line may also specify vertical rulings (see #vr below).

#buttvr

    stop vertical rulings on this line and butt them to a standard-weight horizontal ruling.

#center text

    center text horizontally. This may only be used in title portion.

#font f

    change to font f. f may be one of R regular, B bold, I itlaic, or BI bold italic. The font will be from the same family as the default font or that specified with -font.

#header [vrule format]

    explicitly define where title ends and column headers begin (normally a heuristic is used to determine this; see TABLE PARSING RULES below). The #header line may also specify vertical rulings (see #vr below).

#hr [vrule format]

    draw a horizontal ruling across the table at this point. The #hr line may also specify vertical rulings (see #vr below).

#hr-light
#hr-heavy
#hr-double

    variations of #hr.

#pagebreak

    explicit page break.

#plotbegin scriptfile #

    indicates where top-left of a ploticus graphic is to be placed. scriptfile is executed to render the graphic. The lone pound sign (#) indicates where the top-right is to be placed.

#plotend

    indicates where bottom of graphic is to be placed.

#pltaboptions opt1 opt2 .. optN

    allows command line options to be conveniently embedded within the table file. Any of the available command line options may be used, and the leading dash should be supplied. If additional options are actually given on the command line, these take precedence.
    Example: #pltaboptions -large -width 7.5 -linesperpage 40 -shademode2

#shadeblocks-on

    explicitly turn on default alternating shaded zones (not necessary if -shade specified)

#shadeblocks-off

    explicitly turn off alternating shaded zones

#shade-on

    explicitly begin a shaded zone

#shade-off

    explicitly end a shaded zone

#stopvr

    stop vertical rulings on this line

#textsize n

    change to a text size of n points. n may be an absolute point size or a +/- relative size.

#vr vrule format

    give an explicit vertical rule format. Vertical rule format should contain a '|' in any character column where a single vertical rule is desired, or 'H' in any character column where a heavy (actually double) vertical rule is desired. 'L' or 'LH' may be used to create a single or double vertical rule along the extreme left edge of the table.

#include space

EMBEDDED VARIABLES
The table input text is processed using the same script interpreter as ploticus scripts. Hence, @VARIABLES and #operators may be included. For more information, see #set FILE = scripts.html #set TAG = scripts #include link #include space

EMBEDDED OPERATOR EXAMPLE
Here 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.
#include space

TABLE PARSING RULES
The 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. #include space

NON-POSTSCRIPT OUTPUT MODES

If 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.) #include space

COLORS
Color 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. #include space

ENVIRONMENT
See #set FILE = "../doc/pl.1.html#environment" #set TAG = "pl environment" #include link #include space

BUGS

pltab'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. #include space

AUTHOR
Stephen C. Grubb #include space

SEE ALSO
ploticus(1), pl(1), www.sgpr.net #include bottom