path: root/support/vvcode/doc/vvfiles.tex

@c *************************************************************************
@c CHAPTER: Definition of VVcode-related file formats
@c *************************************************************************
@c    node-name, next, previous,  up
@node File Formats, File Formats, Top, Top
@chapter Definition of VVcode-related file formats


@c =========================================================================
@c SECTION: Format of the VVE file
@c =========================================================================
@section Format of the VVE file

A VVE file consists of three logical sections in the following logical
format:

@example
<VVE file> ::= <initial preamble>
               <encoded data lines> 
               <terminal postamble>
@end example

The @code{<initial preamble>} and @code{<terminal postamble>} sections
contain VVE "header" lines used to record and control the characteristics
of the encoding/decoding process.  The @code{<encoded data lines>} section
contains the data from the original file, encoded using the VVcode scheme.

It is sometimes desirable to transmit the VVE file in more than one part,
so the logical format is extended to cater for multi-part files:

@example
<first part> ::=  <initial preamble>
                  <encoded data lines> 
                  <continuation postamble>

<middle part> ::= <continuation preamble>
                  <encoded data lines> 
                  <continuation postamble>

<last part> ::=   <continuation preamble>
                  <encoded data lines> 
                  <terminal postamble>
@end example

There is always one @code{<first part>} and one @code{<last part>} part in
a multi-part VVE file.  There may be zero (for a two part file) or more
@code{<middle part>} parts.

The sections are described in more detail below.


@c -------------------------------------------------------------------------
@c SUBSECTION: Line Prefix and Suffix
@c -------------------------------------------------------------------------
@subsection Line Prefix and Suffix
@itemize @bullet
  @item each line has a "Vv" prefix and "V" suffix

  @item prefix - elimination of mailer lines

  @item postfix - avoid space stripping by certain mailers
@end itemize


@c -------------------------------------------------------------------------
@c SUBSECTION: Preamble Sections
@c -------------------------------------------------------------------------
@subsection Preamble Sections
The preamble sections are used to initialize VVdecode before it starts to
decode the encoded file data.  Each preamble consists of a set of VVE
header lines, each specifying a particular parameter relevant to the
encoding/decoding operation.  Each preamble section comprises a set of
optional header lines followed by the set of required header lines.  the
syntax and use of the header lines is described in section 1.4.


@subsubsection Preamble
The initial preamble is used to initialize VVdecode parameters before it
starts to decode the encoded file (e.g. the file mode and timestamp).  The
logical format of this section  is:

@example
<initial preamble> ::= <optional initialization headers>
                       <begin header>
@end example

The @code{mode}, @code{format} and optional headers may be in any order,
but the @code{begin} header must be the last header in this preamble
section.  None, any or all of the following optional headers may be present
in the initial preamble section:

@example
<optional initializiation headers> ::= <characterset header>
                                       <comment header>
                                       <decodeversion header>
                                       <format header>
                                       <mode header>
                                       <operatingsystem header>
                                       <recordlength header>
                                       <table header>
                                       <timestamp header>
@end example

Note that only the @code{comment} header line may appear more than once in
this section.

@subsubsection Continuation Preamble

The initial preamble is used to reset certain VVdecode parameters before it
starts to decode the next section of the VVE file. The logical format of
this section is:

@example
<continuation preamble> ::= <optional continuation headers>
                            <skipfrom header>
@end example

The optional headers may be in any order, but the @code{skipfrom} header
must be the last header in this preamble section.  None, any or all of the
following optional headers may be present in this section:

@example
<optional initializiation headers> ::= <comment header>
                                       <table header>
@end example

Note that only the @code{comment} header line may appear more than once in
this section.


@c -------------------------------------------------------------------------
@c SUBSECTION: Postamble Sections
@c -------------------------------------------------------------------------
@subsection Postamble Sections
The preamble sections are used to initialize VVdecode before it starts to
decode the encoded file data.  Each preamble consists of a set of VVE
header lines, each specifying a particular parameter relevant to the
encoding/decoding operation.  Each preamble section comprises a set of
optional header lines followed by the set of required header lines.

