bionic (5) transpec.5.gz

Provided by: docbook-to-man_2.0.0-41_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 onsgmls, 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 onsgmls 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 onsgmls) 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
       -

       instant(1), onsgmls(1), egrep(1).

                                                   file format                                       transpec(5)