Provided by: docbook-to-man_2.0.0-34_amd64 bug

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)