ploticus: the pltab program

## The pltab program | Welcome Gallery Handbook |
| Manual page for The_pltab_program(PL)

## pltab

## SYNOPSIS

pltab tablefile [-small|-medium|-large|-landscape] [detail options]

## DESCRIPTION

pltab 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.``

## 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.``

## EXAMPLES

See the tables gallery examples and

## 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 pl options

## 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).``

## 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.``

## 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.

## 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.``

## PL OPTIONS

The pl command line options are generally supported by pltab, for purposes such as selecting output format, setting graphics defaults, etc.``

## 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`

## 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.``

## 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.

## 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.``

## 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.``

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

## 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).``

## 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.``

## 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 scripts

## 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.

## 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.``

## 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.)

## 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.``

## ENVIRONMENT

See pl environment

## 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.``

## AUTHOR

Stephen C. Grubb

## SEE ALSO

ploticus(1), pl(1), http://ploticus.sourceforge.net
data display engine
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` October 24, 2001.