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 particular 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 translation 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 numbers 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 (anywhere up the tree), child (immediate
child), descendant (anywhere down the tree), parent
(immediate ancestor), sibling (share same parent element),
sibling+ (any later sibling), sibling+1 (the immediately
following sibling), sibling- (any earlier 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 (literal) 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
translation, 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 matching 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
children 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. Messages 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
processed.
Other Fields¶
These fields may appear anywhere. The action occurs when the translation 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
output 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 character
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 command 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 output 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 statements 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 matching 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, optionally 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-separated 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 notation
entity reference. For example, to print the filename in the latex macro
from the epsf macro package, use \\epsfboxi{${_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-parent, parent, and attr, and take different
arguments. Explanations 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 LINKEND 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
specified, 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
specified, 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 element. 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, perform 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 perform 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 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_variable ...}.
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 element, 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
getfull. 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 element with that GI. It
will apply the transpec numbered
1 to that element, 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
-
instant(1),
nsgmls(1),
egrep(1).
