Provided by: docbook-to-man_2.0.0-31_amd64 
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 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
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
-
Related Information
instant(1), nsgmls(1), egrep(1).
file format transpec(5)