SII

Preparing Information for Table API

The Table API gathers information from three sources to generate a table:

Frame document -- Reference pages, Table catalog
Initialization file
Table data/ASCII text file

There are certain rules that must be followed and certain data that must be present in these three sources in order for the API to function properly. This chapter gives a processing overview and explains the steps necessary to prepare these three information sources for the Table API.

Processing Overview

1. The user selects file to import (See "Adding a table" on page 2-2).

2. The file extension (suffix) is used to locate the appropriate processing rules in the initialization file.

3. The API extracts the format name from the initialization file by checking the ``Format'' and ``FormatNumcolumns'' parameters. If initialization file designates ``FormatNumcolumns=yes'', then the API looks at the first row of ASCII text and counts the number of columns. The number of columns is subtracted by one and appended to the format name as designated by the Format parameter. For example, if you have 5 columns of ASCII text, and the corresponding information in the initialization file says:


Format=Apple


FormatNumcolumns=yes

: then the complete name of the format will be ``Apple4''.

4. The Table API searches the reference pages of the current document for a table with a format name that matches the one it found in the previous step. If it does not find a match, it searches the table catalog. The matching format must be found in the reference pages or the table catalog or an error message will appear and the API will be unable to insert a table.

: Format found in reference pages:
: Format not found in reference pages:

5. Once API has initially created the table, it reads a line of ASCII text.

6. Using the format rules found in the initialization file and markup symbols in the ASCII text, the API formats the line of ASCII text and converts it into a table row. See "Text formatting" on page 3-8 for information on text formatting using markup symbols.

7. Steps 5 and 6 are repeated for each successive line of the text file.

External Graphics

Preparing Document Information

The Table API relies on the Frame document for much of the table formatting information. This includes row and column width, cell margins, ruling, shading, paragraph format, and other properties. The API looks for this information in the reference pages and the table catalog. See "Processing Overview" on page 3-1 for how the API searches for table format information. The best way to ensure that the required information is always in a document is to put it in the templates you use for your documents.

Creating Table Formats

1. On the body page of your template, use the FrameMaker Table menu to create one sample table of each type you plan to use in your documents. Refer to your FrameMaker manual if you are unfamiliar with creating tables. Type in some actual or sample data so you can see how the table will look when it is completed. You also may want to specify particular paragraph formats for different areas of your table.

