# transpec

transpec(5)                   File Formats Manual                  transpec(5)

Name
transpec - translation specification for instant

Synopsis
file.ts

Description
The  transpec  file is used by the instant program to translate an SGML
document instance to a format suitable for  a  formatting  application.
The convention is to name the file with the suffix .ts.

A  transpec  file  is  composed  of  a number of individual translation
specs.  Each translation spec (transpec) is made  up  of  a  number  of
fields, one per line.  Translation specs are separated by a line with a
leading dash.  Text after the dash is ignored.  Fields are composed  of
two  parts,  a  name and a value, separated by a colon.  The colon must
immediately follow the name, and any amount of whitespace  (blanks  and
tabs) may be present between the colon and value.  Values should not be
quoted, and you should be careful of trailing spaces.  (Trailing  space
will be considered part of the value.)  Quotes, if they appear, will be
considered part of the value of the  fields.   Lines  that  begin  with
whitespace  (blanks  and tabs) are a continuation of the previous line;
the leading space is ignored.  These characteristics are  very  similar
to those of e-mail headers.  Lines beginning with a # (number sign) are
comments and blank lines are ignored.

Field Descriptions
Some fields are for identifying criteria that determines if a  particu-
lar  spec  matches  an  element  in  the instance.  Others specify what
action is to take place when a match happens, such as sending  text  to
the output stream.

Criteria fields
Criteria  fields  restrict the conditions under which a single transla-
tion spec will apply.  If each field specified in a particular transpec
matches  an  element under consideration in the document instance, then
that translation spec is said to match.  The  appropriate  actions,  as
specified in that spec, are then taken.  The program, instant, searches
the list of transpecs in the order given in the file.   Therefore,  the
more  restrictive specs (those with more criteria) should appear before
less restrictive ones.

For quick reference, this is a brief summary of the  possible  criteria
fields for translation. A complete discussion of each follows.

Field Label   Field Value        Description
GI            gi ...             name of this GI
AttValue      attname reg-expr   current element has attribute with value
Content       reg-expr           is reg-expr in char content>
Context       context            element context, up the tree
NthChild      number             current element is Nth child of its parent
PAttSet       attname (val)      parent has this attribute set (optional to value val)
Relation      relationship gi    gi has relationship to current element
VarREValue    var REvalue        variable is set to regular expression value
VarValue      var value          variable is set to value

GI: gi [...]
gi  is  the  name of the generic identifier, or element name, to
consider.  More than one GI may appear in this field.

AttValue: attname regular-expression
This is an  attribute  name-value  pair,  where  attname  is  an
attribute  if  the  GI.   The  regular-expression is of the form
accepted by the unix program egrep.  This pair  is  compared  to
the  corresponding  attribute  name-value  pairs of the GI under
consideration.  To simply test if an attribute us set, use .  (a
dot)  for  regular-expression.   There  may  be more than one of
these lines for each transpec.

Content: regular-expression
This specifies that the  character  content  of  GI  contains  a
string matching the regular-expression.

Context: context
This  specifies  the  context in which to apply this translation
spec.  It is either a list of generic identifiers or  a  regular
expression  describing a list of generic identifiers, looking up
the hierarchy.  The first is the parent of the GI.

NthChild: number
This specifies that the GI is the numberth child element of  its
parent.   Children  are numbered starting with 1.  Negative num-
bers may be used to  indicate  order  counting  backwards.   For
example, -1 denotes the last child.

PAttSet: attname
This  specifies that the parent has this attribute, attname, set
to any value (not IMPLIED).  A value to match may optionally  be
specified after attname.

Relation: relationship gi
This  specifies that the current element has the relationship to
the named gi.  The acceptable relationships are: ancestor  (any-
where  up  the  tree), child (immediate child), descendant (any-
where down  the  tree),  parent  (immediate  ancestor),  sibling
(share  same parent element), sibling+ (any later sibling), sib-
ling+1 (the immediately following sibling), sibling-  (any  ear-
lier sibling), sibling-1 (the immediately following sibling).

VarREValue: varname REvalue
This  specifies  that  the global variable varname has the value
REvalue, where REvalue is a regular expression (see the VarValue
statement).

VarValue: varname value
This  specifies  that  the global variable varname has the (lit-
eral) value value (see the VarREValue statement).

