@c *************************************************************************
@c CHAPTER: How to port VVcode to a new environment
@c *************************************************************************
@c    node-name, next, previous,  up
@node Porting Guide, Porting Guide, Top, Top
@chapter How to port VVcode to a new environment

This chapter introduces the facilities provided for porting VVcode to a new
environment and recommends the approach that should be taken for particular
examples.

@itemize @bullet
  @item introduction and philosophy
  @item @file{machine.h}
  @item @file{specific.h} and @file{xxx.c}
  @item local.h
@end itemize




@c =========================================================================
@c SECTION: The @file{os.h} header file
@c =========================================================================
@c    node-name, next, previous,  up
@section The @file{os.h} header file

The @file{os.h} file contains tests to identify the environment on which
VVcode is being built.  Once the environment has been identified the file
defines preprocessor macros to define the environment in the format
expected by VVcode.  Environments are defined as the operating system and
variants due to dialects of the operating system or the compiler.  

@itemize @bullet
  @item explain the @samp{OS_xxxx} macros, including the operating systems
        currently supported
  @item explain the @samp{UNIX_yyyy} and related macros
@end itemize



@c =========================================================================
@c SECTION: The @file{machine.h} header file
@c =========================================================================
@c    node-name, next, previous,  up
@section The @file{machine.h} header file

The header file @file{machine.h} 

@itemize @bullet
  @item defines macros to control the behaviour and compilation of VVcode
  @item several categories of definition required:

  @itemize @bullet
    @item environment
    @item command line interface
    @item file specifications
    @item file formats
  @end itemize
@end itemize


@c -------------------------------------------------------------------------
@c SUBSECTION: VVcode environment
@c -------------------------------------------------------------------------
@subsection VVcode Environment

@itemize @bullet
  @item definitions for the environment in which VVcode is built
@end itemize

@subsubsection @code{VV_OPERATING_SYSTEM}

A string recording the operating system for which this version of VVcode
has been implemented.  This value is recorded in the VVE file and used by
VVdecode to detect whether the original file was encoded on a different
operating system.  For example:

@example
#define VV_OPERATING_SYSTEM "MS-DOS"
@end example


@subsubsection @code{VV_IMPLEMENTATION}

A string describing the implementation of VVcode.  Displayed when VVcode
programs are started and recorded in log and VVE files.  For example:

@example
#define VV_IMPLEMENTATION "MS-DOS Turbo-C version 09.1-001 (31 May 1992)"
@end example


@subsubsection @code{ANSI_SYNTAX}

Define as @code{TRUE} if the compiler supports the draft ANSI standard for
C syntax (it shouldn't matter if the run time library is not fully ANSI
compliant).  Define as @code{FALSE} if this syntax is not supported.  The
macro is used to control the declaration of functions and the use of new
ANSI keywords such as @samp{const}.  If your compiler requires old-style
function declarations like:

@example
char *allocate_buffer ();  /* Declaration */
...
char *allocate_buffer (buf_len, buf_name)  /* Function code */
    size_t           buf_len;
    char            *buf_name;
@{
...
@}
@end example

you should define @code{ANSI_SYNTAX} to @code{FALSE}.  Many Unix systems
have compilers that fall into this category, though the GNU C compiler is a
notable exception.  If you have a modern compiler that accepts ANSI style
function declarations like:

@example
char *allocate_buffer (const size_t buf_len,  /* Declaration */
                       const char *buf_name);
...
char *allocate_buffer (const size_t buf_len,  /* Function code */        
                       const char *buf_name)
@{
...
@}
@end example

you should define @code{ANSI_SYNTAX} to @code{TRUE}.  The GNU C compiler
and most of the PC compilers support the ANSI standard.


@c -------------------------------------------------------------------------
@c SECTION: VVcode Command Line Interface
@c -------------------------------------------------------------------------
@subsection{VVcode Command Line Interface}