@subsubsection Postamble
[TODO] put in some text here
@example
<continuation postamble> ::= <skipto header>
                             <comment header>
@end example

The @code{comment} header line is optional and may appear more than once in
this section.

@subsubsection Terminal Postamble
[TODO] put in some text here
@example
<continuation preamble> ::= <end header>
                            <optional terminal headers>

<optional initializiation headers> ::= <bytecount header>
                                       <comment header>
                                       <crc32 header>
@end example


@c -------------------------------------------------------------------------
@c SUBSECTION: Encoded Data Lines
@c -------------------------------------------------------------------------
@subsection Encoded Data Lines
[TODO] put in some text here
@itemize @bullet
  @item describe what these lines are used for

  @item format of the encoded line

  @item termination of each section of encoded data (zero length line)

  @item describe the different underlying data formats for fixed, stream
        and variable format records
@end itemize


@c =========================================================================
@c SECTION: VVE Header Lines
@c =========================================================================
@section VVE Header Lines

A VVE header line takes the form

@example
<header-name> <parameter-1> <parameter-2> ... <parameter-N>
@end example

Most headers take only one parameter and parameters are normally separated
by whitespace, though certain headers (e.g. @code{begin}) take more than one
parameter and can include whitespace in the parameters.  The format of each
of the VVE header lines is described below.  Two important symbols used in
the description are:

@table @code
  @item <WS>
        used to denote whitespace which may include spaces, tabs but not
        the end of the line.  The syntax

        @example
        xyz <WS> parameter <WS> <EOL>
        @end example
        
        states that header @code{xyz} takes a parameter which starts at the
        first non-whitespace character after the @code{xyz} header name and
        is terminated by the first whitespace character after that or the
        end of line.  This syntax is used to specify parameters which do
        not contain whitespace.

  @item <EOL>
        used to denote the end of the line.  The syntax
        
        @example
        xyz <WS> parameter <EOL>
        @end example

        states that header @code{xyz} takes a parameter which starts at the
        first non-whitespace character after the @code{xyz} header name and
        is terminated by the end of the line.  This format would be used to
        specify that parameters can include whitespace.

  @item <NXT-HDR>
        used to denote the next VVE header in the file.  The syntax
    
        @example
        xyz <WS> parameter <NXT-HDR>
        @end example
        
        states that the header @code{xyz} takes a parameter which starts at
        the first non-whitespace character after the @code{xyz} header
        name and is terminated by the start of the next VVE header.  This
        format would be used to specify that parameters can span several
        lines.

        NOTE: the @code{<EOL>} characters are removed when the contents of
              the lines are joined together.
@end table

Following is a detailed description of each VVE header.  For each header
there is a set of headings in the format shown below for the @code{example}
header.

@c -------------------------------------------------------------------------
@c SUBSECTION: @code{example}
@c -------------------------------------------------------------------------
@page
@subsection @code{example}