There are two special GIs.  If specified, _Start and _End are processed
as  if they were GIs in the instance at the start and end of the trans-
lation, respectively.  Their criteria are never  checked.   Only  their
actions are performed.

Action fields
For  quick  reference, this is a brief summary of the action fields for
translation. They are only performed if all the criteria are satisfied.
A complete discussion of each follows.

Field Label   Field Value   Description
Action        spec-id       use transpec whose spec ID is spec-id'
EndText       text          text for end of element
Increment     name          increment variable name'
Ignore        key           flag for ignoring element's children and/or data
Message       text          text to send to stderr
Quit          text          print text and quit program
Replace       text          replace this subtree with text
Set           name value    set variable name to value
SpecID        spec-id       unique Spec ID (int) of this spec
StartText     text          text for start of element

Action: spec-id
Use the actions of the spec identified by the SpecID with match-
ing identifier spec-id.

EndText: text
This specifies text to be output when the end tag is processed.

Ignore: key
This specifies that the data or children for this element are to
be  ignored.   Set  key  to  all to ignore the element (data and
child elements), to data to ignore the immediate character  data
content  (child elements are still descended into), and to chil-
dren to process the immediate character  data  content  but  not
descended  into child elements.  Other actions specified in this
transpec are still performed, however.

Increment: name
This is used to increment a variable whose value  is  a  number.
If  the  variable is not a number, no action will be taken.  The
variable must have been previously defined.  This action is done
immediately before EndText.  There may be more than one of these
lines for each transpec.

Message: text
This specifies a string to be printed to the standard error when
the matching element is processed.  It is intended for informing
the user of the progress of the translation.  It  is  also  used
for  validation  of instances (see the -v flag of instant(1)); a
spec would be written to  recognize  a  construct  that  is  not
allowed.  This action is done immediately after StartText.  Mes-
sages are also useful for debugging spec files; one is  able  to
easily  tell  when a matching spec is processed, without looking
at the actual output of the translation.   Note  that  the  spec
writer  is  responsible for putting newlines (\n) in the message
text.

Replace: text
This specifies text to replace the current subtree  with.   This
is equivalent to StartText and Ignore.

Quit: text
This  specifies  text  to be printed to the standard error.  The
program then terminates with exit status 1.   This  is  intended
for  bailing  out  when  an  undesirable instance is encountered
(such as when it is known that the  formatting  application  can
never handle a class of components, like tables).

Set: name value
This  is  used to set a variable whose name is name and value is
value.  Names that would  be  valid  for  GIs  in  the  document
instance are valid for variable names.  value is the rest of the
line and may be any string.   This action  is  done  immediately
before  EndText.   There may be more than one of these lines for
each transpec.  See the discussion on variables below.

SpecID: spec-id
This names the spec with the number  spec-id.  Other  specs  may
refer  to  this  one  by  this  number  by an Action field or an
_action special variable.  This is used for cases where  several
specs to perform the exact same action.

StartText: text
This  specifies  text  to  be  output when the start tag is pro-
cessed.

Other Fields
These fields may appear anywhere.  The action occurs when the  transla-
tion spec file is read, before any elements are translated.  Theses are
independent of any element processing.

Var: name value
This is used to define a variable whose name is name  and  value
is  value.   It  is similar to Set, but it may occur anywhere in
the file and takes effect when the spec file is read.

Text Strings
The text referred to in the StartText, EndText,  Replace,  and  Message
actions is more than simple character strings.  Special sequences allow
more complex output.

One type of special sequence is for C-style  string  processing.   Most
special characters are escaped with a \ (backslash). Like in C or shell
programs, to print a \ (backslash), you must  escape  it  with  another
backslash. These special character strings are:

\n (backslash-n)
This  specifies that a newline character is to be printed to the
output stream.

\r (backslash-r)
This specifies that a carriage return character is to be printed
to the output stream.

\t (backslash-t)
This specifies that a tab character is to be printed to the out-
put stream.

\s (backslash-s)
This specifies that a space is  to  be  printed  to  the  output
stream.  This is useful for the end of a transpec line, where it
can be difficult to tell if a blank is present at the end.

\007 (backslash-007)
This specifies that the character whose octal value is 007 is to
be printed to the output stream.  This works for any octal char-
acter value.