@itemize @bullet
 @item  defines how to start VVcode and how it interprets the command line
 @item  explain concepts of @dfn{parameters} and @dfn{qualifiers}
 @item  @dfn{parameters} - 
 @item  @dfn{qualifiers} - modify the behaviour of a command#
 @item  give an example and compare the commands @code{rm -i foo} and
        @code{delete /confirm foo}
 @item  this does not preclude implementations that may not usually use
        a command line interface (e.g. Mac).  For example VMS does use a
        CLI but provides a set of system services to handle the CL.  Under
        these circumstances these definitions will only be used to display
        help text in the correct format
@end itemize
    
@subsubsection @code{QUAL_INTRO}

A string containing a set of characters, each of which may be used to
introduce a command line qualifier.  For example:

@example
#define QUAL_INTRO "/-" /* MS-DOS */
#define QUAL_INTRO "-"  /* Unix */
@end example

The examples above indicate that on a Unix system @samp{-} would be used to
introduce a command qualifier, whereas on MS-DOS either @samp{-} or
@samp{/} could be used.


@subsubsection @code{QUAL_SEP}

A string containing a set of characters, each of which may be used to
separate a command line qualifier from its value.  For example:
    
@example
#define QUAL_SEP "=:-" /* MS-DOS */
#define QUAL_SEP " "   /* Unix */    
#define QUAL_SEP " "   /* Unix */    
@end example

The examples above indicate that on an MS-DOS system the qualifier value is
separated from the qualifier by one of the characters @samp{=}, @samp{:} or
@samp{-}.  The Unix example indicates that the value is separated from the
qualifier by a space, i.e. it is the next command line parameter.


@subsubsection @code{OPTIONAL_QUALIFIER_VALUES}

Define as @code{TRUE} if the operating system convention can handle command
line qualifiers with optional values.  On systems such as MS-DOS, VAX/VMS
and VM/CMS the qualifiers are separated from each other by spaces and from
their values by another character such as an equals sign (@samp{=}).  In
the following example it is obvious whether the optional value for the
@samp{log} qualifier is present:

@example
    vvencode /overwrite /log=log-file  ip-file op-file
    vvencode /overwrite /log           ip-file op-file
@end example

On Unix, the convention is to separate qualifiers from each other by spaces
and from their qualifiers by spaces.  In the following example it is
difficult if not impossible to determine whether the @samp{log} qualifier
value is present:

@example
    vvencode -overwrite -log log-file  ip-file op-file
    vvencode -overwrite -log           ip-file op-file
@end example

This problem could be overcome by forcing Unix users to use a different
character like @samp{=} to introduce the qualifier value or by imposing
strict rules on the ordering of parameters and qualifiers.  Neither of
these approaches is likely to be popular so we take the easy way out and
specify whether such optional qualifier values are supported.  If they are
not supported, the qualifiers which could take optional values are modified
either to require a value or to take no value.

Example:

@example
    #define OPTIONAL_QUALIFIER_VALUES TRUE   /* MS-DOS, VMS */
    #define OPTIONAL_QUALIFIER_VALUES FALSE  /* Unix */
@end example


@subsubsection @code{STICKY_DEFAULTS}

Define as @code{TRUE} if the VVcode programs should apply default file
names when determining output file specifications.  For example, on Unix
the definition would usually be:

@example
    #define STICKY_DEFAULTS FALSE  /* Unix */
@end example

and the commands:
   
@example
    vvencode one
    vvencode one two
    vvencode one two -log three
@end example

would create the files @file{one.vve}, @file{two}, and @file{two} plus a
log file @file{three} respectively.  On other systems such as MS-DOS and
VAX/VMS where default file names are customary the definition would usually
be 

@example
    #define STICKY_DEFAULTS TRUE  /* MS-DOS, VMS */
@end example

and the commands:
   
@example
    vvencode one
    vvencode one two
    vvencode one two -log three
@end example

would create the files @file{one.vve}, @file{two.vve} and @file{two.vve}
plus a log file @file{three.log} respectively. 


@subsubsection @code{STDOUT_OUTPUT}

Define as @code{TRUE} if the VVencode program should write to standard
output if an output file is not explicitly specified on the command line.
The command:

@example
    vvencode ip-file
@end example

would write the VVE file to standard output if @code{STDOUT_OUTPUT} is defined
as @code{TRUE} or to @file{ip-file.vve} if it is defined as @code{FALSE}.

Examples:

@example
    #define STDOUT_OUTPUT TRUE  /* Unix */
    #define STDOUT_OUTPUT FALSE /* MS-DOS, VMS */
@end example


@subsubsection @code{SUPPORT_PIPING}

Define as @code{TRUE} if the VVcode programs should support reading from
standard input and/or writing to standard output so that they may be used
as filters.  The programs do not behave as true filters since an input file
must always be specified, but specifying a certain string (e.g. @samp{-})
as the input file specification will cause the program to read from
standard input.  The string used is defined by the macro
@code{STDIO_SYMBOL}.

Examples:

@example
    #define SUPPORT_PIPING TRUE   /* Unix, MS-DOS */
    #define SUPPORT_PIPING FALSE  /* VMS, VM/CMS */
@end example

@subsubsection @code{STDIO_SYMBOL}

A string which when used as a file specification will cause the VVcode
programs to read/write to standard input/output depending on whether that
file is an input or output file.  This string is only used if the macro
@code{SUPPORT_PIPING} is defined as @code{TRUE}.  If it is unused, define
it as "".

On a Unix system, the following definitions would be usual:

@example
    #define SUPPORT_PIPING TRUE
    #define STDIO_SYMBOL   "-"  /* Unix, MS-DOS */
@end example

and piping a binary file into VVencode to could be achieved with the shell
command:

@example
    cat binary-file | vvencode - - | mail kempson@@TeX.Ac.Uk
@end example        


@c -------------------------------------------------------------------------
@c SECTION: File Specifications
@c -------------------------------------------------------------------------
@subsection File Specifications

explain here the VVcode file specification model and how it is used


@subsubsection @code{MAX_PATH}

The maximum number of characters allowed in a file specification.

Example:

@example
    #define MAX_PATH 80   /* MS-DOS */
    #define MAX_PATH 255  /* BSD Unix */
    #define MAX_PATH 255  /* VAX/VMS, some Unix */
@end example


@subsubsection @code{MAX_PREAMBLE}

The maximum number of characters in the preamble component of a file
specification.  If the system does not support a preamble component, define
as zero.
    
Example:

@example
    #define MAX_PREAMBLE 64   /* MS-DOS */
    #define MAX_PREAMBLE 255  /* BSD Unix */
    #define MAX_PREAMBLE 255  /* VAX/VMS */
@end example


@subsubsection @code{MAX_NAME}

The maximum number of characters in the name component of a file
specification.

Example:

@example
    #define MAX_NAME 8    /* MS-DOS */
    #define MAX_NAME 255  /* BSD Unix */
    #define MAX_NAME 39   /* VAX/VMS */
@end example


@subsubsection @code{MAX_EXT}

The maximum number of characters in the extension component of a file
specification.  If the system does not support an extension component,
define as zero.
    
Example: 

@example
    #define MAX_EXT 3    /* MS-DOS */
    #define MAX_EXT 255  /* BSD Unix */
    #define MAX_EXT 39   /* VAX/VMS */
@end example


@subsubsection @code{MAX_POSTAMBLE}

The maximum number of characters in the postamble component of a file
specification.  If the system does not support a postamble component,
define as zero.
    
Example:

@example
    #define MAX_POSTAMBLE 0  /* MS-DOS */
    #define MAX_POSTAMBLE 0  /* BSD Unix */
    #define MAX_POSTAMBLE 5  /* VAX/VMS */
@end example


@subsubsection @code{PREAMBLE_END}

A string containing a set of characters, each of which may be used to
denote the end of the preamble component of a file specification.  If the
system does not support a preamble component, define as "".
        
Example:

@example
    #define PREAMBLE_END ":\\"  /* MS-DOS */
    #define PREAMBLE_END ":/"   /* BSD Unix */
    #define PREAMBLE_END ":>]"  /* VAX/VMS */
@end example


@subsubsection @code{EXTENSION_BEGIN}

The single character that may be used to denote the start of the extension
component of a file specification.  If the system does not support an
extension component, define as @samp{\000}.
        
Example:

@example
    #define EXTENSION_BEGIN '.'  /* MS-DOS */
    #define EXTENSION_BEGIN '.'  /* BSD Unix */
    #define EXTENSION_BEGIN '.'  /* VAX/VMS */