@table @strong 
  @item Purpose:
        Brief summary of the purpose of this header.

  @item Location:
        Describe where in the VVE file that this header will be found. The
        locations are:

        @itemize @bullet
          @item initial preamble
          @item continuation preamble
          @item continuation postamble
          @item terminal postamble
        @end itemize
        
        Also indicated is whether the header is required or optional.  

  @item Syntax:
        @code{example <WS> parameter <WS> <EOL>}
        
        This part shows the syntax of the header including the header name,
        the number of parameters and the delimiters used to separate the
        parameters.

  @item Remarks:
        This part provides extra information on the use of the header and
        includes any limits that are imposed on the parameter value.

  @item VVencode:
        The header will be written to the VVE file by Vvencode and this
        part describes the circumstances under which VVencode will write
        the header line.

  @item VVdecode:
        This part describes how VVdecode should behave when it encounters
        the header in a VVE file.  In addition, specific processing rules
        are documented for specific cases, namely:

        @table @code
          @item OK
                what VVdecode should do if a valid header line is found in
                the VVE file.

          @item MISSING
                what VVdecode should do if the header line was not found in
                the VVE file.

          @item INVALID
                what VVdecode should do if the header line was found, but
                with missing or invalid parameter values.
        @end table

  @item Example:
        @code{example parameter}

        Here you'll find a simple example of a valid example header line.
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{begin}
@c -------------------------------------------------------------------------
@page
@subsection @code{begin}
@table @strong
  @item Purpose:
        Signifies the absolute start of the VVencoded data.

  @item Location:
        Initial preamble (required).

  @item Syntax:
        @code{begin <WS> file-specification <EOL>}
        
  @item Remarks:
        The file specification may include spaces, though leading and
        trailing spaces will be lost.  There is no restriction on the
        characters used in the file specification, but characters outside
        the VVcode default encoding table may be corrupted when passing
        through mail gateways or systems with differing character sets.

  @item VVencode:
        The file specification recorded in the VVE file is usually derived
        from the input file specification stripped of any preamble or
        postamble components and will therefore consist only of a name
        and/or extension component.  The value recorded can be explicitly
        specified with the @code{header_filespec} command qualifier.

  @item VVdecode:
        VVdecode will use the file specification recorded to construct the
        default file specification for the output file.  If the output file
        is specified on the VVdecode command line, the value specified on
        the @code{begin} header will only be used if the implementation of
        VVcode for the operating system has been defined to use "sticky
        defaults".

        The file specification may have been derived from a different
        operating system and may therefore be invalid on the local system.
        Before it is used VVdecode will convert the file specification to
        one that is valid.

        Processing rules:

        @table @code
          @item OK
                If required, convert the file specification so that it is
                legal on the local operating system and use the legal value
                as the default file specification for the output file.

          @item MISSING
                Issue a fatal error message and stop.

          @item INVALID
                Issue a fatal error message and stop.
        @end table

  @item Example:
        @code{begin input-file.txt}@*
        @code{begin input file name with spaces}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{bytecount}
@c -------------------------------------------------------------------------
@page
@subsection @code{bytecount}
@table @strong
  @item Purpose:
        Records the total number of bytes read by VVencode.

  @item Location:
        Final postamble (optional).

  @item Syntax:
        @code{bytecount <WS> total-bytes-read <WS> <EOL>}

  @item Remarks:
        The total is a positive signed 32 decimal bit number and must
        therefore be in the range 0 - 2147483647.  On systems which
        differentiate between binary and text files, this number is likely
        to be dependent on the mode (i.e. binary/text) used to read and
        encode the file.

  @item VVencode:
        VVencode keeps a cumulative total of the bytes read and record this
        total in the terminal postamble of VVE file.

  @item VVdecode:
        VVdecode keeps a cumulative total of the bytes decoded and written
        and compare it with the VVE recorded value as a confidence check.

        Processing rules:

        @table @code
          @item OK
                Compare the VVE recorded value with the total bytes written
                by VVdecode.  Issue a warning if the two totals are
                different.
                
          @item MISSING
                Don't attempt the comparison.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{bytecount 8388608}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{characterset}
@c -------------------------------------------------------------------------
@page
@subsection @code{characterset}
@table @strong
  @item Purpose:
        Records the character set of the VVencoded data.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{characterset <WS> charset-string <WS> <EOL>}

  @item Remarks:
        The parameter string records the character set of the encoded data
        in the VVE file.  There are no formal controls on the string to use
        for a particular character set, the string is simply compared
        against a local value.  Eventually, an informal directory of
        character set strings may evolve.

  @item VVencode:
        VVencode will record the character set of the encoded data which
        under normal circumstances the character set will be the local
        character set for the operating system.  If the
        @code{translation_file} command line qualifier is specified,
        VVencode will translate the original data from the local character
        set to a new character set specified by the translation file.  In
        this case, VVencode will record the new character set.

  @item VVdecode:
        VVdecode uses this header to determine whether the encoded data in
        the VVE file is of the same character set as that used on the local
        operating system.  If the character sets are different, a warning
        will be issued.  

        If the @code{translation_file} command line qualifier is specified,
        VVdecode will translate the VVE encoded data to a new character set
        specified by the translation file.  In this case, VVdecode will
        compare the VVE file character set with the "from" character set
        expected by the translation file.

        Processing rules:

        @table @code
          @item OK
                Compare the VVE character set with the local operating
                system character set (or the translation file "from"
                character set if appropriate).  Issue a warning message if
                the two character sets are different.

          @item MISSING
                Assume that the VVE character set is the same as the local
                operating system character set.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{characterset ASCII}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{comment}