All tables must have titles. If a table does not have a title, the API will be unable to insert a marker, and thus will fail to insert the table correctly. Do not select No Title from the Title Position pop- up menu on the Table designer window when designing a table. If your table does not have a title, you may create an `invisible' title by assigning a paragraph format to the title that is very small and has no automatic numbering.

2. When you have finished designing your table, choose New Format from the Commands pop-up menu in the Table Designer window. Type in the format name.

: Avoid typing blank spaces before and after the format name. Note that this format name will need to correspond to the Format parameter in the initialization file. See "Preparing the initialization file" on page 3-4.

3. Turn on Store in Catalog and Apply to Selection and click on Create.

4. Decide whether you are going to store the format in the table catalog or the reference pages.

: If a table format is relatively simple and does not have any heading, footing or title, you may want to store the format in the table catalog only. The table catalog will not store any custom properties, such as custom ruling and shading and straddled cells.
: If you add properties to a table after it has been imported, the changes you make will be erased when the tables are updated using the Refresh Tables option on the Special menu or the Book menu.
: Reference pages are commonly used in designing templates. The advantage of using reference pages over the table catalog is that more information can be stored in the reference pages. For example, you cannot store text in the table catalog. In the reference pages, you can save the headings, footers, and table title.
Note:: You actually save the format in both the reference pages and the table catalog. The API looks in the reference pages for a table with a specific format name, but the format also is stored in the table catalog.

5. Table catalog

: If you are storing the format in the table catalog only, you are done. Delete the table from the body page. If not go on to the next step.
: Reference pages
: If you are storing the table format in the reference pages, delete all but one body row in the table.
: You must leave at least one body row or Frame will delete the whole table. Leaving more body row text in the table will not prevent the API's operation from completing successfully, but deleting it will save you time and memory later on. When the table format is used by the API, all body row text is automatically deleted and replaced by imported text.

6. Highlight the entire table and copy it to the reference pages of your template.

Preparing the initialization file

The initialization file contains a list of all the different types of tables you intend to use and a few parameters associated with each one. The initialization file tells Frame how to construct the table.

A sample initialization file has been included with this release. This may be used as a reference or it may be modified to create a new initialization file. See also Appendix B, ``Sample Initialization file'' on page B-1.

Parameter	Valid Values	Description
`TableDef=xxx`	Any valid unix file extension: `xwd, rdelay, setup, etc.`	Marks the beginning of a new table definition. xxx should be the suffix of the filename containing the table data.
`Format=xxxxxxx`	Any valid FrameMaker table format name: `Table A, moose, deflist, etc.`	Specifies the name of the FrameMaker table format to be used for specified table definition.
`Delimiter=x\|yy`	A single character or hexadecimal value `2e, \|, *, 20, $, etc.`	Specifies the character to be used to indicate column separations in the ASCII text file.
`FormatNumcolumns=yes\|no`	`yes, no`	This indicates whether the table format should be selected based on the number of columns in the table data.
StradleColumns=(n,n,...,n)	`(), (1,2), (9,1,4,5), etc.`	Indicates which cells are to be straddled.

Initialization file syntax

The initialization file contains a series of table definition sections for each table format used. Each section should contain all the parameters listed below. Each parameter should be on a separate line. Do not insert blank spaces before or after the ``='' character.

TableDef=xxx

This parameter marks the beginning of a new table definition section. It corresponds to the file extension or suffix of the filename of the Cadence table or ASCII text file. This parameter is used by the API to match the table data to a table format name.

You have some ASCII text files named species.newt and trial.newt. The definition section for those tables must begin with

TableDef=newt

Format=xxxxxxx

This parameter indicates which table format the API should use. It should correspond to a format name in the FrameMaker document.

You want the table species.newt and trial.newt to use a table format that is listed in the tables catalog of your document as ``Apple''. The next line of your initialization file:

Format=Apple

Frame table format names are case sensitive, i.e., if the Frame table name is all lower-case letters, the Format parameter must also be in lower cases. You must also take blank spaces into account when typing in the format name. Leading or trailing blanks in the Frame table format name are not allowed.

Delimiter=x|yy

This parameter determines which character is used to indicate cell separations in the ASCII text or data file that is to be imported.

If only a single character is used, then x corresponds to the ASCII character used in the output table as the delimiter. If two characters are used, then yy corresponds to the hexadecimal representation of the character used as the delimiter.

Your .newt files use a period as a delimiter. 7c is the hexadecimal representation of ``|'', so either of the following could be the next line of your initialization file:

Delimiter=|

Delimiter=7c

``='' cannot be used as a delimiter character.

Be careful not to pick a delimiter that occurs in the text files to be imported. We suggest using the ``Tab'' character, as most software programs are capable of producing tab-delimited files.

FormatNumColumns=yes|no

This parameter determines whether the format name should depend on the number of columns in the data. Valid values are ``yes''and ``no''. You can use either upper-case letters or lower-case.

The API counts the number of columns in the first row of text. The number of columns in the table data is subtracted by one and appended to the end of the FrameMaker table format name previously specified.

The format of the .newt tables depends on the number of columns in a table. You would now have in your initialization file:

TableDef=newt

Format=Apple

Delimiter=.

FormatNumcolumns=Yes

Then, if you have 6 columns of ASCII text in species.newt, the complete format name that the API will look for in the Frame document will be Apple5.

All the .newt tables have the same number of columns and use exactly the same table format.Then you would write:

TableDef=newt

Format=Apple

Delimiter=.

FormatNumcolumns=no

The complete format name the API looks for in the Frame document for each .newt file would remain as Apple.

StradleColumns=(n,n,...,n)

This parameter determines which table cells are straddled.

The n's represent the columns that should be straddled when creating the Frame table. Cells that are vertically adjacent in the specified columns are joined into one cell if their contents are exactly the same. Columns are counted upwards from 0, where 0 corresponds to the leftmost column.

If no columns are straddled, you should enter:


StradleColumns=()

The following is the text of species.newt:

External Graphics

Figure 3-3. Sample ASCII text file.
In the initialization file, you have:


TableDef=newt


Format=Apple


Delimiter=|


FormatNumcolumns=no


StradleColumns=(0,2,3)

The resulting table would look like this:

Name	Type	Color	Speed	Awake?
Name	Type	Color	Speed	Awake?
Newt	Alpha	Blue	_fast	yes
	Beta	Blue		yes
	Sigma	Green		yes
	Epsilon	Green		yes
	Omega	Black	slow	yes
	Delta	Black		yes
	Gamma	Red		yes
	Omicron	Red		yes

If there is no straddling, your initialization file would read:


TableDef=newt


Format=Apple


Delimiter=|


FormatNumcolumns=no


StradleColumns=()

and the resulting table, using the same format and text file as above, would look like this:

Name	Type	Color	Speed	Awake?
Name	Type	Color	Speed	Awake?
Newt	Alpha	Blue	_fast	yes
Newt	Beta	Blue	_fast	yes
Newt	Sigma	Green	_fast	yes
Newt	Epsilon	Green	_fast	yes
Newt	Omega	Black	slow	yes
Newt	Delta	Black	slow	yes
Newt	Gamma	Red	slow	yes
Newt	Omicron	Red	slow	yes

Preparing data files for import

The table data file should be an ASCII text file. The suffix of the filename is used as the name of the table to be looked up in the initialization file. Thus, if the filename is:


species.newt

then the API would look for:


TableDef=newt

in the initialization file.

Row boundaries

The Table API treats each line of text as a table row. Thus, each row should be on a single line by itself.

The maximum number of columns in a table is 20, and the maximum length of a cell is 200 characters, including markup symbols. Maximum length of a line is 4,096 characters, including markup symbols.

Cell boundaries

Cell boundaries are denoted in the text file by a delimiter character which is specified in the initialization file. See "Preparing the initialization file" on page 3-4 and Appendix , ``Delimiter=x|yy'' on page 3-5.

The number of columns in the first row is used to determine the table format in cases where the format name depends on the number of columns.

Text formatting

Paragraph level formatting is provided by the FrameMaker table definition (See "Preparing Document Information" on page 3-3). Rudimentary character formatting is provided through a series of markup symbols as follows:

hard spaces off

no strikethrough

normal (no superscript, subscript)

With the exception of <$HR> and <$HS>, these are all properties which are bound to specific ranges of text. Thus, whenever there is a <$UN>, there must be a <$NX> at the end of the text to be underlined. All regular spaces bounded by <$O> and <$F> are replaced by hard spaces, whereas <$HR> and <$HS> are replaced by a single hard return or single hard space.

Let ``_'' represent a hard space. You want the following to appear in your table:

No_newts_were_harmed_during_the_filming_of_this_movie.

: You could type either of the following in your ASCII text file:
: <$O>No newts were harmed during the production of this movie.<F>
: No<$HS>newts<$HS>were<$HS>harmed<$HS>during<$HS>the<$HS>filming<$HS>of<$HS>this<$HS>movie.
Example.

: You want the following to appear in your table:
: Homo sapiens is a rare species!

Markup symbols may also be nested within each other.

You want the following to appear in your table:

The Descent of Man

: You would need to type in your text file:
: <$UN>The <$BO>Descent<NB> of Man<$NX>

Each set of markup symbols bounding a range of text must be in the same table cell.

: cold fusion
You want two cells in your table to have underlined text in them:

: Wrong
: <$UN>cold|fusion<$NX>

: Right
: <$UN>cold<$NX>|<$UN>fusion<$NX>
: where ``|'' is the delimiter character.

Table Inserter API: Contents Introduction Invoking the API Installation Error Messages Sample Initialization File How API uses Markers

[ Frame API's | SII Home Page | Contact Us ]