@end example


@subsubsection @code{POSTAMBLE_BEGIN}

A string containing a set of characters, each of which may be used to denote
the start of the postamble component of a file specification.  If the system
does not support a postamble component, define as "".
        
Example:

@example
    #define POSTAMBLE_BEGIN ""   /* MS-DOS */
    #define POSTAMBLE_BEGIN ""   /* BSD Unix */
    #define POSTAMBLE_BEGIN ";"  /* VAX/VMS */
@end example    


@subsubsection @code{UPPERCASE_FILESYSTEM}

Define as @code{TRUE} if the file system is case insensitive.  For the
benefit of file systems that do care (where lower case names are usual),
VVencode will convert file specifications to lower case before recording
them in the VVE file.

Example:

@example
    #define UPPERCASE_FILESYSTEM TRUE   /* MS-DOS, VAX/VMS */
    #define UPPERCASE_FILESYSTEM FALSE  /* Unix */
@end example


@c -------------------------------------------------------------------------
@c SECTION: File Formats
@c -------------------------------------------------------------------------
@subsection{File Formats}

explain the different file formats and provide a small table showing how
they are used for different operating systems


@subsubsection @code{SUPPORT_FIXED_FMT}

Define as @code{TRUE} if the file system supports fixed length record
format  files.  

Example:

@example
    #define SUPPORT_FIXED_FORMAT TRUE   /* VAX/VMS, VM/CMS */
    #define SUPPORT_FIXED_FORMAT FALSE  /* MS-DOS, Unix */    
@end example    


@subsubsection @code{SUPPORT_STREAM_FMT}

Define as @code{TRUE} if the file system supports stream format files.  
    
Example:

@example
    #define SUPPORT_STREAM_FILES TRUE   /* MS-DOS, Unix, VAX/VMS */
    #define SUPPORT_STREAM_FILES FALSE  /* VM/CMS */
@end example


@subsubsection @code{SUPPORT_VARIABLE_FMT}

Define as @code{TRUE} if the file system supports variable length record
format files.  

Example:

@example
    #define SUPPORT_VARIABLE_FORMAT TRUE   /* VAX/VMS, VM/CMS */
    #define SUPPORT_VARIABLE_FORMAT FALSE  /* MS-DOS, Unix */    
@end example


@subsubsection @code{TEXT_LINE_OVERHEAD}

The extra number of characters written by the file system when writing
lines to text files.  For example, when writing to text files MS-DOS
converts @samp{\n} to @samp{\r\n} and therefore has an overhead of 1.

Example:

@example
    #define TEXT_LINE_OVERHEAD 1  /* MS-DOS, VAX/VMS */
    #define TEXT_LINE_OVERHEAD 0  /* Unix */
@end example


@subsubsection @code{DEF_MODE}

Define as the default mode for file encoding & decoding to be used if the
mode is not specified on the command line and cannot be determined from the
input file.  It must be @code{MODE_BINARY} or @code{MODE_TEXT}.
    
Example:

@example
    #define DEF_MODE MODE_BINARY  /* most systems */
@end example


@subsubsection @code{DEF_TEXT_FMT}

Define as the default file format for text files.  It must be one of
@code{FMT_FIXED}, @code{FMT_STREAM} and @code{FMT_VARIABLE} and only a
supported format may be specified.
    
Example:

@example
    #define DEF_TEXT_FMT FMT_STREAM    /* MS-DOS, Unix */
    #define DEF_TEXT_FMT FMT_VARIABLE  /* VAX/VMS */
@end example


@subsubsection @code{DEF_BINARY_FMT}

Define as the default file format for text files.  It must be one of
@code{FMT_FIXED}, @code{FMT_STREAM} and @code{FMT_VARIABLE} and only a
supported format may be specified.

Example:

@example
    #define DEF_BINARY_FMT FMT_STREAM  /* MS-DOS, Unix */
    #define DEF_BINARY_FMT FMT_FIXED   /* VAX/VMS */
@end example


@subsubsection @code{MIN_VARIABLE_RECORD_LEN}