@c -------------------------------------------------------------------------
@page
@subsection @code{comment}
@table @strong
  @item Purpose:
        Records commentary information deemed to be of sufficient
        importance to warrant displaying it when VVdecoding the file.

  @item Location:
        Initial preamble, continuation preamble, continuation postamble,
        final postamble (optional).

  @item Syntax:
        @code{comment <WS> comment-string <EOL>}

  @item Remarks:
        The comment string is free form text, but care should be taken not
        to use characters that may be corrupted by mail gateways or when
        passing through systems with different character sets.

  @item VVencode:
        VVencode will record information deemed (by the programmer) to be
        important and worth flagging to the VVdecode user.  Currently this
        facility is only used to record the original character set when
        VVencode has been invoked with @code{translation_file} command line
        qualifier to convert the original data to a new character set
        before VVencoding.

  @item VVdecode:
        Generally VVdecode will display any comments encountered on the log
        file.

        Processing rules:

        @table @code
          @item OK
                If the @code{log} command line qualifier was specified,
                display the comment on the log file, otherwise ignore the
                comment.

          @item MISSING
                No action.

          @item INVALID
                Issue a non-fatal error message and ignore the comment.
        @end table

  @item Example:
        @code{comment This file is only useful on Unix systems}@*
        @code{Original character set was `EBCDIC'}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{crc32}
@c -------------------------------------------------------------------------
@page
@subsection @code{crc32}
@table @strong
  @item Purpose:
        Records the 32 bit CRC of the bytes read by VVencode.

  @item Location:
        Final postamble (optional).

  @item Syntax:
        @code{crc32 <WS> input-file-crc32 <WS> <EOL>}

  @item Remarks:
        The CRC value is an unsigned 32 bit hexadecimal number and must
        therefore be in the range 0 - FFFFFFFF.  On systems which
        differentiate between binary and text files, this number is likely
        to be dependent on the mode (i.e. binary/text) used to read and
        encode the file.

        The CRC polynomial used is the same as that used by the popular ZIP
        and ARJ archiving programs.  When encoding in binary mode, the CRC
        recorded should be identical to that computed by ARJ and ZIP.

  @item VVencode:
        VVencode computes a 32 bit CRC of the bytes read and record this
        CRC in the terminal postamble of VVE file.

  @item VVdecode:
        VVdecode computes a 32 bit CRC of the bytes decoded and written and
        compare it with the VVE recorded value as a confidence check.

        Processing rules:

        @table @code
          @item OK
                Compare the VVE recorded value with the total bytes written
                by VVdecode.  Issue a warning if the two CRCs are
                different.

          @item MISSING
                Don't attempt the comparison.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table


  @item Example:
        @code{crc32 1e0cb8a7}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{decodeversion}
@c -------------------------------------------------------------------------
@page
@subsection @code{decodeversion}
@table @strong
  @item Purpose:
        Records the minimum major version number of VVcode required to
        decode the VVE file.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{decodeversion <WS> min-decode-version <WS> <EOL>}

  @item Remarks:
        The minimum decode version is a positive integer and records the
        minimum major version of VVcode required to decode the VVE file.

        The VVcode version number has a "major" and "minor" version.  For
        example, VVcode version 1.2 has a major version of 1 and a minor
        version of 2 and the header

        @example
        decodeversion 2
        @end example
        
        signifies that VVdecode version 2.0 or later is required to decode
        the file.

        Whenever a change is made to the VVE file format that is not
        backwards compatible, the major version number of VVcode will be
        incremented.

  @item VVencode:
        VVencode records the minimum major version number required to
        decode the VVE file in the initial preamble of the VVE file.

  @item VVdecode:
        VVdecode uses the recorded value to check whether it can decode the
        file.

        Processing rules:

        @table @code
          @item OK
                Check that the major version of VVdecode is not less than
                the recorded value.  If it is, issue a fatal error message
                and stop.

          @item MISSING
                Assume that the current version of VVdecode is OK and
                proceed.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{decodeversion 1}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{end}
@c -------------------------------------------------------------------------
@page
@subsection @code{end}
@table @strong
  @item Purpose:
        Signifies the absolute end of the VVencoded data.

  @item Location:
        Final postamble (required).

  @item Syntax:
        @code{end <WS> <EOL>}

  @item Remarks:
        This header signifies that there are no more encoded data lines to
        process and that the terminal preamble is about to start.

  @item VVencode:
        After the complete input file has been encoded, VVencode will write
        a "zero length" encoded line followed by the @code{end} header line
        and the terminal postamble section.

  @item VVdecode:
        After reading this header, VVdecode will cease decoding the encoded
        data bytes and start to read the terminal postamble.

        Processing rules:

        @table @code
          @item OK
                Cease decoding the encoded data bytes and start to read the
                terminal postamble.

          @item MISSING
                Issue a fatal error message and stop.
     
          @item INVALID
                This shouldn't be possible, but if so issue a fatal error
                message and stop.
        @end table

  @item Example:
        @code{end}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{format}
@c -------------------------------------------------------------------------
@page
@subsection @code{format}
@table @strong
  @item Purpose:
        Records the file organization format of the VVencoded file.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{format <WS> format-string <WS> <EOL>}

  @item Remarks:
        The format string must be one of "fixed", "stream" or "variable",
        though the value may be lower, upper or mixed case.  VVcode
        supports these three type of file organization, though not all
        operating systems will support all three.  Note that the internal
        format of the encoded data will depend on the file organization.

  @item VVencode:
        VVencode records the organization of the encoded file.  Note that
        this is the format used by VVencode to read the file which may not
        necessarily be the real format of the original file.

  @item VVdecode:
        VVdecode will use this header to identify the internal format of
        the encoded data to enable it to be decoded correctly.  The format
        will also be used as the default format to create the output file.

        If the VVE file format is not supported by the local operating
        system, VVdecode will create the output file using the default file
        format for the operating system.  The @code{format} command line
        qualifier may be used to override the format of the output file.

        Processing rules:

        @table @code
          @item OK
                Use the header value to decode the encoded data bytes and
                to determine the default format of the output file.

          @item MISSING
                Issue a fatal error message and stop.

          @item INVALID
                Issue a fatal error message and stop.
        @end table

  @item Example:
        @code{format stream}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{mode}
@c -------------------------------------------------------------------------
@page
@subsection @code{mode}
@table @strong
  @item Purpose:
        Records the mode of the VVencoded file.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{mode <WS> mode-string <WS> <EOL>}

  @item Remarks:
        The format string must be one of "binary" or "text", though the
        value may be lower, upper or mixed case.  VVcode supports both
        binary and text mode files, though not all operating systems will
        support both modes.  The mode will often influence the default file
        format used by the operating system.  Most operating systems
        distinguish between text and binary files, though Unix is a notable
        exception.

  @item VVencode:
        VVencode records the mode of the encoded file.  Note that this is
        the mode used by VVencode to read the file which may not
        necessarily be the real mode of the original file.

  @item VVdecode:
        VVdecode will use this header to mode of the encoded file.  The
        mode will also be used as the default mode for the output file.

        If the VVE file mode is not supported by the local operating
        system, VVdecode will create the output file using the default file
        mode for the operating system.  The @code{mode} command line
        qualifier may be used to override the mode of the output file.

        Processing rules:

        @table @code
          @item OK
                Use the header value to determine the default mode of the
                output file.

          @item MISSING
                Issue a fatal error message and stop.

          @item INVALID
                Issue a fatal error message and stop.
        @end table

  @item Example:
        @code{mode binary}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{operatingsystem}
@c -------------------------------------------------------------------------
@page
@subsection @code{operatingsystem}
@table @strong
  @item Purpose:
        Records the operating system on which the file was VVencoded.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{operatingsystem <WS> operating-system-name <WS> <EOL>}

  @item Remarks:
        The parameter string records the operating system on which the
        version of VVencode used to create the VVE file was running. There
        are no formal controls on the string to use for a particular
        character set, the string is simply compared against a local value.
        The string is coded into the VVcode machine dependent header file
        so this shouldn't be too much of a problem.

        It is useful for the decoder to know whether the file was encoded
        on the same operating system to influence the decoding process.
        For example, if the original operating system is different any
        private data would usually be ignored.

  @item VVencode:
        VVencode will record the string for the local operating system as
        coded in the machine dependent header file (machine.h).

  @item VVdecode:
        VVdecode will compare the header value with that recorded for the
        local operating system in the machine dependent header file
        (machine.h) to determine whether the original file was encoded on
        the same operating system.

        Processing rules:

        @table @code
          @item OK
                Compare the header value with the local operating system
                string to determine whether the two operating systems are
                different.  Parts of the decoding process will be affected
                by this decision.

          @item MISSING
                Assume that the operating system on which the file was
                encoded is the same as the local operating system.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{operatingsystem MS-DOS}@*
        @code{operatingsystem Unix}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{recordlength}
@c -------------------------------------------------------------------------
@page
@subsection @code{recordlength}
@table @strong
  @item Purpose:
        Records the maximum and longest length records in the VVencoded
        file.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{recordlength <WS> max-rec-len <WS> long-rec-len <WS> <EOL>}

  @item Remarks:
        Both versions of the record length must be either a decimal number
        within the VVcode supported range of 0 - 65535 or -1.  The value -1
        has a special meaning for each of the record lengths:
  
        max-rec-len the maximum record length is unknown or there is no
                         explicit maximum record length for this file
                         (this usually defaults to the maximum record
                         length supported by the operating system).

        lng-rec-len the length of the longest record in the file is
                    unknown.

        The record length is usually relevant only for fixed and variable
        length record format files.  The maximum record length is that
        allowed by the operating system for the file, whereas the longest
        is the length of the longest record in the file.  For variable
        length record files the longest length must be less than or equal
        to the maximum record length, whereas for fixed length record
        files, the longest record length should be equal to the maximum
        record length.

  @item VVencode:
        Where possible, VVencode will attempt to determine these parameters
        and record them in the VVE file.  Note that the @code{recordlength}
        header is in the initial preamble so these parameters must be
        determined before the file is opened for encoding.  The value may
        be overridden by the @code{record_length} command line qualifier.

  @item VVdecode:
        If the output file format is fixed or variable length records,
        Vvdecode will use these values to create a file of the correct
        type.  The parameter values will be checked, even if they will not
        be used during the subsequent decoding activities.  If the
        parameter values are unknown or invalid, VVdecode will use default
        values appropriate to the file format and the local operating
        system.

        Note that the record length might be valid for the VVE file (i.e.
        in the range 0 - 65535), but be invalid for the file format and
        local operating system.

        Processing rules:

        @table @code
          @item OK
                Use the values to create a file of the correct type and
                format.

          @item MISSING
                Use appropriate default values for the file format and
                local operating system.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{recordlength    -1   132}@*
        @code{recordlength   255    -1}@*
        @code{recordlength 32256 32256}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{skipfrom}
@c -------------------------------------------------------------------------
@page
@subsection @code{skipfrom}
@table @strong
  @item Purpose:
        Signifies the start of a segment of VVencoded data.

  @item Location:
        Continuation preamble (required).

  @item Syntax:
        @code{skipfrom <WS> part-number <WS> file-specification <EOL>}

  @item Remarks:
        The @code{skipfrom} header is used when VVencode creates a
        multi-part VVE file and is analogous to the @code{begin} header in
        the first part.  The part-number parameter records the number of
        the previous VVE file part.  Both parameters are included in the
        header to provide a reasonable degree of confidence that the wanted
        part of the encoded file has been found.

  @item VVencode:
        A @code{skipfrom} header will only be written if VVencode was
        invoked with the @code{split_size} command line qualifier and the
        VVE file is long enough to require more than one part.  The file
        specification recorded in the VVE file is the same as that in the
        @code{begin} header.  The number of the previous VVE file part is
        also recorded.

  @item VVdecode:
        VVdecode will check that the file specification and part number
        match those expected for the next part.  If both do not match,
        VVdecode will continue to look for the wanted VVE file part.

        Processing rules:

        @table @code
          @item OK
                If the wanted part has been found, start to decode the next
                section of encoded data lines.  If this @code{skipfrom}
                does not correspond to the wanted part, continue to search
                for the correct @code{skipfrom} header.

          @item MISSING
                Issue a fatal error message and stop.

          @item INVALID
                Issue a non-fatal error message and ignore the header.
        @end table

  @item Example:
        @code{skipfrom 2 input-file.txt}@*
        @code{skipfrom 2 file name with spaces}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{skipto}
@c -------------------------------------------------------------------------
@page
@subsection @code{skipto}
@table @strong
  @item Purpose:
        Signifies the end of a segment of VVencoded data with more data
        still to come.

  @item Location:
        Continuation postamble (required).

  @item Syntax:
        @code{skipto <WS> part-number <WS> <EOL>}

  @item Remarks:
        The @code{skipto} is used when VVencode creates a multi-part VVE
        file and is analogous to the @code{end} header in the last part.
        The parameter records the number of the next VVE file part.

  @item VVencode:
        A @code{skipto} header will only be written if VVencode was invoked
        with the @code{split_size} command line qualifier and the VVE file
        is long enough to require more than one part.  The number of the
        next VVE file part is recorded.

        After the section of encoded files has been completed, VVencode
        will write a "zero length" encoded line followed by the @code{skipto}
        header line.

  @item VVdecode:
        After reading this header, VVdecode will check that the part number
        recorded is correct.  If it is, VVdecode will start to search for
        the next VVE file part.

        Processing rules:

        @table @code
          @item OK
                Start to search for the next VVE file part.

          @item MISSING
                Issue a fatal error message and stop.

          @item INVALID
                Issue a fatal error message and stop.
        @end table

  @item Example:
        @code{skipto 2}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{table}
@c -------------------------------------------------------------------------
@page
@subsection @code{table}
@table @strong
  @item Purpose:
        Records the character table used to encode the file data bytes.

  @item Location:
        Initial preamble, continuation preamble (optional).

  @item Syntax:
        @code{table <WS> table-contents <NXT-HDR>}

  @item Remarks:
        The encoding table is recorded along with the data to enable the
        decoding program to detect any simple character translations or
        corruptions that may have occurred during the transmission of the
        VVE file.  There is no restriction on the characters that may be
        used in the encoding table, but it is sensible to use characters
        that are normally immune to network corruptions.

        The table comprises 64 characters which are used to represent the
        codes 0 - 63 of the VVcode encoding character set.  The table
        contents may be presented on the same line as the @code{table}
        header or preferably split over several lines to avoid the wrapping
        of long lines performed by some mail gateways.  If the table
        contents are split over several lines, the newline characters are
        removed before the lines are concatenated.  The next valid header
        line encountered will terminate the reading of the table contents.

        Note that whitespace characters at the end of a line may be removed
        in transmission by certain systems that strip trailing whitespace
        from files.  It is strongly recommended that whitespace characters
        are not used in encoding tables.

  @item VVencode:
        VVencode will record the contents of the encoding table used to
        encode the original file.

  @item VVdecode:
        VVdecode will use the contents of the encoding table to construct
        (by inversion) the table to decode the VVE file data.  The table
        contents will be checked for length and repeated characters which
        would prevent the construction of a valid decoding table.

        Processing rules:

        @table @code
          @item OK
                Use the table contents to construct the decoding table and
                thus decode the VVE file.

          @item MISSING
                Assume the default VVcode table.

          @item INVALID
                Issue a fatal error message and stop.
        @end table

  @item Example:
        @code{table}@*
        @code{+-0123456789}@*
        @code{abcdefghijklmnopqrstuvwxyz}@*
        @code{ABCDEFGHIJKLMNOPQRSTUVWXYZ}@*
        @code{begin file-specification}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{timestamp}
@c -------------------------------------------------------------------------
@page
@subsection @code{timestamp}
@table @strong
  @item Purpose:
        Records the modification time of the VVencoded file.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{timestamp <WS> VVcode-timestamp <WS> <EOL>}

  @item Remarks:
        This header is used to record the modification time of the encoded
        file so that it can be preserved when the file is decoded.  The
        timestamp is recorded in the format:

        @example
        YYYY.MM.DD-HH:MM:SS
        @end example
        
        where each of the components are defined as:

        @table @code
          @item YYYY 
                year (range: 1970 - 2037)
          @item MM
                month (range: 01 -12)
          @item DD
                day of month (range: 01 - 31)
          @item HH
                hour (range: 00 - 23)
          @item MM
                minutes (range: 00 - 59)
          @item SS
                seconds (range: 00 - 59)
        @end table
        
        The time is based on the Unix internal time format which represents
        the time as a signed 32 bit integer recording the number of seconds
        since 1-Jan-1970 00:00 GMT.  The VVE timestamp recorded must be in
        the range:

            1970.01.01-00:00:00  to  2037.12.31-23:59:59 GMT

        Some operating systems support a wider range of system times (e.g.
        VAX/VMS) and some support only a narrower range (e.g. MS-DOS) but
        implementations of VVcode for these systems must ensure that
        timestamps in the VVcode range can be handled when encoding and
        decoding.
          
        Note: The timestamp is always recorded as a GMT (or Coordinated
              Universal Time) time.

  @item VVencode:
        VVencode will record the modification time of the encoded file or
        that specified with the @code{timestamp} command line qualifier.
        If VVencode cannot determine the modification time of the encoded
        file and the time is not specified using the @code{timestamp}
        command line qualifier, the @code{timestamp} VVE header line will
        not be recorded.  If the timestamp of the file is outside the range
        of times supported by the VVE file, VVencode should either
        "truncate" the time value to a value that is within the range or
        not record the timestamp.  In either case, a warning should be
        issued.

  @item VVdecode:
        VVdecode will use the @code{timestamp} header value to set the
        modification of the decoded file to that recorded.  If the
        implementation of VVdecode is unable to do this, it should issue a
        warning.

        If the timestamp recorded in the VVE file is outside the range of
        times supported by the operating system, VVdecode should either
        "truncate" the time value to a value that is within the range or
        not set the file timestamp.  In either case, a warning should be
        issued.

        Processing rules:

        @table @code
          @item OK
                Use the header value to set the modification time of the
                decoded file.

          @item MISSING
                Do not attempt to set the modification time of the output
                file (it will probably be created with a timestamp of the
                current date and time).

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{timestamp 1991.12.01-12:10:34 GMT}
@end table


@c =========================================================================
@c SECTION: VVE encoded data format
@c =========================================================================
@section VVE encoded data format


@c =========================================================================
@c SECTION: XLT translation file format
@c =========================================================================
@section XLT translation file format


@c =========================================================================
@c SECTION: TBL encoding table file format
@c =========================================================================
@section TBL encoding table file format