transpec


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


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

       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,
       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
       _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.

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

       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
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017 Hurricane Electric. All Rights Reserved.