The minimum record length in bytes supported by the file system for
variable length record format files.  Must be within the VVcode limits of 0
to 65535.  If the system doesn't support variable length record format files
define as @code{INV_RECORD_LEN}.

Example:

@example
    #define MIN_VARIABLE_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define MIN_VARIABLE_RECORD_LEN 0               /* VAX/VMS */
@end example


@subsubsection @code{MAX_VARIABLE_RECORD_LEN}

The maximum record length in bytes supported by the file system for
variable length record format files.  Must be within the VVcode limits of 0
to 65535.  If the system doesn't support variable length record format files
define as @code{INV_RECORD_LEN}.

Example:

@example
    #define MAX_VARIABLE_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define MAX_VARIABLE_RECORD_LEN 32765           /* VAX/VMS */
    #define MAX_VARIABLE_RECORD_LEN 65535           /* VM/CMS */
@end example


@subsubsection @code{DEF_VARIABLE_RECORD_LEN}

The default maximum record length in bytes supported by the file system for
variable length record format files.  Must be in the range defined by
@code{MIN_VARIABLE_RECORD_LEN} and @code{MAX_VARIABLE_RECORD_LEN}.  If the
system doesn't support variable length record format files define as
@code{INV_RECORD_LEN}.

Example:

@example
    #define DEF_VARIABLE_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define DEF_VARIABLE_RECORD_LEN 512             /* VAX/VMS */
    #define DEF_VARIABLE_RECORD_LEN 255             /* VM/CMS */
@end example


@subsubsection @code{MIN_FIXED_RECORD_LEN}

The minimum record length in bytes supported by the file system for fixed
length record format files.  Must be within the VVcode limits of 0 to
65535.  If the system doesn't support fixed length record format files
define as @code{INV_RECORD_LEN}.

Example:

@example
    #define MIN_FIXED_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define MIN_FIXED_RECORD_LEN 0               /* VAX/VMS */
@end example


@subsubsection @code{MAX_FIXED_RECORD_LEN}

The maximum record length in bytes supported by the file system for fixed
length record format files.  Must be within the VVcode limits of 0 to
65535.  If the system doesn't support fixed length record format files
define as @code{INV_RECORD_LEN}.

Example:

@example
    #define MAX_FIXED_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define MAX_FIXED_RECORD_LEN 32765           /* VAX/VMS */
    #define MAX_FIXED_RECORD_LEN 65535           /* VM/CMS */
@end example


@subsubsection @code{DEF_FIXED_RECORD_LEN}

The default record length in bytes supported by the file system for fixed
length record format files.  Must be in the range defined by
@code{MIN_FIXED_RECORD_LEN} and @code{MAX_FIXED_RECORD_LEN}.  If the system
doesn't support fixed length record format files define as
@code{INV_RECORD_LEN}.

Example:

@example
    #define DEF_FIXED_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define DEF_FIXED_RECORD_LEN 512             /* VAX/VMS */
    #define DEF_FIXED_RECORD_LEN 255             /* VM/CMS */
@end example


@subsubsection @code{DEF_TEXT_PADCHAR}

Define as the default character used to pad out short records in text fixed
length record format files.  Must be a valid character constant and will
usually be a space character.  If the system doesn't support fixed length
record format files, define as @samp{\000}.

Example:

@example
    #define DEF_TEXT_PADCHAR '\000' /* MS-DOS, Unix */
    #define DEF_TEXT_PADCHAR ' '   /* VAX/VMS, VM/CMS */
@end example


@subsubsection @code{DEF_BINARY_PADCHAR}

Define as the default character used to pad out short records in binary
fixed length record format files.  Must be a valid character constant and
will usually be a null character.  If the system doesn't support fixed
length record format files, define as '\000'.

Example:

@example
    #define DEF_BINARY_PADCHAR '\000'  /* MS_DOS, Unix */
    #define DEF_BINARY_PADCHAR '\000'  /* VAX/VMS, VM/CMS */
@end example                 



@c =========================================================================
@c SECTION: The @file{xxx.c} operating system specific module
@c =========================================================================
@section The @file{xxx.c} operating system specific module



@c =========================================================================
@c SECTION: Porting VVcode - an example
@c =========================================================================
@section Porting VVcode - an example