^ (caret)
This specifies the that position in the string will  be  at  the
start of a line in the output stream.

If  the  first  token  of  the text string is #include, then the second
token is taken to be a file name and that file  is  included.   If  the
file  is  not  found,  the  library  directory,  as mentioned above, is
searched.  If the text string starts with a ! (exclamation point),  the
rest  of  the line is taken to be a command and the output of that com-
mand is inserted.

An element's attributes may also be used in the text of output  fields.
To use an attribute value, precede its name with a ${ (dollar sign-left curly bracket) and follow it with a } (right curly bracket). (This style is followed by the Bourne shell.) For example,${TYPE}.  If the
attribute is not set (not IMPLIED), nothing will be printed to the out-
put  stream.   To  specify  a value to use if the attribute is not set,
place the value after the attribute name, separated  by  a  space.   To
return  the  attribute  value  in  lower-case,  add a colon followed by
lower-case l (${TYPE:l}. Variables Variables in instant are similar to those in many other string-oriented programming languages, such as sh and awk. They are set by: Var: name value and Set: name value. Values may be set and reset to any string. In a Var line, if the value begins with a !, then the rest of the line is executed as a command, and its output is taken as the value. A reference to the value of a variable follows the same syntax as a reference to the value of an attribute:${name}.  If that variable has
not been defined, a null value will be returned.  A default  value  can
be  returned  instead  of  null  for an undefined variable by using the
form:  ${name default}. Variables may be used as attributes are, that is in any of the text strings mentioned above. In fact, if an attribute name is referred to and it is not set for a given element, instant looks for a variable with the same name. This way global defaults can be set. If you want to be sure that you are accessing a local variable value, not an attribute value, you can use lower or mixed case names. Attribute names, as passed by nsgmls, are in upper case. Any number of Var actions may appear in the spec file. These set the values of the variables before any translation takes place. The Set actions within transpecs are performed when that spec is processed when an element matches the given criteria. Preset Variables Several variables are preset by instant upon start of the program. Their values may be overridden in transpec files or on the command line. date This is the date and time that the program started. The format is: Tue 10 Aug 1993, 16:52. host This is the name of the host where the program is run. It is what is returned by the gethostname library call. transpec This is the translation spec filename. user This is the login name of the user running the program. Special Variables There is a collection of special variables called special variables. These are identified by starting the names with a _ (underscore). This is a summary of the special variables. A complete discussion of each special variable follows. spec-id refers to a number specified in a SpecID field. When used in a special variable, it means to perform the action in that translation spec. Note that when a spec-id is given in a special variable, the default is to perform the translation spec named by the spec-id ignoring of any criteria statements found there. For most special variables that use a spec-id, postpending a "t" to the spec-id (with no spaces between them, eg, "${_followrel child TITLE 15t}"), will cause  the  criteria  state-
ments  in  the  named  translation spec to evaluate successfully before
that translation spec will be processed.

Variable Usage                       Description
_action spec-id                      do spec with id spec-id
_allatts                             print all attribute/value pairs
_attval att [value] spec-id          use spec-id if attribute matches
_chasetogi gi spec-id                follow IDREFs until gi found
_eachatt att spec-id [spec-id]       do spec-id for each word of attribute value
_eachcon spec-id [spec-id]           do spec-id for each word of content
_env env-variable                    return value of env variable
_filename                            filename of notation
_find rel gi spec-id                 find gi based on relationship
_followlink [attname] spec-id        follow IDREFs [attname] and use spec-id
_followrel rel gi spec-id            do spec-id on rel if it matches
_gi [M|L|U]                          return GI name; M, L, U case
_id id [spec-id]                     find element with ID and use spec-id
_include filename                    insert file here
_infile [line]                       instance filename [and line number]
_insertnode S|E spec-id              do spec-id when element is traversed

_isset var [value] spec-id           do spec-id if variable matches
_location                            print location of current element
_namelist spec-id [spec-id]          content is namelist, do spec-id for each
_nchild [gi]                         number of child elements [named attname]
_osftable format [flag]              print table format specification
_path                                print path to current element
_pattr attname                       value of parent's attribute
_pfind args ...                      same as _find, but start at parent
_relation rel gi spec-id [spec-id]   do spec-id if relation matches
_set var value                       set variable to value
_!command                            command to run

_action spec-id
Use the actions of the spec identified by the SpecID with match-
ing  identifier  spec-id.   This behaves similarly to the Action
action, but is in addition to the present translation spec.

_allatts
Print all attribute name-value pairs of the current  element  to
the  output  stream.   The  name  and value are separated by a =
(equals sign), and the value is surrounded by quotes.  This  can
be useful for creating a normalized version of the instance.

_attval attname [value] spec-id
If  the  current element has an attribute named attname, option-
ally whose value matches value, use the actions of the  transpec
identified by spec-id.

_chasetogi gi spec-id
Follow IDREF attributes until if finds an element whose GI is gi
or which has a child element with that GI.  It  will  apply  the
transpec  spec-id  to that element.  By default, instant assumes
the attributes named LINKEND, LINKENDS, and IDREF  are  of  type
IDREF or IDREFS.  (This corresponds with the OSF DTDs.)  You can
change this by setting the variable link_atts to  a  space-sepa-
rated list of attribute names.

_eachatt att spec-id [spec-id2]
The  transpec  named  by  spec-id  is invoked once per each word
found in the value of the  attribute  att.   Inside  the  target
transpec,  the  current word being processed is available in the
variable named each_A (${each_A}). If spec-id2 is specified, it will use spec-id for the first word in the attribute and spec- id2 for the others. _eachcon spec-id [spec-id2] The transpec named by spec-id is invoked once per each word found in the content of the current element. Inside the target transpec, the current word being processed is available in the variable named each_C (${each_C}).  If spec-id2 is specified, it
will use spec-id for the first word in the content and  spec-id2
for the others.

_env env-variable
Print  the value of the environment variable env-variable to the
output stream.

_filename
Print the filename of the notation associated with this element,
if  any.   This is used to get the filename of an external nota-
tion entity reference.  For example, to print  the  filename  in
the  latex  macro  from  the  epsf  macro  package,  use \\epsf-
boxi{${_filename}}. _find [top] relationship args ... spec-id Descend the document hierarchy finding elements that match one of several criteria. When one is found, the action specified by spec-id is performed. If top is specified, the search starts at the top of the document hierarchy, rather than at the current element. The possible values for relationship are gi, gi-par- ent, parent, and attr, and take different arguments. Explana- tions may be best done by example: _find gi CHAPTER 123 means to find elements whose GI is CHAPTER, and perform action 123; _find gi-parent TITLE CHAPTER 124 means to find elements whose GI is TITLE and whose parent is CHAPTER, and perform action 124; _find parent BODY 125 means to find elements whose parent's GI is BODY, and perform action 125; _find attr TYPE UGLY 125 means to find elements whose attribute named TYPE is set to UGLY, and perform action 126. _followlink [attname] spec-id When processing an element, instant will follow the IDREF attributes until an element with no IDREF attributes is found. It will then apply the transpec specified by spec-id to that element. If specified, it will follow the link pointed to by attname. By default, instant assumes the attributes named LINK- END and LINKENDS are if type IDREF or IDREFS. You can change this by setting the variable link_atts to a space-separated list of attribute names. _followrel relationship gi spec-id If the gi has the specified relationship to the current element, perform the action specified by spec-id on the related element. See the discussion of the criteria field Relation for acceptable relationship names. _gi [M|L|U] Print the name of the current GI to the output stream. If spec- ified, M, L, or U will ensure the GI name is printed in mixed, lower, or upper case, respectively. _id id [spec-id] Find the element with id and use spec-id, if set. If not set, use the spec for that element's context. _include filename Insert the file filename into the output stream. _infile [line] Print the name of the sgml instance file to the output stream. If line is specified, also print the line number. This depends on nsgmls being called with the -l option. _insertnode S|E spec-id Do spec-id when the current element is traversed at a later pass. This can be considered inserting a node, without content, into the hierarchy. This is only useful if done to elements before they are processed. Typically _chasetogi or _followlink is specified early in an instance's processing, so that when the elements found by one of these actions are processed in their turn, the added actions are performed. _insertnode would be specified as the action of a spec-id pointed to in a _chasetogi or _followlink usage. _location The location of the current element is printed to the output stream in several ways: the path to the element (see _path), a position hint, which is the nearest title, the line number, if the ESIS (output from nsgmls) contains line numbers, and the ID of the element, if it has one. This is especially useful when using the Message action to validate an instance. _namelist spec-id [spec-id2] This assumes that the content of the current element is a namelist (a list of element IDs), and applies the action based on spec-id for each element pointed to. If spec-id2 is speci- fied, it will use spec-id for the first ID in the namelist and spec-id2 for the others. _nchild [gi] Print the number of child elements of the element to the output stream. If gi is specified, print the number of child element with that name. _osftable tex|tbl|check [flag] Print table markup into the output stream. The format depends on whether tex or tbl is specified. The flag may be one of cellstart, cellend, rowstart, rowend, top, or bottom. The value determines what markup or text will be generated. If cellstart is specified, the correct markup for the beginning of a cell is output. If top, bottom, or rowend are specified, the correct markup for the end of the appropriate position is printed to the output stream. If check is specified, the attributes and child elements are checked for errors and consistency. _path Print the path to current GI to the output stream. A path is each element, going down the tree from the topmost element. A number in parentheses after each element name shows which child element the next one is in the order of children for that ele- ment. Ordering starts at 0. For example: OSF-BOOK(3) BODY(0) CHAPTER(4) SECTION. This says the path is <OSF-BOOK>'s third child, <BODY>'s zeroth, and <CHAPTER>'s fourth, which is named <SECTION>. _pattr name Print the value of parent's attribute whose name is name to the output stream. _pfind rel gi spec-id This is exactly the same as _find except that the search starts at the current element's parent. _relation relationship gi spec-id [spec-id2] If the gi has the specified relationship to the current element, perform the action specified by spec-id on the current element. If the relationship test fails and spec-id2 is specified, per- form that action. See the discussion of the criteria field Relation for acceptable relationship names. _set varname value Set the value of the variable varname to value. _isset varname [value] spec-id If the value of the variable varname is set to value, then per- form action referred to by spec-id. If value is not specified, action will be performed if varname is set to any value. _! command Run the command command, directing its standard output into the output stream. Immediate Variables Immediate variables are like special variables, except that they are expanded when the transpec is originally processed (special variables are processed later, near when the final output is being generated). The general syntax of immediate variables is${+immediate_vari-
able ...}.

There is currently only one immediate variable defined:

+content
This  special  variable  is  replaced by the data content of the
current element.

Examples
The following will output the given string for elements  whose  generic
identifier  is P (for paragraph).  At the start of processing this ele-
ment, the program ensures that the output starts on  a  new  line,  the
troff macro <.P> is output, then a newline.  At the end of this element
processing, the program ensures that the output starts on a new line.
GI:             P
StartText:      ^.P^
EndText:        ^
-

The following will output the given string for elements  whose  generic
identifier  is CMD-ARGUMENT and which have an attribute PRESENCE set to
the value OPTIONAL.
GI:             CMD-ARGUMENT
AttValue:       PRESENCE OPTIONAL
StartText:      $\$EndText: \$ - The following prints the section number, title, and page number of the target of a cross reference. Assume the cross reference points to a section element, which contains a title element. The criteria for this spec to match is that the attribute OSFROLE is set to the value get- full. The action is to replace the content of the <XREF> element with the given string. When processing the string, instant will follow the IDREF attributes of <XREF> until an element with no IDREF attributes is found. It will then apply the transpec numbered 87 to that element, which will print the name of the GI in mixed case into the output stream. It will then print the LaTeX reference instruction with the value of the LINKEND attribute as an argument. (This will become the section number after processing by LaTeX.) It will then follow IDREFs until if finds an element whose GI is TITLE or which has a child ele- ment with that GI. It will apply the transpec numbered 1 to that ele- ment, which copies the title into the output stream where the cross reference occurs. Finally, it will print the word page followed by the LaTeX instruction to obtain the page number of a reference. GI: XREF AttValue: OSFROLE getfull Replace:${_followlink 87} \\ref{${LINKEND}},\s {\\bf${_chasetogi TITLE 1}}, page \\pageref{${LINKEND}} - # Print GI name, in mixed case GI: _pr_gi_name SpecID: 87 Ignore: 1 EndText:${_gi M}
-
GI:             _pass-text
SpecID:         1
-

Related Information
instant(1), nsgmls(1), egrep(1).

file format                      transpec(5)